CLAUDE.md: Standing Instructions
Every session you find yourself telling Claude the same things: run the tests with pytest -q, keep pricing logic in pricing.py, never hand-edit migrations. A CLAUDE.md file lets you say it once and have it heard every time.
The rule
Write once what you would otherwise repeat every session.
CLAUDE.md is a plain Markdown file that Claude Code reads automatically at the start of every session in the project. Its contents become part of the context, so Claude begins each session already knowing them.
What belongs:
- Commands: how to install, run, test and lint.
- Rules and conventions that the code does not make obvious.
- Gotchas: the things that have tripped up Claude, or new teammates, before.
- Workflow: how you want changes checked and committed.
What does not: things the code already shows plainly, long tutorials, secrets of any kind, and notes that change daily.
The /init command gives you a head start: it looks around the project and drafts a CLAUDE.md. Treat the draft as a first version to cut down, not a finished file.
Remember that CLAUDE.md is guidance. Claude reads it and usually follows it, but a rule that must never be broken also needs a permission rule or a hook. Commit the file, and review changes to it like code, because it steers every session your team runs.
Keep it true, too. When a fact changes, such as the test command or the folder where pricing lives, update the line in the same commit as the code. A stale CLAUDE.md is worse than none, because Claude follows its wrong advice with full confidence.
# tiffin
Order and billing app for a home kitchen that delivers lunch tiffins.
## Commands
- Run tests: `pytest -q`
- Run the app locally: `flask --app app run`
## Rules
- Pricing logic lives in `pricing.py`; routes in `app.py` only call it.
- Never hand-edit files in `migrations/`; generate them.
- Don't change existing tests to make them pass; ask first.The shortcut
Use the second-time rule: the second time you type the same instruction, or correct the same mistake, add a line to CLAUDE.md.
Draft
Run
/init. The draft is sixty lines long, including a file-by-file listing of the project.
Drills
Answer fast — trust the rule.
When does Claude Code read the project's CLAUDE.md?
Which line belongs in CLAUDE.md?
What does /init do?
You have now corrected Claude twice for hand-editing a migration. What does the second-time rule say?
Remember
- Write once in
CLAUDE.mdwhat you would otherwise repeat every session. - Shortcut: the second time you repeat or correct something, add a line.
- Trap: treating
CLAUDE.mdas enforcement; it guides, while hooks and permission rules enforce.