How to Keep AGENTS.md Current with dox

Why your AGENTS.md dey wrong after three weeks

An AGENTS.md file dey become stale because nothing connect am to the code. You write am once, by hand, on the day the repository look one particular way. Then test runner change, package name change, service delete, and the file still dey describe June. Nothing fail because no build step dey read am.

The agent read am and believe am. Na this part dey cost you. Repository wey no get AGENTS.md make coding agent look around before e act. Repository wey get wrong AGENTS.md make am stop to look, because e don already get answer. E run the command wey your file name, shell answer Missing script: "test", and now the agent start to guess. Many times e edit package.json to add the script wey your documentation promise. The stale file no fail quietly. E cause edit wey you no want.

dox na one answer to this problem. Na set of rules wey dem write for the agent. E make documentation update part of finishing the work, so the file change for the same commit with the code wey make am wrong.

Wetin dox be, and wetin e no be

dox na one Markdown file. The repository na agent0ai/dox, e get MIT license, and as of 11 August 2026 the whole project na one 3906-byte AGENTS.md, one README, one LICENSE and two images. No package dey to install, and no runtime dey.

This matter because the word generator fit make person think say na program wey dey parse your code. Nothing dey parse your code. dox na contract wey your coding agent dey read: your agent na the generator, and dox na instruction set wey dey tell am when to read the docs, when to rewrite dem, and the format wey each document suppose get.

The file get ten sections, and na two of dem dey do the main work. "Read Before Editing" dey tell the agent make e walk from repository root reach every path wey e plan touch, and make e read every AGENTS.md along each route, for the current session, without relying on memory. "Update After Editing" dey tell am say every meaningful change require one DOX pass, meaning one documentation update step wey dem must run before the task fit count as done. The pass dey update the nearest owning document when purpose, structure, workflow, permissions or user preferences change.

The remaining sections na about format. A child AGENTS.md get default section order: Purpose, Ownership, Local Contracts, Work Guidance, Verification, and Child DOX Index. The root file dey hold project-wide rules plus the top-level Child DOX Index, wey agent dey use to discover the child documents. "Closeout" na the checklist wey agent dey run for the end of task: check the changed paths again against the chain, update the nearest owning docs, refresh every affected index, delete contradictions, run existing verification, and report which docs e deliberately leave untouched.

Pin dox to one commit, main no be am

Repository no get tags or releases, so no version number dey to pin. Pin the commit instead. The current AGENTS.md na commit f34ec7ad1055d3393887e5a2670e8cb7320c9165, dated 1 August 2026.

mkdir -p .agent
curl -fsSL -o .agent/dox-f34ec7a.md \
  https://raw.githubusercontent.com/agent0ai/dox/f34ec7ad1055d3393887e5a2670e8cb7320c9165/AGENTS.md
wc -c .agent/dox-f34ec7a.md

wc -c suppose print 3906. If e print different number, e mean say you no fetch the file wey this guide dey describe, so read am before you trust am. If you type the commit hash wrong, -f go make curl stop with curl: (22) The requested URL returned error: 404 and e no go write any content, then wc -c go print 0. File wey cut short worse pass no file, because agent go follow half contract without knowing am.

cp .agent/dox-f34ec7a.md AGENTS.md
git add AGENTS.md .agent/dox-f34ec7a.md
git commit -m "Add DOX rules (agent0ai/dox @ f34ec7a)"

That cp na for repository wey never get AGENTS.md. If you already get one, no overwrite am. Put the dox sections above your existing content, keep your own rules underneath, then read the result once from top to bottom. Two documents wey contradict each other go make agent follow whichever line e read last.

Then ask your agent, inside the repository, to do the first pass. README get the exact wording:

Initialize DOX tree for this project now.

E go create the child AGENTS.md files and the indexes wey point to dem. Check wetin e do before you trust am:

git status --short
find . -name AGENTS.md -not -path './.git/*' | sort

Every file for that find output suppose appear somewhere above am inside a Child DOX Index. If no index mention a child document, agent fit miss am, because na the index dey help am find documents wey no dey directly for the path wey e dey walk.

Wetin dox fit see, and wetin e no fit know

The agent wey dey build your tree dey read the repository, so anything wey dey inside repository fit enter the inventory: directory layout, package manifests and lockfiles, the scripts for package.json or Makefile or pyproject.toml, CI workflow files, Dockerfiles, entry points, and CODEOWNERS if you get one. Inventory wey dem build from these things fit maintain itself well. When package move, the next pass go move the line wey describe am.

Everything wey dey below na your own to state, because e no dey inside repository for agent to read:

