{"slug": "what-agents-md-can-and-can-t-enforce", "title": "What AGENTS.md Can and Can't Enforce", "summary": "A closed feature request on Anthropic's Claude Code repository asking the tool to support the open AGENTS.md format instead of its own CLAUDE.md drew 181 points and 103 comments on Hacker News, with commenters arguing the real issue is reliability, not format. The request, filed as issue #6235, noted that Codex, Amp, Cursor, and Jules are standardizing on AGENTS.md, stewarded by the Agentic AI Foundation under the Linux Foundation. Commenters pointed out workarounds like symlinks or one-line references, but reported that Claude Code can randomly ignore instructions in referenced files, highlighting that markdown files are prompts followed probabilistically, not deterministically.", "body_md": "Articles\n\n# What AGENTS.md Can and Can't Enforce\n\nA closed Claude Code feature request to support AGENTS.md drew 181 points and 103 comments on Hacker News, and the thread's best argument was about reliability, not format.\n\n[The request](#the-request)\n\n[Issue #6235](https://github.com/anthropics/claude-code/issues/6235) on the `anthropics/claude-code`\n\nrepo asks for one thing: make Claude Code read `AGENTS.md`\n\n, the way Codex, Cursor, Jules, and a dozen other tools already do, instead of requiring its own `CLAUDE.md`\n\n. The original post is short:\n\nCodex, Amp, Cursor, and others are starting to standardize around AGENTS.md (https://agents.md/) - a unified Markdown file that coding agents can use to understand a codebase. By contrast, CLAUDE.md feels too specific to Claude Code. It doesn't work as well when collaborating with other developers who aren't using Claude Code.\n\nThe issue is closed, with no maintainer response recorded. It still reached [181 points and 103 comments on Hacker News](https://news.ycombinator.com/item?id=49367350), which is a lot of engagement for a request that sounds, on its face, like a config file rename.\n\n[What AGENTS.md actually is](#what-agents-md-actually-is)\n\nAGENTS.md is an open format stewarded by the Agentic AI Foundation under the Linux Foundation, with OpenAI Codex, Amp, Google Jules, Cursor, and Factory named as founding contributors. The file itself is plain Markdown with no required schema:\n\n```\n# AGENTS.md\n\n## Setup commands\n- Install deps: `pnpm install`\n- Start dev server: `pnpm dev`\n- Run tests: `pnpm test`\n\n## Code style\n- TypeScript strict mode\n- Single quotes, no semicolons\n- Use functional patterns where possible\n```\n\nThe pitch is straightforward: one file, read by whichever agent shows up, instead of a `CLAUDE.md`\n\nfor Claude Code, a `.cursorrules`\n\nfor Cursor, and separate setup for every other harness a team happens to use. Claude Code does not read `AGENTS.md`\n\non its own. It reads `CLAUDE.md`\n\n, and a developer can point one at the other with a symlink or a one-line `@AGENTS.md`\n\nreference.\n\n[The workaround undercuts the format, not the argument](#the-workaround-undercuts-the-format-not-the-argument)\n\nSeveral commenters pointed out that the fix is trivial. User chomp: \"My Claude.md has one line that says to read agents.md, this is a bit of a nothingburger.\" Others noted a symlink does the same job in one command.\n\nThat workaround is also the most interesting part of the thread, because it turns a format dispute into a reliability question. `@AGENTS.md`\n\n-style references and symlinks both add a layer of indirection between \"the instructions exist in the repo\" and \"the model actually read them this session.\" User superfrank reported exactly that gap in practice: a non-technical co-founder's `CLAUDE.md`\n\npoints at a shared instructions file, and \"Claude still will randomly ignore instructions in there,\" including basic things like PR naming conventions. Another commenter (wfurney) noted that `/clear`\n\npreserves `CLAUDE.md`\n\ncontext but drops indirectly-referenced files, so the same session can behave differently depending on when the reference file was loaded relative to a context reset.\n\nUser acedTrex cited an evaluation claiming most of what teams put in these files does not move agent output on real tasks. Whether or not that specific study holds up, it points at the same thing superfrank ran into directly: a markdown file is a prompt, and prompts are followed probabilistically, not deterministically.\n\n[What a markdown file can't do](#what-a-markdown-file-can-t-do)\n\nSet the format war aside. Whether it's `AGENTS.md`\n\nor `CLAUDE.md`\n\n, this class of file works the same way: it gets loaded into the model's context at some point in the session, and the model decides how much of it to honor. That mechanism has three properties worth naming plainly:\n\n**It depends on the file being loaded.** A subagent spawned mid-session, an agent invoked through the API directly rather than through the CLI's config-loading path, or a session that hits`/clear`\n\nat the wrong moment can all run without the instructions ever entering context.[Claude Code's own permission system has the same shape](/blog/how-claude-code-permissions-actually-work/)-`--dangerously-skip-permissions`\n\ndoes not check`CLAUDE.md`\n\neither, because there is nothing in the runtime that requires it to.**It depends on the model attending to it.** Even loaded correctly, an instruction competes with everything else in context. superfrank's report of \"randomly ignore\" is the expected behavior of a probabilistic reader, not a bug in one tool's implementation.**It is advisory by construction.** Nothing about a markdown file stops an agent from doing the thing the file says not to do. The file is content the model reads, not a check the runtime performs.\n\nNone of that makes AGENTS.md useless. Setup commands, code style, and \"here's how this repo is organized\" are exactly the kind of context a model benefits from having and suffers only mildly from missing. The failure mode is soft: worse suggestions, a style violation, a missed convention.\n\n[Where enforcement has to live instead](#where-enforcement-has-to-live-instead)\n\nThe distinction that matters is between instructions the model reads and rules the runtime checks. Say a team writes \"only call `api.internal.example.com`\n\n, nothing else\" into `AGENTS.md`\n\n. As a line of markdown, that rule holds exactly when the model both loaded the file and chose to comply with it, on every single tool call, for the life of the session. As a network-layer allowlist enforced by whatever sits between the agent and the internet, that rule holds regardless of context window state, regardless of whether the agent was invoked through a CLI or an SDK, and regardless of whether the model paid attention to that line.\n\nThat is the actual argument for pushing constraints out of the repo and onto the boundary the agent's traffic has to cross. A file the agent reads is a fine place to put things you want the agent to know. It is the wrong place to put anything you need to remain true whether or not the agent cooperates.", "url": "https://wpnews.pro/news/what-agents-md-can-and-can-t-enforce", "canonical_source": "https://rye.ai/blog/agents-md-cannot-enforce-anything/", "published_at": "2026-08-19 00:00:00+00:00", "updated_at": "2026-08-20 06:12:47.200874+00:00", "lang": "en", "topics": ["developer-tools", "ai-tools", "ai-agents"], "entities": ["Anthropic", "Claude Code", "OpenAI Codex", "Amp", "Cursor", "Jules"], "alternates": {"html": "https://wpnews.pro/news/what-agents-md-can-and-can-t-enforce", "markdown": "https://wpnews.pro/news/what-agents-md-can-and-can-t-enforce.md", "text": "https://wpnews.pro/news/what-agents-md-can-and-can-t-enforce.txt", "jsonld": "https://wpnews.pro/news/what-agents-md-can-and-can-t-enforce.jsonld"}}