{"slug": "agents-md-is-not-enough-for-safe-ai-agent-execution", "title": "AGENTS.md Is Not Enough for Safe AI Agent Execution", "summary": "A developer argues that AGENTS.md files, while useful for providing repo-specific guidance to AI coding agents, are insufficient for ensuring safe, verifiable, and inspectable agent execution. The post advocates for additional machine-readable declarations of safe commands, verification paths, and execution receipts to create a governance layer beyond mere instructions.", "body_md": "`AGENTS.md`\n\nis useful.\n\nIt gives AI coding agents a place to find repo-specific guidance:\n\nThat is a meaningful improvement over sending an agent into a repo with no instructions at all.\n\nBut `AGENTS.md`\n\nis not enough.\n\nIt can tell an agent to be careful.\n\nIt cannot, by itself, make execution safe, verification trustworthy, or review inspectable.\n\nFor that, a repository needs more than instructions.\n\nIt needs:\n\nThat is the difference between agent guidance and execution governance.\n\nAn instruction file is still prose.\n\nThat means it can express intent, but it does not automatically create operational truth.\n\nFor example, `AGENTS.md`\n\ncan say:\n\nThose are good rules.\n\nBut notice what they leave unresolved:\n\nThat is where many agent workflows still break down.\n\nThe agent may follow the spirit of the instructions and still take the wrong execution path.\n\nOne of the biggest gaps in agent-oriented repos is that they often declare guidance without declaring a safe command surface.\n\nThe repo may tell the agent:\n\nRun tests before you finish.\n\nBut that still leaves a dangerous amount of interpretation.\n\nWhich task is safe?\n\nIs it:\n\n`npm test`\n\n`pnpm test`\n\n`make check`\n\n`docker compose run test`\n\nAnd if several exist, which one is canonical for a routine code change?\n\nThe repo should not force the agent to infer that from scattered hints.\n\nIt should declare safe commands explicitly.\n\nThat means giving the repo a machine-readable answer to questions like:\n\nThat is much stronger than asking an agent to \"be careful\" around shell commands it still has to interpret.\n\nThe second gap is verification.\n\nMany repos still treat verification like a recommendation rather than a declared path.\n\nAn instruction file might say:\n\nMake sure everything still works before handoff.\n\nThat sounds fine, but it is too loose for reliable agent execution.\n\nA trustworthy repo should be able to say something more concrete:\n\nThat is the difference between advice and governance.\n\nWithout a declared verification path, the agent may:\n\nEven explicit commands and verification paths are still weaker than they should be if nothing\n\nrecords what actually ran.\n\nThis is where receipts matter.\n\nA verification receipt is the difference between:\n\nand:\n\nThat is the trust boundary most agent workflows still lack.\n\nReceipts help answer questions like:\n\nWithout receipts, review still depends too heavily on:\n\nWith receipts, verification becomes inspectable.\n\nA stronger repository keeps these layers distinct:\n\n`AGENTS.md`\n\nfor human-written behavioral guidanceFor example:\n\n```\n- Prefer small diffs.\n- Do not edit generated files manually.\n- Escalate before changing deployment or billing flows.\n- Use the declared verification path before handoff.\nagent:\n  safe_tasks:\n    - lint\n    - typecheck\n    - test\n  verify_after_changes:\n    - test\n\ntasks:\n  test:\n    command:\n      exe: pnpm\n      args: [test]\n    depends_on:\n      - setup\n\nworkflows:\n  verify:\n    setup:\n      task: setup\n    run:\n      task: test\n```\n\nAnd then the execution layer should be able to produce evidence rather than only output:\n\n```\nota run test --json\nota receipt --json --archive\n```\n\nThe exact tool does not matter as much as the structure:\n\nThat is the minimum shape of trustworthy agent execution.\n\nThis was already useful when agents mostly suggested edits.\n\nIt becomes much more important when agents are expected to:\n\nAt that point, the problem is no longer just \"does the agent have instructions?\"\n\nThe problem is whether the repo can expose:\n\nThat is a higher bar than `AGENTS.md`\n\nalone can satisfy.\n\nIf you only need the boundary between instructions and contracts, read:\n\nThis post is narrower.\n\nIts claim is not just that `AGENTS.md`\n\nand `ota.yaml`\n\ndo different jobs.\n\nIts claim is that even a good instruction file is still not enough unless the repo also declares:\n\n`AGENTS.md`\n\nis a good start.\n\nBut repo instructions alone do not make agent execution safe, reviewable, or trustworthy.\n\nTo get there, repositories also need:\n\nThat is how you move from:\n\nto:\n\nOriginal Post: [https://ota.run/blog/agents-md-is-not-enough-for-safe-ai-agent-execution](https://ota.run/blog/agents-md-is-not-enough-for-safe-ai-agent-execution)", "url": "https://wpnews.pro/news/agents-md-is-not-enough-for-safe-ai-agent-execution", "canonical_source": "https://dev.to/otaready/agentsmd-is-not-enough-for-safe-ai-agent-execution-1h3b", "published_at": "2026-06-30 21:24:04+00:00", "updated_at": "2026-06-30 21:48:33.907220+00:00", "lang": "en", "topics": ["ai-agents", "developer-tools", "ai-safety", "large-language-models"], "entities": ["AGENTS.md", "ota.yaml", "pnpm", "npm", "make", "docker compose"], "alternates": {"html": "https://wpnews.pro/news/agents-md-is-not-enough-for-safe-ai-agent-execution", "markdown": "https://wpnews.pro/news/agents-md-is-not-enough-for-safe-ai-agent-execution.md", "text": "https://wpnews.pro/news/agents-md-is-not-enough-for-safe-ai-agent-execution.txt", "jsonld": "https://wpnews.pro/news/agents-md-is-not-enough-for-safe-ai-agent-execution.jsonld"}}