• why rule dey exist, and na this one dey stop agent from removing am as unnecessary complexity
• which one of two working paths na the supported one, and which one dem dey wait to delete
• anything wey dey outside repository, like staging environment or why dependency dey pinned two versions behind
• wetin you plan to do next week, because na this one dey separate file wey current from file wey useful

dox know this about itself. Its own rules talk say Work Guidance must reflect the current standards of the project or the user's instructions, and if none dey yet, you leave the section empty. Verification must reflect an existing check, so if repo no get test framework, that section go remain empty until one dey. Generated file wey invent standard worse than empty section, because agent go then enforce the invention.

Make sure hand-written intent no enter generated inventory

Na this one dey make people give up on generated docs. You write paragraph wey explain say jobs queue must remain single consumer. Three weeks later one pass rewrite the file and your paragraph don disappear, inside diff of forty lines wey mostly just rearrange file names, and nobody notice am.

Two mechanisms dey, and you need both.

First, move durable intent go another file. Design decisions and the reasons behind dem belong inside DESIGN.md wey you write for the agent, while notes wey people need belong where you separate HUMAN.md from AGENTS.md. AGENTS.md then hold the inventory and local contracts. Na exactly this part suppose change when code change.

Second, protect the intent wey must remain inside AGENTS.md. Put am inside markers and treat the block as human-owned:

## User Preferences

<!-- dox:keep start -->
The jobs queue stays single consumer. Ordering is the reason this service exists.
Deploys ship on Tuesday. A Friday deploy is a human decision, not an agent decision.
<!-- dox:keep end -->

Markdown comments no dey show for the page, but the agent still dey read dem. Now make the block survival checkable, so any pass wey remove am go fail clearly. Run this for CI (continuous integration) on every pull request:

git fetch -q origin main
sed -n '/dox:keep start/,/dox:keep end/p' AGENTS.md > /tmp/keep.head
git show origin/main:AGENTS.md | sed -n '/dox:keep start/,/dox:keep end/p' > /tmp/keep.base
diff -u /tmp/keep.base /tmp/keep.head

diff no dey print anything and e dey exit 0 when nobody touch the block. Any output mean say the pass rewrite human-owned text, so person must approve am or revert am. The check go work without anybody needing to remember am.

Generate again for pull request, no be based on timer

The best time to refresh document na the commit wey make am wrong. Put DOX pass for the same pull request wey get the structural change, and the diff go remain small enough for person to actually read am.

A blocking check wey enforces this:

#!/usr/bin/env bash
set -euo pipefail
git fetch -q origin main
base=$(git merge-base origin/main HEAD)
changed=$(git diff --name-only "$base" HEAD)
if grep -qE '^(src|apps|packages)/' <<<"$changed" && ! grep -q 'AGENTS\.md$' <<<"$changed"; then
  echo "Code changed but no AGENTS.md was touched. Run a DOX pass, or say why not."
  exit 1
fi

Change the paths to match your repository. The benefit na say e go fail for the branch, where fixing am cheap, and e go fail with reason wey reviewer fit act on.

Schedule na backup, no be the mechanism. Weekly job dey catch things wey nobody notice for branch: files wey rebase move, package wey merge delete, or document wey mention directory wey no longer exist. Run am for small box, the same one wey you fit use to run coding agent for VPS, and make am open pull request instead of pushing go main.

#!/usr/bin/env bash
set -euo pipefail
cd /srv/src/myapp
git fetch -q origin
git switch -c "dox/refresh-$(date +%Y%m%d)" origin/main
# Your agent CLI goes on the next line, in whatever non-interactive mode it offers.
# Prompt: "Run a DOX pass over this repository. Change AGENTS.md files only."
git add '*AGENTS.md'
git commit -m "dox: refresh AGENTS.md tree" || { echo "nothing to refresh"; exit 0; }
git push -q -u origin HEAD
gh pr create --fill

That comment dey there as placeholder on purpose. Every agent get im own CLI (command line interface) and im own non-interactive flag. Command wey person copy from web page but no match your version go fail inside cron, where nobody go see the error. Fill am in, then run the script by hand once before you schedule am. The || exit 0 matter too: git commit go exit non-zero with nothing to commit, working tree clean when the tree don already current, and under set -e that one go report healthy run as failure.

Every pass dey cost tokens, because “Read Before Editing” dey make agent read the whole chain for every task. Na the trade-off be that, and e worth monitoring if you don already dey count wetin your agent runs cost.

Monorepo: plenty contracts, one index

One root AGENTS.md for repository wey get forty packages fit produce regeneration diff wey nobody dey read, plus document wey mostly no relate to wetin agent dey do now. dox answer na Child DOX Index: root dey keep repo-wide rules and point to the child files, while each durable boundary dey own its file. How to arrange that tree, and which tools dey read nested files at all, dey covered for nested AGENTS.md files for monorepos.

