CLAUDE.md die wél werkt: vier patronen uit de praktijk

Een projectinstructiebestand — CLAUDE.md, AGENTS.md of hoe je tool het ook noemt — is het goedkoopste stuk gereedschap dat je hebt. Het wordt bij elke sessie meegelezen, dus elke regel die er onnodig in staat, betaal je duizend keer. En elke regel die er ontbreekt, betaal je in herstelwerk.

Hieronder vier patronen die in de praktijk het verschil maken, met de bijbehorende tegenwerping. Ze gaan uit van een homelab-achtige opstelling: eigen machines, eigen data, meerdere agents die aan dezelfde repository werken.

1. Schrijf verboden op, geen wensen

"Schrijf nette code" doet niets. Een agent kan niet toetsen of hij daaraan voldoet. Een verbod is wél toetsbaar, en dat is precies wat je wil.

## Harde regels
- Nooit `rm -rf`, glob-deletes of recursieve chmod/chown op home- of volumeroots.
- Nooit een bestand wijzigen zonder eerst `bestand.bak.$(date +%Y%m%d_%H%M%S)`.
- Nooit een dienst herstarten zonder eerst de status te tonen en te wachten op akkoord.
- Bij twijfel: één controle te veel boven dataverlies.

Tegenwerping: te veel verboden maken een agent passief, en dan gaat hij bij elke stap vragen. Houd het bij regels waar een fout onomkeerbaar is. Alles wat je kunt terugdraaien hoort niet in deze lijst.

2. Zet de kaart van je systeem erin, niet de handleiding

Een agent verdwaalt niet in je code, hij verdwaalt in je infrastructuur: welke poort, welke host, welk configbestand, wat draait native en wat in een container. Die kaart is kort en verandert zelden — perfect voor een instructiebestand.

## Waar dingen draaien
| Dienst        | Host        | Poort | Beheer            |
|---------------|-------------|-------|-------------------|
| model-router  | mac .135    | 8087  | systemd (native)  |
| fallback-laag | mac .135    | 8093  | systemd (native)  |
| reverse proxy | nas .176    | 8090  | docker            |

Kritieke diensten draaien native op schijf, niet alleen in een dockerstack.

Wat er níét in hoort: uitleg die de agent zelf kan opzoeken. Verwijs naar het bestand in plaats van het te kopiëren, anders loopt je instructiebestand achter op de werkelijkheid — en een verouderde kaart is erger dan geen kaart.

3. Beschrijf de verificatiestap, niet alleen de taak

Het duurste faalpatroon bij agents is niet een fout maar een gemelde succesvolle afronding die niet klopt. Leg daarom vast hoe "klaar" eruitziet.

## Klaar betekent
- De test draaide en je plakt de laatste 5 regels output in je antwoord.
- Voor een webwijziging: HTTP-status van de betrokken URL, geen "zou moeten werken".
- Voor een configwijziging: `systemctl is-active` van de dienst.

Dit is dezelfde gedachte als bij het meten van agents: beoordeel de uitkomst, niet de belofte. De methode daarvoor staat in ons stuk over het evalueren van een AI-agent, en de faalpatronen die je hiermee vroeg vangt staan in agentic loops debuggen.

4. Eén regel over geld, en zet hem bovenaan

Zodra een agent externe modellen of betaalde diensten aanroept, hoort de grens in het instructiebestand te staan — niet in je hoofd.

## Geld
- Nooit een abonnement afsluiten of een betaling doen zonder schriftelijke toestemming.
- Dure modellen alleen voor de eindstap; verkenning gaat via het goedkope profiel.
- Meld het geschatte verbruik van een taak vóór je hem uitvoert, niet erna.

Wie dit structureel wil afdwingen in plaats van het aan de agent te vragen, zet het een laag lager vast met harde kostenlimieten en een kill switch. Een instructiebestand is een afspraak; een quotum is een grens. Je wil allebei.

Wat je juist weglaat

• Stijlvoorkeuren die een linter kan afdwingen. Zet ze in de linter.
• Lange verhalen over de architectuur. Die verouderen; verwijs naar het ontwerpdocument.
• Geheimen, hostnamen van privénetwerken en API-sleutels. Een instructiebestand belandt in elke sessie, en soms in een logregel.
• Beleefdheden. "Wees behulpzaam" kost tokens en levert niets op.

Hoe je het onderhoudt

Behandel het bestand als code: versiebeheer, en een regel erbij op het moment dat je een fout hersteld hebt die je niet nog eens wil. Dat is de enige betrouwbare aanwas. Regels die je "voor de zekerheid" toevoegt, worden zelden getest en verzwakken de rest.