Codex AGENTS.md: give your repository a working brief

I would rather write the build command once than correct the same generated-file mistake in six conversations. A repository needs a short working brief that survives the end of the chat.

That is the job I give AGENTS.md: preserve the facts an incoming operator needs to make a responsible change. Think of it as the note taped inside the workshop door, not the entire company handbook.

Put recurring mistakes into explicit rules

For a generated website, a useful instruction says which files are source and which are output. If articles come from JSON and templates, editing the generated HTML alone creates a change that disappears on the next build. That is a repository fact worth preserving.

For the fictional Cedar Metrics reporting project, the equivalent rule might say that campaigns.json is the immutable fixture and report.md is generated output. The agent should change the report generator when behavior changes, then regenerate and verify the result.

I would write instructions from concrete failure modes rather than aspirations. “Be careful” cannot guide a decision. “Preserve the source fixture and write derived reports to a separate path” can. Each rule should help the agent choose an action when the repository presents an ambiguity.

Understand which instructions load

Codex discovers instructions through a defined startup process. Global guidance comes from the Codex home location, commonly ~/.codex, and project guidance is collected along the path from the project root to the current working directory. More specific guidance can refine rules for the area being worked on.

The current documentation gives AGENTS.override.md precedence over AGENTS.md within an inspected directory. It also documents a default project-document size limit of 32 KiB. These details matter when a long file or an unexpected override makes the effective instructions differ from what you intended.

Keep the hierarchy shallow enough to explain. A root brief can describe the whole project, while a nested file can describe a specialized subdirectory. Avoid contradictory instructions scattered through the tree and then hoping the agent interprets your organizational history correctly.

Write the first project brief

A small AGENTS.md should explain what the project is, where its source lives, how to build it and how to verify a change. Add important constraints such as preserving raw inputs or avoiding generated-file-only edits. Keep commands exact enough to run from a named directory.

The example below describes a fictional Python reporting project. Its commands are a pattern to adapt after checking your own repository; do not paste nonexistent commands into a real project. Incorrect persistent instructions can waste more time than no instructions because they look authoritative.

I would also define the expected completion note: changed files, checks run and material limitations. That makes the agent’s final report easier to assess without asking for a transcript of every command.

Separate instructions from reference material

AGENTS.md is a good place for rules that apply broadly to work in the repository. A long product brief, research archive or full API manual usually belongs in a referenced document. The startup brief can point to it and explain when it matters.

This separation keeps the working context focused. If every task loads pages of unrelated background, the important build rule has to compete with material that may not apply. A short instruction plus an authoritative path is easier to maintain and inspect.

For Cedar Metrics, keep metric definitions beside the dataset or in a maintained reference file. In AGENTS.md, require the agent to use those definitions and preserve their meaning. You avoid maintaining two slightly different descriptions of the same business metric.

Use nested files for real local differences

A repository can contain different kinds of work. The website directory may need accessibility checks, while the reporting directory needs calculation tests. A nested AGENTS.md can describe the rules for that part of the tree without burdening unrelated tasks.

Use this only when the boundary is meaningful. A separate file for every small preference creates a scavenger hunt. Start with root guidance, then add local rules when there is a clear difference in source structure, toolchain or review requirements.

When moving a task between directories, confirm the effective guidance. The applicable instruction path depends on the project and working directory at startup. If a rule seems absent, investigate discovery and scope rather than repeatedly telling the agent to remember harder.

Test whether the instructions affect behavior

After editing startup guidance, start a new session in the intended directory. Ask Codex to identify the authoritative source, build command and verification steps for a small task. Compare its answer with the file and project structure.

Then give it a bounded change that exercises an important rule. For the fictional reporting project, ask for a wording correction in the generated report. A useful result identifies the source that generates the wording, changes that source and rebuilds the output.

The goal is behavioral verification, not merely hearing the filename repeated. An agent can acknowledge AGENTS.md and still take the wrong path if the instruction is ambiguous or contradicted by the repository. Improve the rule around the actual decision it needs to guide.

Keep preferences and permissions separate

An instruction can say to preserve source data or avoid external writes, but runtime access is controlled by the environment and permission policy. Do not confuse a prose rule with an enforced filesystem or network boundary.

Likewise, AGENTS.md should not contain API keys, service tokens or private credentials. Use the supported secret configuration for the tool that needs them. Repository guidance is designed to be read by the agent and often by teammates; it is a poor place to hide anything.

I would pair clear instructions with appropriate permissions. The brief explains the intended workflow, while the runtime controls what actions are available. Both matter, and one does not make the other redundant.

Where repository instructions go wrong

The common failures are stale commands, contradictory local files and a root brief that tries to document every possible workflow. Instructions should change with the project. A renamed build script should trigger a corresponding update to the working brief.

Another failure is turning every one-off preference into a permanent rule. Keep task-specific decisions in the task unless they represent a durable project convention. Use a skill for a repeatable procedure that should load only when relevant.

Review AGENTS.md when onboarding a teammate or changing the toolchain. If a human cannot explain it, an agent is unlikely to make it simpler. Which repeated correction in your repository belongs in a short, testable instruction?

How to set it up

Frequently asked questions

Sources & further reading

• Instruction discovery and precedence
• Skill authoring
• Runtime permissions

ChatGPT and Codex change quickly. This page was last reviewed September 22, 2026; verify time-sensitive details against the official docs above before relying on them.