CLAUDE.md is not a README. It's not documentation for humans. It's an instruction set for an AI system that will read it before every session and use it to decide what to do and what not to do.
Most developers write CLAUDE.md once, during setup, with whatever feels relevant in the moment. It starts accurate and becomes outdated. Within weeks, it's a list of generic principles that apply to every project and therefore help with none. The AI follows the file; the file no longer reflects the project. The gap widens silently.
A production-grade CLAUDE.md has a specific structure: project identity, technical constraints, architectural decisions, banned patterns, and workflow rules. It's written to be unambiguous. It's updated when decisions change. It's versioned and reviewed like code.
This module teaches you to build one from scratch — for a real project, with content that actually constrains AI behavior.
A developer is three months into a solo SaaS project. TypeScript, Next.js, Supabase, deployed on Vercel. They've been using AI assistance from the start. It's been productive — fast prototyping, decent code generation, useful for debugging.
But they're noticing a pattern. Every time they start a new session with the AI, they spend five to ten minutes re-establishing project context. They paste in schema definitions. They remind the AI that they're using a service layer — the AI keeps trying to call Supabase directly from components. They clarify that state management goes through Zustand, not React context. They specify the naming conventions their linter enforces.
They have a CLAUDE.md. It says: "Use TypeScript. Prefer functional components. Write clean code. Follow the existing patterns in the codebase." The AI reads it and continues to make the same mistakes.
The developer starts to wonder: what would actually be in a CLAUDE.md that helps? Not principles — the AI already knows principles. What specific information, written in what specific way, would actually change what the AI does in a new session?
This is the right question. The answer is not about writing more. It's about writing precisely.
A CLAUDE.md that changes AI behavior has five sections. Each does a specific job. Generic entries in any section are wasted space.
One paragraph describing what the project does, who it's for, and what it's trying to achieve. Not tech stack — purpose. The AI uses this to make judgment calls about what good output looks like for this specific context. "A B2B SaaS product for small law firms to manage client intake" tells the AI more than "a web app."
A precise list of what the AI must and must not do technically. Not "write clean code" — that's meaningless. Specific: "Never import directly from @supabase/supabase-js in components — use lib/db.ts." "All API routes must use the withAuth middleware." "State goes through Zustand — no React context for shared state." Each entry is a constraint the AI can apply or violate. Test every entry: if the AI could technically ignore it, rewrite it.
The decisions that shaped the project structure — recorded so the AI doesn't re-litigate them. "We use a service layer between components and data access. This decision is final — do not suggest bypassing it for simplicity." The AI will frequently suggest "simpler" alternatives to your architectural choices. This section makes clear those choices were deliberate.
Explicit list of patterns that were tried and rejected, with reasons. This section is high-value because it covers the gap between "not in conventions" and "actively harmful here." "Do not use useEffect for data fetching — we use React Query everywhere. If you're reaching for useEffect for a data case, stop and ask." The reason matters: it prevents the AI from reasoning around the ban.
How this project handles AI work: commit conventions, branch naming, PR scope rules, what the AI is and isn't authorized to do. "Do not commit to main directly. Do not suggest force-pushing. When changing a shared utility, flag it before proceeding." This section implements NIST GOVERN requirements in practice.
GOVERN requires that AI use is bounded by documented policies and that accountability is established. A CLAUDE.md that includes workflow rules (what AI can and cannot commit, what requires human review, when to escalate) directly implements GOVERN. A CLAUDE.md with only technical guidance and no workflow rules is incomplete from a governance standpoint — the AI is technically constrained but organizationally unchecked.
Article 4 requires that organizations ensure personnel using AI systems have sufficient knowledge to operate them appropriately. Writing a CLAUDE.md is itself an act of AI literacy — it requires understanding what the AI will and won't infer, what ambiguity costs, and where explicit instruction is needed. Teams that have written careful CLAUDE.md files have, by necessity, developed the AI literacy that Article 4 requires.
Every entry in a CLAUDE.md should pass three tests before it stays in the file. You'll apply these in the lab when building your own.
Can you write a specific line of code that would violate this entry? If yes, the entry is specific enough. "Write clean code" fails — there's no specific violation. "Never call fetch() directly in a React component — use the api/ module" passes — a developer could immediately show you code that violates it.
Would a capable developer already know this without being told? If yes, the entry is probably too generic to help. "Handle errors" is redundant. "All API route errors must be logged with logger.error() before returning a 500 — never let errors silently return null" is specific and non-obvious.
When was this entry last reviewed? An entry that hasn't been touched since the project started is suspect. CLAUDE.md entries should be reviewed when the decision they describe changes — and the review date should be part of a comment in the file. Outdated entries are worse than absent ones: they actively misdirect the AI.
In the lab, you'll build a complete CLAUDE.md for a sample project, applying all three tests to every entry you write. The AI will review each section and tell you where your entries are too generic to help.