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

At a glance

What this is: NHI Mgmt Group's analysis, drawing on Sonar's blog post: AGENTS.md works well for stable operational guidance, but fails as a governance mechanism for coding agents because prose cannot reliably carry architecture, security, and reuse decisions.

Why it matters: IAM, NHI, and AI governance teams should treat agent instructions as one input, not enforcement, because reliable control depends on structured, current context rather than static documentation.

Context

AGENTS.md is a project-level instruction file for coding agents, but it is not a control plane for policy enforcement. The core governance gap is that prose can document intent, yet it cannot reliably encode current architecture, task-specific security requirements, or reusable patterns in a way that survives changing code and long context windows.

For identity and security teams, that gap matters because coding agents behave like non-human actors operating inside software delivery pipelines. When their guidance is static and unstructured, the programme is left depending on memory, not governed context, which is a weak model for secure reuse, secure architecture, and consistent change control.

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 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. A larger AGENTS.md can therefore reduce compliance instead of improving it, because the agent may underweight the exact guidance the team cares about most.

Q: What breaks when teams treat AGENTS.md as their security control?

A: The control becomes documentary rather than operational. Teams may believe security guidance is enforced because it is written down, but the agent is still free to weight other cues, use stale instructions, or miss the rule entirely when the file is large and the task is specific.

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.

Technical breakdown

Why static instruction files lose precision over time

AGENTS.md is plain Markdown, so it can only provide text the model parses at generation time. That makes it useful for stable facts like how to run tests, but weak for evolving controls such as architecture rules, security exceptions, or repository-specific reuse guidance. As code changes, the file has to be maintained by hand, which creates drift between what the project is and what the agent is told. The problem is not the file format itself, but the mismatch between static prose and a living codebase.

Practical implication: Treat AGENTS.md as orientation material, not as the authoritative source of control or policy.

Why long-context prompting degrades coding agent governance

The article points to well-known context effects: models do not use long inputs uniformly, and relevant instructions buried deep in a file are less likely to shape output. That means a larger AGENTS.md does not necessarily produce better compliance. It often produces the opposite, because the important instruction is now competing with many less relevant ones. In practice, this turns governance into a visibility problem. The rule exists, but the model may not weight it when it matters most.

Practical implication: Keep agent instructions short and task-relevant, and move critical controls into structured context delivered at the point of use.

How structured context changes agent behaviour

Sonar’s argument is that the stronger mechanism is not more prose, but analysed context: task-scoped coding guidance, current architecture, semantic code navigation, and dependency checks delivered when the agent is about to act. That is a different governance model. Instead of hoping a model infers intent from a static file, the environment provides machine-readable evidence about what is allowed, what exists, and what should change. For coding agents, that is the difference between advisory documentation and operational control.

Practical implication: Deliver architecture, standards, and dependency intelligence as generated context rather than relying on manually maintained instructions alone.

NHI Mgmt Group 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.

Long-context degradation is the hidden control failure behind overstuffed instruction files. The more teams pack into AGENTS.md, the more likely critical rules are to be diluted by context effects and competing priors. This is especially relevant for coding agents because they operate probabilistically, not deterministically, so compliance depends on how instructions are surfaced, not merely whether they are written down. Practitioner conclusion: keep high-value guidance close to the action and short enough to retain force.

Structured context is the real identity-adjacent control for coding agents. Coding agents act as non-human systems inside the software supply chain, so their governance has to resemble runtime authorisation more than policy prose. The article’s core insight aligns with the broader NHI problem: the system that acts needs current, scoped context, not a static statement of intent. Practitioner conclusion: govern agent behaviour with live context, scoped evidence, and task-specific controls.

AGENTS.md is best understood as a documentation boundary, not an enforcement boundary. That distinction matters because modern development teams are starting to rely on agents for code changes, refactoring, and reuse decisions that have direct security consequences. A readable policy file can support shared expectations, but only structured analysis can keep those expectations aligned with the codebase. Practitioner conclusion: separate developer guidance from the mechanisms that actually constrain agent action.

Code guidance should move from remembered rules to generated controls. The article points toward a broader operating model in which standards, architecture, and dependency knowledge are produced from analysis and delivered at generation time. That is where agent governance becomes repeatable and auditable. Practitioner conclusion: if the control cannot be refreshed with the code, it will eventually govern the wrong system.

From our research library:

• 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.
• Read next: AI Agent Identity Security Buyer's Guide

What this signals

Task-scoped context will replace static policy text as the practical governance layer for coding agents. Teams that continue to rely on prose files alone will keep seeing drift between stated standards and generated code, especially as repositories and agent prompts grow. The better model is to generate current context from the codebase and surface it at the moment of action, not after a review has already failed.

Agent governance now looks closer to non-human identity control than to developer documentation. A coding agent is a software actor that needs scoped instructions, current boundaries, and evidence of what it is allowed to do. That makes the control problem about issuance of context, not just authoring of rules, which is why static guidance should be treated as one layer in a broader governance stack.

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. That level of leakage risk is a reminder that AI-assisted coding needs runtime controls around output quality, secret detection, and review boundaries. Practitioner programmes should assume that instruction quality alone will not suppress risky behaviour.

For practitioners

• 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.
• Make reuse guidance machine-findable Pair instructions to reuse existing code with semantic navigation or repository intelligence so the agent can locate the right implementation by meaning, not just by search.

Key takeaways

• AGENTS.md is useful for stable project instructions, but it does not reliably enforce architecture, security, or reuse decisions as code changes.
• Long instruction files weaken governance because relevant rules can be buried in the middle of the context window and underweighted by the model.
• Structured, task-scoped context delivered at generation time is a stronger control model for coding agents than static prose alone.

Key terms

• Coding Agent: A coding agent is a software system that can plan, generate, and modify code with limited human prompting. In governance terms, it is not just a tool but an actor whose permissions, tool access, and rollback path must be managed as part of the delivery process.
• Schema Context: Schema context is the information that tells a system how data is shaped, named, and related. For agents, it includes field names, record types, and example values. Without it, a model may query the wrong columns, misinterpret relationships, or produce answers that are syntactically valid but logically wrong.
• 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.
• Context rot: Context rot is the loss of investigative focus that happens when an incident agent or analyst is forced to reason across too many logs, traces, and dependencies at once. The result is overconfidence in the wrong clue, which makes approval boundaries and evidence scoping more important than raw model size.

Deepen your knowledge

NHI Foundation Level course, the industry's only accredited NHI security programme, covers NHI governance, agentic AI identity, and machine identity security. It is designed for practitioners who need to align identity controls with real operational behaviour, not just documented intent.