Node.js example
Use a Node.js AGENTS.md when the main risk is stale package commands or broad frontend edits. Include package manager, install command, development command, test command, build command, lint command, generated folders, and UI verification notes.
Example wording: 'Use npm. Run npm test before completion. Run npm run build for public page changes. Do not edit .env files, generated coverage reports, or production deployment files without approval. For UI changes, mention the route checked and any visual risk.'
Python service example
Use a Python AGENTS.md when the agent needs to know virtual environment setup, test runner, migrations, formatting, and API boundary rules. Name whether pytest, ruff, mypy, Alembic, or another tool proves the change.
Example wording: 'Create a virtual environment only when needed. Run pytest for backend changes. Do not create or edit migrations without approval. Never log secrets or customer data. If a test requires unavailable external services, report the blocker instead of weakening the test.'
Monorepo example
In a monorepo, the root AGENTS.md should stay short: repo purpose, shared safety rules, top-level install command, workspace layout, generated folders, and the rule for nested files. Then add apps/web/AGENTS.md, packages/api/AGENTS.md, or docs/AGENTS.md only when commands or ownership differ.
Example wording for a nested file: 'Inside apps/web, use npm test and npm run build. Avoid touching packages/api unless the task explicitly includes backend behavior. For routes, verify the relevant page in a browser and mention mobile overflow risk.'
What to keep out
Do not include tokens, private URLs, customer data, personal credentials, or vague taste rules. Agents follow concrete commands and file boundaries better than slogans.
Do not duplicate the full root file into every nested AGENTS.md. Duplication makes drift likely. A nested file should explain only what changes inside that directory.
Recommended play
- Start with a root AGENTS.md that covers shared commands, safety, and completion criteria.
- Add nested AGENTS.md files only for folders with different commands, generated files, or ownership.
- Keep every example copyable, but replace placeholder commands with commands that pass from a clean checkout.
- Review examples whenever package managers, CI commands, or repo boundaries change.
Which AGENTS.md example should you use?
Pick the smallest example that matches the repo shape and risk boundary.
| Area | Use this example | When it fits | What must be explicit |
|---|---|---|---|
| Root baseline | Every Codex-enabled repository | The repo has one shared install, test, and build flow | Purpose, commands, forbidden files, secrets policy, and review rule |
| Node.js app | Frontend, Next.js, React, API routes, or package scripts drive the work | UI and build commands are easy to confuse | Package manager, route checks, generated folders, and build command |
| Python service | Backend behavior, tests, migrations, or formatting are the main risk | The agent needs a clear test runner and migration rule | pytest command, migration boundary, env policy, and external service limits |
| Nested monorepo file | A folder has different commands or owner review | Root instructions would be too broad or misleading | Local commands, local forbidden paths, and when to escalate |
Execution steps
Choose the root baseline
Write the repo purpose, shared commands, safe edit scope, generated folders, secret policy, and completion standard.
Replace placeholders
Swap npm, pnpm, pytest, build, lint, and browser-check examples for commands that actually pass in the repository.
Add nested files only where needed
Create folder-level AGENTS.md files when a package has different commands, owners, generated files, or approval rules.
Test the instruction
Run one small Codex task that depends on the file and confirm the agent used the expected command and respected the boundary.
Common pitfalls
Copying examples without testing commands
Run the commands once and update the example before asking an agent to follow it.
Making nested files too long
Keep local files focused on what changes in that folder.
Turning AGENTS.md into a secrets file
List environment variable names and approval boundaries, never secret values.
Implementation checklist
- Include the repository purpose.
- List install, test, build, lint, and formatting commands when they exist.
- Name generated folders and files that should not be edited.
- State the secret and credential policy.
- Define the completion standard and expected verification output.
- Use nested files only when folder-level commands or risks differ.
Questions this guide answers
What should you do first?
Start with a root AGENTS.md that covers shared commands, safety, and completion criteria.
Who is this guide for?
Developers and maintainers writing Codex repository instructions for real projects.
What evidence supports this guide?
This guide uses listed source material from OpenAI, AGENTS.md. Source links and scope notes are available on this page.