Writing a CLAUDE.md that actually changes what the AI does

Short answer: CLAUDE.md is a file in your repo that Claude Code reads at the start of every session. Treat it like onboarding notes for a sharp new hire who forgets everything overnight: how to build and test, where things live, rules that are not obvious from the code, and what "done" means. Keep it short, concrete and checkable. Add a line every time the agent makes the same mistake twice.

A real example: the third time it used DateTime.Now

An agent adds a feature to a payment service. The code works, the tests pass, and it uses DateTime.Now in three places. The project uses TimeProvider everywhere, so reconciliation tests can control time. You fix it. The next day, in a new session, it does it again, because nothing it reads tells it otherwise.

One line in CLAUDE.md ("Never use DateTime.Now or DateTime.UtcNow; inject TimeProvider") fixes this for every future session. That is the whole idea: turn repeated review comments into standing instructions.

What belongs in it

1. Commands. Exact build, test, run and migration commands. The agent will run them, so they must be copy-paste correct.
2. Map. Which project does what, where the entry points are, where tests live. Five to ten lines, not a directory dump.
3. Rules that aren't visible in the code. Money is long Rials, never double. Times are UTC in the database. No new NuGet packages without asking.
4. Definition of done. Build passes, tests pass, a migration is added if the model changed, no warnings introduced.
5. Danger zones. Files or folders never to edit (generated code, production configs, the payments module without tests).

What to leave out

• Generic advice like "write clean, maintainable code". It changes nothing.
• Things the agent can read from the code in a second, such as which ORM you use.
• Long explanations. One sentence of why is enough; the agent needs the rule, not the history.
• Secrets. Connection strings and keys never go in a file the agent reads and might echo.

A real CLAUDE.md for a .NET project

# Wallet service

## Commands
- Build: dotnet build -warnaserror
- Test: dotnet test
- Add migration: dotnet ef migrations add <Name> -p src/Wallet.Infrastructure -s src/Wallet.Api

## Map
- src/Wallet.Api: minimal API endpoints, DI setup (Program.cs)
- src/Wallet.Domain: entities and rules, no EF or HTTP references
- src/Wallet.Infrastructure: EF Core DbContext, gateway clients
- tests/: xUnit, one test project per src project

## Rules
- Money is long in Rials. Never double or float.
- Never use DateTime.Now/UtcNow; inject TimeProvider.
- Ledger entries are append-only. No UPDATE or DELETE on LedgerEntries.
- Every POST that moves money takes an Idempotency-Key header.
- Don't add NuGet packages without asking.
- Don't edit tests to make them pass; fix the code or ask.

## Done means
- Build and all tests pass.
- New behaviour has a test.
- A migration exists if the model changed.

Keeping it alive

• Nest when it grows. A CLAUDE.md inside a subfolder applies when the agent works there, so module-specific rules don't bloat the root file.
• Review it like code. It is in the repo, so changes go through pull requests and stale rules get deleted.
• Test the important rules. If a rule really matters (no DateTime.Now), back it with an analyzer or an architecture test. The file guides; the build enforces.

Pros and cons

Pros

• Fewer repeated review comments; the agent starts every session with your conventions.
• Doubles as onboarding notes for human teammates.
• Cheap: one small file, versioned with the code.

Cons

• It is guidance, not enforcement; important rules still need tests or analyzers.
• A long or contradictory file is followed inconsistently.
• Needs maintenance, or it starts describing a codebase that no longer exists.

Want to set up an AI-assisted workflow for your team or ship a project with one? See how I can help.