Writing AGENTS.md project instructions
Generating a starting file with /init, how global, repository and nested files combine, and which instructions actually change behaviour.
Generating and shaping the file
# let the agent draft a first version from what it can see
codex
> /init
# then edit it by hand: the draft is a starting point, not a specification
git add AGENTS.md && git commit -m "Add AGENTS.md with build and test instructions"# AGENTS.md
## Build and test
- Python 3.12, dependencies via `uv sync`.
- Run the test suite with `uv run pytest -q`. Never run `pytest` directly.
- Type check with `uv run mypy src`. Both must pass before a change is complete.
## Layout
- `src/api/` HTTP handlers. Keep them thin: validation and calls only.
- `src/domain/` business logic. No framework imports belong here.
- `tests/` mirrors `src/`. One test file per module, named `test_<module>.py`.
## Conventions
- Format with ruff; do not hand-format.
- Every public function has a type signature. No `Any` without a comment explaining why.
- Errors are raised as subclasses of `AppError`, never as bare `Exception`.
- Database changes require a migration in `migrations/` with a reversible `downgrade`.
## Do not
- Do not modify `tests/` beyond the file named in the task.
- Do not add a dependency without asking. This repository has a strict review policy.
- Do not touch `infra/` or `.github/workflows/` in a feature task.- The build and test commands are the highest-value lines. An agent that knows the exact command verifies its own work instead of guessing.
- The layout section prevents the most common failure: putting logic in the wrong layer because nothing told it where things belong.
- Prohibitions matter as much as instructions. "Do not modify tests" is the single line that stops a run from reaching a green suite by weakening an assertion.
- Keep it to roughly one screen. Instructions that run long get diluted, and unrelated rules compete for attention.
How the files combine
| Location | Scope | Typical content |
|---|---|---|
Global (~/.codex/AGENTS.md) | Every project on this machine | Personal preferences: commit style, language, verbosity |
Repository root AGENTS.md | The whole project | Build, test, layout, conventions, prohibitions |
Nested AGENTS.md in a subdirectory | That subtree | Module-specific rules, local commands, extra context |
AGENTS.override.md | Replaces the file at the same level | Rare: use when the local rules must not be blended |
| Inline instructions in the task | The current run only | The specific outcome and constraints for this task |
# nested files let a monorepo carry local rules without one giant root file
repo/
AGENTS.md # build, global conventions
services/api/AGENTS.md # python service specifics
web/AGENTS.md # node, pnpm, component conventions
infra/AGENTS.md # terraform: plan before apply, never apply unattended
# verify what the agent is actually reading for a given path
codex --sandbox read-only "list every instruction file you are following and where it is"- Instructions combine down the tree: the root file applies everywhere, and a nested file adds detail for its subtree. Avoid repeating the root rules in a nested file.
- The global file is personal and untracked. Team-wide rules belong in the repository, or a new contributor inherits none of them.
- Contradictions are unavoidable if they exist. If the root says "run pytest" and a nested file says "use tox", the agent will pick one and you will not know which.
- An instruction file is code. Review changes to it in a pull request, and expect a change to alter agent behaviour across the whole team.
What actually changes behaviour
| Instruction | Effect | Why |
|---|---|---|
| The exact test command | Strong | Turns an unverified task into a verified one |
| A stated prohibition | Strong | Removes a whole category of unwanted change |
| A named file to copy the pattern from | Strong | Gives a concrete example rather than an abstraction |
| A short, specific convention | Moderate | Followed when it is unambiguous |
| A long style guide | Weak | Dilutes the rest and is rarely applied consistently |
| Vague quality aspirations | None | "Write clean code" changes nothing observable |
💡
Write instructions the way you would brief a contractor on their first day: the commands to run, where things live, what must not be touched. Anything you would not say out loud in that briefing is probably not worth the tokens.
FAQ
How long should AGENTS.md be?
Long enough to name the build and test commands, the layout, the conventions that are not enforced by tooling, and the prohibitions. That is usually under a page. If it is longer, move the detail into the tools instead.
Should I commit it?
Yes. Checked in, it is reviewed, versioned and shared. Untracked, it exists only on your machine and silently diverges from your colleagues'.
Related
What Codex is and how to set it up Configuration with config.toml and profiles
Last refreshed 2026-09-18.