4 incidents, 4 rules: how my CLAUDE.md wrote itself

try { if(localStorage) { let currentUser = localStorage.getItem('current_user'); if (currentUser) { currentUser = JSON.parse(currentUser); if (currentUser.id === 3897818) { document.getElementById('article-show-container').classList.add('current-user-is-article-author'); } } } } catch (e) { console.error(e); } Michel Faure Posted on Apr 28 4 incidents, 4 rules: how my CLAUDE.md wrote itself #claudecode #ai #productivity #softwareengineering My ERP with Claude Code (3 Part Series) 1 How much are 91,000 lines produced with Claude Code actually worth? 2 Supabase RLS in production: four traps that silence your queries 3 4 incidents, 4 rules: how my CLAUDE.md wrote itself If you have 30 seconds. An effective CLAUDE.md doesn'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 (root CLAUDE.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 Enter fullscreen mode Exit fullscreen mode It looks innocuous written like that. Yet it bears the scar of a…

This excerpt is published under fair use for community discussion. Read the full article at DEV Community.