CLAUDE.md examples that make a repository easier to work in

Write the context a new contributor would need

It should not become a second copy of the documentation, a list of generic programming advice or a collection of every instruction you have ever given an assistant. Those additions make the important constraints harder to find. Start with the information you repeatedly explain during real development work.

The examples below are original templates for a fictional Python service. Replace the paths and commands with ones that exist in your project. An inaccurate instruction file is worse than a short one because it gives the assistant a confident route to the wrong place.

A compact Python backend example

Imagine a repository with an API layer, a domain layer and background workers. The instructions should describe those boundaries in terms of changes the assistant is likely to make. A short architecture note is more useful than a diagram of modules that no longer exist.

Use the following lines as the substance of a project file. They can be copied into CLAUDE.md as headings and bullet points. Keep the formatting simple so the purpose, commands and boundaries are easy to find.

• Purpose: this service classifies support requests and prepares drafts for human review. It does not send customer replies automatically.
• Layout: app/api handles HTTP; app/domain contains business rules; app/workers handles background processing. Keep decisions about eligibility in app/domain.
• Setup: install the development dependencies with the project's documented environment manager. If setup fails, report the error rather than inventing a replacement environment.
• Verification: run python -m pytest tests/domain for a domain-only change. Run the relevant integration suite when changing API or worker behaviour.
• Boundaries: use synthetic fixtures in tests. Do not copy production customer content into fixtures, examples or logs.
• External failures: keep the request available for manual handling when the model or queue is unavailable.
• Review: describe the files changed, the checks actually run and any assumptions that remain unverified.

Turn vague advice into repository decisions

“Write clean code” does not tell an assistant which of two plausible designs belongs in your project. “Keep request handlers thin; put eligibility decisions in app/domain” gives it a concrete boundary. “Be careful with tests” is similarly weaker than explaining which test suite exercises the behaviour being changed.

Add examples only where they prevent a recurring mistake. If your service uses a shared error type, name it and point to its existing implementation. If migrations follow a particular naming rule, state that rule and the directory. Avoid pasting a complete implementation into the instruction file when the source file is the authority.

Commands should be verified by a developer when the file is created. If a command needs a local database or secrets, say so. An assistant should not treat a missing environment variable as permission to connect to a production service or skip the check without explanation.

Keep shared instructions small and specific rules local

Anthropic documents several instruction locations and ways to scope guidance, including project files and path-specific rules. Its current guidance recommends keeping CLAUDE.md concise, targeting fewer than 200 lines. That is a recommendation for clarity, not a guarantee that every instruction will be followed.

Keep genuinely shared information in the project-level file: purpose, layout, common commands and boundaries. Put specialised frontend, migration or deployment guidance close to the relevant work using the documented scoping mechanism. This reduces the chance that a rule for one directory distracts from a task somewhere else.

Be careful when reading advice about memory limits. Anthropic describes automatic memory and CLAUDE.md separately. A limit discussed for the initial part of a memory file should not be copied into a claim that every CLAUDE.md is truncated in the same way. Check the current documentation for the feature you are using.

Instructions do not replace permissions

Writing “never deploy without approval” is useful context. It is not the same as configuring which commands and actions the tool may execute. Claude Code has a separate permission system. Use it to control capabilities, and use your repository instructions to explain the expected workflow.

For a client repository, begin with the least access needed for the task. Keep production credentials out of the working environment unless that work genuinely requires them. Review how shell commands, file access and external connections are permitted. A reassuring sentence in a markdown file cannot enforce an infrastructure boundary.

This distinction also makes debugging easier. If an instruction is ignored, improve the instruction or task context. If an action must be impossible without approval, configure an enforceable control. Treating those as separate jobs prevents a large instruction file from becoming a false security policy.

Test the file with three normal tasks

Give the assistant a domain change, a test-only change and a task whose environment is intentionally incomplete. Check whether it finds the right layer, runs the right available checks and reports the missing dependency accurately. Inspect the diff for unnecessary edits.

Record the instructions that helped and the mistakes that repeated. Add one specific rule for a recurring repository mistake, then repeat the relevant task. Do not add a rule for every unexpected answer. Sometimes the task brief was ambiguous, or the repository itself needs clearer boundaries.

Review CLAUDE.md when scripts, directories or architecture change. Assign it the same ownership as other contributor documentation. The best template is not the longest one: it is the smallest accurate guide that still helps a new contributor work safely in your codebase.