alle gidsen
Architectuur & Integratie
6 regels voor een agents.md die werkt
Iedereen schrijft tegenwoordig een AGENTS.md, maar ETH Zürich-onderzoek op 138 repo's en 5.694 pull requests laat zien dat de meeste versies de agent trager en duurder maken, niet beter. Dit zijn de zes regels die wél werken, plus de koppeling met een bestaande CLAUDE.md.
download de pdf- Wat is een AGENTS.md?
- Een gewoon Markdown-bestand in de root van je repository, zonder schema of verplichte velden. Elke ondersteunende agent leest het automatisch voordat hij begint. In een monorepo geldt nearest-file-wins: OpenAI's eigen repo gebruikt 88 losse AGENTS.md-bestanden, één per submodule.
- Wat zegt het onderzoek over automatisch gegenereerde bestanden?
- Een door een LLM gegenereerd bestand (bijvoorbeeld via het init-commando) verlaagt het slagingspercentage met gemiddeld 3% en verhoogt de kosten met ruim 20%. Een zelf geschreven bestand levert maar 4% op, en kost ook meer. De agent volgt de instructies namelijk trouw op: meer tests, meer file-reads, meer checks. Grondig, maar niet per se wat de taak nodig had. Een codebase-overzicht laat de agent bovendien niet sneller navigeren, die structuur vindt hij toch zelf.
- Welke zes regels werken wél?
- Eén: houd het kort, onder de 150 tot 300 regels, want elke regel gaat mee in élke sessie en kost tokens. Twee: zet commando's letterlijk en vroeg, niet "installeer de dependencies" maar het exacte commando. Drie: voorbeelden boven uitleg, één codefragment wint van drie alinea's die de stijl beschrijven. Vier: expliciete grenzen, wat de agent nooit aanraakt (secrets, productieconfig, specifieke mappen); nooit secrets committen is de meest voorkomende regel. Vijf: laat weg wat de agent zelf vindt, codestijl hoort in een linter. Zes: vertrouw nooit blind op een auto-gegenereerd bestand, want dat dupliceert vaak je README.
- Hoe koppel je AGENTS.md aan een bestaande CLAUDE.md?
- Claude Code leest AGENTS.md niet automatisch. Zet als eerste regel van je CLAUDE.md een import naar AGENTS.md, of draai het init-commando in een repo die al een AGENTS.md heeft. Werk je met veel losse taken, zet dan details zoals de testflow of het databaseschema in aparte bestanden onder docs/ en verwijs ernaar vanuit AGENTS.md, in plaats van alles in één bestand te proppen.