The concept
AGENTS.md is a plain text file in your project that tells Codex how your team works. Codex loads it before it starts, so you don't repeat rules in every prompt.
How Codex finds it:
- Personal file: ~/.codex/AGENTS.md applies to all your projects.
- Project file: AGENTS.md at the root of the repo (the top folder).
- Folder files: an AGENTS.md in a subfolder adds rules for that area; the closest file wins.
The fastest start: type /init in the Codex CLI and it drafts an AGENTS.md for you to edit.
Walkthrough: an insurance premium-quote calculator
Illustrative repo: a car-insurance quote tool. Unguided, an agent might round too early, apply discounts in the wrong order or "tidy up" rate tables.
The root AGENTS.md, short on purpose:
Project: premium quote calculator
- Run tests with: pytest
- Money: use Decimal, round to 2 decimals only on the final premium.
- Order: base rate, then surcharges, then discounts.
- Every new rating rule needs a test with a worked example.
- Never log customer names or dates of birth.
And rates/AGENTS.md:
- These tables come from the pricing team. Don't edit values; ask instead.
Now ask Codex: "Add a 10% no-claims discount."
Illustrative numbers:
1. Base premium: $600.00
2. Young-driver surcharge, flat +$150: $750.00
3. No-claims discount −10%: $675.00
The Order rule puts the discount after the surcharge (wrong order: $540 + $150 = $690). The test rule adds a test asserting $675.00. rates/AGENTS.md keeps the tables untouched.
When Codex gets something wrong, ask it to add the lesson to AGENTS.md so the next session inherits it.
Where you see it at work
- Insurance: rating order and rounding rules every change must follow.
- Banking: "never print account numbers" and the approved test command.
- Healthcare: where patient data may and may not appear.
- Retail: which pricing files need a second reviewer.
- Business analysts: business rules written where the agent reads them.
Try it today (10–15 min)
1. Read the official guide: https://learn.chatgpt.com/docs/agent-configuration/agents-md
2. In yesterday's project, run codex, then /init.
3. Cut the draft to 5 rules you'd tell a new teammate.
4. Start a new session and ask: "Summarize the rules you're following in this repo."
Keep it short: Codex stops reading past a size limit (32 KiB by default).
In one sentence
AGENTS.md is the onboarding note for your coding agent: short, specific rules in the repo, loaded before every task.
What's the one rule you'd put first in your team's AGENTS.md? 👇