AGENTS.md en HUMAN.md uitgelegd

Wat AGENTS.md is

AGENTS.md is een eenvoudig markdown-bestand in de hoofdmap van een repository. Het bestand beschrijft hoe een coding agent aan dat project moet werken. De officiële site omschrijft het als "een README voor agents: een speciale, voorspelbare plaats om context en instructies te geven waarmee AI-codingagents aan uw project kunnen werken." Het formaat valt onder het beheer van de Agentic AI Foundation binnen de Linux Foundation. Meer dan twintig agents lezen het bestand, waaronder Codex, Cursor, Jules, Devin en GitHub Copilot (per juli 2026).

De reden voor deze conventie is praktisch. Een nieuw teamlid leest de README, raadt het build-commando en vraagt iemand om hulp als de inschatting onjuist is. Een agent kan dat niet. De agent raadt het, voert npm test uit in een project dat pnpm test gebruikt, leest de foutmelding en probeert iets anders. U betaalt voor elk van die tokens. Door het juiste commando eenmalig vast te leggen, voorkomt u deze hele categorie fouten.

Er zijn geen verplichte velden. De site zegt dit expliciet: "AGENTS.md is gewoon standaard-Markdown. Gebruik de headings die u wilt; de agent parseert eenvoudigweg de tekst die u opgeeft." Dat is de volledige specificatie. De waarde zit niet in het formaat. De waarde zit in het bestand op een pad dat elke tool al controleert.

Waar het bestand komt te staan en welk bestand voorrang krijgt

Plaats het eerste bestand in de hoofdmap van de repository. In een monorepo kunt u meer bestanden toevoegen in elk subproject. De regel is eenvoudig: "agents lezen automatisch het dichtstbijzijnde bestand in de directorystructuur, dus het bestand dat het dichtst bij staat, heeft voorrang." Bij een conflict tussen twee bestanden krijgt het bestand dat het dichtst bij het bestand dat u bewerkt staat voorrang. Alles wat u in de chat typt, overschrijft beide bestanden.

my-repo/
├── AGENTS.md              # project-wide rules
├── services/
│   ├── api/
│   │   └── AGENTS.md      # wins for edits under services/api/
│   └── web/
│       └── AGENTS.md      # wins for edits under services/web/
└── README.md

Het is zinvol om deze nesting te gebruiken. Dit is namelijk de enige manier om iets vast te leggen dat in de ene map waar is en in de volgende map niet. Een regel zoals "elk endpoint valideert de invoer" hoort naast de endpoints te staan. In een bestand in de hoofdmap wordt deze regel bij elke niet-gerelateerde taak geladen en levert deze niets op.

Wat hoort in een AGENTS.md

Leg vast wat een agent niet uit de code kan afleiden. Begin met de exacte opdrachten voor build, tests en linting, in de vorm waarin u ze in een terminal zou plakken. Voeg de opdracht toe om één test uit te voeren. Een agent die alleen weet hoe de volledige testsuite moet worden uitgevoerd, voert anders de volledige testsuite veertig keer uit. Benoem conventies die afwijken van de standaardinstellingen van de tools. De agent kent die standaard al en hoeft alleen uw afwijking te kennen. Voeg ook de indeling van commitberichten en de regels voor pull requests toe als die van toepassing zijn.

Wees concreet genoeg om een bewering te kunnen controleren. "Gebruik inspringing van 2 spaties" is een bruikbare instructie, omdat kan worden vastgesteld of dit wel of niet is toegepast. "Formatteer de code correct" is dat niet, omdat niets in die instructie kan worden geverifieerd. Hetzelfde geldt voor locaties: "API-handlers staan in src/api/handlers/" is beter dan "houd bestanden geordend".

Negatieve regels zijn ook nuttig. "Bewerk nooit bestanden onder dist/; deze worden gegenereerd door npm run build" voorkomt één specifieke fout. Omdat de oorzaak wordt genoemd, kan de agent het overeenkomstige geval afleiden dat niet expliciet is beschreven.

Wat nooit in een ervan hoort

Zet nooit een geheim in een van deze bestanden. Het bestand wordt naar git gecommit, aan het begin van elke sessie in de context geladen en bij elk verzoek naar een modelprovider gestuurd. Een API key in een AGENTS.md staat in uw repositorygeschiedenis en in de logs van een derde partij. Verwijs naar het geheim in plaats van het te plakken: "het databasewachtwoord staat in .env, dat door git wordt genegeerd; vraag voordat u het leest." De bredere werkwijze wordt behandeld in referenties naar credentials buiten het bereik van een agent houden.

