Agent entrypoint conventies voor projecten
Definitie
Een agent entrypoint is een bestand in de root van een project dat een AI coding agent (Claude Code, Cursor, Cline, Copilot) gebruikt om het project te begrijpen zonder aanvullende instructies. De drie gangbare bestanden zijn AGENTS.md (platform-agnostisch), CLAUDE.md (Claude-specifiek) en README.md (mens-primair).
Context
Toen project-handoff workflows werden uitgewerkt kwam de vraag naar boven: welk bestand moet een agent als eerste lezen? README.md is geschreven voor mensen en bevat vaak marketing of context die niet machine-actionable is. AGENTS.md ontstond als een expliciet formaat voor agent-brieven. CLAUDE.md is een Claude Code specifieke laag daarboven voor tool- en workflow-afspraken die niet tot de algemene agent-laag horen.
Kernpunten
- README.md is voor mensen. Marketing, installatie-overview, voorbeelden. Een agent kan hem lezen maar moet er geen instructies uit afleiden die in conflict zijn met AGENTS.md.
- AGENTS.md is de universele agent-brief volgens de emerging standaard agents.md. Inhoud: project-samenvatting, stack, exacte setup-commando’s in fenced code blocks, build/test/run commando’s, coding conventies, wat niet te doen, waar op te letten. Platform-agnostisch, werkt in Claude Code, Cursor, Cline, Copilot.
- CLAUDE.md wordt door Claude Code gelezen bij elke sessie-start. Bovenop AGENTS.md: welke tools wel/niet gebruiken, welke hooks actief zijn, welke MCP-servers nodig zijn, backlog-afspraken als het project Backlog.md gebruikt.
- Stapeling: CLAUDE.md leest eerst AGENTS.md als baseline en voegt alleen Claude-specifieke regels toe. Dubbele inhoud vermijden.
- Agent-reproduceerbaarheid test: een subagent met alleen toegang tot de AGENTS.md-map moet het project volledig kunnen opstarten. Als er impliciete kennis nodig is, is het entrypoint incompleet.
- Waarschuwing: als je alleen een README schrijft en verwacht dat een agent zelf uitzoekt wat relevant is, krijg je inconsistent gedrag. Maak de agent-brief expliciet.
Verbanden
- Zie ook: wiki-tdd-claude-code-skills
- Zie ook: wiki-secrets-safeguard-project-handoffs
- Zie ook: wiki-slash-commands-vs-skills
- Gerelateerd project: project-handoff-skill
Bronnen
- agents.md. (2026). Open format for AI coding agent instructions. Geraadpleegd via https://agents.md/
- Augment Code. (2026). How to Build Your AGENTS.md: The Context File That Makes AI Coding Agents Actually Work. https://www.augmentcode.com/guides/how-to-build-agents-md
- HumanLayer. (2026). Writing a good CLAUDE.md. https://www.humanlayer.dev/blog/writing-a-good-claude-md