CLAUDE.md: set up Claude Code instructions with a ready-to-adapt example

Claude Code can read your code, but some of the rules you work by are not written there. Why the test environment must never email customers. Which directories are generated. Which check confirms that a fix worked. If you find yourself explaining these in every new task, put them in CLAUDE.md.

CLAUDE.md is a Markdown file of persistent instructions for Claude Code. It holds project commands, important constraints and the criteria for checking work. One file at the repository root is enough to start with. Anthropic's documentation explains where these files can live and how they load.

• Anthropic's documentation

The example below is a small web project. Take it as a starting point and replace its paths and commands with yours. The template shows what to include; nobody has tested it against your application.

Which rules belong in the file?

Imagine adding a “Company” field to an enquiry form. Knowing that the project uses TypeScript will not get the agent far. It has to find the form, work out where the data goes, and test submission without the enquiry landing with the real sales team.

A useful rule helps with a concrete decision:

The right-hand column will not fit every repository. It is useful because it matches this project. If TextField does not exist in yours, rewrite the rule, or the instruction itself becomes a source of errors.

Look back at the feedback you have given the agent recently. Which comments will matter again? A requirement about one button belongs in the current task. A convention for all forms belongs in the project rules.

Where to create CLAUDE.md

Put the team's shared rules in `CLAUDE.md` at the project root. Personal preferences that apply across projects can live in `~/.claude/CLAUDE.md`. Files in nested directories load when Claude reads files in those directories.

• Project-context guide

A simple starting structure:

project/
├── CLAUDE.md
├── README.md
├── package.json
└── src/

If the file already exists, read it first. Two sets of similar rules are harder to maintain: a test command gets updated in one and forgotten in the other.

Check the exact filename as well. An editor that hides extensions can leave you with `CLAUDE.md.txt` without your noticing.

Generate an initial draft

Run `/init` in an open Claude Code session. It drafts an initial CLAUDE.md from the project. Review what it produces: the commands must exist, the paths must be current, and the constraints must match how you work. See Anthropic's guidance.

• Anthropic's guidance

To see a proposal before any file changes, ask:

Inspect README, package.json scripts and the directory structure. Propose CLAUDE.md for this project. Include startup and verification commands, important change boundaries and details that cannot be confidently inferred from code. List unknowns as questions. Do not create or modify files yet.

You get a text you can compare with the repository. Do not accept it because it looks polished. `npm test` is useless if the project has no such script.

A CLAUDE.md example for a web project

We wrote the template below for this guide. It describes a hypothetical service website that uses npm, TypeScript, translation dictionaries and separately configured form tests. Replace the command and directory names with the ones your project actually uses.

# Project

Service website with an enquiry form. Interface in Russian and English.
Main user journey: choose a service and submit an enquiry.

## Where to find code
- src/components/forms/ — fields and forms.
- src/server/leads/ — enquiry processing.
- src/i18n/ — interface dictionaries.
- tests/leads/ — enquiry-processing tests.

## Commands
- npm run dev — start locally.
- npm run typecheck — check types.
- npm run test:leads — test enquiry processing.
- npm run build — build the application.

## Change rules
- Reuse existing form components and error handlers.
- Keep interface text in dictionaries for both locales.
- Do not add dependencies when existing project tools suffice.
- Preserve other people's unfinished changes.

## Verification
- For enquiry changes, check required fields, invalid email and
  successful submission to a test destination.
- Run npm run typecheck for TypeScript changes.
- Run npm run test:leads for enquiry-processing changes.
- Check the affected screen in a browser for interface changes.
- If a check is unavailable, report why and what remains uncertain.

## Environment
- Use only the test destination for submission checks.
- Required variable names are documented in .env.example.
- Do not put secret values in code, reports or documentation.

## Report
Briefly describe the change, checks performed and remaining problems.
Separate test results from assumptions about application behavior.

Check the commands first. Then make sure the verification rules can actually be carried out. An instruction cannot conjure up a test destination that does not exist, so prepare the test environment or document an alternative that is available.

You do not need every section. A library may need rules about its public API and compatibility. An article website may need rules about content structure, metadata and internal links.

Check whether the instructions help

There are two separate questions here: did the file load, and did the agent's behavior change?

Run `/context` and look for your file under Memory files. Then assign a small task with a clear outcome. Anthropic explicitly recommends this way of checking that the file loaded.

• CLAUDE.md setup

For the sample site, something like this:

Add an optional “Company” field to the enquiry form. Before editing, locate the existing field component and submission handler. Afterward, check submission with and without a company. List only checks you actually performed.

Then look at three things:

1. Did the agent use the intended component and translation dictionaries?
2. Does submission still work without the optional field?
3. Can the reported checks be verified against tool output?

If any of them fails, find out why. The rule may be ambiguous. There may be a second, similar handler in the code. The tests may not cover the scenario. Add another prohibition only once you understand what went wrong.

Keep a short log: the task, what you expected the agent to do, what it did, and which rule you revised. It lets you compare later attempts. This is a way of assessing instructions that we suggest, and we are not reporting an experiment here. One successful run does not prove a rule will always be followed.

If Claude ignores CLAUDE.md

First confirm that the intended file loaded. Then look for instructions on the same topic elsewhere in the project. According to the documentation, every CLAUDE.md that Claude discovers is combined in context, so a nested file does not automatically cancel the rules set above it.

• Loading behavior

Next, look at the wording. “Test thoroughly” leaves the agent too many choices. “Run this command after changing the enquiry handler” names an action whose result you can see.

The instruction may simply be stale. When tests move or the directory layout changes, review the rules that refer to them. An agent cannot do much with documentation for a project that no longer exists.

Finally, cut repetition and generic wishes. Anthropic recommends concise, project-specific instructions that you keep revising. No file length guarantees obedience.

• Content recommendations

When to use rules and Skills

As the project grows, split instructions by purpose. `.claude/rules/` holds topic-specific rules, including ones tied to particular paths. Skills suit repeatable procedures that are only needed in certain situations.

• Project rules
• Claude Code Skills

This makes the instructions easier to maintain: when the release process changes, you do not have to edit every workflow description. Splitting files does not make the rules more precise by itself, though. Contradictions still have to be resolved in substance.

Why CLAUDE.md is not access control

“Do not email real customers” is a useful description of how you work. Technical access restrictions are configured separately. Claude Code has `/permissions` and allow, ask and deny rules, and nothing you write in CLAUDE.md changes them.

• Permissions documentation

For the form example, set up the test environment so that submissions physically go to a test destination. Then the right recipient no longer depends on how the agent reads a paragraph.