Course · Codex · Rules (AGENTS.md)

The size cap, fallback filenames, and why AGENTS.md is not a boundary

You can write a rule now, price what it costs, place it where it only charges rent to the sessions that need it, and phrase it so Codex actually follows it. A 36-times return on the file’s own cost, from the last lesson, is a real number. It is not the whole story. This lesson is where the chapter admits what that number does and doesn’t buy you - two practical limits that will quietly bite if you don’t know them, and one conceptual one that matters more than the rest of the chapter combined.

The size cap truncates silently

The combined AGENTS.md brief - every file Codex concatenated on its discovery walk - has a ceiling. It’s set by project_doc_max_bytes in config.toml, and the default is 32 KiB (32,768 bytes) as of this writing - a default like this is exactly the kind of value that moves between releases, so read it off the config reference rather than trusting the number here. Here’s the part that bites: once the concatenated size reaches that limit, Codex stops adding content and gives you no warning that it did. Rules past the cap simply aren’t in context, and nothing on screen tells you a rule went missing. A rule you paid to write and never got read is worse than no rule at all - you still think it’s covered, and the ledger you’ve been building this chapter doesn’t know the difference.

For budgetcli this is comfortable headroom - your money, category, and date rules are a few hundred bytes, nowhere near the cap on their own. But the cap is on the combined brief across the whole hierarchy from the last lesson. Stack a long global ~/.codex/AGENTS.md, a fat project file, and a few subdirectory files, and they all sum toward one budget - the rule you actually care about might be the one that falls off the end. The fix is the same discipline as the last lesson: keep each file lean so you never approach the limit. If you genuinely need more room, you can raise project_doc_max_bytes, but the better instinct is to prune first.

# Default is 32 KiB. Raising it is a last resort - prune first.
project_doc_max_bytes = 32768

Fallback filenames

Codex looks for AGENTS.md by name. If a project doesn’t have one, you can tell Codex to accept other filenames instead via project_doc_fallback_filenames - an array of additional names it tries when AGENTS.md is missing:

project_doc_fallback_filenames = ["CONTEXT.md", "CONVENTIONS.md"]

This is useful when a repo already carries its standing context under a different name and you’d rather not duplicate it. Note the order from the discovery walk still holds: at each level Codex checks AGENTS.override.md, then AGENTS.md, then your fallback names. The fallbacks are a safety net for the base file, not a replacement for the override. Both knobs are documented in the config reference.

The hard line: guidance is not a boundary

Now the part to internalise, and the reason a 36-times return on a rule’s cost still isn’t the end of the argument. Everything in this chapter - the money rule, “never write to ledger.db directly,” the whole file - is guidance the model interprets, not a constraint the system enforces. AGENTS.md shapes what Codex tends to do. It does not prevent anything. A great ratio on paper doesn’t change what kind of number it is.

This matters most on budgetcli precisely because it’s your own financial data. Suppose you write “never touch the production ledger database” in AGENTS.md. That’s a good rule, gradeable by the last lesson’s own bar, and Codex will usually honor it. But “usually” is not “cannot.” The model could misread the situation, a rule could fall past the silent size cap above, or a confusing prompt could lead it somewhere the rule said not to go. If the only thing standing between Codex and your real ledger is a sentence in a Markdown file, you have a wish costed to look like a guarantee, not a guardrail.

The actual guardrail is the sandbox and approval posture. That’s the entire reason the approvals-and-sandbox chapter came before this one. workspace-write with the network off, writable_roots scoped to a copy of the data, and approvals gating anything destructive establish a default capability boundary; interactive approvals can still authorize exceptions. AGENTS.md tells Codex the right thing to do; the sandbox and approval policy constrain what it can do by default. You need both, and you must never let a rule stand in for a boundary - not even one you’ve just watched pay for itself thirty-six times over.

The ledger, three rows in

Two rows opened this course’s ledger back in chapter one, and every chapter since has kept score the same way: tokens, turns, blast radius, and whether the move’s value survives past the session it happened in.

Move	Tokens	Turns	Blast radius	Recurs?
Read-only question (“what does this do”)	~3,900 est.	1	None - nothing written	No - next session starts blind again unless it’s written down
Fix the CSV date bug	~2,100 est. (csv.py alone)	4	Money-adjacent - briefly drifted into the amount field	Partly - the line holds in git, but the habit that let it drift doesn’t
Write `AGENTS.md` (the three facts)	~284 est., paid every session	0 - reads automatically, before your first prompt	None - guidance, not enforcement	Yes

That last cell is the first one in this ledger that gets to say yes. The read-only question taught you something that evaporated by the next session. The CSV fix held for one line and left the reason it broke undocumented, so the same class of mistake found a new line to hide in. The AGENTS.md you wrote this chapter doesn’t wait to be triggered again and doesn’t need a human to catch it a fourth time - it’s read fresh, in full, before Codex’s first move of every session from now on, for as long as the file stays in the repo. That’s what “recurs” means here: not that the mistake keeps coming back, but that the fix does, automatically, without you.

budgetcli now explains itself to Codex. The float-money bug, the invented categories, the day-first dates - written down once, read automatically every run, layered across scopes, phrased so Codex follows, and priced against the mistakes they replace. And you know the file’s edges: the silent size cap, the fallback names, and the hard line that guidance never substitutes for the sandbox.

But being correct isn’t the same as being efficient. Every session now reads a file that keeps Codex from guessing wrong about money - and every session, on every task, Codex still spends exactly as much thought as it would have spent anyway, whether the task was a boilerplate endpoint or the hardest design decision in the repo. Fixing what Codex knows was free once you wrote it down. What it’s still spending on how hard to think isn’t priced at all yet. That’s the next chapter: tuning reasoning effort to fit the work.