How to Write a CLAUDE.md

A CLAUDE.md is the highest-leverage markdown file in your repository: every agent session starts by reading it, so every line either improves or degrades everything the agent does afterward. This guide covers the structure that works, the content that earns its place, and the anti-patterns that quietly poison agent behavior.

Start With the Commands

The first thing an agent needs is the ability to verify its own work. Lead with the exact build, test, and lint commands — copy-pasteable, with working directories spelled out:

# Build + test checks (run before every commit)
cd backend  && go build ./... && go test ./...
cd frontend && npx tsc --noEmit && npm run test:unit

An agent that can self-verify catches its own mistakes; one that can't ships them to you. If your project has a dev-server setup, ports, or environment variables, state them once here rather than letting each session rediscover them.

Rules Need Reasons

The single biggest quality difference between weak and strong instruction files: strong ones explain why. Compare “Never use UpdateMany” with “Per-row UpdateOne, never UpdateMany — a buggy UpdateMany filter once polluted 4,143 documents in production.” The second version generalizes: the agent learns not just the rule but the shape of the risk, and applies the caution to situations the rule never anticipated. Write constraints as compressed war stories, not commandments.

What Belongs

  • Project mental model — two or three sentences on what this system is and its central design intention (“small enough to read on a Sunday; don't add infrastructure unless the feature demands it”).
  • Load-bearing conventions — the patterns that must survive refactors, each with its reason.
  • Hard boundaries — what the agent must never do autonomously: destructive database operations, force-pushes, publishing secrets, deploying without a green test suite.
  • Pointers, not payloads — link to deeper docs (“see STRATEGY.md before touching trading logic”) instead of inlining them; the agent will read the target when it matters. This is progressive disclosure applied to your own repo.
  • Non-obvious gotchas — the list of things that bit someone once. This section pays the highest rent per line.

What Doesn't Belong

  • Anything the code already says. Directory listings, API signatures, and framework boilerplate go stale instantly and waste the agent's context budget.
  • Aspirations. “We value clean code” changes no behavior. Every line should be checkable: could you tell whether the agent obeyed it?
  • Novels. Past roughly a few hundred lines, marginal instructions start crowding out important ones. Prune as ruthlessly as you add.

Use the Hierarchy

Global preferences (your personal style, tone, tooling) go in the user-level file. Project truths go in the repo root. Subtree-specific rules — the frontend's state-management idioms, the data pipeline's ordering constraints — go in per-directory files so they load only when relevant. Rule of thumb: put each instruction at the narrowest scope where it's always true.

Maintain It Like Code

The file earns its keep through maintenance. When an agent makes a mistake twice, that's a missing line. When a rule stops being true, delete it the same day — a false instruction is worse than none, because agents follow it confidently. And review changes with your team: an edit to CLAUDE.md is a change to every future agent session, which is why teams review these files like PRDs. markupmarkdown is built for exactly this loop — open your CLAUDE.md by GitHub URL, drag-select a rule and comment, let colleagues (and agents, via MCP) propose one-click suggested edits, run checks for banned placeholder text like TBD, and push the approved revision back as a PR. Its markdown indexes even give you an org-wide claude.md filter tab — one page listing every instruction file across all your repos, which is the natural starting point for an audit.

Further Reading