A useful CLAUDE.md tells Claude Code how your project works: what it is, where the important parts live, which commands are actually supported, and which decisions require a human review. You can write one from scratch or improve an existing file, but the source of each instruction should be a current project record or an approved team rule. A plausible-looking command invented by a template is still the wrong command.

This guide takes you from those records to a reviewed, complete project manual. The final check uses a new Claude Code process and one question whose answer you can verify independently. BIG CHANGE has checked Anthropic's documentation for this procedure; we have not run it in a reader's repository or measured its cost or success rate.

The big change

  • What changed: Claude Code can load project instructions from CLAUDE.md alongside its session context. A team can put enduring, repository-specific guidance in one reviewed file instead of repeating it in each prompt. The file supplies guidance; tool permissions still control access.
  • Why it matters: A maintainer who checks commands and boundaries against the real project can give collaborators a common starting point. A stale build command or contradictory rule can instead send work in the wrong direction, so the manual needs the same ownership and review as other project files.
  • What to watch: The useful acceptance test is the saved file plus a fresh session that lists the intended memory path and answers one bounded project question correctly. That observation supports a local check, not a guarantee that every later response will follow the file.

1. Gather the facts before writing

Use a repository you own or are authorized to maintain. Confirm that your chosen Claude Code account or provider is allowed to process the project material you plan to show it. Anthropic's data-use documentation distinguishes consumer and commercial arrangements; a file stored on your computer does not make the model's processing local. Check the account route and permissions before asking Claude to read sensitive files. Keep credentials and material that should not enter the session out of the manual and prompts.

From the actual project root, collect the current README, build or package manifest, test configuration, architecture decisions, coding conventions, security rules, and release instructions. Name the person or team that can approve changes to them. For each command you intend to include, identify the file or owner that establishes it. If records disagree, settle that discrepancy with the owner first. Do not fill the gap with a familiar command from another project.

Inventory instructions already in force. Anthropic's memory guide documents a project file at CLAUDE.md or .claude/CLAUDE.md, ancestor instructions, personal CLAUDE.local.md, imports, .claude/rules/, and nested files that load when relevant. The applicable files accumulate, so an older rule can conflict with a new one. Check the effective project-instructions setting and any managed policy. Decide whether a rule belongs to the shared project file, a personal file, or a narrower path-scoped rule. Keep one-off task directions out of the shared manual.

If the chosen file already exists, preserve its exact bytes before editing and check whether someone else is changing it. For a new file, record that the prior state was absent. Use the repository's normal review process for a shared instruction file.

2. Compose the whole manual

Write a compact file in the chosen project location. This is a section plan, not a file to paste unchanged: include only sections supported by your project, replace every prompt below with verified facts, and write the actual commands from your manifest. A complete manual should cover the project's purpose and layout, supported commands, enduring conventions, boundaries, review path, and pitfalls where those facts exist.

Markdown
# [Actual project name and purpose]

## Project layout
[Where the relevant components live and how they fit together, from current project records.]

## Commands
[Exact build, test, lint or other commands from this project's current manifests.]
[State the directory and conditions for each command.]

## Conventions
[Approved naming, code or content rules that recur across tasks.]

## Boundaries
[Files or decisions requiring owner review; refer to enforceable permissions separately.]

## Review
[Actual checks and approval path before a change is accepted.]

## Known pitfalls
[Specific recurring mistakes documented by the project, if any.]

For every line, ask: Who or what says this is current? Give a command its exact working directory and any required setup. State boundaries as concrete actions, such as which owner reviews a particular change. Do not put a password, token, private client text, or unapproved URL into the file. Anthropic advises keeping CLAUDE.md concise, with fewer than 200 lines as a useful target rather than a parser limit. Cut repeated prose and move narrow instructions to the appropriate scoped file; keep necessary project facts even when they take more room.

You may use /init as an optional starting point. Anthropic documents that it can create a file or suggest improvements to an existing one. Preserve the prior version and inspect any proposed or written text against your fact sheet before accepting it. Anthropic also documents an interactive proposal flow with CLAUDE_CODE_NEW_INIT=1; check your installed version and the prompt before allowing a write. Neither route validates a guessed command or authorizes unrelated generated files. Manual composition works without /init.

3. Review and save the exact file

Read the entire proposed manual, including imports it refers to. Match every command and path to the current project. Compare rules with ancestor, nested and .claude/rules/ instructions for contradictions. Check the full text and diff for secrets, private material, stale names and instructions that belong to one person's preferences. Anthropic documents /doctor prompt-audit in supported versions as an optional aid for stale or conflicting instructions; inspect any proposed edit yourself. A clean report does not replace source and owner review.

Inspect the saved version at the exact path you chose. For a tracked file, use your normal version-control diff and status view. For a newly created, untracked file, open the whole saved file: ordinary git diff does not display its content. Record the path and resulting version or hash, plus where the exact prior copy can be restored. If a write had an uncertain result, or another editor changed the file, reread the bytes before doing anything else. Restore only this approved file from its preserved copy if the change must be reversed; a repository-wide reset can erase unrelated work.

4. Check it in a genuinely new Claude Code process

Close the process used to write or review the file. From the recorded project root, start a new process with plain claude. Anthropic's CLI reference distinguishes that from claude -c and claude -r, which continue or resume a conversation. In the new process, check the working directory and run /context. Its Memory files list should show the intended instruction path when that file is in scope. A nested file may load only after an authorized relevant file is accessed.

Ask one narrow, nonsensitive question governed by a distinctive rule in your new manual, without supplying its answer. For example, ask which test command applies to an actual approved part of this project. Compare the response with the source manifest and the saved manual; if you authorize Claude to run a command, separately inspect its permission request and actual output. Record the question, response, loaded path and independent source check. A matching answer does not reveal which internal context caused it, and a listed file does not prove future obedience or restrict tool access. Enforce access with Claude Code permissions and the project's own controls.

If the path is missing, check where the process started, the chosen file path, project-instruction setting, imports, exclusions, trust and installed version. If the answer is wrong, inspect the saved bytes and competing rules, correct the specific ambiguity with the owner, and repeat the check in another new process. Hold acceptance while a source fact, permission or concurrent edit is unresolved. The result to approve is the full saved manual and its review record, with a successful source-checked fresh-session check or a precise reason it remains on hold.

Claude Code usage depends on the account, provider and work performed. Check Anthropic's cost guide and your own billing route before using /init, audits or test sessions. This guide supplies no fixed charge or measured saving.

Sources & further reading