CLAUDE.md Best Practices: Writing Project Memory for Claude Code

By og.cc.cd · Published 2026-10-18 · Updated 2026-10-18 · 4 min read

CLAUDE.md is the file Claude Code reads at the start of every session to learn your project’s commands, conventions and rules. Done well, it saves you repeating yourself; done badly, it wastes context and gets ignored. These practices come straight from Anthropic’s documentation.

Generate a CLAUDE.md →All guides

Where CLAUDE.md files live

Claude Code loads CLAUDE.md and CLAUDE.local.md from the working directory and every directory above it at launch, concatenating them (root first, so closer files are read last). Files in subdirectories load on demand when Claude reads or edits files there. Run /context and look under “Memory files” to see what actually loaded.

Start with /init, then edit

Running /init makes Claude analyse the codebase and draft a CLAUDE.md with build commands, test instructions and conventions it discovers; if a file exists, it suggests improvements instead of overwriting. The draft is a starting point. Your job is to add what Claude can’t discover from the code, and delete what it can.

Seven practices that make it work

1. Keep it under about 200 lines. Anthropic’s guidance is to target under 200 lines per file: longer files consume more context and reduce adherence.
2. Write verifiable instructions. “Use 2-space indentation” beats “format code properly”; “Run npm test before committing” beats “test your changes”; “API handlers live in src/api/handlers/” beats “keep files organised”.
3. Structure with headings and bullets. Grouped instructions are easier to follow than dense paragraphs.
4. Remove contradictions. If two instructions conflict, Claude may pick one arbitrarily. Review nested files and rules periodically; /doctor prompt-audit (v2.1.283+) can flag outdated or conflicting instructions.
5. Add a line when a mistake repeats. The docs suggest adding to CLAUDE.md when Claude makes the same mistake twice, when code review catches something it should have known, or when you type the same correction you typed last session.
6. Leave notes for humans in HTML comments. Block-level <!-- … --> comments are stripped before the content reaches Claude, so they cost no tokens.
7. Know what CLAUDE.md is not. It is context, not enforced configuration. If something must happen every time (formatting after each edit, blocking a command), use a hook or permission rule instead.

A lean example

# CLAUDE.md

@AGENTS.md

## Claude Code specifics
- Use plan mode for changes under `src/billing/`.
- After editing TypeScript, run `pnpm typecheck` and fix errors before replying.
- Prefer editing existing components in `src/ui/` over creating new ones.

<!-- Maintainers: keep this file under 60 lines. Shared rules live in AGENTS.md. -->

Imports, local files and rules

• @imports: write @path/to/file anywhere to pull a file in at launch (relative to the importing file, up to four hops deep). Imports organise a long file but do not reduce its context cost, because imported files load too.
• CLAUDE.local.md: personal, per-project notes (sandbox URLs, test data). Add it to .gitignore.
• .claude/rules/: split large instruction sets into topic files. A rule with paths: front matter, such as "src/api/**/*.ts", only loads when Claude works on matching files — this is the real way to save context.
• Skills: if a section has grown into a multi-step procedure, move it into a skill, whose body loads only when used. See how to write a SKILL.md.

For teams and large repositories

• Organisations can deploy one managed CLAUDE.md to every machine (via MDM, Group Policy or Ansible), or put the text directly in managed-settings.json under the claudeMd key. Managed files cannot be excluded by individual settings.
• In a monorepo where other teams’ CLAUDE.md files get picked up, list them in claudeMdExcludes (glob patterns against absolute paths), for example in .claude/settings.local.json.
• Use settings for enforcement (blocking tools, sandboxing) and CLAUDE.md for behavioural guidance; Anthropic draws exactly this line.

CLAUDE.md and AGENTS.md together

By default Claude Code reads AGENTS.md only when there is no CLAUDE.md (or CLAUDE.local.md) in the working directory or above. If your team already maintains an AGENTS.md for other tools, either rely on that, or create a CLAUDE.md that starts with @AGENTS.md and adds Claude-specific lines below. A symlink (ln -s AGENTS.md CLAUDE.md) also works, but Anthropic recommends the import if anyone on the team uses Windows, where symlinks need extra setup. Note that adding a CLAUDE.local.md stops AGENTS.md from loading under the default setting.

CLAUDE.md versus auto memory

Claude Code has a second, complementary memory system. Auto memory is written by Claude itself from your corrections and preferences, stored per repository in ~/.claude/projects/<project>/memory/ with a MEMORY.md index; the first 200 lines or 25 KB of that index load each session. Use CLAUDE.md for rules you want the whole team to share; let auto memory capture personal working preferences. Open /memory to browse, edit or switch auto memory off.

What to leave out

Anthropic’s /doctor checkup proposes trimming checked-in CLAUDE.md content that Claude can derive from the codebase — directory layouts, dependency lists, architecture overviews — while keeping pitfalls, rationale and conventions that differ from tool defaults. That is a good editorial rule for humans too:

• Keep: “Integration tests need a local Redis on port 6380”, “Never import from legacy/ in new code — it is being removed”, “We use tabs because the generator emits them”.
• Cut: a copy of package.json scripts, a tree of every folder, a paragraph explaining what React is.

Troubleshooting

• Not followed? Run /context to confirm it loaded, make the instruction more specific, and look for conflicts across files.
• Lost after /compact? The project-root CLAUDE.md is re-read from disk after compaction; instructions given only in chat are not — put them in the file.
• Too large? Move part-of-the-codebase rules into path-scoped rules, and cut anything Claude can derive from the code.

The generator can produce a CLAUDE.md skeleton from your project details; trim it to what matters.

Sources

Vendor features and prices were checked against these official pages on 2026-10-18. Products change; if something here no longer matches, the official page is right.

• Claude Code — How Claude remembers your project
  https://code.claude.com/docs/en/memory
• Claude Code — Extend Claude with skills
  https://code.claude.com/docs/en/skills

Related guides

• How to Write a SKILL.md: Agent Skills Format, Fields and Examples
• What Is MCP (Model Context Protocol)? A Beginner’s Explainer
• How to Set Up MCP Servers in Claude Desktop, Cursor and VS Code