Wetin dox change na the review surface. Pull request wey touch packages/api suppose produce documentation diff inside packages/api and nowhere else:

git diff --stat -- '*AGENTS.md'

If that command list six files for change wey affect one package, the tree no correct. Either the boundaries too broad, or person copy rule wey suppose dey root into every child. dox talk the fix directly: put broad rules for parent docs, and concrete details for child docs. Na duplicated rules dey make normal pass rewrite everything. If the same rules truly apply across separate repositories, na different problem be that, and sharing agent skills across repositories na the better tool for am.

Review diff like code

Generated documentation diff easy to approve without reading, and na so wrong file dey ship. Read am with the same suspicion wey you go use for generated code, and look for four things.

• command wey file don name now, wey you suppose run by yourself before you merge am. Invented build instructions na the most common failure.
• deleted line wey carry intent. Additions cheap. Na deletions dey cause the loss.
• absolute path, hostname, internal URL, or anything wey look like credential
• inventory entry for something wey no longer exist, wey ls fit settle within one second

Then use wc -l AGENTS.md check the size. If root file pass two hundred lines, e mean say you suppose split am, because the main value of the chain na say agent dey read the small relevant part instead of everything.

When e break

The pass delete your intent block. The diff check wey dey above go print the lines wey e remove. Restore the file from the branch point with git restore --source=origin/main AGENTS.md, then run the pass again with narrower instruction wey name the sections e fit touch.

Two branches regenerate the same thing. You go see CONFLICT (content): Merge conflict in AGENTS.md and conflict markers <<<<<<< HEAD inside the file. No edit the markers by hand. The file na generated file, so the correct way to resolve am na fresh pass over the merged tree.

The agent ignore the file completely. Check which filename your tool really dey read. If e dey read another one, point am to the same content with ln -s AGENTS.md CLAUDE.md and commit the symlink, so you keep one source instead of two documents wey go drift apart. If the filename correct already and the rules still dey skip, run the diagnosis for why coding agents dey ignore your instructions before you rewrite the document again.

The tree grow children wey nobody index. Compare the find . -name AGENTS.md output with the index entries for the parent documents. If no index mention one child, the agent fit waka pass am directly.

When generator no dey necessary

One package, one test command, and two people wey both sabi the repository: write the twenty lines by hand. AGENTS.md wey get twenty lines no dey become outdated fast enough to justify tree, index, CI check, and weekly job. Read am again anytime you change the build. Na the full maintenance cost be that, and e smaller than the cost of the machinery around am.

dox make sense when the repository get boundaries wey nobody fit remember all by themselves: several packages wey get different rules, or contributors wey dey join without the background knowledge. The value no be the generated text. Na say the documentation become something wey pull request fit fail on. Na only this reason make any file for repository stay current.

FAQ

I need install anything before I fit use dox?

No. dox na one Markdown file, e get MIT license, and as of 11 August 2026 the repository no get any package or releases. You go copy the contents enter your project's AGENTS.md, then your coding agent go follow the rules from there. Pin the commit wey you copy, f34ec7ad1055d3393887e5a2670e8cb7320c9165 as at the time of writing, and put the name for your commit message so you fit know later which version of the rules your tree use build.

How I fit stop regeneration from deleting rules wey I write by hand?

Keep intent and inventory separate. Put durable reasoning for another document, and put anything wey must remain inside AGENTS.md inside a marked block. Then check the block for CI: extract am from the branch and from origin/main with sed, compare both with diff, and fail the build if dem differ at all. Person go then approve or revert the change, instead make e pass unnoticed inside one large diff.

How often I suppose regenerate AGENTS.md?

For the pull request wey make am wrong. Structural change and the documentation wey describe am suppose dey inside one diff, because na that time person get the context to review both. Weekly scheduled pass na backup for drift wey escape from a branch, and e suppose open pull request instead of committing to main.

Build commands suppose dey for root AGENTS.md or for child?

Put dem for the nearest document wey own dem. Repo-wide rules and the child index dey for root. Command wey apply to one package dey for that package's AGENTS.md. dox dey resolve conflicts based on distance: document wey near control local details, and no child fit weaken rule from parent. Na copying the same command enter every child dey make routine pass rewrite the whole tree.

dox worth am for small repository?

Usually, no. One package with one test command and twenty-line AGENTS.md dey decay slowly, and you fit fix am within the minute wey you notice. dox earn the cost when repository get several boundaries with different rules, or contributors wey no get the background, because then the chain of documents dey do work wey no single person dey do.