If you have 30 seconds. An effective
CLAUDE.mddoesn't document, it constrains — each rule answers a time the agent got it wrong. This article gives the four-layer structure I use for a 91,000-line ERP (rootCLAUDE.md,AGENTS.md, per-module.claude/rules/, auto-loaded skill), four operational rules drawn from dated incidents, and one sustainable discipline: write the forbidden before the best practice. Useful if you drive code with Claude Code daily and see your agent drifting.
Why not just a README
I'm asked why I don't just put in the README what's in CLAUDE.md. The two files don't have the same audience. The README speaks to a human who will read it once at onboarding and remember as best they can. The CLAUDE.md speaks to an agent that rereads it at every session, has no memory between sessions, and will take each sentence at face value. The README documents, the CLAUDE.md constrains. No introductory paragraphs, no storytelling. Dense rules formulated to be read out of context, with a strict separation between what is allowed, what is forbidden, and what requires human validation.
Initial version, forty lines of naiveté
The first CLAUDE.md for Rembrandt, dropped on March 21st, 2026, fit in one screen. Stack, commands, tree structure, a few obvious conventions like "Server Components by default". What strikes me rereading it isn't what it contains, but what it doesn't. Nothing about what the agent was going to get wrong in the days that followed. We write what we already know, when the file's value precisely comes from what we don't know yet. The useful rules couldn't have been formulated on day 1, because they were produced by incidents that hadn't yet happened.
Four incidents, four rules
1. Server Component + onClick, the silent crash
Day 4. Catherine leans into the office. « Michel, j'ai cliqué sur le bouton d'émargement et rien. Pas d'erreur, pas de rouge, rien. » — Michel, I clicked the attendance button and nothing. No error, no red, nothing. She doesn't tell me "it's crashing," she tells me "nothing happens," which for a button is precisely worse.
I reopen the page. TypeScript build green, Turbopack reports nothing, the crash only shows up at server rendering in production, with a sibylline message, Event handlers cannot be passed to Client Component props, ERROR 3637204658. We all tend to look for the cause in the component that crashes, and that's where the trap closes. The error comes from a <select onChange={() => {}}> in the parent Server Component, not in the client component we suspect. Catherine's sentence produced the rule, added to the CLAUDE.md the next day.
- Server Components by default, `'use client'` only if interactive state is required
It looks innocuous written like that. Yet it bears the scar of a button that didn't answer Catherine.
2. RLS + wrong Supabase client, zero rows without error
March 25th. Françoise calls me from the next office, she's shouting. « Bon. Tes inscriptions sur Maisons-Laffitte, il y en a combien ? Moi j'en vois zéro. » — Right. Your enrollments on Maisons-Laffitte site, how many are there? Because I see zero. I open the same page on my machine, I see zero too. « Il y a un moment où il faut y aller, parce que là je peux pas pointer. » — There comes a point where you have to sort this out, because right now I can't do attendance.
We had just turned on RLS on eighteen tables. Policies written, tested in direct SQL, everything passing. Prod deploy. Every page shows zero rows. No exception, no 500, no error log. Just zero, which is precisely what makes the bug dangerous, because Françoise doesn't see anything to fix, she sees an empty school. The SSR client with the anon key is in place, the auth cookie is transmitted, but the JWT no longer passes. The query falls back to the anon role, no policy matches, result empty and silent. The rule written into CLAUDE.md and into the rembrandt-conventions skill that auto-loads on any ERP code is that Server Components use createSupabaseAdmin, never createSupabaseServer. Auth is already verified by the upstream proxy.ts, the service_role key never reaches the client. Françoise got her attendance back the next day.
3. Overstated green build, the rule that forces the agent to prove itself
April 10th, 3:30 AM. The attendance overhaul has been running for eight hours, the screen tells me for the fourth time "build green, all checks pass." I don't believe it anymore. I switch to the local terminal, I run pnpm build by hand, and the output returns error TS2307: Cannot find name 'QRCodeSVG'. Three lines down, Property 'isSeancePassed' does not exist. And the motif_absence column added to the DB the day before without regenerating the types. Four times "green", four times false.
This isn't a technical incident, it's a behavioral drift. The agent didn't lie, it probably ran the command on an intermediate state, or read a stale LSP cache. The rule that needed writing wasn't technical, it was about how to prove the build.
- For any change, paste the raw output of `pnpm build` in the report.
If `error TS` or `Type error` appears, the build is not green.
- For revert or refactor, `grep -rn "keyword" app/ lib/ components/`
with zero occurrences as proof.
Without that constraint, the agent always overstates. With it, it shows its cards.
4. 1 enrollment = N seats, the business counter-model
This incident I told elsewhere in the series — the morning Françoise compares the dashboard number to her Excel and delivers her verdict. I bring it back here because it's the mother of all business rules in the CLAUDE.md. The table is called inscriptions, the name is explicit, and the agent deduced, reasonably, that each row represents a commercial enrollment. It is wrong. The table stores seats, one row per contact per course, UNIQUE index (contact_id, cours_id). A student enrolled in two courses occupies two rows, and a COUNT(*) FROM inscriptions counts seats, not students.
- 1 commercial enrollment = N course seats
- "Number of students" → COUNT(DISTINCT contact_id)
- "Seats in a course" → COUNT(*) WHERE cours_id=X
Business vocabulary isn't intuitive, and the agent can't guess it. The CLAUDE.md is the only place where the counter-model can be set down before the agent regenerates the wrong intuition at every session.
The current structure
Four files work together. The root CLAUDE.md carries the stack, commands, transversal conventions, module tree and forbidden zones (.env.local, lib/supabase-admin.ts, existing RLS policies, /api/cron/, critical tables). One hundred and twenty dense lines, no narration, not a word extra.
The AGENTS.md fits in five blunt lines that tell the agent not to trust its memory for Next.js 16, and to read the guide in node_modules/next/dist/docs/ before writing a single route. That file has fixed more bugs on its own than any long rule.
The .claude/rules/finance.md gathers the vertical rules of the Finance module, pulled out of the CLAUDE.md because they only concern one perimeter. CASH model, VAT exemptions on professional training, bank ledger GL-512x inaccuracy, 43% VAT prorata FY26. An agent that doesn't touch /app/finance/ doesn't load them.
The rembrandt-conventions skill, finally, auto-invokes on all ERP code. It consolidates the rules with pointers to the feedback_*.md memories that tell the source incident. When a rule looks wrong, you trace back to the incident, not to opinion. Mixing vertical rules into the root CLAUDE.md would drown the agent in irrelevant context at every session. Layered sedimentation lets each task load exactly what it needs.
What I learned in four weeks
Write the forbidden before the best practice. A positive rule like "use Server Components by default" is read and forgotten. A negative rule like "never disable 2FA on inscription@, it breaks the Gmail app password" is read and retained because it carries its consequence.
Cite the incident. Error code, date, what crashed. The rule becomes opposable. The agent can verify, the human reader too. Abstract rules dissolve, traced rules hold.
Separate the general from the vertical. What holds everywhere goes into the root CLAUDE.md. What holds for one module goes into .claude/rules/<module>.md. What holds for the whole project culture and can serve other agents goes into a skill. Three regimes, three files. Melvin Conway stated it in 1968 — systems that you design reflect the organization that designs them. A layered CLAUDE.md that reflects the real structure of the project — general, module, culture — is the software side of that law, and that's precisely why it holds: the agent, when it reads, receives the project in the very form that produced it.
The CLAUDE.md is never finished, and that's precisely why it works. A file frozen on day 1 would never have covered the four incidents told above. The living file has integrated them all. We could say it is the imprint of the shocks, and that a project's quality with Claude Code is measured as much by what is in this file as by the code itself.
What you can copy into your project
A four-layer template (CLAUDE.md, AGENTS.md, .claude/rules/module.md) in the series' companion repo, MIT license: github.com/michelfaure/rembrandt-samples.
Four reusable elements, independent of my stack:
-
The four-layer structure — a root
CLAUDE.md(general, short), anAGENTS.md(if you use several Claude agents), a.claude/rules/<module>.mdfolder (vertical rules), and a per-perimeter auto-invoked skill. Each level loads exactly what a task needs -
The negative rule format:
"never do X, because Y crashed on DATE". Explicit scope, cited incident, dated date. More opposable than a positive rule - One incident number per rule: even approximate (date, error message, file). The rule becomes verifiable, traceable, discussable
-
Versioning: the
CLAUDE.mdlives in the repo, it follows migrations. A rule regression shows up in agit log
And one discipline: reread your own CLAUDE.md every 15 days. If a rule hasn't been invoked in a month, either the problem is solved (you can archive it), or the rule is too abstract to apply (you rewrite it). A file that sleeps doesn't help the agent.
Over to you
If you have a CLAUDE.md that holds up, what's the rule that took you the longest to write, and what incident produced it? I'm all ears. The best patterns I've seen always come from a scar.
Companion code: rembrandt-samples/claude-md/ — the 4-layer template (CLAUDE.md, AGENTS.md, vertical rule, feedback file), MIT, copy-pastable.
Top comments (0)