TL;DR: Static AGENTS.md guidance helps with stable project rules, but it cannot reliably enforce architecture, security, or reuse decisions as code changes, according to Sonar. Long files and probabilistic instruction-following let important rules drift out of view, weakening governance at the point of change.
Editorial analysis by NHI Mgmt Group, based on content published by Sonar: “AGENTS.md is a workaround, not a solution”.
Key questions
Q: Why does a long instruction file create more risk for coding agents?
A: Long instruction files increase the chance that important rules are buried in the middle of the context window, where models are less reliable.
Q: What breaks when teams treat AGENTS.md as their security control?
A: The control becomes documentary rather than operational.
Q: How should teams govern coding agents if AGENTS.md is not enough?
A: Use AGENTS.md for stable project instructions, then add structured, task-scoped controls for architecture, security, and dependency decisions.
Practitioner guidance
- Use AGENTS.md for stable operating facts Keep installation steps, test commands, and repository-specific workflow rules in AGENTS.md, but limit it to information that changes slowly and is genuinely useful across edits.
- Move security and architecture rules into structured context Provide coding agents with analysed architecture maps, secure coding guidance, and task-scoped policy data at generation time instead of relying on prose paragraphs.
- Shorten instruction files before they lose force Review long AGENTS.md files for buried exceptions, repeated guidance, and rules that should be delivered through tooling rather than maintained as text.
Bottom line: AGENTS.md is useful for stable project instructions, but it does not reliably enforce architecture, security, or reuse decisions as code changes.
Glossary terms: Coding Agent, Schema Context, Instruction drift, Context rot
Explore further
View Full Forum → | NHI Foundation Course → | Our Services → | Read the full analysis →
AGENTS.md creates governance theatre when teams mistake documentation for control. A file of prose can coordinate routine behaviour, but it cannot enforce architecture boundaries, secure reuse, or current policy across a changing repository. That makes it a useful companion to governance, not the governance layer itself. For practitioners, the risk is assuming compliance because instructions exist, when the real question is whether the control is structurally available to the agent at decision time.
A few things that frame the scale:
- Claude Code-assisted commits leaked secrets at a rate of 3.2%, more than double the human-only baseline of 1.5%, with peaks reaching 31 secrets per 1,000 commits in August 2025, according to the State of Secrets Sprawl 2026.
A question worth separating out:
Q: What is the difference between agent instructions and structured context?
A: Agent instructions are static prose that describes expectations, while structured context is analysed, current, and task-specific information delivered when the agent acts. The first helps orient behaviour. The second is what makes governance repeatable, because it reflects the codebase and the task rather than a remembered policy.
👉 Read our full editorial: AGENTS.md is useful, but it cannot govern coding agents alone