What belongs in AGENTS.md—and what should be retrieved per task?

Give the instruction file a clear job.

An instruction file is most useful when it makes ordinary work predictable: how to build, which checks matter, where a boundary lives, and which stable conventions apply. It becomes harder to maintain when every incident, temporary workaround, and completed task contributes another permanent paragraph.

Before adding an entry, ask which future task should receive it. If the answer is almost every task in this scope, it may belong in project instructions. If the answer is one kind of change or a historical explanation that needs checking, attach it more selectively. This is an authoring rule of thumb, not a claim about a model’s guaranteed behavior.

Instruction discovery is tool-specific.

Codex documents an instruction chain that combines applicable guidance from broader locations down to the current working directory. It supports directory-level overrides and configurable fallbacks. The actual chain, limits, and scope should be checked in its current documentation.

Current Claude Code documentation also describes AGENTS.md support, alongside CLAUDE.md. Which files load can depend on version, project configuration, and other instruction files. Do not assume a filename gives every coding tool identical behavior, and do not add an old import workaround without checking whether it is needed.

After changing instructions, verify what the tool loaded in a fresh relevant task. Existence in the repository is not proof of inclusion. If a requirement needs deterministic enforcement, use the appropriate build, policy, test, or permission boundary rather than relying on prose alone.

Sort the proposed entry.

Work an example before rewriting the file.

Suppose the project guidance has grown to include a long story about retries. It contains one stable convention—use the existing request identifier—and an incident-specific explanation about acceptance succeeding before a response is lost. It also contains an old note that a consumer audit is pending.

Keep the durable convention concise and link its contract. Move the incident reasoning into a dated, inspectable decision record. Check the consumer audit’s actual status; retain it as pending if that remains true, or replace the stale task status with the verified result and date. Do not silently delete a live dependency because it looks historical.

For the next retry change, assemble a brief from those sources. The brief should include the relevant invariant, the incident sequence, current code, and any unresolved conflict policy. A change to an unrelated UI should not have to interpret the entire retry history.

Edit by responsibility, not by word count.

Take a small section of your instruction file. Label each entry stable guidance, scoped guidance, task state, decision evidence, or uncertainty. Choose an owner and a maintenance trigger for anything you keep. Deleting redundant prose is useful when the remaining rule still points to enough context to act correctly.

Do not split a file into many imports merely to make the top file look short. Depending on the tool, imported content may still be loaded. The objective is relevant guidance and clear ownership, not a cosmetic line-count target.

Entry: reuse the existing order request ID.
Scope: changes to order creation and retry handling.
Authoritative contract: link the current accepted decision.
Task evidence to retrieve: lost-response incident and current behavior.
Open questions: list policies not established by those sources.
Refresh trigger: accepted contract change or relevant incident.

Check the next task, then keep the smallest useful structure.

Give a coding assistant a relevant change and ask it to identify the applicable instructions and unresolved questions before implementation. Inspect its source references. Then try an unrelated task and check whether the guidance creates unnecessary work.

For a team, this creates a modest maintenance practice: each instruction needs a scope and a reason; each changing record needs an owner and a freshness trigger. Start with one troublesome section rather than rewriting the whole repository handbook.

Use the native instruction system when it is sufficient. Introduce task retrieval when important reasoning is scattered or changes over time, and keep the evidence inspectable. The two mechanisms solve different parts of the same preparation problem.