Managing Agent Drift
Introduction
In earlier lessons, you created an AGENTS.md file to capture durable, repo-specific guidance for Codex. This lesson is about keeping that guidance accurate over time—because the repo won’t stand still, and your agent instructions shouldn’t either.
Think of this as routine maintenance: small updates that keep Codex helpful and predictable as the project evolves.
Introduction To Drift Control
AGENTS.md works best as a living document. When the repository’s behavior, workflows, or standards change, a quick update to your agent rules helps Codex keep doing the right thing by default.
This lesson focuses on “human steering” (updating instructions). In real teams, you’ll usually reinforce the most important expectations with CI checks and PR review—so quality doesn’t depend on anyone remembering every step.
What Is Knowledge Drift?
Knowledge drift is the gap between:
- what the repository currently expects (tools, scripts, conventions, docs, tests), and
- what
AGENTS.mdstill tells Codex to do.
When drift shows up, it often looks like:
- Codex runs commands that used to work, but don’t anymore.
- It changes code successfully, but misses expected follow-ups (docs, tests, examples).
- It follows conventions that were true last month, but aren’t true today.
The good news: drift is usually fixed with small, targeted edits—no big rewrite needed.
Common Drift Triggers (When You Should Consider Updating AGENTS.md)
Use this as a practical “should we update the agent rules?” list:
- Tooling changes: new test runner, formatter, linter, type checker, package manager, runtime/Node version.
- Repo structure changes: moved entrypoints, new packages/workspaces, renamed directories, new “source of truth.”
- Workflow changes: updated CI steps, different build commands, new release process.
- Policy changes: documentation expectations, security constraints, dependency rules, review requirements.
- Product/API changes: new public APIs, changed config formats, breaking changes needing migration notes.
You don’t need to add rules for everything—but if a change repeatedly causes mistakes or omissions, it’s a great candidate for AGENTS.md.
