CLAUDE.md: het architectuurgeheugen van je project — en waarom het geen garantie isCLAUDE.md: your project's architecture memory — and why it's no guarantee
Geen documentatiedocument dat niemand leest, maar een levend bestand dat elke sessie automatisch wordt ingeladen. En toch is het maar de helft van het verhaal.Not a documentation file nobody reads, but a living file that gets loaded automatically every session. And still only half the story.
Elke developer kent dit moment. Je opent een nieuwe sessie en je hebt context nodig. Dus leg je uit hoe de architectuur werkt, welke conventies je hanteert en waarom bepaalde keuzes zijn gemaakt. Elke. Keer. Opnieuw.
Dat lost een CLAUDE.md op. Een bestand dat Claude bij elke sessie automatisch inlaadt. Geen uitleg meer. Gewoon direct aan het werk.
Wat er in een CLAUDE.md staat
Alles wat anders in een onboarding-gesprek zou eindigen. De architectuur van het project. Hoe lagen van elkaar afhangen. Naamconventies die je hanteert. Patronen die je altijd terugziet. En concrete voorbeelden, zodat het niet bij theorie blijft.
Elk project is anders. Mijn CLAUDE.md voor een Shopware-project ziet er heel anders uit dan die voor een Next.js-project. Dat is ook het punt. Het is geen template. Het is een reflectie van hoe jij denkt en hoe jouw project in elkaar zit.
Maar het belangrijkste is niet wat erin staat. Het is wat het schrijven ervan afdwingt. Want als je iets niet kunt opschrijven, snap je het zelf ook niet goed genoeg. De CLAUDE.md is het architectuurgeheugen van een project. En het groeit mee.
Het geheugen dat Claude zelf bijhoudt
Naast wat jij uitlegt, heeft Claude ook een eigen geheugen. Claude Code slaat van zichzelf al observaties op in een jsonl-bestand. Wat er is besproken, welke beslissingen zijn genomen, welke bestanden zijn aangepast. Maar dat bestand wordt na verloop van tijd gecomprimeerd en opgeschoond. En het is niet doorzoekbaar.
Daar gebruik ik claude-mem voor. Een plugin voor Claude Code die via lifecycle hooks automatisch vastlegt wat er per sessie gebeurt. Bij elke sessiestart, elke prompt, elke tool-actie en elke afsluiting. Alles gaat per project in een SQLite-database. Doorzoekbaar. Persistent. Niet opgeschoond. Bij een nieuwe sessie krijg je automatisch een samenvatting van de vorige: beslissingen en waarom voor aanpak A is gekozen en niet B, bugfixes, gebouwde features, ontdekkingen die het team moet weten.
Het verschil: de CLAUDE.md is wat jij aan Claude uitlegt over je project. claude-mem is wat Claude over zichzelf onthoudt over tijd. Samen zijn ze een volledig geheugen. Eén voor architectuur en context. Eén voor beslissingen en voortgang.
Waarom het geen garantie is
CLAUDE.md werkt. Maar alles wat je erin schrijft is advisory. Claude leest het, begrijpt het en probeert het te volgen. Het blijft suggestief. Bij een lange sessie, een vol context window of gewoon een andere keuze van het model kan een instructie worden genegeerd.
Dat besefte ik pas goed na een gesprek met Vincent van Deth. Zijn punt: wat echt afdwingt zijn hooks. Een hook draait deterministisch buiten het LLM om. Voor een prompt. Na een tool-aanroep. Bij het afsluiten van een sessie. Claude heeft er geen invloed op. Het systeem voert hem uit. Altijd.
Het verschil in de praktijk: CLAUDE.md zegt "log altijd een Jira-reactie na een codewijziging" — een hook doet het, zonder uitzondering. CLAUDE.md zegt "schrijf geen secrets naar bestanden" — een hook controleert de diff en blokkeert de actie als er toch iets in staat. Dat is het verschil tussen opschrijven en afdwingen.
Hetzelfde principe geldt voor guardrails in agent-architectuur. Je definieert vooraf wat een agent wel en niet mag doen. En als hij daarbuiten wil gaan, stopt het systeem en volgt er een menselijke check. Niet omdat we AI niet vertrouwen. Maar omdat vertrouwen zonder controle geen architectuur is. Het is hopen.
Every developer knows this moment. You open a new session and you need context. So you explain how the architecture works, which conventions you follow and why certain choices were made. Every. Single. Time.
That's what a CLAUDE.md solves. A file Claude loads automatically at the start of every session. No more explaining. Straight to work.
What goes into a CLAUDE.md
Everything that would otherwise end up in an onboarding conversation. The project's architecture. How layers depend on each other. The naming conventions you follow. Patterns that keep showing up. And concrete examples, so it doesn't stay theoretical.
Every project is different. My CLAUDE.md for a Shopware project looks nothing like the one for a Next.js project. That's the point. It's not a template. It's a reflection of how you think and how your project fits together.
But the most important part isn't what's in it. It's what writing it forces you to do. Because if you can't write something down, you don't understand it well enough yourself. The CLAUDE.md is a project's architecture memory. And it grows with it.
The memory Claude keeps on its own
Beyond what you explain, Claude also has a memory of its own. Claude Code already records observations in a jsonl file. What was discussed, which decisions were made, which files were changed. But that file gets compressed and cleaned up over time. And it isn't searchable.
That's what I use claude-mem for. A Claude Code plugin that uses lifecycle hooks to automatically capture what happens in each session. At every session start, every prompt, every tool action and every session end. Everything goes into a SQLite database per project. Searchable. Persistent. Never cleaned up. When you start a new session, you automatically get a summary of the previous ones: decisions and why approach A was chosen over B, bug fixes, features that were built, discoveries the team should know about.
The difference: the CLAUDE.md is what you explain to Claude about your project. claude-mem is what Claude remembers about itself over time. Together they form a complete memory. One for architecture and context. One for decisions and progress.
Why it's no guarantee
CLAUDE.md works. But everything you write in it is advisory. Claude reads it, understands it and tries to follow it. It stays suggestive. In a long session, with a full context window, or simply because the model makes a different call, an instruction can get ignored.
That only really sank in after a conversation with Vincent van Deth. His point: what actually enforces things is hooks. A hook runs deterministically, outside the LLM. Before a prompt. After a tool call. When a session ends. Claude has no say in it. The system runs it. Every time.
The difference in practice: CLAUDE.md says "always log a Jira comment after a code change" — a hook just does it, without exception. CLAUDE.md says "never write secrets to files" — a hook checks the diff and blocks the action if something slipped in anyway. That's the difference between writing things down and enforcing them.
The same principle applies to guardrails in agent architecture. You define up front what an agent is and isn't allowed to do. And if it tries to step outside that, the system stops and a human check follows. Not because we don't trust AI. But because trust without control isn't architecture. It's hoping.