Last reviewed: 2026-05-29

Direct answer

Prompt registry drift happens when the instruction files your coding agent reads — AGENTS.md, CLAUDE.md, .github/copilot-instructions.md, or tool-specific memory files — no longer accurately describe the tools, commands, workflows, or conventions available in the actual runtime environment. The agent acts on what the files say, not on what is currently true. The result is confidently wrong decisions: commands that no longer exist, paths that have moved, tools that were added but never documented, or entire workflow sections that describe a previous version of your stack.

The fix is to treat instruction files as first-class registry entries that must stay in sync with the codebase, and to make CI enforce that sync. Concretely:

1. Identify every instruction file your agent reads (project root, subdirectories, global config).
2. Define a small set of anchor facts that each file claims — tool names, key paths, required commands, workflow steps.
3. Write CI checks that verify those anchor facts against the actual repo state on every pull request.
4. Fail the build when anchor facts in an instruction file no longer match the repo.

The remainder of this guide covers each step with concrete patterns across Codex, Claude Code, and GitHub Copilot.

For broader release checks, see AI Coding Agent Setup, Security, and Model Routing .

Who this is for

This guide is for engineering teams that operate one or more AI coding agents against a shared repository. You may be:

• Running OpenAI Codex cloud tasks or CLI sessions with AGENTS.md checked into the repo root or subdirectories.
• Using Claude Code with CLAUDE.md project rules or per-directory memory files.
• Using GitHub Copilot with a .github/copilot-instructions.md file that customizes Copilot’s suggestions for your codebase.
• Running multiple agents in parallel on the same repo and noticing that their behavior diverges as the instruction files fall behind.

If your team has invested in repository instruction files and wants a repeatable way to prevent those files from becoming stale, this guide is for you.

Key takeaways

• Prompt registry drift is structural, not accidental. Instruction files are written once and then forgotten while the codebase evolves around them.
• Each agent runtime reads instruction files differently. AGENTS.md applies hierarchically in Codex; CLAUDE.md applies per-project in Claude Code; .github/copilot-instructions.md applies repository-wide in Copilot. Verify current behavior against the docs linked below before assuming identical semantics.
• CI is the right enforcement layer. A drift check belongs in the same pipeline as your linter and test suite — not in a manual review checklist.
• Drift checks do not need to be complex. Checking that a handful of named commands, paths, or tool references in an instruction file still exist in the repo is often enough to catch the most damaging drift.
• Fixing drift is a documentation commit, not a code change. The bar to fix it is low; the cost of ignoring it accumulates quietly.
• If you use a shared model gateway to power your coding agents, verify that the gateway’s model routing and endpoint configuration is documented in your instruction files. Gateway endpoint changes are a common source of drift. See Route Coding Agent Model Calls Without Endpoint Drift for that workflow.

Understanding prompt registry drift

What the instruction file is

Every major coding agent runtime provides a way to embed project-level instructions in the repository itself:

• OpenAI Codex reads AGENTS.md files. When the child_agents_md feature flag is enabled, it applies hierarchical scope rules, appending guidance about AGENTS.md scope and precedence to the agent’s instruction message. Verify current hierarchical behavior and feature flag requirements in the OpenAI Codex AGENTS.md documentation before relying on subdirectory scoping.
• Claude Code reads CLAUDE.md files at the project level and supports additional memory files for project rules. See the Claude Code memory documentation for the current file locations, precedence rules, and which memory types are project-scoped versus global.
• GitHub Copilot reads .github/copilot-instructions.md as a repository-level custom instructions file. See Add repository instructions for GitHub Copilot for current setup and format requirements.

These files tell the agent what tools to use, what paths matter, what commands to run, what coding conventions to follow, and what the overall workflow looks like. They are, in effect, a registry of truths about the repo as seen from the agent’s perspective.

How drift happens

Drift accumulates gradually:

• A CI command in AGENTS.md references npm run lint:strict, which was renamed to npm run lint six months ago. The agent now fails lint steps silently or invents alternatives.
• CLAUDE.md documents a monorepo layout that was restructured. The agent creates files in the old locations.
• .github/copilot-instructions.md says the project uses a specific test framework that has since been replaced. Copilot suggestions apply patterns from the old framework.
• An AGENTS.md section describes an internal API endpoint that no longer exists after a gateway migration.

None of these represent a failure in the agent. The agent is doing exactly what the instruction file says. The failure is that nobody updated the file.

Why it is hard to catch manually

Manual review of instruction files tends to happen at creation time and then stops. The files are not code — they do not produce test failures when they go stale. A developer changing a script name has no natural prompt to also update AGENTS.md. Over months, a small number of stale anchors accumulates until an agent session produces clearly wrong output — at which point debugging feels mysterious because the agent “should have known better.”

For guidance on structuring instruction files so they are easier to keep current, see How to Write Repository Instructions for Coding Agents.

Drift check approach

Step 1: Enumerate your instruction files

Before writing checks, list every file your agents read. For a repo using Codex, Claude Code, and Copilot simultaneously, your list might be:

