Catch Instruction Drift Before Long Coding Agent Runs Go Off Track

Last reviewed: 2026-06-25

Direct answer

A coding agent instruction drift check is a short operating checkpoint that confirms the agent is still working from the right repository guidance, task brief, memory file, and worktree before it continues a long run. Use it before a large edit, after a resumed session, after switching directories, after loading new context, and before asking the agent to finalize a change or prepare a pull request.

The check should stay concrete. You are not trying to prove what the model knows internally. You are verifying the visible inputs that govern the next action: which instruction files apply, what task is active, what directory or worktree is in use, which files are in scope, what evidence has already been gathered, and what the agent plans to do next. If the agent cannot answer those questions from visible repository state and the current task brief, pause the run before it edits more code.

Use this workflow:

1. Setup assumptions: the repository has committed instruction files for the agent you are using, the current task has clear acceptance criteria, and any parallel work is isolated in its own Git worktree or branch.
2. Happy-path request plan: ask the agent to restate the active instruction files, summarize the task goal, name the current branch or worktree, list files it expects to touch, and state the next command or edit it plans to make.
3. Error-path check: ask what it will do if instructions conflict, a memory file disagrees with the task, the working tree is dirty in an unexpected way, or the requested command needs credentials or external access.
4. Minimum assertions: the agent should identify the closest applicable instruction file, preserve higher-priority rules, avoid unrelated files, and keep changes inside the intended worktree.
5. Pass/fail logging fields: record the run id, repository path, branch or worktree, instruction files checked, task goal, planned next step, result, and unresolved questions.
6. What not to assert: do not claim hidden context, pricing, rate limits, service availability, or model-specific behavior from this smoke test. It only verifies visible operating context.

For nearby setup work, pair this with Instruction File Scope Checks for Coding Agent Repos so the repository rules are clear before the run starts. If you use parallel branches, keep Use Git Worktrees to Keep Parallel Coding Agents Isolated close at hand because drift is harder to spot when two agents are editing similar files in different directories.

Who this is for

This guide is for engineers, tech leads, staff engineers, and developer-experience teams who let coding agents run for more than a quick one-file edit. It is especially useful when sessions resume after a pause, use persistent project instructions, operate across nested directories, or run in parallel worktrees.

The check is also useful for reviewers. A pull request can look tidy while still being based on stale task assumptions. A short pre-handoff drift check gives the reviewer a compact explanation of what guidance the agent followed, why the touched files were in scope, and which uncertainty remains. That makes the final diff easier to evaluate because the reviewer does not have to reconstruct the agent’s operating context from commit messages alone.

Use the check when the task has more than one source of instructions. For example, a repo may have global guidance at the root, path-specific guidance under a package, tool-specific memory files, and a one-off task brief from the human operator. Those inputs can all be reasonable, but a long-running agent can start blending old and new guidance unless it is asked to restate what applies right now.

Key takeaways

• Treat instruction files as active operating inputs, not background decoration.
• Re-check scope whenever a session is resumed, moved into a subdirectory, given new context, or handed off.
• Keep tool-specific instruction files aligned without assuming every coding agent reads the same filenames or applies them in the same way.
• Use Git worktrees to separate parallel agent runs, then require each run to report its branch and worktree before editing.
• Make the agent say what it will do if guidance conflicts or required evidence is missing.
• Log only sanitized operational fields; never paste secrets, full prompts, full generated responses, prices, limits, credentials, or availability claims into the run record.

Sanitized log-record template:

run_id: "agent-run-placeholder"
repo_path: "repo/path-placeholder"
branch_or_worktree: "worktree-placeholder"
instruction_files_checked: ["instruction-file-placeholder"]
task_goal: "short sanitized goal"
planned_next_step: "next command or edit category"
result: "pass|fail|needs-human"
open_questions: ["question-placeholder"]
secret_values_recorded: "none"

A strong drift check has a narrow output. It should not become a second task brief, a long essay, or a place to relitigate the whole implementation. The best version is a small checkpoint that lets the operator say yes, pause, or redirect. If the agent’s answer introduces new files, new dependencies, new external services, or new assumptions, treat that as a reason to ask one more question before continuing.

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.
• Instruction collision: a root instruction file, path-specific file, memory file, and task brief point in different directions. The agent should name the conflict and ask for a human decision instead of silently choosing the easiest path.
• Worktree confusion: the agent reports the right task but the wrong branch or linked working tree. Stop before edits continue, because the next command may mutate the wrong copy of the repository.
• Unreviewed fallback: the agent changes models, endpoints, permissions, dependencies, 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.

When a failure mode appears, do not ask the agent to keep going in the same shape. Ask it to restate the active guidance, name the smallest safe next step, and identify which human decision or source evidence is missing. That pause is cheaper than repairing a large, plausible-looking diff that followed the wrong assumptions.

Reader next step

Before your next long coding-agent session, add a five-line drift checkpoint to the task brief and require the agent to answer it before the first broad edit. Use this starter prompt:

Before editing, confirm the active repository instructions, current task goal, branch or worktree, files you expect to touch, and the first command or edit you plan to make. If any instruction conflicts, evidence is missing, or credentials are required, stop and ask before continuing. Use <API_KEY_PLACEHOLDER> for any credential placeholder.

Then save the agent’s answer with the run notes. If the answer is specific and matches the intended scope, proceed. If it is vague, names the wrong worktree, skips a relevant instruction file, or proposes unrelated cleanup, pause and tighten the task before edits begin. For handoff-heavy teams, combine this with Repository Handoff Notes for Coding Agent Runs so the next person can see both the starting context and the final result.

Use Write Change Scope Notes Before an Agent Pull Request as the next comparison point. Keep Agent Memory Review Before Long-Running Tasks nearby for setup and permission checks.

Sources checked

• OpenAI Codex AGENTS.md guidance - accessed 2026-06-25; purpose: verify repository instruction-file context for coding agents.
• GitHub Copilot repository instructions documentation - accessed 2026-06-25; purpose: verify repository instruction guidance.
• Claude Code memory documentation - accessed 2026-06-25; purpose: verify project memory and instruction-file context for agent workflows.
• Git worktree documentation - accessed 2026-06-25; purpose: verify parallel worktree isolation commands and constraints.

Contract details to verify

FAQ

How often should I run an instruction drift check?

Run it before a long edit, after any session resume, before a pull request handoff, and whenever the agent changes directories, worktrees, or task scope.

Is this the same as reviewing the final diff?

No. A drift check happens before more work continues. Diff review still matters, but it catches the result after the agent has already acted.

Should every agent use the same instruction filename?

No. Different tools document different files and loading behavior. Keep a small mapping in the repository so humans know which files each tool reads.

Can this check prove an agent saw hidden system context?

No. It should only verify visible repository guidance, task scope, worktree state, and the agent’s stated next step.

What should fail the check immediately?

Fail the check if the agent cannot identify the active task, names the wrong worktree, ignores a nearby instruction file, proposes unrelated edits, or asks to expose credentials in logs.