How do I write a good CLAUDE.md so my coding agent follows my rules?

Keep the file short. Put in only what the agent cannot guess from your code: commands, where things are, and a few concrete rules with the reason for each. Then move every rule that must never break out of the file and into a real check: a hook, a permission, a test or a linter.

What a CLAUDE.md file is, and the same file in other tools

CLAUDE.md is a plain Markdown file in your project. Claude Code reads it at the start of every session, before your first message. Other agents have the same idea under another name. AGENTS.md is the shared one: OpenAI released it in August 2025, and by December 2025 more than 60,000 open-source projects used it.

The advice below works for all of them.

Why does my coding agent ignore my rules?

The agents do read the files. A team at ETH Zurich tested them on real tasks in 2026 and found that agents follow the instructions well. When a rule is missed, the cause is usually the rule itself, or what happens to it on the way.

The file is too long. In the IFScale test (July 2025, 20 models), the best ones stayed near perfect up to about 150 instructions and fell to about 68% at 500. They also favoured the instructions that came first. Anthropic’s advice is under 200 lines per file, because “longer files consume more context and reduce adherence”.

The rule is vague. GitHub read over 2,500 agent files in November 2025: “Most agent files fail because they’re too vague”. “Be careful with the database” gives the agent nothing to do.

Two rules fight. If your user file says one thing and the project file says another, Claude “may pick one arbitrarily”.

The rule is out of date. The file says npm test and the repo moved to pnpm last month. The agent trusts the file. A June 2026 study of 100 popular repos found style rules a linter should own in 62% of AGENTS.md files, and bloat in 42%.

It was said in chat, not written in the file. In Chroma’s 2025 tests of 18 models, answers got worse as the input grew. When Claude Code compacts a long session (shortens it into a summary), it reads the root CLAUDE.md again from disk. A rule you only typed in chat may not survive the summary.

It is a hope, not a check. The file reaches the model as a message, and Anthropic says “there’s no guarantee of strict compliance”. In August 2026 a study of 481 public CLAUDE.md files found that only about 4% to 16% of their security rules had a built-in control that could enforce them.

What to put in a CLAUDE.md, and what to leave out

Anthropic’s test for every line: “Would removing this cause Claude to make mistakes? If not, cut it”.

The ETH study found that repository overviews did not help. The files paid off for “non-standard coding practices”, the things a new person would get wrong. They also raised cost by over 20% on average, because agents read and test more when a file asks them to.

Real files often miss the unusual parts. In a study of 2,303 agent files, 75.9% covered testing, but only 14.8% said anything about security.

How to write one rule the agent will follow

One rule is one idea, short enough to check, with the reason after it. Anthropic’s prompting guide says that the reason helps, because the model can “generalize from the explanation”.

Capital letters are not a fix. Anthropic now tells people to “dial back any aggressive language”, because newer models follow plain instructions closely. If one line keeps getting skipped, add “IMPORTANT” to that line alone: “If you emphasize many lines, none of them stands out”.

One more line from GitHub’s study: “One real code snippet showing your style beats three paragraphs describing it”.

Use layers: your file, the project file, folder rules

Personal habits go in your user file. Mine is 33 lines, mostly about how agents should write to me, and it opens with a “Why this matters” line. Team rules go in the project file, in git, so everyone fixes the same file.

Rules that apply to one part of the code go lower. In Claude Code, a file in .claude/rules/ with a paths: line loads only when the agent opens a matching file. Cursor uses globs for the same thing, and Copilot uses applyTo.

Watch the imports. A line like @docs/testing.md loads that file at launch, so it costs as much as pasting it in. For long guides, write the path as plain text (“Testing guide: docs/testing.md”). The agent opens it only when the task needs it, the same idea as in my article on RAG in daily coding.

Turn the rules that must never break into checks

Anthropic’s docs say it directly: “An instruction like ‘never edit .env’ in CLAUDE.md or a skill is a request, not a guarantee. A PreToolUse hook that blocks the edit is enforcement”.

A hook is a small script that Claude Code runs on an event, such as before a tool runs. It can block the action and tell the agent why. Permissions are enforced “by Claude Code, not by the model”. In Claude Code’s .claude/settings.json, one deny list keeps the agent away from secrets and pushes:

{
  "permissions": {
    "deny": ["Read(./.env)", "Read(./secrets/**)", "Bash(git push *)"]
  }
}

The docs warn that a push written another way, such as git -C . push, is not matched, so CI still matters. Codex does the same job with its approval and sandbox modes. Tests, linters and CI work for every tool. Boris Cherny, who created Claude Code, said in January 2026 that giving Claude a way to verify its work will “2-3x the quality of the final result” (quoted by paddo.dev). How to check AI-written code is the subject of my article on checking AI code quality.

My test for each rule: if breaking it once is cheap, it stays as words. If breaking it once does real harm (a leaked key, a broken production database), it becomes a check, and the file keeps one line that says the check exists. Setting up rules, hooks and checks for a team’s agents is part of what my team does; here is how we work.

Keep the file alive

Mitchell Hashimoto calls this “harness engineering”: when an agent makes a mistake, “engineer a solution such that the agent never makes that mistake again.” About his AGENTS.md he wrote: “Each line in that file is based on a bad agent behavior, and it almost completely resolved them all” (February 2026). OpenAI’s Codex guide gives the same trigger: when the agent “makes the same mistake twice”, update the file.

At Anthropic, each team keeps its file in git to note mistakes. In January 2026 the Claude Code team’s file was about 2,500 tokens. In one study, CLAUDE.md files changed about once a day, with a median of 57 words added per change and fewer than 15 deleted. That is how a file reaches 400 lines. Prune when you add.

A sample CLAUDE.md you can copy

This one is for an invoice API. Change every line to fit your project.

# CLAUDE.md
Invoice API for small builders. Python 3.12, FastAPI, Postgres 16.

## Commands
- Install: uv sync
- Test one file: uv run pytest tests/test_invoices.py -q
- All tests (about 2 minutes): uv run pytest -q
- Lint and format: uv run ruff check --fix && uv run ruff format

## Where things are
- API routes: app/routes/  Billing rules: app/billing/
- Database changes: migrations/ (Alembic)
- Why we chose things: docs/decisions/ (read before you change billing)

## Rules
- Money is integer cents, never float. Float rounding breaks totals.
- Store dates in UTC. Show them in Australia/Sydney time.
- Every schema change gets a new migration. Never edit an old one: it has run in production.
- Ask before you add a dependency. We keep the container small.

## Do not touch
- app/legacy_tax/ (old tax rules, still used for 2024 invoices). Ask first.
- .env and secrets/ are blocked in settings.

## Done means
- Tests pass, ruff is clean, and you show me the test you added.
- If you could not run something, say so.

## Read when needed
- API style: docs/api-style.md
- Testing guide: docs/testing.md

How common are these files? 2025, 2026 and a guess for 2027

• 2025. AGENTS.md came out in August. By 9 December, more than 60,000 projects used it. Stack Overflow: 30.9% of developers used AI agents at work.
• 2026. In September, Stride (a developer tool company) counted all 7,370 public GitHub repos with 5,000+ stars: 33.4% had an agent file. JetBrains found that 90% of developers use AI coding agents at work every week.
• 2027 (my guess). About half of popular repos will have one, and AGENTS.md becomes the shared name now that Claude Code reads it too. The files get shorter, and more of the rules move into hooks and tests.

A checklist for your file today