How to Write a CLAUDE.md That Improves AI Output

A CLAUDE.md is the highest-leverage file in an AI-assisted repo and the most commonly misused. It is loaded into the model's context automatically at the start of every session, which means two things at once: everything you put in it steers every task, and everything you put in it costs context on every task. The best ones respect both facts.

This guide covers what CLAUDE.md is, where the files live and how they combine, what actually belongs in one, and the failure mode, namely bloat, that quietly makes them worse. The same principles carry over to the emerging AGENTS.md convention other tools read, so the effort is not Claude-specific.

What CLAUDE.md is for

CLAUDE.md is a memory file: plain Markdown that Claude Code reads into context when a session begins, before you type anything. It is the place to encode the project knowledge a competent new teammate would need on day one but cannot infer from the code alone, such as how to build and test, which conventions to follow, and what not to touch.

The most useful way to think about it is as a standing prompt, not a document. That reframing leads to better choices:

• Every line competes for the model's attention, so a fact that does not change behavior is not neutral; it dilutes the facts that do.
• It is instructions, not prose, so write imperatively and concretely: run the exact test command, not the project has a comprehensive test suite.
• It is read every session, so stale content is actively harmful; a wrong command in CLAUDE.md gets followed confidently, every time.

Where the files live and how they combine

CLAUDE.md is hierarchical. A file in the project root is shared with the team through the repo; a file in your home directory holds personal preferences that apply across every project; and a CLAUDE.md inside a subdirectory is picked up when the agent works in that part of the tree. They layer, so global rules, project rules, and module rules all reach the session together.

You can also compose files by importing others, which keeps each one focused:

# Project: billing-service

## Commands
- Build:          pnpm build
- Test one file:  pnpm vitest run path/to/file.test.ts
- Lint and fix:   pnpm lint --fix

## Conventions
- Money is always integer cents, never floats.
- API handlers live in src/routes and return typed Result objects.
- Never edit generated files under src/db/schema.

## Gotchas
- The test DB must be running: docker compose up -d db

## More detail
@docs/architecture.md

What actually belongs in one

A strong CLAUDE.md is mostly the things that are true about your project but invisible to someone reading a single file. In practice that is a short list.

• Commands: the exact build, test, lint, and run invocations, including the incantation to test a single file, so the agent stops guessing them.
• Conventions: the non-obvious rules, such as money in integer cents, errors returned not thrown, or this directory is generated, that the code follows but never states.
• Boundaries: the do-not list, such as files never to edit or commands never to run, which prevents whole categories of mistake.
• Pointers: links to deeper docs the agent can open when it needs them, so detail lives one hop away instead of bloating the main file.

Keep it lean with progressive disclosure

The dominant failure mode is length. A CLAUDE.md that grows into a 500-line manual stops being read carefully, both by the model, which skims, and by you, who stops maintaining it. The discipline is to keep the always-loaded file short and push depth into files the agent pulls in only when relevant.

This is the same progressive-disclosure idea that skills use: a lean top level with pointers to detail. If a section is only relevant to one workflow, it belongs in a doc that workflow references, or in a skill, not in the file that loads on every single turn regardless of what you are doing.

Maintain it like code

A CLAUDE.md is only as good as its accuracy, and accuracy decays. Treat the file as a living part of the codebase rather than a one-time setup step.

• Commit it and review changes to it in pull requests, because a change to how the agent behaves deserves the same scrutiny as a change to the code.
• Prune on a schedule: when a convention changes or a command is renamed, fix CLAUDE.md in the same commit, and delete anything you cannot vouch for.
• Prefer a human-curated file over a fully auto-generated one; the generated version is a starting point, but the judgment about what matters is yours to add.

A great CLAUDE.md is short, specific, and true: a tight brief a sharp new hire could act on immediately, not an encyclopedia. Write down the commands, the non-obvious conventions, and the boundaries; push everything else behind a pointer; and keep it honest as the project moves. Get that right and every session starts from a better place, before you have typed a word.