Rules with AGENTS.md

A sandbox and an approval policy bound what a coding agent may do. There is a second lever almost every agent also gives you: a file of standing instructions the agent loads automatically at the start of every session - in Codex’s case, AGENTS.md. Write the repo’s conventions there and every session starts knowing them, without you retyping anything.

The catch is what that file is not. This chapter’s example repo, budgetcli (166 lines of Python, about 230 lines including tests, config, rules, and README), has carried a correct AGENTS.md since before you arrived. It says “Never use floats for currency” and “Never use locale-dependent date formats.” The unpublished starter fixture violates both: a day-first date parse that breaks on ISO data and a float money conversion, with the six-test suite green. In the course’s labeled continuation the earlier chapter fixes the date defect, while the money defect remains for this audit. The rules were read. The bugs shipped anyway.

That mismatch is not a reason to give up on the file. It is the bill for misunderstanding what the file is. If you expect AGENTS.md to prevent bugs, budgetcli is your counterexample: a correct, auto-loaded rules file governing a 21-line parser that broke its date rule and its money rule at once.

If you expect it to inform - to put the repo’s conventions in context before your first prompt - it has been doing that all along. When the date bug was fixed, the agent’s plan cited the ISO-date rule it had read for free, before anyone mentioned dates. A rule can inform a fix without having prevented the bug.

The trade this chapter is actually pricing

Anything written in a file Codex reads automatically gets read automatically, every session, whether or not that session touches the subject of the rule. Call that what it is: rent. The cost is not fixed - a longer file costs more tokens per session, in direct proportion - but the mechanism is. A rules file is a lease, and every line in it 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 - but what earns a line, and that turns out to be arithmetic, not taste.

Here is the claim, stated before it is earned. The file is 21 lines, 460 characters, roughly 115 estimated tokens by this course’s prose estimator (a declared teaching assumption, not a Codex measurement) - a fraction of the roughly 2,000 estimated tokens of the whole repo, paid once per session. Against that: one line of it already informed a committed fix, one line of it is being violated in a live money path right now, and one line is missing that would name the exact path the violation takes. The next four lessons do that audit line by line.

• Read the AGENTS.md you already have - the real file quoted in full, audited against the code it governs, and priced at roughly 115 tokens a session.
• Understand the discovery walk - how Codex builds its instruction chain once per session, from your global file down to the directory where you launched.
• Learn what makes a rule Codex follows versus one it skims past - and why even a file of perfect rules didn’t stop the importer.
• Know the limits of the file - the size cap that stops silently, the fallback filenames, and the hard line: guidance is never a boundary.

Start by reading the file you already have.