AGENTS.md # Codex root-level instructions src/AGENTS.md # Codex subdirectory scope (if child_agents_md enabled) CLAUDE.md # Claude Code project rules .github/copilot-instructions.md # GitHub Copilot repository instructions

Verify the exact files each tool reads by consulting the linked documentation. File names, locations, and scope rules vary and may change.

Step 2: Extract anchor facts

For each instruction file, extract a short list of anchor facts — specific claims the file makes that are verifiable against the repo:

• Named scripts (npm run test, make build, ./scripts/check.sh)
• Directory paths (src/api/, infra/docker/)
• Configuration file names (docker-compose.yml, .eslintrc.json)
• Tool names that must exist in package.json, Makefile, or requirements.txt
• Required environment variables that should be documented in .env.example

Keep the anchor list short. Five to ten items per file is enough. The goal is to catch the most disruptive drift, not to validate every sentence.

Step 3: Write the CI check

A drift check is a script that reads the instruction file, extracts the anchor facts it cares about, and asserts that each one exists in the repo. The script exits non-zero when any anchor is missing.

Here is a minimal example for checking that commands named in AGENTS.md still exist as scripts in package.json:

#!/usr/bin/env python3 “““check_agent_instructions_drift.py

Verify that scripts named in AGENTS.md exist in package.json scripts. Exit 1 if any named script is missing. "”” import re, json, sys, pathlib

INSTRUCTION_FILE = pathlib.Path(“AGENTS.md”) PACKAGE_FILE = pathlib.Path(“package.json”)

if not INSTRUCTION_FILE.exists(): print(“SKIP: AGENTS.md not found”) sys.exit(0)

if not PACKAGE_FILE.exists(): print(“SKIP: package.json not found”) sys.exit(0)

text = INSTRUCTION_FILE.read_text() package = json.loads(PACKAGE_FILE.read_text()) defined_scripts = set(package.get(“scripts”, {}).keys())

Match patterns like npm run in instruction file