Laat alles weg wat de agent kan afleiden door te kijken. Een geplakte directoryvermelding, een kopie van uw dependencylijst, een architectuuroverzicht dat de mapnamen opnieuw beschrijft: dit alles raakt verouderd in de week nadat u het schrijft en kost ondertussen context in elke sessie. Behoud de valkuilen en de redenen. Laat de inventaris weg.

CLAUDE.md is de Claude Code-variant van hetzelfde idee

Claude Code leest CLAUDE.md en leest AGENTS.md niet automatisch. Een projectbestand staat in ./CLAUDE.md of ./.claude/CLAUDE.md. Persoonlijke voorkeuren voor elk project staan in ~/.claude/CLAUDE.md. Een organisatie kan op Linux een systeembreed bestand plaatsen in /etc/claude-code/CLAUDE.md. Gevonden bestanden worden samengevoegd vanaf de hoofdmap van het bestandssysteem tot aan uw werkmap. Het bestand dat het dichtst bij de locatie staat waar u de sessie hebt gestart, wordt dus als laatste gelezen.

Als uw repository al een AGENTS.md bevat, moet u geen tweede kopie bijhouden. Importeer het bestand en voeg alleen Claude-specifieke inhoud toe:

@AGENTS.md

## Claude Code

Use plan mode for changes under `src/billing/`.

Een symbolische koppeling werkt als u niets extra's hoeft toe te voegen:

ln -s AGENTS.md CLAUDE.md

De opdracht geeft bij succes niets weer. Voer in uw volgende sessie /context uit en controleer of CLAUDE.md onder Geheugenbestanden verschijnt. Als het bestand niet in die lijst staat, is het nooit geladen en is de inhoud ervan niet toegepast. Als u een eerste concept wilt genereren in plaats van zelf een bestand te schrijven, voert u /init uit. Deze opdracht leest de codebase en maakt een startbestand. Als er al een CLAUDE.md bestaat, stelt de opdracht verbeteringen voor in plaats van het bestand te overschrijven.

Houd elk bestand onder ongeveer 200 regels. Langere bestanden gebruiken meer ruimte in het contextvenster, waardoor de naleving afneemt. Als u wilt zien wat nog meer beslag legt op die ruimte, geeft wat er precies in het contextvenster van een agent staat een overzicht.

Eén punt verdient nadruk. Een AGENTS.md bevat richtlijnen en is geen machtigingssysteem. De inhoud wordt als gewone context aangeleverd. Het model leest deze inhoud en volgt de richtlijnen meestal, maar niets blokkeert een actie die ermee in strijd is. Gebruik voor een regel die altijd moet gelden, zoals "push nooit naar main", een hook of een machtigingsinstelling. Deze worden als code uitgevoerd en zijn niet afhankelijk van de beslissing van het model om de regel te volgen.

Tools die deze bestanden voor u schrijven

Twee projecten uit de GitHub-trendlijst van 30 July 2026 laten zien in welke richting de conventie zich ontwikkelt.

agent0ai/dox (1,368 stars in July 2026) is een framework om een boomstructuur van AGENTS.md-bestanden actueel te houden. Het project bevat geen package en geen runtime. U kopieert de inhoud van het AGENTS.md-bestand naar uw eigen root AGENTS.md-bestand. Dat is de installatie. Voor een bestaand project geeft u uw agent de volgende opdracht:

Initialize DOX tree for this project now.

De agent maakt vervolgens de onderliggende AGENTS.md-bestanden en hun indexen aan. Voor elke wijziging doorloopt de agent eerst deze boomstructuur voordat er iets wordt bewerkt. Na een wijziging werkt de agent de betreffende documentatie bij. De achterliggende aanname is dat documentatie die een agent als onderdeel van zijn werk onderhoudt, actueel blijft. Documentatie die iemand handmatig bijwerkt, blijft dat volgens deze aanname niet.

HUMAN.md, dezelfde aanpak gericht op uzelf

Intuition-Lab/personal-model (1,260 sterren per juli 2026) past dit patroon toe op een persoon in plaats van op een repository. Het project beschrijft uw HUMAN.md als de uitvoer van het systeem, niet als een bestand dat u zelf typt: "een actueel model van wat nu belangrijk is, hoe u doorgaans beslissingen neemt en waar uw aandacht naartoe gaat." Het draait lokaal op macOS 13 of later, legt activiteit vast nadat u macOS daarvoor toestemming hebt gegeven en maakt het resultaat via MCP (model context protocol) beschikbaar voor agents. De korte installatieroute:

