Based on Anthropic’s official docs, checked November 11, 2026

CLAUDE.md examples: instructions your team can actually use

A useful CLAUDE.md tells Claude Code something it cannot reliably infer from the repository: the command your team actually uses to validate a change, the architecture boundary reviewers enforce, or the generated directory it should leave alone. It is not a place to paste an entire handbook in the hope that more context guarantees better work. This guide follows Anthropic’s memory documentation, checked November 11, 2026, and gives copy-adaptable templates plus a loading check. The examples are editorial templates, not vendor defaults or a tested project configuration. For the broader distinction between instruction formats, use the existing AGENTS.md, CLAUDE.md and Cursor rules comparison. For Claude-specific navigation, start at the Claude Code rules hub.

1. 1. Put the file where Claude will load it

   Anthropic documents a project file at either ./CLAUDE.md or ./.claude/CLAUDE.md. Shared project instructions belong in version control. Personal preferences should not silently become policy for everyone else. A CLAUDE.local.md can hold personal, project-specific instructions; add it to your ignore rules rather than committing private notes. Do not put credentials in either file. Instructions above the working directory load at launch; files in subdirectories load on demand. A nested file is useful for a specialized area, but it is not a substitute for a root instruction that should apply everywhere.

   touch CLAUDE.md
   # or: mkdir -p .claude && touch .claude/CLAUDE.md
   echo 'CLAUDE.local.md' >> .gitignore

2. 2. Start with a small project contract

   Replace every bracketed item with a fact checked against your project. These are placeholders, not commands to run as written. The value is specificity: “Write good code” does not tell an agent how your team reviews a patch. “State which checks ran” produces an observable result. Do not copy another project’s scripts into your instructions without checking that they exist.

   # Project instructions
   
   ## What this project does
   - [One sentence describing the product and its main users.]
   - [Name the principal application entry points.]
   
   ## Validation
   - Install dependencies with: [verified install command].
   - Run the relevant tests with: [verified test command].
   - Before reporting completion, state which checks ran and their results.
   - If a check cannot run, explain the blocker; do not claim it passed.
   
   ## Change boundaries
   - Keep each change focused on the requested behavior.
   - Do not edit generated output; change its documented source instead.
   - Ask before adding a dependency or changing a public API.
   - Do not deploy or contact outside services as part of local validation.

3. 3. Write review criteria instead of vague style advice

   A review-oriented file can tell Claude what evidence to bring back rather than prescribing every implementation detail. Do not leave the architecture placeholders in a live file. Ask a maintainer to confirm the real boundary and remove statements that merely repeat obvious directory names. A short, accurate contract is easier to review than a long, aspirational document.

   ## Review expectations
   - Explain how the change affects the main success and failure paths.
   - Add or update a regression test for a reproduced bug where practical.
   - Identify behavior changes separately from formatting changes.
   - If a test depends on a network service, call that out explicitly.
   - Do not describe a simulated or mocked check as a production test.
   
   ## Architecture
   - [Name the module that owns external API calls.]
   - [Name the boundary where input validation belongs.]
   - Reuse the existing boundary rather than adding a second path.

4. 4. Add scoped rules for a larger repository

   Anthropic supports .claude/rules/ for topic-specific instructions, including rules scoped with paths frontmatter. Use that organization when one area genuinely needs different guidance. The path below is an example for a hypothetical TypeScript repository. Match it to real files before adopting the rule. Do not assume a path-scoped rule governs unrelated work. Put universally applicable requirements in the root instructions, and keep specialized guidance close to the area that needs it. Anthropic’s memory docs also recommend targeting under 200 lines per CLAUDE.md file; longer files consume more context and can reduce adherence. Imports help you organize a long file but do not reduce its context cost, because imported files load with the CLAUDE.md that imports them.

   ---
   paths:
     - "src/api/**/*.ts"
   ---
   # API change checks
   - Preserve documented response shapes unless the task changes them.
   - Include a failing-input test when modifying validation behavior.
   - Explain any compatibility effect in the final change summary.

5. 5. Verify the file actually loaded

   In a Claude Code session, Anthropic documents /context all as a way to inspect loaded memory files. Check the list under Memory files before concluding that the model ignored your file. For a nested instruction, make sure the relevant area has actually been read. You can also run /init to generate a starting CLAUDE.md from the codebase, or /doctor prompt-audit (Claude Code v2.1.283 or later) to have Claude report outdated, missing or conflicting instructions without changing files until you ask it to apply edits. Then use a small acceptance test: ask Claude to describe the validation command and change boundaries without making edits, compare the answer with the file, and try one representative task. This is an editorial testing method, not a guarantee of obedience. If instructions conflict, simplify them.

   /context all
   # optional, v2.1.283 or later:
   /doctor prompt-audit

CLAUDE.md is context, not an enforcement boundary

Anthropic describes CLAUDE.md as persistent instructions written by people. Auto memory is a separate system of notes Claude writes itself. Both provide context, not an enforcement boundary. If an action must be blocked regardless of the model’s interpretation, use a PreToolUse hook or other enforced settings rather than relying on wording in the file. Keep that distinction in mind when writing rules about production, secrets or destructive commands.

Write instructions that are concrete enough to verify. Anthropic’s examples prefer “Use 2-space indentation” over “Format code properly,” and “Run npm test before committing” over “Test your changes.” If two instructions contradict each other, Claude may pick one arbitrarily, so review root files, nested files and .claude/rules/ when build scripts or architecture change, not only after a failure.

Import stable reference material deliberately

The memory documentation supports @path/to/file imports. Relative paths resolve relative to the file containing the import, not the current working directory. Imports inside Markdown code spans or fenced code blocks are not expanded. For a project with an actual docs/testing.md, a live instruction could include an import of that file. Do not add the import merely because a template mentions it. First verify the file exists, remains maintained and contains only material appropriate for the agent’s context.

An imported handbook still consumes context. Importing everything can make the most important requirements harder to find. Prefer a concise root contract and a few deliberate references over a directory-sized instruction bundle. The first time Claude Code encounters an import that resolves outside the working directory, it shows an approval dialog; if you decline, those external imports stay disabled.

AGENTS.md, /init and what not to copy

If the repository already has an AGENTS.md and no CLAUDE.md or CLAUDE.local.md on the project path, Claude Code v2.1.277 or later can read AGENTS.md as the project instructions. A CLAUDE.md or CLAUDE.local.md in the working directory or above it causes Claude to read the CLAUDE.md files instead, unless you change the Project instructions setting. Run /init to generate a starting CLAUDE.md; if one already exists, /init suggests improvements rather than overwriting it.

Do not store tokens, production passwords, private customer records or transient debug output in CLAUDE.md. Do not turn a vendor benchmark into a promise about your team’s results. Do not label an instruction as a security control merely because it says “never.” For connected tools, keep this file about when and why a tool is appropriate, not as a secret-bearing config store. Use the MCP config generator as a starting aid and check its output against your client documentation.

Tips

• Write down the correction you keep repeating, not a complete style guide.
• Keep the root CLAUDE.md short; move area-specific guidance into path-scoped rules under .claude/rules/.
• Run /context all before rewriting a file that may not have loaded.
• Commit project instructions and gitignore CLAUDE.local.md so personal notes stay personal.
• Use hooks or managed settings when a rule must hold even if the model ignores the file.

Next steps

Sources

• https://code.claude.com/docs/en/memory · checked 2026-11-11