Terms in this guide: AGENTS.md · Context
An AGENTS.md file gives Codex durable instructions about how work should happen in a repository. The useful version reads like a maintainer briefing: short, specific, and easy to verify.
Start with the repository map
Explain where the application code, tests, documentation, generated files, and deployment configuration live. This reduces aimless searching and makes the first plan more accurate.
- Name the main runtime directories.
- Point to the closest tests for each area.
- Call out generated or vendored paths.
- Describe any nested instruction files.
Make validation executable
Write the exact commands that prove a change works. Include the working directory when a monorepo or subproject requires it, and distinguish fast focused checks from the full suite.
# Validation
- Unit tests: npm test
- Focused test: npm test -- path/to/test
- Lint: npm run lint
- Production build: npm run buildState boundaries with a reason
A useful boundary tells Codex what to avoid and why. Explain which interfaces are stable, which data is sensitive, and which actions require coordination. Review the file whenever team practice changes.
- Keep instructions local to the repository or subtree they govern.
- Prefer direct commands over vague quality goals.
- Remove rules that no longer reflect the codebase.
- Test the file against a real task and revise confusing language.
Official references
Continue with a practical next step
Progress stays in this browser. No account needed.
Updates and upgrade guidance
- Learning context added
Added prerequisites, a suggested practice estimate, expected output, and connected definitions. The article procedure was not independently re-evaluated in this change.
What to do: Use the opening checklist to prepare. No software update is required for this editorial change.
This log starts with the first recorded review; it is not a reconstruction of earlier revisions.