Blog
What Are Your Coding Agents Actually Following? A Practical Audit Guide
A practical workflow to inventory AGENTS.md and other instruction files, detect drift, and roll out updates across repos without breaking teams.
Last updated: March 18, 2026
TL;DR
- Agents follow instruction files quietly; most teams can’t answer what’s in force across repos.
- Start with inventory, then measure instruction drift against a baseline, then roll out changes via PRs.
- Keep instructions short and stack-specific; don’t duplicate what tools can read from the repo.
Why this matters: instructions are already executing
Your coding agents are following instructions every time they run. The problem is that those instructions are rarely owned: AGENTS.md, CLAUDE.md, GEMINI.md, and Copilot instruction files get copy-pasted into new repos, tweaked locally, and left to drift.
The operational question is simple: what are our agents actually following today? If you manage more than a handful of repos, you can’t answer it by memory.
Step 1: inventory instruction files (per repo, not per team)
Start by listing what exists and where it lives. In most orgs you’ll see a mix of:
- AGENTS.md at repo root
- CLAUDE.md and GEMINI.md in some repos
- .github/copilot-instructions.md and .github/instructions/*.instructions.md
Inventory is valuable even before you debate “standardization.” It tells you which repos are operating without guidance and which are carrying stale templates.
Step 2: define a baseline that’s small enough to maintain
Don’t start by writing the perfect global constitution. Start with a baseline that’s easy to review and hard to misinterpret:
- How to run tests and what counts as passing
- Lint/format expectations that actually block merges
- Migrations and data-handling constraints
- Security rules that change agent behavior (e.g., no secrets in logs)
Avoid restating what an agent can discover from package.json, build configs, and CI pipelines. That text becomes drift fuel.
Step 3: measure instruction drift like configuration drift
Instruction drift is the delta between your intended baseline and what each repo actually contains. It shows up as:
- Missing sections in some repos
- Conflicting directives between files
- Stale references (old tooling, old workflows, dead links)
- Risky imports and copied templates that diverged
If you want a deeper definition and examples, see Instruction Drift in AI Coding Agents.
Step 4: roll out updates via reviewable PRs (not bulk commits)
Treat instruction updates like any other production configuration change:
- Preview changes repo by repo
- Ship updates via pull requests with clear diffs and owners
- Roll out in batches, starting with representative repos
- Document exceptions instead of letting “local tweaks” go untracked
This keeps teams in control while still letting platform/dev productivity move the fleet.
A good starting point: run a scanner locally
The fastest way to start is a local scan: discover files, normalize the content, and export a report you can share. See the scanner quickstart and pricing when you’re ready for hosted inventory, standards, rollouts, and audit trails.
FAQ
Should every repo have the exact same AGENTS.md?
Not always. Most orgs keep a shared core baseline and allow limited, documented repo-level variations. The key is making differences explicit and reviewable instead of accidental drift.
How often should we audit instruction files?
Tie audits to meaningful change: major dependency upgrades, test/build tooling changes, security policy updates, and periodic fleet scans as the repo count grows.
Which instruction file should we standardize first?
Start with AGENTS.md as the cross-tool baseline, then layer tool-specific files (CLAUDE.md, GEMINI.md, Copilot instructions) where you use those tools heavily.