referenced = set(re.findall(r"npm run ([\w:_-]+)”, text))

missing = referenced - defined_scripts if missing: print(f"DRIFT: {len(missing)} script(s) referenced in AGENTS.md not found in package.json:") for m in sorted(missing): print(f" - npm run {m}") sys.exit(1)

print(f"OK: {len(referenced)} script reference(s) in AGENTS.md all present in package.json")

Adapt this pattern for file paths, env vars, or tool references as needed.

Step 4: Wire the check into GitHub Actions

Add a workflow step that runs the drift check on every pull request. The check should run after checkout but before any agent-driven steps:

.github/workflows/agent-instruction-drift.yml

name: Agent Instruction Drift Check

on: pull_request: paths: - ‘AGENTS.md’ - ‘CLAUDE.md’ - ‘.github/copilot-instructions.md’ - ‘package.json’ - ‘scripts/’ - ‘Makefile’

jobs: drift-check: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-python@v5 with: python-version: ‘3.12’ - name: Check agent instruction drift run: python3 scripts/check_agent_instructions_drift.py

The paths filter keeps the check fast by only triggering when instruction files or the artifacts they reference actually change. See GitHub Actions documentation for the full trigger and path-filter reference.

Smoke-test workflow

Setup assumptions

• Repository has at least one instruction file (AGENTS.md, CLAUDE.md, or .github/copilot-instructions.md).
• The drift check script is present at scripts/check_agent_instructions_drift.py (or equivalent).
• Python 3.x is available locally and in CI.
• GitHub Actions or equivalent CI is configured to run on pull requests.

Happy-path check

1. Run the drift check script locally against the current repo:

python3 scripts/check_agent_instructions_drift.py

2. Expected: exits 0, prints an OK line listing the number of anchor references verified.
3. Open or update a pull request that changes AGENTS.md or a referenced script — CI drift check job runs and passes.

Error-path check

1. Temporarily rename a script in package.json that AGENTS.md references (do not commit).
2. Run the check locally:

python3 scripts/check_agent_instructions_drift.py

3. Expected: exits 1, prints a DRIFT line listing the missing script name.
4. Restore the script name. Confirm the check exits 0 again.

Minimum assertions

• Exit code 0 when all anchor facts are present.
• Exit code 1 when at least one anchor fact is missing.
• The drift output names the missing anchor (script name, path, etc.) — not just a count.

What the smoke test must not assert

• Do not assert that the instruction file content is “correct” or complete in a semantic sense.
• Do not assert model behavior or model availability.
• Do not assert that the agent will interpret the file in a specific way across different runtimes.
• Do not assert prices, rate limits, or API quotas.

Log-record template

After running the smoke test, record the following fields. Use placeholder values; do not log real credentials, prompts, generated responses, or cost data.

drift_check_run:
  date: YYYY-MM-DD
  repo: <repo-name-placeholder>
  instruction_files_checked:
    - AGENTS.md
    - CLAUDE.md
    - .github/copilot-instructions.md
  anchor_count: <N>
  missing_count: <N>
  exit_code: <0 or 1>
  ci_job_url: <ci-job-url-placeholder>
  triggered_by: <pr-or-local>
  action_taken: <none | updated-instruction-file | updated-script>
  notes: <optional-free-text>

Failure modes

• Evidence gap: the agent cannot inspect the failing log, source page, pull request, or local command output. The safe action is to stop and record the missing evidence instead of guessing.
• Scope drift: the agent edits files that are not connected to the observed failure. Keep the repair tied to the failing signal and leave unrelated cleanup for a separate task.
• Environment mismatch: the local check uses different versions, credentials, feature flags, or runtime settings than the hosted path. Record the mismatch before treating the result as proof.
• Unreviewed fallback: the agent changes models, endpoints, permissions, or retry behavior to make a run pass without preserving the review boundary. Treat access and provider failures as operational blockers, not topic failures.
• Weak handoff: the final note says the issue is fixed but omits the command, result, changed files, and remaining uncertainty. That makes the next operator repeat the investigation.
• Silent anchor expansion: an instruction file grows new claims over time — new script names, new paths — but the anchor list in the drift check is never updated to match. The check passes while new drift accumulates unchecked. Review the anchor list whenever an instruction file gains significant new sections.
• Path filter miss: a CI workflow uses a narrow paths: trigger. A refactor that moves a referenced script to a new directory does not match the old filter, so the drift check never runs on that PR. Audit path filters when repo structure changes.

Sources checked

• OpenAI Codex AGENTS.md guidance - accessed 2026-05-29; purpose: verify repository instruction-file context for coding agents.

• GitHub Copilot repository instructions documentation - accessed 2026-05-29; purpose: verify repository instruction guidance.

• Claude Code memory documentation - accessed 2026-05-29; purpose: verify project memory and instruction-file context for agent workflows.

• GitHub Actions documentation - accessed 2026-05-29; purpose: verify workflow runs, jobs, steps, checks, and logs.

• CometAPI documentation root - accessed 2026-05-29; purpose: gateway context for teams routing agent model calls through CometAPI; verify current endpoint paths and model IDs before use.

Contract details to verify

FAQ

What is prompt registry drift in the context of coding agents?

Prompt registry drift is the gap that opens between what an agent’s instruction file claims is true about the repository — commands, paths, tools, workflows — and what is actually true at runtime. As the codebase evolves, instruction files that are not actively maintained become increasingly inaccurate guides. The agent follows the stale instructions confidently, leading to incorrect commands, wrong file paths, or outdated workflow steps.

Which files count as part of the prompt registry?

Any file that a coding agent reads to understand the repository context. For common tools this includes AGENTS.md (Codex), CLAUDE.md and project memory files (Claude Code), and .github/copilot-instructions.md (GitHub Copilot). Verify the exact file names and locations in the documentation for each tool, as these can change and may differ across runtime versions.

How often should drift checks run?

At minimum, on every pull request that touches instruction files or the artifacts they reference (scripts, config files, directory structure). With path-filtered GitHub Actions triggers this adds negligible CI time. For teams with frequent structural changes, a nightly scheduled run against the main branch can catch drift that accumulates outside of PR workflows.

What if our instruction files are too complex to check with simple regex?

Start with the anchors that cause the most disruption when stale: script names, critical path references, and required tool names. You do not need to validate every sentence. A check that catches five high-impact anchor mismatches is more useful than no check at all. More sophisticated checks — such as parsing structured sections of a Markdown instruction file — can be added incrementally once the basic infrastructure is in place.

Does this workflow apply to agents running in cloud or sandboxed environments?

Yes. The instruction files are still read from the repository, so the same drift risk applies regardless of where the agent executes. For cloud-based Codex tasks or similar environments, the instruction file in the repository is the primary context source. Verify current cloud task behavior in your agent runtime’s documentation.

How does prompt registry drift relate to model gateway changes?

A model gateway migration is one of the most common sources of targeted drift. If AGENTS.md or CLAUDE.md documents an endpoint path, base URL, or model ID that has changed after a gateway migration, the agent will attempt to use the stale values. See Route Coding Agent Model Calls Without Endpoint Drift for how to keep gateway configuration consistent. If your team routes agent calls through a shared API gateway, verify current endpoint paths and model IDs in the gateway docs before updating your instruction files to reference them.

Reader next step

Run python3 scripts/check_agent_instructions_drift.py against your repo today and note how many script references in your instruction files are still valid. Then review AI Coding Agent Setup, Security, and Model Routing for the surrounding setup and permission baseline. For a structured approach to writing instruction files that age well, see How to Write Repository Instructions for Coding Agents.

If your team routes agent model calls through a shared API gateway, CometAPI provides a unified endpoint that reduces the risk of per-model base-URL drift in your instruction files — verify current model availability and endpoint paths in their documentation before updating your registry.

Use AI Coding Agent Setup, Security, and Model Routing as the next comparison point. Keep Triage CI Failures With a Coding Agent Without Losing the Evidence nearby for setup and permission checks.