Claude Md Rules Memory — Claude Code Guide

CLAUDE.md — a short instruction for the agent

`README.md` explains the project’s purpose and startup to people, while `CLAUDE.md` describes Claude’s working rules: commands, risk areas, and report format. The most valuable entries are non-obvious agreements that cannot be reliably inferred from the code.

Before writing instructions, check the Git state, separate branch, access rights, and the correct working directory.

A reference CLAUDE.md minimum

# CLAUDE.md

## Commands
- run: `npm run dev`
- test: `npm test`
- check: `npm run check`

## Rules
- do not change the public API without confirmation
- do not combine mass formatting with a functional change
- list files and checks in the summary

## Do not
- do not read or edit .env* without a direct request
- do not perform broad refactoring outside the scope

CLAUDE.local.md for local details

`CLAUDE.local.md` is suitable for machine-dependent parameters and personal preferences that the whole team does not need. This file is usually excluded from Git, but it must not contain secrets.

Do not hide a stable team rule in a local file: other sessions and colleagues will not see it.

# CLAUDE.local.md

## Local environment
- database runs on port `5454`
- test CSV files are in `~/projects/data/subscriptions/`

## Personal preferences
- show changes in small blocks
- briefly describe the plan before changes in more than two files

Where to put a specific rule

1. If the rule is needed by the whole team and most sessions, add it to CLAUDE.md.
2. If it is needed only by you, use CLAUDE.local.md or the user level.
3. If it concerns a specific folder or file type, move it to a separate rule.
4. If it is a temporary observation or new fact, consider auto memory.
5. If an entry is neither stable nor useful, do not add it just “in case.”

Rules and auto memory do not replace protection

Rules help narrow the context for a specific area, while auto memory can preserve a temporary solution or observation. Memory may be incomplete, wrong, or outdated, so a critical agreement must not be stored there alone.

Markdown instructions are not an enforcement mechanism. Protection also requires Git permissions, permission modes, `.gitignore`, secret management, tests, and human review.

• Review auto memory regularly.
• Delete accidental and outdated entries.
• Move stable rules to the shared CLAUDE.md or a focused rule.
• Do not turn CLAUDE.md into an encyclopedia of the entire project.