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.

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.

Knowledge drift is the gap between:

• what the repository currently expects (tools, scripts, conventions, docs, tests), and
• what AGENTS.md still 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.

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.

When you spot drift (or you’re about to create it), use this quick process:

1. Name what changed
   Example: “Docs location moved,” “Build command changed,” “New required checklist item.”

2. Update the smallest relevant section of AGENTS.md
   Aim for a small patch that’s easy to review and easy to keep accurate.

3. Make sure it matches the repo reality
   If AGENTS.md says “run pnpm test” but the repo uses yarn test, fix the guidance immediately.

4. Optionally add an enforcement hook for high-impact rules
   If it matters (tests, lint, docs), consider backing it up with CI or a PR template so it doesn’t get skipped accidentally.

A very common form of drift is “code changes, docs lag behind.” You can reduce that by adding a gentle but clear rule linking user-visible changes to documentation updates.

Add something like this to AGENTS.md:

Why this helps:

• It’s a clear “when X happens, also do Y” reminder.
• It doesn’t assume a specific docs system—Codex can look for whatever the repo actually uses.
• It nudges the agent toward the habit you want: “ship the change + teach users about it.”

If your project does have CLI-specific docs (manpages, generated help output, etc.), you can be more specific:

A Definition of Done (DoD) is a short checklist that answers: “What do we consider complete?” For an agent, it’s a reliable end-of-task quality pass.

Add this section to AGENTS.md:

A couple of practical tips:

• Keep the DoD short and checkable—you want it used, not ignored.
• Wording like “should aim to” keeps it flexible while still setting a consistent expectation.

AGENTS.md is great for steering, but it’s not a guarantee. If something is important, automation should carry the weight:

• CI checks: require tests/lint/type checks/formatting to pass.
• Doc drift prevention: generate docs from source where possible, or add checks for mismatch.
• PR templates: mirror the DoD so humans and agents follow the same checklist.
• Docs-as-code: keep docs versioned and reviewed alongside code.

Use AGENTS.md to encourage the right defaults—then use CI and review to make the important parts consistent.

In this lesson, you learned how to keep Codex aligned as the repo evolves by:

• Updating AGENTS.md when tooling, structure, workflows, policies, or public behavior changes.
• Adding documentation linkage rules so user-visible changes prompt doc updates.
• Adding a Definition of Done checklist to keep work consistently “finished,” not just “implemented.”
• Backing key expectations with CI/PR templates/docs-as-code when you need real enforcement.

Next, you’ll practice updating an AGENTS.md file in the CodeSignal IDE by adding documentation rules and a DoD checklist in a real repository.