uv tool install personal-model
persome onboard
persome model open --after 30

U hebt hiervan niets nodig om het grootste deel van het voordeel te behalen. Een handgeschreven HUMAN.md is ongeveer twintig regels lang: uw rol, uw tijdzone, de stack die u daadwerkelijk gebruikt, beslissingen die u al hebt genomen en niet opnieuw wilt bespreken, en hoeveel uitleg u terug wilt krijgen. Hiermee voorkomt u dezelfde herhaalde uitleg als met een projectbestand, maar een niveau hoger.

Een aandachtspunt. Een HUMAN.md is per definitie een profiel van een persoon en bevat dus gevoelige informatie. Houd het bestand buiten een openbare repository. Plaats het in ~/.claude/CLAUDE.md of in een door git genegeerd CLAUDE.local.md in de hoofdmap van het project. Dit bestand wordt samen met het gecommitte bestand geladen en op dezelfde manier behandeld.

Een startsjabloon dat u kunt kopiëren

Dit is bewust kort. Verwijder de secties die niet van toepassing zijn en voeg geen secties toe die u niet actueel kunt houden.

# AGENTS.md

## Project
A Django API serving the mobile app. Python 3.12, PostgreSQL 16.

## Setup
uv sync
docker compose up -d db
./manage.py migrate

## Commands
Run one test: pytest tests/test_orders.py::test_refund
Run everything: pytest
Lint: ruff check . && ruff format --check .

## Conventions
Type hints on every public function. Line length 100, not 88.
Migrations are generated, never hand-edited.
Never edit files under static/dist/, they come from npm run build.

## Secrets
Local credentials live in .env, which is gitignored. Ask before reading it.

## Pull requests
Title format: [area] short description. Run the linter before opening one.

Schrijf het en corrigeer het vervolgens op dezelfde plaats. De aanwijzing om een regel toe te voegen is dat u dezelfde correctie twee keer in de chat hebt getypt. Deze ene regel houdt het bestand bruikbaar en voorkomt dat het bestand uitgroeit tot een document dat niemand leest, ook machines niet. Zodra het stabiel is, reist het mee met de repository. Dat is vooral belangrijk wanneer de agent ergens anders wordt uitgevoerd dan op uw laptop: een coding agent op uw eigen server uitvoeren behandelt die configuratie.

FAQ

Is AGENTS.md hetzelfde bestand als CLAUDE.md?

Het is hetzelfde concept met twee bestandsnamen. Claude Code leest CLAUDE.md en negeert AGENTS.md tenzij u ze koppelt. Houd één bestand aan als bron van waarheid en koppel het andere daaraan, bijvoorbeeld met een regel @AGENTS.md bovenaan uw CLAUDE.md of met ln -s AGENTS.md CLAUDE.md. Twee volledige kopieën die afzonderlijk worden onderhouden, wijken binnen een maand van elkaar af.

Garandeert het schrijven van een AGENTS.md dat de agent de instructies volgt?

Nee. De inhoud wordt als context doorgegeven. Het model leest deze dus en volgt de instructies doorgaans op, maar niets blokkeert een actie die ermee in strijd is. Vage instructies worden het minst betrouwbaar opgevolgd. Als twee bestanden tegengestelde instructies geven, kiest de agent willekeurig een van beide. Gebruik voor een regel die altijd moet gelden een hook of een permission rule. Deze worden door de client afgedwongen, ongeacht de beslissing van het model.

Moet AGENTS.md aan git worden toegevoegd?

Ja, voor alles wat voor het project geldt, zoals buildopdrachten, de indeling en conventies. Dat is het doel van het bestand: de agents van uw team starten dan met dezelfde context als uw agent. Persoonlijke informatie of informatie die specifiek is voor één machine hoort in een afzonderlijk bestand dat door git wordt genegeerd. Credentials horen in geen van beide.

Wat is HUMAN.md en heb ik er een nodig?

HUMAN.md is een machineleesbaar profiel van een persoon, niet van een project. Het bevat uw rol, uw beperkingen en de beslissingen die u al hebt genomen, zodat die niet in elke sessie opnieuw ter discussie worden gesteld. U hebt geen tooling nodig om te beginnen: twintig zelfgeschreven regels in uw instructiebestand op gebruikersniveau leveren het grootste deel van de waarde. Behandel dit als persoonlijke gegevens en houd het buiten elke repository die u pusht.