In Claude Code (versie 2.1.277+) is de ondersteuning voor het bestand AGENTS.md afhankelijk van een remote feature flag. Wanneer telemetrie of niet-essentieel verkeer is uitgeschakeld (via variabelen zoals DISABLE_TELEMETRY=1), wordt het lokale bestand genegeerd zonder dat er een waarschuwing verschijnt.
De auteur heeft dit bevestigd met tests waarbij 'kanarie-woorden' in AGENTS.md niet werden herkend bij uitgeschakelde telemetrie. Als workaround kan men een eénregelige CLAUDE.md aanmaken met de inhoud @AGENTS.md om het bestand alsnog te laden.
De auteur vindt het onacceptabel dat een privacy-instelling stilletjes lokaal gedrag uitschakelt. Er wordt gepleit voor:
- Het loskoppelen van lokale bestandsfuncties van telemetrie.
- Zichtbare waarschuwingen wanneer bestanden worden overgeslagen.
- De implementatie van een globale
AGENTS.md en natieve ondersteuning voor gedeelde agent-skills.
Claude Code leest AGENTS.md alleen wanneer telemetrie is ingeschakeld
Claude Code 2.1.277 kondigde ondersteuning aan voor AGENTS.md. In een project zonder CLAUDE.md zou het programma in plaats daarvan AGENTS.md moeten lezen. Ik heb telemetrie in mijn shell uitgeschakeld, en in mijn repositories werd het bestand nooit geladen. Issue #95690 legt uit waarom; ik heb mijn eigen metingen aan dit issue toegevoegd. Dit artikel verzamelt deze bevindingen op één plek.
Waar de blokkade zit
De loader wordt geleverd als een ingebouwde plugin genaamd agents-md. De registratie in het 2.1.280-bundel ziet er als volgt uit:
var W = !1;
var B = () => Oa("tengu_agents_md_mod", W);
var H = "AGENTS.md as project instructions: by default loaded where the project has no CLAUDE.md; ...";
Hierbij is W de isOnByDefault-waarde van de plugin en deze is false. B is isAvailable en vraagt naar een remote feature flag genaamd tenguagentsmd_mod, met false als fallback. Wanneer Claude Code de flag niet kan ophalen, is de plugin niet beschikbaar en wordt het lokale bestand nooit gelezen. Het lezen van een Markdown-bestand uit de werkmap vereist helemaal geen netwerkverbinding, maar in dit geval wacht het systeem op een server-side schakelaar.
Hoe ik het heb getest
Ik heb een lege map aangemaakt die alleen een AGENTS.md bevat met een "kanarie-woord" (testwoord), en ik heb claude -p gevraagd naar dat woord. Elke setup werd in twee sessies uitgevoerd, omdat de eerste sessie in een nieuwe configuratie alleen de flag ophaalt en de tweede sessie deze gebruikt.
echo 'The canary word is PERIWINKLE.' > AGENTS.md
claude -p 'What is the canary word from the project instructions? Answer NONE if you have none. Do not read files.'
Wat ik heb gemeten
CLAUDECODEDISABLENONESSENTIALTRAFFIC=1 blokkeert de functie, zoals in het issue wordt vermeld.DISABLE_TELEMETRY=1 blokkeert dit ook. Met een van beide variabelen ingesteld werd AGENTS.md nooit geladen; ik moest beide wissen.- Het instellen van een van beide variabelen op
0 helpt niet. De blokkade blijft bestaan. De documentatie over omgevingsvariabelen stelt dat elke waarde telt, maar dat is makkelijk over het hoofd te zien wanneer je probeert een functie in te schakelen.
- Een
env-blok in het .claude/settings.json van het project dat beide variabelen wist, had geen effect. Er is geen manier om de functie voor een enkele repo in te schakelen.
- Een override op sessieniveau werkt wel vanaf de tweede sessie:
claude --settings '{"env":{"DISABLE_TELEMETRY":"","CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC":""}}'
In geen van deze gevallen wordt er een waarschuwing geprint. De sessie start, het model antwoordt zonder de projectinstructies, en er is niets dat aangeeft dat een bestand is overgeslagen. Het issue wijst er ook op dat third-party gateways, Bedrock en Vertex hetzelfde probleem hebben, omdat de flag daar ook niet op true kan worden gezet.
De workaround
CLAUDE.md ondersteunt @path-imports, en deze zijn niet afhankelijk van de flag. Een eénregelige CLAUDE.md naast de AGENTS.md laadt deze terwijl telemetrie uitgeschakeld is:
echo '@AGENTS.md' > CLAUDE.md
Met dit bestand aanwezig geeft dezelfde kanarie-test het woord terug, zelfs wanneer CLAUDECODEDISABLENONESSENTIALTRAFFIC=1 nog steeds is ingesteld. De prijs is één extra bestand per repo, wat precies is wat de ondersteuning voor AGENTS.md had moeten wegnemen.
Waarom ik dit onacceptabel vind
Ik heb telemetrie bewust uitgeschakeld, en ik verwacht dat die keuze me enkel kost aan diagnostische gegevens en niets anders. Hier kost het me stilletjes een functie die een bestand van mijn eigen schijf leest. Een remote flag kan zinvol zijn voor een functie die met een server communiceert, maar de enige input die deze functie nodig heeft, bevindt zich al in de werkmap.
De blokkade raakt bovendien de mensen die waarschijnlijk het meeste baat hebben bij AGENTS.md. Iemand die één instructiebestand voor meerdere agents bijhoudt, is meestal voorzichtig met wat elk hulpprogramma naar huis stuurt, en teams op Bedrock, Vertex of een gateway schakelen niet-essentieel verkeer vaak uit vanwege het bedrijfsbeleid. Zij krijgen allemaal een functie die als beschikbaar wordt aangekondigd, maar vervolgens niets doet.
De stilte is het ergste deel. Ik heb de oorzaak bevestigd met een kanarie-woord en een zoekopdracht door het binary-bestand, maar de meeste mensen zullen dat niet doen. Zij zullen concluderen dat het model hun instructies negeert en tijd verspillen aan prompts, terwijl het bestand in eerste instantie nooit het model heeft bereikt.
Een privacy-instelling zou nooit stilletjes ongerelateerd lokaal gedrag moeten uitschakelen. Als Anthropic een gefaseerde uitrol wil, zou de fallback voor een flag die niet kan worden opgehaald het gedocumenteerde gedrag moeten zijn, of in ieder geval een zichtbaar bericht dat aangeeft wat is overgeslagen en waarom.
Wat ik zou willen zien
Het lezen van een lokaal bestand zou niet afhankelijk moeten zijn van telemetrie. Als de blokkade moet blijven voor een geleidelijke uitrol, zou een waarschuwing bij het opstarten — wanneer een AGENTS.md aanwezig is maar wordt overgeslagen — mensen de tijd besparen die ik aan de kanarie-test heb besteed.
Een globale AGENTS.md. De plugin zoekt alleen naar AGENTS.md en .claude/AGENTS.md in projectmappen; er is geen gebruikersbestand naast de gebruikers-CLAUDE.md. Codex leest een globale ~/.codex/AGENTS.md, en het /import-commando in Claude Code kan dit kopiëren naar de gebruikers-CLAUDE.md, maar de kopie volgt latere bewerkingen niet. Als je één set persoonlijke instructies voor meerdere agents bijhoudt, heb je nog steeds een @-import nodig in de gebruikers-CLAUDE.md die naar het gedeelde bestand wijst.
Natieve ondersteuning voor gedeelde agent-skills. Codex leest skills uit .agents/skills in het project en uit ~/.agents/skills in de home-directory. Claude Code 2.1.280 kent die paden alleen in /import, wat de skills kopieert naar .claude/skills. Ik heb een kanarie-skill in .agents/skills geplaatst en Claude Code lijstte deze niet op, maar hij lijstte dezelfde skill uit .claude/skills in dezelfde repo wel. Een kopie wijkt af van de bron, dus ik link .claude/skills naar ../.agents/skills via een symlink, en Claude Code volgt die symlink.
Tot die tijd gebruik ik de eénregelige CLAUDE.md voor instructies en een symlink voor skills.
Claude Code leest AGENTS.md alleen wanneer telemetrie is ingeschakeld
Claude Code 2.1.277 kondigde ondersteuning aan voor AGENTS.md. In een project zonder CLAUDE.md zou het programma in plaats daarvan AGENTS.md moeten lezen. Ik heb telemetrie in mijn shell uitgeschakeld, en in mijn repositories werd het bestand nooit geladen. Issue #95690 legt uit waarom; ik heb mijn eigen metingen aan dit issue toegevoegd. Dit artikel verzamelt deze bevindingen op één plek.
Waar de blokkade zit
De loader wordt geleverd als een ingebouwde plugin genaamd agents-md. De registratie in het 2.1.280-bundel ziet er als volgt uit:
var W = !1;
var B = () => Oa("tengu_agents_md_mod", W);
var H = "AGENTS.md as project instructions: by default loaded where the project has no CLAUDE.md; ...";
Hierbij is W de isOnByDefault-waarde van de plugin en deze is false. B is isAvailable en vraagt naar een remote feature flag genaamd tenguagentsmd_mod, met false als fallback. Wanneer Claude Code de flag niet kan ophalen, is de plugin niet beschikbaar en wordt het lokale bestand nooit gelezen. Het lezen van een Markdown-bestand uit de werkmap vereist helemaal geen netwerkverbinding, maar in dit geval wacht het systeem op een server-side schakelaar.
Hoe ik het heb getest
Ik heb een lege map aangemaakt die alleen een AGENTS.md bevat met een "kanarie-woord" (testwoord), en ik heb claude -p gevraagd naar dat woord. Elke setup werd in twee sessies uitgevoerd, omdat de eerste sessie in een nieuwe configuratie alleen de flag ophaalt en de tweede sessie deze gebruikt.
echo 'The canary word is PERIWINKLE.' > AGENTS.md
claude -p 'What is the canary word from the project instructions? Answer NONE if you have none. Do not read files.'
Wat ik heb gemeten
CLAUDECODEDISABLENONESSENTIALTRAFFIC=1 blokkeert de functie, zoals in het issue wordt vermeld.DISABLE_TELEMETRY=1 blokkeert dit ook. Met een van beide variabelen ingesteld werd AGENTS.md nooit geladen; ik moest beide wissen.- Het instellen van een van beide variabelen op
0 helpt niet. De blokkade blijft bestaan. De documentatie over omgevingsvariabelen stelt dat elke waarde telt, maar dat is makkelijk over het hoofd te zien wanneer je probeert een functie in te schakelen.
- Een
env-blok in het .claude/settings.json van het project dat beide variabelen wist, had geen effect. Er is geen manier om de functie voor een enkele repo in te schakelen.
- Een override op sessieniveau werkt wel vanaf de tweede sessie:
claude --settings '{"env":{"DISABLE_TELEMETRY":"","CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC":""}}'
In geen van deze gevallen wordt er een waarschuwing geprint. De sessie start, het model antwoordt zonder de projectinstructies, en er is niets dat aangeeft dat een bestand is overgeslagen. Het issue wijst er ook op dat third-party gateways, Bedrock en Vertex hetzelfde probleem hebben, omdat de flag daar ook niet op true kan worden gezet.
De workaround
CLAUDE.md ondersteunt @path-imports, en deze zijn niet afhankelijk van de flag. Een eénregelige CLAUDE.md naast de AGENTS.md laadt deze terwijl telemetrie uitgeschakeld is:
echo '@AGENTS.md' > CLAUDE.md
Met dit bestand aanwezig geeft dezelfde kanarie-test het woord terug, zelfs wanneer CLAUDECODEDISABLENONESSENTIALTRAFFIC=1 nog steeds is ingesteld. De prijs is één extra bestand per repo, wat precies is wat de ondersteuning voor AGENTS.md had moeten wegnemen.
Waarom ik dit onacceptabel vind
Ik heb telemetrie bewust uitgeschakeld, en ik verwacht dat die keuze me enkel kost aan diagnostische gegevens en niets anders. Hier kost het me stilletjes een functie die een bestand van mijn eigen schijf leest. Een remote flag kan zinvol zijn voor een functie die met een server communiceert, maar de enige input die deze functie nodig heeft, bevindt zich al in de werkmap.
De blokkade raakt bovendien de mensen die waarschijnlijk het meeste baat hebben bij AGENTS.md. Iemand die één instructiebestand voor meerdere agents bijhoudt, is meestal voorzichtig met wat elk hulpprogramma naar huis stuurt, en teams op Bedrock, Vertex of een gateway schakelen niet-essentieel verkeer vaak uit vanwege het bedrijfsbeleid. Zij krijgen allemaal een functie die als beschikbaar wordt aangekondigd, maar vervolgens niets doet.
De stilte is het ergste deel. Ik heb de oorzaak bevestigd met een kanarie-woord en een zoekopdracht door het binary-bestand, maar de meeste mensen zullen dat niet doen. Zij zullen concluderen dat het model hun instructies negeert en tijd verspillen aan prompts, terwijl het bestand in eerste instantie nooit het model heeft bereikt.
Een privacy-instelling zou nooit stilletjes ongerelateerd lokaal gedrag moeten uitschakelen. Als Anthropic een gefaseerde uitrol wil, zou de fallback voor een flag die niet kan worden opgehaald het gedocumenteerde gedrag moeten zijn, of in ieder geval een zichtbaar bericht dat aangeeft wat is overgeslagen en waarom.
Wat ik zou willen zien
Het lezen van een lokaal bestand zou niet afhankelijk moeten zijn van telemetrie. Als de blokkade moet blijven voor een geleidelijke uitrol, zou een waarschuwing bij het opstarten — wanneer een AGENTS.md aanwezig is maar wordt overgeslagen — mensen de tijd besparen die ik aan de kanarie-test heb besteed.
Een globale AGENTS.md. De plugin zoekt alleen naar AGENTS.md en .claude/AGENTS.md in projectmappen; er is geen gebruikersbestand naast de gebruikers-CLAUDE.md. Codex leest een globale ~/.codex/AGENTS.md, en het /import-commando in Claude Code kan dit kopiëren naar de gebruikers-CLAUDE.md, maar de kopie volgt latere bewerkingen niet. Als je één set persoonlijke instructies voor meerdere agents bijhoudt, heb je nog steeds een @-import nodig in de gebruikers-CLAUDE.md die naar het gedeelde bestand wijst.
Natieve ondersteuning voor gedeelde agent-skills. Codex leest skills uit .agents/skills in het project en uit ~/.agents/skills in de home-directory. Claude Code 2.1.280 kent die paden alleen in /import, wat de skills kopieert naar .claude/skills. Ik heb een kanarie-skill in .agents/skills geplaatst en Claude Code lijstte deze niet op, maar hij lijstte dezelfde skill uit .claude/skills in dezelfde repo wel. Een kopie wijkt af van de bron, dus ik link .claude/skills naar ../.agents/skills via een symlink, en Claude Code volgt die symlink.
Tot die tijd gebruik ik de eénregelige CLAUDE.md voor instructies en een symlink voor skills.
Groetjes,