What this covers
CLAUDE.md is not a readme for humans — it is the system prompt your agent loads on every session. Treat it that way and your output quality jumps; treat it as an afterthought and the agent re-discovers your conventions every chat. This guide is for engineers running Claude Code on a real project who keep hitting the same friction: it ignores your import order, edits files you said to leave alone, runs the wrong test command, or rewrites idioms it should have followed.
Key tools and concepts:
- Claude Code: Anthropic’s command-line AI coding agent that reads, edits, and runs code in your terminal.
- CLAUDE.md: A Markdown file at repo root (or per-package) that Claude Code auto-loads as durable context.
- Subdirectory CLAUDE.md: Per-folder files inherit / override; useful for monorepos with different stacks per package.
Who this is for
Anyone using Claude Code on a real project bigger than a script. Especially valuable in monorepos, polyglot codebases, or repos where unwritten conventions outweigh the README.
When to reach for it
Whenever you set up Claude Code on a new repo, when the agent keeps making the same mistake, or when onboarding a new team member to AI-assisted work — the CLAUDE.md doubles as the human’s quick reference.
Before you start
- Re-read your existing README. Anything human-only or marketing-flavored should NOT go into CLAUDE.md. The agent does not need feature lists; it needs constraints.
- Note three behaviors you wish the agent did better. These become explicit rules.
- Identify forbidden paths: generated code, vendored libraries, migrations, secrets. The agent should never edit these.
- Decide on a single source of truth for commands (test, lint, build). The agent will obey what is in CLAUDE.md even if package.json disagrees.
Step by step
- Top section: 3-5 sentences on what this project is, who runs it, primary entry points. Example:
Next.js 15 app, App Router, deployed via Vercel. Entry: app/page.tsx. Background jobs: lib/jobs/*.ts. - Conventions block: imports (named not default), file naming (kebab-case), formatting (prettier defaults plus 100-char width), error handling pattern. Show one tiny example per rule, not paragraphs.
- Forbidden block: paths the agent must not touch. Be explicit:
Do not edit src/generated/*, prisma/migrations/*, or any file matching *.gen.ts.The agent honors this surprisingly well. - Quality gates: exact lint, type, and test commands. Example:
Test: pnpm test --run. Lint: pnpm lint. Type: pnpm typecheck. Run all three before declaring a task complete. - Per-task hints: a “When asked to add a route” section with the 4 files the agent should touch and the order. Same for components, migrations, and tests.
- Mistakes log: a small section at the bottom listing things the agent did wrong in past sessions, with the corrected behavior. Add to it after every session where you noticed drift.
First-run exercise
- Skim a recent PR you reviewed in this repo. Write down the top 3 nitpicks you gave the author.
- Convert each nitpick into a single-sentence rule in CLAUDE.md.
- Run a small Claude Code task that touches similar code. Confirm the agent follows the new rules.
- If it ignored a rule, sharpen the wording (specific example beats abstract principle) and re-run.
Quality check
- Does CLAUDE.md fit in one or two screens? Anything longer gets ignored. Cut historical context and feature descriptions.
- Are commands copy-pasteable exactly as written? Slight wording variations confuse the agent (“run tests” vs
pnpm test --run). - Does each rule include a tiny concrete example? Abstract rules without examples regress.
- Does the agent follow the rules in practice? If not, the wording is too vague — rewrite with explicit do/don’t.
How to reuse this workflow
- Template the CLAUDE.md across your projects: same sections (intro, conventions, forbidden, gates, per-task, mistakes), customized content.
- Share the template across a team — consistent CLAUDE.md across repos makes onboarding new engineers (and switching projects) faster.
- Diff CLAUDE.md against itself monthly to see what you have learned about agent behavior.
- For monorepos, keep a root CLAUDE.md with global rules and per-package CLAUDE.md with stack-specific rules.
Recommended workflow
Write CLAUDE.md → run small tasks → update CLAUDE.md when the agent does something you didn’t want → repeat. The file is never done; it stabilizes around month 2 of regular use.
FAQ
- How long should CLAUDE.md be?: One to two screens. Past that, the agent skims and ignores rules at the bottom.
- Should secrets go in CLAUDE.md?: No. CLAUDE.md is committed; treat it like any source file. Reference env var names, not values.
- What if my conventions differ per directory?: Use subdirectory CLAUDE.md files. The agent merges; deeper ones override.
- How is this different from a README?: README is for humans onboarding. CLAUDE.md is for an agent operating today. Different audience, different content.
- Will Claude Code follow rules from CLAUDE.md strictly?: Mostly yes for explicit do/don’t with examples; vague rules (“write clean code”) get ignored.
- Do I need one for solo projects?: Even a 15-line file helps. Without it, the agent re-derives conventions every time.
Common mistakes
- Writing it once and never updating — agent behavior changes, your code evolves, the file goes stale fast.
- Vague constraints like “write clean code” instead of “use named exports, no default exports”.
- Letting it grow past 3 screens — long files get partially loaded and rules at the bottom get ignored.
- Mixing human onboarding content with agent rules — split into README.md and CLAUDE.md, keep them separate.
- Forgetting to list forbidden paths — the agent will eventually edit generated code if you don’t say not to.
- Not including the exact test/lint/build commands — the agent guesses, often wrongly.
Related
- Claude Code does not understand project
- Claude Code beginner guide
- Claude Code Project Setup
- AI coding context management
Tags: #AI coding #Tutorial #Claude Code