Notifications
Clear all
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.
NHIMG editorial — based on content published by Sonar: AGENTS.md has won the fight to become the standard place to brief a coding agent
By the numbers:
- The 2024 Lost in the Middle study found that performance degrades when relevant information sits in the middle of long contexts, even for long-context models.
- Chroma’s Context Rot report evaluated 18 leading models and found context use becomes increasingly unreliable as input length grows.
Questions worth separating out
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 do long agent instruction files become less effective over time?
A: Because instruction quality degrades as context grows and the most important guidance can end up buried in the middle of a long file.
Q: How can security teams keep AI coding agents aligned with architecture rules?
A: Give the agent the current architecture graph, intended dependency relationships, and the specific files affected by the change.
Practitioner guidance
- Treat AGENTS.md as project guidance, not a control boundary Keep stable build, test, and contribution instructions there, but do not rely on it to enforce security rules, architecture decisions, or code reuse requirements.
- Move security-sensitive rules into structured task context Deliver access, dependency, and architecture constraints at generation time so the agent receives the right policy for the specific change it is making.
- Limit instruction-file size and exception sprawl Remove duplicated style notes, edge-case instructions, and outdated warnings so the file stays short enough to be read and retained reliably.
What's in the full article
Sonar's full article covers the operational detail this post intentionally leaves for the source:
- The exact AGENTS.md limitations Sonar identifies in long-context coding workflows
- The research-backed explanation of why prompt files lose effectiveness as they grow
- The Agent Centric Development Cycle context augmentation model and its four stages
- The practical difference between static agent guidance and analysis-derived repository context
👉 Read Sonar's analysis of why AGENTS.md cannot govern coding agents alone →
AGENTS.md and coding agents: where the governance gap starts?
Explore further
16/09/2026 9:21 am
AGENTS.md is a control approximation, not a governance layer. It is useful for stable instructions, but security and architecture drift faster than prose files can be maintained. That distinction matters in identity-adjacent development, where agents may touch secrets, auth flows, or workload access patterns that need current constraints, not remembered guidance. Practitioners should treat the file as documentation, not enforcement.
A question worth separating out:
Q: What should engineering leaders do first when agent guidance is scattered across files?
A: Start by trimming AGENTS.md down to stable, universal instructions such as build steps, test commands, and contribution format. Then identify the controls that must be task-specific, such as security posture, code ownership, or approved module paths, and deliver those through structured context rather than a growing prose file.
👉 Read our full editorial: AGENTS.md is useful, but it cannot govern coding agents alone
