Use AGENTS.md for stable, human-owned conventions such as build commands, test commands, code style, and pull request norms. Use live code intelligence for current architecture, dependency health, and enforcement after each edit. The file should stay lean and portable, while the runtime check handles rules that must always run. That split reduces drift and gives teams both context and control.
How to split repository rules between AGENTS.md and live checks
Teams should treat AGENTS.md as the stable contract for human readers, then let live code-intelligence checks enforce what can change underneath that contract. The cleanest split is documentation for conventions and runtime checks for state that must be re-evaluated after every edit, so the repo stays understandable without becoming stale.
The practical benefit is that the file can remain short enough to trust, while the live check can inspect the current tree, dependency graph, and enforcement conditions with each run. That avoids turning AGENTS.md into a maintenance bottleneck and keeps the repository’s operating rules closer to the code they govern.
What belongs in AGENTS.md versus the runtime layer
AGENTS.md works best for durable instructions that change slowly: build commands, test entry points, code style, review expectations, and any repository-specific norms that a contributor or agent should know before acting. These are the rules that improve orientation and reduce accidental churn because they are readable without executing anything.
Live code intelligence should own the checks that depend on current repository state, such as whether the architecture still matches the documented pattern, whether a dependency has drifted into a risky version, or whether a change violates a rule that can only be validated after the edit is made. If a rule can be stale by tomorrow, it usually belongs in the runtime layer, not in the static file.
A useful test is whether the instruction is meant to be followed or verified. If it is primarily guidance, keep it in AGENTS.md. If it is primarily an assertion about the present codebase, enforce it in the live check so the result is based on the actual repository state rather than memory.
How the split reduces drift and preserves control
The main failure mode is duplication. When the same rule appears in both places, teams eventually update one side and forget the other, which creates conflicting sources of truth and lowers confidence in both. A lean AGENTS.md avoids that problem by keeping only the durable operating context that humans can reasonably maintain by hand.
Live checks add control where static instructions cannot. They can reject an edit that breaks a current dependency constraint, surface a newly introduced mismatch between declared and actual architecture, or re-run enforcement after every change so the repository does not quietly accumulate exceptions. That is especially important when the repo has frequent edits or many contributors.
For teams working with automation, this split also improves portability. The static file travels with the repo and is easy to inspect, while the runtime enforcement can evolve independently as the codebase, toolchain, or policy expectations change. The result is less re-documenting, fewer stale instructions, and tighter feedback on the rules that matter most in the moment.
Standards & Framework Alignment
This section maps relevant standards and security frameworks to the operational risks and controls described in this guidance.
OWASP SAMM, NIST CSF 2.0, NIST SP 800-53 Rev 5 and OWASP ASVS set the governance and control requirements practitioners need to meet.
| Framework | Control / Reference | Relevance |
|---|---|---|
| OWASP SAMM | Governance — Governance | Repository conventions and enforcement split shape secure SDLC governance. |
| Recommendation — Define where static instructions end and runtime checks begin in your SDLC policies. | ||
| NIST CSF 2.0 | GV.PO-01 — Policy | The question is about separating written policy from operational enforcement. |
| Recommendation — Document repository rules as policy and keep execution checks in operational controls. | ||
| NIST SP 800-53 Rev 5 | CM-3 — Configuration Change Control | Live checks enforce changes against current repository state and control drift. |
| CA-7 — Continuous Monitoring | Runtime code-intelligence checks provide ongoing validation after edits. | |
| Recommendation — Require review and validation for changes that alter enforced repository behavior. Continuously monitor the repository for post-change control violations. | ||
| OWASP ASVS | V15 — Secure Coding and Architecture | The live check validates current architecture and enforcement after code changes. |
| Recommendation — Verify that implemented architecture still matches the intended secure design. | ||
Practitioner Guidance
What to prioritise: Put only human-owned, low-churn conventions in AGENTS.md, and reserve live checks for anything that depends on the current tree, dependency state, or post-edit validation. If a rule needs frequent re-interpretation, it is usually too volatile for the file.
What to verify: Check that AGENTS.md does not restate rules already enforced by the runtime layer, except where the static note helps the reader find or understand the check. The best sign of a good split is that the file remains short even as enforcement becomes stronger.
Common mistake: Teams often try to make AGENTS.md the full policy surface. That creates drift, makes onboarding harder, and encourages people to trust prose instead of the current repository state.
Practitioner takeaway: Use AGENTS.md to set expectations, but let runtime intelligence be the source of truth for anything that must stay aligned with the live codebase.
Related resources from NHI Mgmt Group
- How should security teams combine AI agents with deterministic code analysis in application security workflows?
- How should security teams reduce the risk of repository exposure turning into wider SaaS compromise?
- How should security teams prioritise NHI remediation in cloud environments?
- How should security teams govern non-human identities at scale?
Deepen Your Knowledge
Reviewed and updated by the NHIMG editorial team on September 25, 2026.
NHI Mgmt Group — the #1 independent authority on Non-Human Identity, IAM, and Agentic AI security. nhimg.org
