{"slug": "agents-md-is-advisory-here-s-what-it-takes-to-make-it-executable", "title": "AGENTS.md is advisory. Here's what it takes to make it executable", "summary": "A developer proposes making AGENTS.md files executable by linking documentation claims to automated tests. The approach uses test suites that verify enforcement rules and a pre-push hook that rejects commits where the document's claims no longer match reality. The developer's own repository demonstrates this with a self-auditing AGENTS.md that fails specific claims when rules are removed.", "body_md": "AGENTS.md is a great convention: one predictable place where a coding agent learns your build commands, style, and boundaries. Over 60k open-source projects ship one.\n\nBut look at what the format actually promises. From the official FAQ at [agents.md](https://agents.md/): \"AGENTS.md is just standard Markdown. Use any headings you like; the agent simply parses the text you provide.\" And: \"Treat AGENTS.md as living documentation.\"\n\n*Parses the text.* Nothing checks whether the text is true, and nothing fails when the agent ignores it. Every claim in your AGENTS.md (\"we never read `process.env`\n\ndirectly\", \"these rules auto-load\", \"run make self-audit\") is prose. Prose drifts. Agents skip prose under context pressure, and nobody notices, because a document that lies looks exactly like a document that doesn't.\n\nDocs lie; tests don't. So what does it take to make an AGENTS.md that *can't* lie?\n\nThree properties, each mechanical:\n\nThis is not a mock-up. It's the root [ AGENTS.md](https://github.com/artyhoo/getff/blob/main/AGENTS.md) of the getff repo.\n\n**Claim 1, AGENTS.md:76:** \"Read configuration through the injected config accessor, never\n\n`std::env::var`\n\ndirectly\" carries the line:\n\n```\n> Enforced: cargo-clippy-toml ✅ · npm-eslint-declarative — FF7001 (typed rules are not\n> expressible in the no-restricted-syntax declarative class; route to a type-aware backend)\n```\n\nThe ✅ isn't decoration. `packages/core/composition/demo/root-agents-demo.test.ts:97`\n\nbacks it with the live-fired cell of the cargo capability matrix. And note the second half: where the npm backend *can't* enforce it, the doc says so with an error code (FF7001) instead of pretending.\n\n**Claim 2, AGENTS.md:82:** the mirror convention for TypeScript (\"never\n\n`process.env`\n\ndirectly\") is enforced by the ESLint backend. The test at `root-agents-demo.test.ts:73`\n\nfeeds the \"Never (fires)\" example (`const url = process.env.DATABASE_URL;`\n\n) to the real generated `no-restricted-syntax`\n\nrule and asserts it fires; `:86`\n\nasserts the \"Always (clean)\" accessor form stays silent. If someone edits the example into something the rule no longer catches, the suite goes red.**Claim 3, AGENTS.md:26-51:** the rule index (20 rules, each with class and enforcement channel) sits inside a generated region.\n\n`scripts/render-rule-index.mjs --check`\n\nre-renders it from the actual rule files and exits 1 on any drift, wired into the pre-push hook (`packages/core/hooks/pre-push.ts:792-799`\n\n). You physically can't push an AGENTS.md whose rule table disagrees with the rules on disk.On top of all three sits a ratchet: `root-agents-demo.test.ts:41`\n\nre-composes the whole demo region and requires the committed bytes to be equal. One `make self-audit`\n\n(`Makefile:3`\n\n) runs the lot.\n\nComment out the rule a claim references, run `make self-audit`\n\n, and the gate fails naming the specific claim: not \"docs may be stale\", but \"this enforcement line no longer matches reality\".\n\nThe point isn't the tooling; it's the inversion. In a normal repo, the doc describes the checks and rots independently of them. Here the doc is *downstream* of the checks: enforcement status is derived from live outcomes, so the earliest reachable channel (pre-push, not a human reader six weeks later) catches the lie.\n\nThis works today on our own repository: the executable AGENTS.md you can open and audit is ours. Generating *your* executable AGENTS.md from *your* conventions is the next milestone, not a shipped feature.", "url": "https://wpnews.pro/news/agents-md-is-advisory-here-s-what-it-takes-to-make-it-executable", "canonical_source": "https://dev.to/artyhoo/agentsmd-is-advisory-heres-what-it-takes-to-make-it-executable-111a", "published_at": "2026-07-10 17:48:36+00:00", "updated_at": "2026-07-10 18:15:04.554816+00:00", "lang": "en", "topics": ["developer-tools", "ai-agents", "mlops"], "entities": ["AGENTS.md", "getff", "ESLint", "cargo-clippy", "TypeScript"], "alternates": {"html": "https://wpnews.pro/news/agents-md-is-advisory-here-s-what-it-takes-to-make-it-executable", "markdown": "https://wpnews.pro/news/agents-md-is-advisory-here-s-what-it-takes-to-make-it-executable.md", "text": "https://wpnews.pro/news/agents-md-is-advisory-here-s-what-it-takes-to-make-it-executable.txt", "jsonld": "https://wpnews.pro/news/agents-md-is-advisory-here-s-what-it-takes-to-make-it-executable.jsonld"}}