标签：#agentsmd

Overview AGENTS.md is useful. It gives AI coding agents a place to find repo-specific guidance: how to behave what conventions matter what areas need extra caution what kinds of changes should trigger review That is a meaningful improvement over sending an agent into a repo with no instructions at all. But AGENTS.md is not enough. It can tell an agent to be careful. It cannot, by itself, make execution safe, verification trustworthy, or review inspectable. For that, a repository needs more than instructions. It needs: declared safe commands a canonical verification path receipts that show what actually ran That is the difference between agent guidance and execution governance. Instructions Help. They Do Not Govern Execution. An instruction file is still prose. That means it can express intent, but it does not automatically create operational truth. For example, AGENTS.md can say: run the right checks before handoff avoid destructive commands do not edit generated files ask before touching infrastructure Those are good rules. But notice what they leave unresolved: which checks are the right ones which commands are actually safe which paths are protected structurally versus only suggested what should count as evidence that verification happened how to tell whether a failure came from code, setup, or drift That is where many agent workflows still break down. The agent may follow the spirit of the instructions and still take the wrong execution path. Safe Commands Need To Be Explicit One of the biggest gaps in agent-oriented repos is that they often declare guidance without declaring a safe command surface. The repo may tell the agent: Run tests before you finish. But that still leaves a dangerous amount of interpretation. Which task is safe? Is it: npm test pnpm test make check docker compose run test a narrower unit-test path the CI workflow itself And if several exist, which one is canonical for a routine code change? The repo should not force the agent to infer that