Agentic Dev Wiki

Writing and maintaining CLAUDE.md

4 min read

CLAUDE.md only helps if Claude actually follows it, and adherence drops as the file grows or goes stale. Treat it like code: add to it on evidence, keep it short, and clean it up regularly.

When to use it

When you start a CLAUDE.md, every time you are about to add a line to one, and every few weeks on a project you work on often.

How to do it

  1. Add a rule when you have a reason. Good triggers: Claude makes the same mistake a second time; a code review catches something Claude should have known about the codebase; you type the same correction you typed last session; a new teammate would need the same context.
  2. Write rules you can check. “Run npm test before committing”, not “test your changes”. “API handlers live in src/api/handlers/”, not “keep files organized”. Group related rules under headings and bullets.
  3. Leave out what Claude can see in the code. Directory trees, dependency lists and architecture overviews cost context and go stale; Claude can read the repo. Keep what the code does not tell it: pitfalls, the reason behind a rule, conventions that differ from the tool defaults.
  4. Keep each file under about 200 lines. Longer files cost more context and get followed less reliably. Splitting a file into @ imports does not help here, because imported files load at startup too.
  5. Move the rest out. A multi-step procedure becomes a skill, which loads only when needed. Rules for one part of the codebase become a rule in .claude/rules/ with a paths: glob, which loads only when Claude touches matching files.
  6. Audit it regularly. Contradictory rules make Claude pick one arbitrarily, and stale rules point it at files that no longer exist. Run /doctor prompt-audit: Claude checks your CLAUDE.md, CLAUDE.local.md, AGENTS.md and the rules, skills and other files under .claude/ and ~/.claude/ for outdated wording, references to missing files and contradictions, and proposes edits. Nothing changes until you ask it to apply them.
  7. Keep personal instructions out of the shared repo (see below).

Keeping personal instructions out of the repo

You wantPut it in
Your habits, in every project~/.claude/CLAUDE.md or ~/.claude/rules/
Your notes for one projectCLAUDE.local.md in the project root, listed in .gitignore
The same notes across several git worktrees of one repoA file in your home directory, imported with @~/.claude/my-project-instructions.md; a gitignored CLAUDE.local.md exists only in the worktree where you created it
A personal file in the repo folder without touching the shared .gitignoreList it in .git/info/exclude, git’s per-repository ignore file that is never committed

Two things to know. The first time a project’s CLAUDE.md imports a file from outside the project (like the home-directory import above), Claude Code asks you to approve it. And .git/info/exclude, like .gitignore, has no effect on files git already tracks.

Example

An audit of a real side project’s instruction files: a 14-line CLAUDE.md that imports a 292-line rules file. /doctor prompt-audit found, among other things:

  • hard-coded counts and line numbers that had drifted within weeks (“24 of the 60 handlers” when there were 62; database.ts:60 that had moved to line 68; a directory described as empty that no longer existed);
  • a rule naming one migration file when the folder held eight;
  • a reminder added after one session’s mistake, next to a list that was already correct;
  • five skills saved as flat files in .claude/skills/ instead of <name>/SKILL.md, so none of them ever loaded.

Each finding came with a confidence level and a proposed diff, and nothing was applied automatically. The lesson that generalizes: counts, line numbers and single file names rot with every commit. State the rule, and give the command that checks it (for example a grep), instead of the current number.

Common mistakes

  • Using CLAUDE.md as documentation. A full project tour is context Claude pays for in every session. Link to docs or let Claude read the code.
  • Assuming the running session sees your edit. Changes apply after /clear, /compact or a restart.
  • Relying on it for hard limits. CLAUDE.md is guidance. Use hooks or permission rules for things that must never happen.
  • Adding CLAUDE.local.md to a repo that relies on AGENTS.md. It stops Claude from reading AGENTS.md unless Project instructions is set to claude-md-and-agents-md.

Citations

  1. How Claude remembers your project
  2. Extend Claude with skills
  3. gitignore

Graph View

Backlinks