Anthropic Best Practices for CLAUDE.md Files

A CLAUDE.md file is the project-level memory Claude Code reads automatically at the start of every session in a repository. Anthropic's guidance on it boils down to one idea: treat it like onboarding notes for a new engineer, not documentation for humans who already know the codebase. It should tell Claude what it can't infer from the files themselves — build commands, conventions, gotchas, and constraints — and skip everything it can figure out by reading the code.

This matters because Claude Code injects the contents of CLAUDE.md into context on every run. A bloated or vague file wastes tokens and dilutes the signal; a sharp, specific one measurably improves how well Claude follows your team's conventions without you repeating yourself in every prompt.

What Actually Belongs in CLAUDE.md

Anthropic's own examples and community consensus converge on a fairly short list of categories:

• Build, test, and lint commands — the exact commands, not "run the tests." Include flags you actually use (npm test -- --watch=false, pytest -x).
• Code style rules that aren't enforced by a linter — naming conventions, preferred patterns, things like "always use named exports" or "no default exports in this repo."
• Repository structure notes — where things live if it's not obvious (src/api/ is generated, don't edit; hand-written routes go in src/routes/).
• Known gotchas — flaky tests to ignore, environment quirks, "this package needs Node 18 not 20," or "the staging DB seed script must run before integration tests."
• Workflow expectations — whether Claude should run tests before committing, whether it should ask before installing new dependencies, whether commits need a specific message format.

What doesn't belong: long prose explanations of architecture that live better in a README, copies of your API documentation, or generic best-practice advice Claude already knows (it doesn't need to be told what a unit test is).

Keep It Short and Skimmable

The single most common mistake is writing CLAUDE.md like a wiki page. Anthropic recommends short, direct bullet points over paragraphs. A file that reads like:

# Project Notes

- Run `pnpm test` before committing. Do not run `pnpm test:e2e` unless asked — it needs a live staging DB.
- All new API routes go in `src/routes/` and must have a corresponding test in `src/routes/__tests__/`.
- Use `zod` for input validation, not manual type checks.
- Never edit files in `src/generated/` — they're overwritten by `pnpm codegen`.
- Commit messages follow Conventional Commits (`feat:`, `fix:`, `chore:`).

...is far more useful than three paragraphs describing the project's history and tech stack philosophy. Claude parses instructions well; it doesn't need narrative framing.

Use Nested CLAUDE.md Files for Monorepos

If you're working in a monorepo, Anthropic's recommendation is to place a CLAUDE.md at the root for global conventions, and additional CLAUDE.md files inside subdirectories for package-specific rules. Claude Code picks up the nearest relevant file based on where it's working, so a packages/api/CLAUDE.md can override or extend root-level guidance without cluttering the top-level file with details that only matter to one service.

Iterate on It Like Code

Treat CLAUDE.md as a living file, not a one-time setup step. When Claude does something wrong repeatedly — uses the wrong test runner, edits a generated file, misses a required env var — that's a signal to add a line to CLAUDE.md rather than correcting it every session. Anthropic explicitly suggests using the # shortcut in Claude Code to quickly append a note to the file mid-session, so corrections get captured immediately instead of being forgotten.

It's also worth periodically pruning the file. Rules that are now enforced by a linter, a pre-commit hook, or CI don't need to live in CLAUDE.md anymore — remove them so the file stays focused on things automation can't catch.

Don't Duplicate What Tools Already Enforce

A well-configured linter, formatter, and CI pipeline should handle style and correctness. CLAUDE.md is for the judgment calls that tooling can't express — architectural boundaries, business logic quirks, and team conventions that are social rather than mechanical. If you find yourself writing "always use 2-space indentation" in CLAUDE.md, that's a sign your .prettierrc should be doing that job instead.

Where CLAUDE.md Fits Into a Broader Workflow

For teams that use Claude both inside an editor via Claude Code and programmatically — say, a CI job that calls Claude to review a diff or a backend service that generates content — it's worth keeping the same conventions consistent across both surfaces. If you're building that kind of integration, SubToAPI turns your existing Claude access into a straightforward HTTPS API with per-application keys (sub_live_...), so a CI script or internal tool can call Claude the same way your editor does, without separate billing or credential sprawl. The quickstart and messages API docs cover the request format if you're wiring that up alongside your CLAUDE.md-driven editor workflow.

A Minimal Starting Template

If you're setting one up for the first time, start small and expand only as needed:

# CLAUDE.md

## Commands
- Install: `pnpm install`
- Dev server: `pnpm dev`
- Test: `pnpm test`
- Lint: `pnpm lint`

## Conventions
- TypeScript strict mode, no `any` without a comment explaining why.
- API routes live in `src/routes/`, one file per resource.

## Do Not
- Edit anything in `src/generated/`.
- Run migrations automatically — ask first.

Expand it as you notice gaps, not preemptively.

Questions

Does CLAUDE.md need to be committed to the repo? Yes — it's meant to be shared team infrastructure, not a personal preference file. Commit it alongside your code so everyone using Claude Code gets the same context, and update it through normal PR review like any other project file.

How long should a CLAUDE.md file be? Long enough to cover build commands, conventions, and gotchas — typically well under one page. If it's growing past a few dozen lines, look for content that belongs in a README or that's better enforced by tooling instead.

Can CLAUDE.md include secrets or API keys? No. It's plain text checked into version control and read into every session's context, so it should never contain credentials, tokens, or connection strings — reference environment variables by name instead.