The AGENTS.md Book: Source of Truth and Read Order

Start with decision domains, not a list of every document. For a small website, the first map may cover:

• website goal and audience
• approved content
• navigation and routes
• brand values and assets
• functional scope
• implementation rules
• live code and configuration
• decision rationale

Meeting notes and old screenshots can remain useful evidence. They do not need authority unless the project explicitly gives it to them.

Create a short source-of-truth.md file. Map each decision domain to one authoritative source and list any supporting material separately.

• Website goal = project/brief.md
• Routes = content/navigation.md
• Brand values = brand/brand-reference.md
• Functional scope = project/scope.md
• Current implementation = code and configuration
• Decision rationale = decisions/

If two files own the same fact, the conflict has only been renamed. Choose one owner or mark the decision as unresolved.

This site runs on the same rule. AGENTS.md carries the implementation rules and a dated record of what changed, lib/tools.ts is the only registry for the tool list, and when the two disagree the registry decides what exists while the record explains why it changed. The map costs an hour. It pays for itself the first time two files disagree.

Put the global rule where the agent is expected to load it. Keep it short: current task instructions apply first, the authority map assigns ownership by domain, scoped rules apply only inside their scope, and supporting notes cannot override an authoritative source.

Established instruction systems use scope and precedence. The AGENTS.md specification gives the closest applicable file priority, while GitHub Copilot documents several instruction scopes. Exact technical behaviour varies by tool, so check the documentation for the agent you use.

Finish with one stop rule: when no declared source resolves a conflict, the agent records the issue and asks for a human decision.

Code is authoritative for what the system currently executes. It is a poor place to preserve the full reason behind every important choice.

Use a short decision record for choices that are expensive to rediscover or likely to be challenged. The Architecture Decision Record project defines an ADR as a record of an important decision with its context and consequences.

For example, route configuration can implement /contact, while decisions/use-contact-route.md records why it replaced /get-in-touch. The code carries the current behaviour; the record carries the reason.

Names such as final.md, final-v2.md, and latest-notes.md describe confidence, not ownership. They become misleading as soon as another change arrives.

Prefer stable names such as project/brief.md, content/navigation.md, brand/brand-reference.md, and decisions/use-contact-route.md.

The ADR project recommends short, present-tense imperative names with lowercase words and dashes for decision records. The wider rule is simpler: a new person or agent should predict what a file owns from its name.

Put the read order near the top of the instruction file your agent actually supports. Its job is to route the agent, not duplicate the whole project history.

OpenAI recommends keeping AGENTS.md small and adding routing guidance when Codex reads too many documents. Its Codex team describes the file as a table of contents pointing to deeper repository knowledge. Read the Codex customization guidance and the harness-engineering example.

If your work still lives in disconnected chats, start by turning prompts into a project system. A read order only helps once those decisions live in files the agent can open.

A small website project might start here:

Read these files before changing anything:

1. `AGENTS.md` - working rules, required checks, and stop conditions.
2. `docs/source-of-truth.md` - approved decisions and conflict precedence.
3. `docs/brand.md` - approved names, tone, colours, and assets.
4. `docs/routes.md` - approved public paths and redirects.
5. `briefs/current-page.md` - the goal and scope for this task.

Keep the mandatory list short. Add conditional routes for specialist work instead of loading every document for every task:

Only when the task changes analytics, also read `docs/analytics.md`.
Only when the task changes forms, also read `docs/forms.md`.

This is progressive disclosure: the agent starts from a stable map and opens deeper material only when the current task needs it.

This is the read order only. How the agent should behave once it has read those files - workflow rules, checklists, stop rules, and recurring checks - belongs in Set Rules & Workflows, and should not be duplicated here.

A filename alone still leaves room for guessing. Add one short purpose after every path so the agent can distinguish a route decision from a tone rule or a temporary brief.

The purpose should say what the file controls. It should not summarise the file or repeat its contents. If you cannot write the purpose in one line, the file probably owns more than one thing.

Ask for a compact report before the first edit. This creates a review point before a wrong assumption spreads through code or content.

Before implementation, report:

* files read
* required files that are missing
* material conflicts found
* the source that will govern each conflict
* any unresolved decision that requires a stop

Do not start implementation until this check is complete.

A read receipt can expose missing paths and obvious conflicts. It is not proof by itself: an agent can repeat a filename without using the important value inside it.

A test that names both files and says which one wins proves only that the agent can follow that sentence. Run it in two parts, and keep the fixture harmless: no legal terms, no credentials, no tracking identifiers, no production routes.

Part one, precedence. content/navigation.md says the contact route is /contact; an archived sitemap says /get-in-touch. Ask the agent which wins, which file decides, and why - with no edits. It passes when it answers /contact and cites the rule.

Part two, the route. Put two fixture files in the read order, with one harmless disagreement: fixtures/general.md says the launch label is Preview, fixtures/page.md says Early access, and a temporary rule gives page copy to fixtures/page.md. Then start a fresh session and ask one question that names neither file: *What launch label should the page use, and which file decided it?*

It passes when the answer is Early access from fixtures/page.md. It fails when the agent returns Preview, merges the two, or cannot name the deciding file. Remove the fixtures and the temporary rule afterwards.

One pass is evidence, not a guarantee. GitHub notes that Copilot may not follow custom instructions the same way every time. Repeat the check after changing the instruction file's structure, switching agent surfaces, or reorganising the project.

Use observable evidence as the second layer: referenced files, terminal history, the final diff, and test output.

• A reference list can show that an instruction file entered the context.
• The fixture answer shows which source governed one decision.
• The diff shows what changed.
• Build, lint, and test results show whether the output passed mechanical checks.

GitHub Copilot can show custom instructions in its References list on supported Chat surfaces. OpenAI also recommends reviewing Codex terminal logs and test results before integration. See GitHub's verification note and OpenAI's Codex review guidance.

Reading the right file is only the start of correct work. Review the result against the source and the project's normal checks.

If the agent reads too much, shorten the default list and add conditional routes. A read order should not become another large manual.

If it misses a file, verify the path from the working directory. Then confirm that your agent and current surface support the instruction file you chose.

If two sources keep disagreeing, repair the documentation. A conflict rule is a decision mechanism, not permission to maintain duplicate truths forever.

If the receipt looks correct but the fixture fails, inspect the tool's built-in instruction hierarchy. A closer or higher-priority instruction may be active.

If the fixture passes but the implementation fails, read order is no longer the main problem. Improve the task brief, acceptance checks, or source content.

A named source can still be stale or wrong. Authority improves consistency; it does not guarantee accuracy.

If two authoritative sources conflict, or no source owns the disputed fact, mark it as unknown and stop. Ask the relevant owner to decide, then update the map or decision record before implementation continues.

This continues the rule from Prepare Website Inputs: missing information should stay visible instead of being invented by the builder or agent.