Make AGENTS.md useful
Repo rules Codex reads before work
After this, you'll be able to write AGENTS.md guidance with commands, boundaries, proof, and project-specific rules Codex can follow.
Before you start
Complete Open the right repo before you ask first.
The idea
AGENTS.md is the repo memory Codex reads before the task starts. It should not be a company handbook. It should contain the rules Codex needs on almost every run.
| Ready | Needs work | |
|---|---|---|
| Job fit | The file names concrete commands | The task is still vague |
| Proof | The file names risky areas | The result is assumed |
| Risk | Low | Breaks when the file contains stale commands because Codex follows bad proof |
| Next move | Continue | Clarify first |
Use Ready only when the proof is visible.
Here is the before and after: before, Codex is guessing from a loose request. After, you can write AGENTS.md guidance with commands, boundaries, proof, and project-specific rules Codex can follow.
Now try it use the exercise prompt on one real repo task. Keep the output small enough to check before you accept the change.
You are ready when the Codex action, boundary, and proof all match the task.
Try it (12 min)
Watch out for
- Writing generic advice Codex already knows.
- Storing a one-off task brief in AGENTS.md.
- Adding old commands that no longer pass.
- Making the file too long for people to maintain.
Paste this into Claude
Draft an AGENTS.md for this repo: Project type: [Next.js app, Swift app, Python package, etc.] Install command: [command or unknown] Test/build commands: [commands] Do not touch: [paths or systems] Generated files: [paths or none] Style rules: [repo rules] Human approval required for: [auth, billing, schema, deployment, etc.] Write a concise AGENTS.md with sections for commands, boundaries, proof, and approval triggers.
What a good response looks like
AGENTS.md includes: install with pnpm install, run npm run lint-content and npm run build for content changes, do not edit generated sitemap by hand, ask before touching auth or billing, preserve unrelated dirty files.
What good looks like
- The file names concrete commands
- The file names risky areas
- The file separates repo rules from task-specific instructions
- The file is short enough to review
When this breaks
- Breaks when the file contains stale commands because Codex follows bad proof instructions.
- Breaks when AGENTS.md contains conflicting rules because Codex has to choose without knowing which rule wins.
AI can help with this
Use Codex to help you you can write AGENTS.md guidance with commands, boundaries, proof, and project-specific rules Codex can follow. Start with the exercise prompt and your real input. Ask for one draft, then check it against this proof: The file names concrete commands. Accept only the version you can verify yourself.
You can now
You can distinguish repo rules from task briefs
- You can name proof commands
- You can name protected areas
- You can keep AGENTS.md maintainable
Key takeaways
AGENTS.md is not documentation for everything. It is the set of repo rules Codex needs before it edits.
- Concrete commands beat generic quality advice.
- Boundaries protect risky systems.
- Stable rules belong in AGENTS.md.
- Task-specific details belong in the prompt.
Go deeper