Rules with AGENTS.md

Go back to the moment at the end of Ship your first reviewed change. Codex quietly wrote float(row["amount"]) where budgetcli has stored every amount as an integer number of cents since before you inherited the repo. You caught it because you were reading a four-line diff. You fixed it, and the fix is in git now - it isn’t going anywhere. The ledger cell you left behind already said the honest thing about it: the line holds, but the habit that let it drift doesn’t, so the drift comes back.

It already has. Onboarding a fourth bank’s CSV, the job this whole course is building toward, reintroduces that exact class of mistake three separate times on a Monday cold start - and the one you just caught was the first. Nothing about that session told Codex budgetcli treats money as integer cents. It guessed, the way most APIs handle currency, and guessed wrong. Two sessions from now, on a file you haven’t opened yet, it will guess the same way again, because nothing you said out loud on Monday survived the session that heard it. That is the villain of this course wearing its cheapest disguise: not an agent that cannot understand your conventions, but one that has to be told them again every single morning. It has been running up a bill since chapter one. This chapter is where the bill stops.

The trade this chapter is actually pricing

Not by catching the mistake faster. By making sure Codex never has to guess in the first place - and that fix has a cost of its own, which is the real subject of this chapter. Anything you write into a file Codex reads automatically gets read automatically, every session, whether or not that session ever touches money at all. Call it what it is: rent. A rules file isn’t a place to dump everything you know about budgetcli; it’s a lease, and every line renews itself, unread by you, on every run. So the question this chapter answers is never “what could I tell it” - you could tell it anything - it’s what earns a line, and that turns out to be arithmetic, not taste.

Quick check before you keep reading: if you’ve corrected Codex on the same fact more than once this week, on budgetcli or a repo of your own, you already have the problem this chapter solves. If you haven’t yet, the arithmetic below still holds - you’re just early.

Here’s the claim, stated before it’s earned. The file this chapter ends with is 32 lines, comes to roughly 284 tokens by the same estimator this course has used since chapter one, and gets read automatically before Codex’s first move of every session. Against that: one reintroduction of the float-money bug costs a full re-read of the file where the rule actually lives, plus the turn that finds the mistake, plus the turn that fixes it - and Monday alone paid that bill three times. Price both sides properly and the file doesn’t just look worth it. It looks absurdly cheap. The next four lessons do the pricing.

• Write the first AGENTS.md - the three facts Codex keeps guessing wrong, captured once, and what the file actually costs to carry.
• Understand the discovery walk - how Codex finds and concatenates every AGENTS.md from your git root down to where you launched, and why not every fact should pay rent everywhere.
• Learn what makes a rule Codex follows versus one it skims past - and the exact arithmetic that says whether a given line earns its rent.
• Know the limits of the file - the size cap that truncates silently, and the hard line: guidance is never a boundary.

Start by writing the first AGENTS.md.