Topic starter
16/09/2026 9:21 am
TL;DR: AGENTS.md is an effective place for stable project instructions, but Sonar argues it cannot govern coding agents because static prose, long contexts, and probabilistic instruction-following all undermine reliable policy enforcement. The gap matters to identity and security teams because guidance for secure coding, architecture, and reuse must be structured and current, not merely documented.
Editorial analysis by NHI Mgmt Group, based on content published by Sonar: “AGENTS.md is a workaround, not a solution”.
Key questions
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.
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.
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.
Explore further
View Full Forum → | NHI Foundation Course → | Our Services → | Read the full analysis →
16/09/2026 9:21 am
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