CLAUDE.md: the documentation your agent reads

If your repo doesn't have a `CLAUDE.md` in 2026, you're losing hours every week. Not because AI doesn't work: it does. But because every session you start from scratch explaining the same things. This guide explains what a useful `CLAUDE.md` looks like, how to structure it, and what NOT to include (because it saturates the context and tanks response quality). ## What CLAUDE.md is It's a file at the project root (or per feature) that your agent reads automatically when it opens the repo. It holds the rules, conventions, and prohibitions you expect it to follow. It's not a README. The README is for humans landing on the repo. CLAUDE.md is for the agent about to write code in the repo. ## Recommended structure ```markdown # [Project Name] — Development Guide ## Core Stack - The bare minimum: framework, DB, auth, package manager ## Critical Rules (NON-NEGOTIABLE) ### 1. Directory Structure ### 2. Import Rules ### 3. Dependency Rules ### 4. Language & Code Style ### 5. No Comments Policy ### 6. No Business Logic in Page Components ## Project Structure ## Decision Tree: Where to Put New Code? ## Anti-Patterns (DO NOT DO THIS) ``` Each section is 5-15 lines, not 5 paragraphs. The goal isn't to teach; it's to remind. ## Rules that DO work in CLAUDE.md - **Concrete and verifiable**: "no `console.log`, use `@/lib/errors/logger`". The agent can check. - **With short before/after examples**: ```ts // Wrong import { Button } from '@/shared/components/ui'; // Right import { Button } from '@/shared/components/ui/button'; ``` - **Explicit prohibitions** ("NEVER use npm/yarn") work better than recommendations. ## Rules that DON'T work - **Abstract philosophy**: "write clean code". The agent has no idea what that means. - **Rules that drift**: if your CLAUDE.md pins a version of each library, in 6 months it's outdated and the agent trusts the wrong info. - **Docs that duplicate the README**: redundancy that's useless and burns tokens. ## CLAUDE.md per feature On top of the root CLAUDE.md, add one per feature in sensitive modules: ``` src/features/auth/CLAUDE.md src/features/payments/CLAUDE.md src/features/blog/CLAUDE.md ``` Each with: - Security prohibitions ("NEVER trust user HTML", "ALWAYS sanitize") - Module-specific patterns - Valid states (e.g., `draft → published → archived`) - Common bugs you've already had So when the agent touches `src/features/blog/`, it also reads local rules and doesn't have to guess. ## Common mistakes when writing CLAUDE.md **1. Too long**: if your CLAUDE.md is 800 lines, the agent processes it but loses priorities. Aim for 200-400 lines max at the root. **2. Contradictory rules**: "always use X" in one place, "avoid X" in another. Happens when you edit at different times. Review the whole file when adding. **3. No "WHY" on weird rules**: if you say "don't use Edge runtime", briefly explain: "Prisma doesn't support it." Without the reason, the agent may skip the rule when the situation looks different. **4. Confusing `README` with `CLAUDE.md`**: README explains what the project is. CLAUDE.md explains how to work inside it. Don't mix them. ## How to iterate your CLAUDE.md - **Every time the agent makes the same mistake 3 times**: the rule isn't clear, or it doesn't exist. Document it. - **Every time you repeat the same thing in a prompt**: add it to CLAUDE.md. - **Every major release**: check if versions, commands, or conventions changed. ## Bottom line `CLAUDE.md` is the difference between an agent that "helps you type" and an agent that "works in your repo as if it had known it for months". 5 minutes a day writing it saves 30 minutes a day of repeated prompts. In a month that's hours. In six, a whole feature.