AGENTS.md is useful, but it cannot govern coding agents alone

At a glance

What this is: Sonar argues that AGENTS.md is useful operational documentation for coding agents, but it is not a governance mechanism for architecture, security posture, or task-specific judgment.

Why it matters: This matters because IAM, NHI, and security teams increasingly rely on agent workflows, and those workflows need enforceable, current controls rather than static prose instructions.

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.

👉 Read Sonar's analysis of why AGENTS.md cannot govern coding agents alone

Context

AGENTS.md solves a real problem: it gives coding agents a predictable place to find stable project instructions. The governance gap appears when teams expect a Markdown file to carry architecture rules, security considerations, and changing coding standards that need to be current at the moment of action. For identity and security teams, that is the same distinction seen in NHI governance: documentation helps, but it does not enforce.

In practical terms, static instructions can describe desired behaviour, but they do not prove that the agent is acting within approved boundaries. That becomes more important as coding agents interact with secrets, deployment workflows, and code paths that shape authentication, access control, and runtime trust. Sonar’s argument is strongest where agent behaviour intersects with security-sensitive development work.

The article’s starting position is typical for modern engineering teams: they have one artifact for guidance and another for reality, and the two drift apart.

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. The most reliable model is layered: a short instruction file, live repository analysis, and verification checks that operate on the specific change. That approach governs behaviour at the moment it matters, rather than hoping prose survives context drift.

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. Static files also depend on humans to keep them current, so the written policy drifts away from the codebase. The result is a weaker control even when the document looks more complete.

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. That lets the model reason from live structure instead of generic prose about layering or reuse. For security teams, this is especially important when the change touches secrets handling, authentication, or privileged workflows.

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.

Technical breakdown

Why static prompt files fail as governance

AGENTS.md is plain Markdown, which makes it easy to adopt but hard to govern. It can store conventions and reminders, but it cannot express machine-checkable policy, control dependencies, or live architectural constraints. That means the file depends on human upkeep, while the codebase changes continuously. In security terms, it is documentation of intent, not a runtime control. When teams ask it to carry security posture or reuse rules, they are assuming the model will consistently interpret prose as enforceable policy, which is not how probabilistic systems work.

Practical implication: Use AGENTS.md for stable instructions, but move security-critical constraints into structured, task-scoped controls.

How context length undermines long instruction files

Large context windows do not solve instruction quality. Research cited by Sonar shows that relevant information is most reliably used near the start or end of the prompt and becomes less dependable in the middle. That matters because AGENTS.md tends to grow as teams add exceptions, style notes, and security cautions. The result is a longer file with weaker effective control. For agents, that means the most important rule may be the one least likely to influence generation at the right moment.

Practical implication: Keep agent instructions short and task-specific, then deliver deeper policy context only when the change requires it.

Why structured code intelligence beats prose for secure development

Sonar’s core point is that agents need analysis-derived context, not just written guidance. Structured inputs such as dependency maps, semantic code navigation, and current architecture relationships let the system align its output with the repository’s actual state. That is especially relevant when code changes affect secrets handling, authentication flows, or workload identity boundaries. A prose file can say 'reuse existing utilities,' but structured context can point the agent to the exact approved path and surrounding dependencies.

Practical implication: Pair agent instructions with live repository analysis so security-relevant code paths are surfaced before generation.

NHI Mgmt Group analysis

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.

Instruction drift is the named failure mode here: guidance lag. The article describes a recurring condition where human-written agent instructions remain static while code, standards, and risk posture change. That creates a gap between the policy teams think exists and the behaviour the agent actually sees. For security programmes, the practical conclusion is to reduce dependence on memory-based policy and move toward structured, analysed context that refreshes with the repository.

Large context is not a substitute for precision. Sonar’s cited research on long-context degradation reinforces a broader control lesson: adding more text does not reliably increase compliance. Teams that keep expanding prompt files to capture exceptions often make the most important guidance less visible to the model. Practitioners should optimise for task relevance, not document length, especially where agent decisions can affect code security and identity handling.

Coding agents need current repository truth, not editorial intent. The article’s strongest insight is that agent reliability improves when the system is given the actual architecture, dependency relationships, and relevant code locations at generation time. That approach aligns better with secure software engineering and with identity governance patterns that rely on live state rather than static declaration. The lesson for practitioners is to govern the context pipeline, not just the instruction file.

AI coding governance will increasingly look like control composition. Static instructions, semantic retrieval, dependency analysis, and verification checks each solve a different part of the problem, but none is sufficient alone. That is the direction the market is moving: from 'write a file' to 'assemble a governed context.' For teams running identity-sensitive software, that shift will matter more than the syntax of the instruction file.

What this signals

Guidance drift will become a larger problem as coding agents move deeper into software delivery. Teams will need to govern the context layer, not just the instruction layer, because the security risk is no longer limited to what a file says but to what the model actually receives and uses.

The operational pattern is moving toward structured context plus verification. That aligns with how identity programmes already work: policies matter, but live state, approvals, and enforcement determine whether the control is real. For agentic workflows, the same principle now applies to code security and privileged change paths.

For practitioners

• 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.
• Use repository analysis to surface the right code paths Provide semantic navigation and live architecture relationships so the agent can identify approved dependencies and affected locations by meaning, not just search terms.

Key takeaways

• AGENTS.md is valuable for stable project instructions, but it cannot carry live governance, architecture, or security enforcement on its own.
• Longer instruction files and static prose both weaken agent reliability when the codebase and risk posture keep changing.
• Security teams should govern the context pipeline with structured, current repository intelligence instead of assuming written guidance will hold.

Key terms

• AGENTS.md: A project-level instruction file that an AI coding agent may load before handling a task. In autonomous workflows it behaves like executable context, so any command, path, or setup step inside it must be treated as potentially adversarial until reviewed and approved.
• Context Augmentation: A pattern for injecting only the most relevant information into an AI agent’s working context before it acts. In security workflows, it is used to reduce noise, constrain tool use, and make the agent’s next step more efficient and more predictable.
• Instruction drift: Instruction drift is the gradual change in how an agent ranks or interprets instructions after repeated interactions. It matters because the agent can begin to prefer conditioned context over original policy, creating a slow governance failure that is difficult to detect in a single review cycle.
• Semantic Navigation: Semantic navigation is the use of code relationships such as call stacks, hierarchies, references, and source locations to help an AI agent understand a codebase. It is more reliable than simple string search because it reflects how the software actually connects, not just how text appears in files.

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

👉 Sonar's full article expands the context-augmentation model and the limits of static agent instructions

Deepen your knowledge

The NHI Foundation Level course, the industry's only accredited NHI security programme, covers NHI governance, workload identity, and secrets management for practitioners who need stronger control over machine and agent access patterns. It helps security and identity teams build the governance habits that modern software delivery now depends on.