Rules with AGENTS.md

The approvals and sandbox work made Codex safe on your financial data — it can’t touch the real ledger or reach the network without you saying so. But safe isn’t the same as correct. Across the last few sessions you’ve watched Codex make the same mistakes on a loop. You fix the float-money bug in one file; two sessions later it writes amount * 1.0 in another and reintroduces it. You tell it the category list, it nods, and next turn it invents "dining" when the project has only ever used "groceries" and "restaurants". Every session you re-teach budgetcli from scratch, and every session the lesson evaporates when the context window closes.

That re-teaching tax is exactly what this chapter ends. Codex looks for a file called AGENTS.md and reads it automatically before it does any work — once per run, at the top of every session, no flag required. A fact you write there is a fact you never re-establish. This is context engineering at its most concrete: you stop renting Codex its knowledge of budgetcli by the session and start owning it.

What AGENTS.md is — and isn’t

AGENTS.md is plain Markdown that you author. Rules, domain facts, conventions, the commands that matter, the things Codex would otherwise get wrong. It’s the standing brief you’d hand a new teammate on day one, except you write it once and Codex re-reads it on every launch. It is guidance — instructions the model interprets and tends to follow, not a switch it’s mechanically forced to obey. That distinction matters enough that the last lesson of this chapter is entirely about it: AGENTS.md is not a security boundary. The sandbox is. Rules shape behavior; they don’t enforce it.

The bugs we’ll stop reintroducing

Same budgetcli you’ve been living in. Over the next few lessons you’ll stop re-explaining it and start writing it down so Codex actually follows along:

• Write the first AGENTS.md — money is integer cents never float, the real category list, how dates are handled. The three facts Codex keeps fumbling, captured once.
• Understand the discovery walk — how Codex finds and concatenates every AGENTS.md from your git root down to where you launched, why the closer file wins, where ~/.codex/AGENTS.md and AGENTS.override.md fit.
• Learn what makes a rule Codex follows versus one it ignores — concrete and testable beats vague and polite, with budgetcli examples you could grade.
• Know the limits of the file — the size cap that truncates silently, the fallback filenames, and the hard line: guidance is not a boundary.

By the end, budgetcli will explain itself to Codex. You’ll open each session already past the float-money bug and the made-up categories, instead of re-arguing them for the hundredth time.

Start by writing the first AGENTS.md.