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

Claude Code can inspect your code, but some working rules are invisible there: why test environments must not email customers, which directories are generated, or which check confirms a fix. If you explain these conditions in every new task, put them in CLAUDE.md.

CLAUDE.md is a Markdown file of persistent instructions for Claude Code. Use it for project commands, important constraints and verification criteria. Start with one file at the repository root. Anthropic's documentation explains locations and loading.

• Anthropic's documentation

The example below is for a small web project. Adapt paths and commands: it is an instructional template, not a configuration tested against your application.

Which rules belong in the file?

Imagine adding a “Company” field to an enquiry form. Knowing the project uses TypeScript is not enough. The agent needs to find the form, understand where the data goes and test submission without contacting the real sales team.

A useful rule supports a concrete decision:

The right column is not universal. Its value comes from matching the project. If TextField does not exist, change the rule or the instruction itself becomes a source of errors.

Review your recent feedback to the agent. Which comments will matter again? A requirement about one button belongs in the current task. A convention for all forms belongs in project rules.

Where to create CLAUDE.md

Put shared team rules in `CLAUDE.md` at the project root. Personal general preferences can live in `~/.claude/CLAUDE.md`. Files in nested directories are loaded when Claude reads files there. Project-context guide.

• Project-context guide

A simple starting structure:

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

If a file already exists, read it first. Duplicate rule sets are harder to maintain: a test command may get updated in one and forgotten in another.

Check the exact filename too. An editor that hides extensions can leave you with `CLAUDE.md.txt`.

Generate an initial draft

Run `/init` in an open Claude Code session. It helps prepare an initial CLAUDE.md from the project. Review the result: commands must exist, paths must be current and constraints must match your workflow. See Anthropic's guidance.

• Anthropic's guidance

To see a proposal before changing files, 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.

This produces text you can compare with the repository. Do not accept it simply because it looks polished. For example, `npm test` is useless when that script does not exist.

A CLAUDE.md example for a web project

This original learning template describes a hypothetical service website using npm, TypeScript, translation dictionaries and separately configured form tests. Command and directory names illustrate the structure; replace them with real ones.

# 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 ensure the verification rules are feasible. An instruction cannot create a missing test destination: prepare the test environment or document an available alternative.

You do not need every section. A library may need public API and compatibility rules. An article website may need content structure, metadata and internal-link checks.

Check whether the instructions help

Separate two questions: did the file load, and did the agent's behavior change?

Run `/context` and inspect Memory files. Then assign a small task with a clear outcome. Anthropic explicitly recommends this loading check. CLAUDE.md setup.

• CLAUDE.md setup

For the sample site:

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.

Review three points:

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 something fails, investigate why. The rule may be ambiguous; there may be another similar handler; the tests may miss the scenario. Add a prohibition only after understanding the failure.

A small log can track task, expected action, actual result and rule revision. This is a proposed evaluation method, not an experiment report. One successful run does not prove future compliance.

If Claude ignores CLAUDE.md

First confirm the intended file loaded. Then find instructions on the same topic elsewhere. Discovered CLAUDE.md files are combined in context; do not assume a nested file automatically cancels all earlier rules. Loading behavior.

• Loading behavior

Check wording next. “Test thoroughly” leaves many choices. “Run this command after changing the enquiry handler” specifies an observable action.

The instruction may also be stale. Review rules when tests move or the directory layout changes. It is difficult to follow documentation for a project that no longer exists.

Finally, remove repetition and generic wishes. Anthropic recommends concise, project-specific instructions and ongoing revision. No universal file length guarantees obedience. Content recommendations.

• Content recommendations

When to use rules and Skills

As the project grows, separate instructions by purpose. `.claude/rules/` supports topic-specific rules, including path-related ones. Skills suit repeatable procedures needed in particular situations. Project rules, Claude Code Skills.

• Project rules
• Claude Code Skills

This simplifies maintenance: changing the release process does not require editing every workflow description. Splitting files does not make rules more precise by itself; resolve actual contradictions.

Why CLAUDE.md is not access control

“Do not email real customers” describes a useful workflow rule, but technical access restrictions are configured separately. Claude Code has `/permissions` and allow, ask and deny rules; CLAUDE.md does not change them. Permissions documentation.

• Permissions documentation

For the form example, configure the test environment to route submissions to a test destination. The correct recipient then does not depend solely on interpreting a paragraph.