Blog
How to Audit AI Coding Instructions Across Repositories
A repeatable audit workflow for finding stale, conflicting, or risky AGENTS.md, CLAUDE.md, GEMINI.md, and Copilot instructions across repos.
Last updated: April 1, 2026
TL;DR
- Start by inventorying all instruction surfaces, not just AGENTS.md.
- Audit for stale commands, contradictions, missing directives, and risky patterns before you standardize.
- Ship fixes through reviewable pull requests and keep exceptions explicit.
Step 1: inventory every instruction surface
A good audit starts with visibility. Teams often think they are auditing AGENTS.md, but the real instruction surface also includes CLAUDE.md, GEMINI.md, Copilot instruction files, and any scoped rules living under tool-specific folders.
The first deliverable is simple: which repos have which instruction files, where they live, and which ones look like local copies of a broader template.
Step 2: compare the fleet against a baseline
Once you have inventory, compare each repo against the baseline you actually want to maintain. That baseline should be small enough to review and important enough to matter: test commands, security constraints, migration rules, and workflow expectations that change agent behavior.
This is where drift becomes visible. Some repos will be missing directives. Others will carry old commands or tool-specific conflicts that quietly pull agents in different directions.
Step 3: review stale, conflicting, and risky findings
- Stale references to outdated build, test, or release workflows.
- Conflicting rules across AGENTS.md and tool-specific files.
- Missing sections required by the org baseline.
- Risky imports, unsafe shell snippets, or other high-trust content problems.
Keep the audit explainable. Each issue should answer what is wrong, where it lives, and how to fix it. That makes follow-through much easier for repo owners.
Step 4: fix the fleet through PR-based rollout
Do not end the audit with a spreadsheet. Turn findings into reviewable pull requests. Start with a representative batch of repositories, gather feedback, then expand once the baseline language is stable.
For teams adopting the cost and quality wedge, this audit is the bridge between discovery and action. It also pairs naturally with instruction quality scoring, since scoring helps rank what to fix first.
FAQ
How often should teams run a fleet-wide instruction audit?
A meaningful cadence is after major workflow or tooling changes, plus a periodic scan for teams with lots of active repositories. The right frequency depends on how often the fleet changes.
Should audits be owned by platform or security?
Usually platform or developer productivity owns the workflow, with security contributing policy input and reviewing higher-risk findings.
What is the fastest way to start an audit?
Run a local scanner to inventory files and export findings, then choose a small baseline and review a subset of repositories before attempting full fleet rollout.