1.3 AGENTS.md: Repo Memory

If this course only left you with one habit, this would be the one.

Here's the problem it solves. Without an AGENTS.md, every new session starts from zero — Codex has to re-derive your conventions by reading files, guessing at patterns, and occasionally guessing wrong. You'll watch it scaffold a component using a pattern your team abandoned eighteen months ago, not because it's bad at reading code, but because nothing told it that decision existed. That correction costs you a message, a re-generation, and a small dent in trust. Multiply that across every session, every teammate, every week, and it adds up to real friction that has nothing to do with model quality.

AGENTS.md is a plain markdown file — max 32 KiB, YAML frontmatter plus regular markdown content — sitting at your project root, read automatically at the start of every session. It's not an OpenAI-only convention either: the same file format is shared across Codex, Cursor, GitHub Copilot, and tens of thousands of open-source repos, which means writing a good one pays off even outside Codex specifically. Treat it as the onboarding doc you'd hand a sharp new hire on day one — not a full engineering wiki, just the stuff that actually changes what they'd do differently.

Four things worth including, in rough order of how often they save you: commands, stated exactly — not "run the tests" but pnpm test, not "start the server" but pnpm dev --port 3001. Ambiguity here means Codex guesses between npm, yarn, and pnpm and sometimes guesses wrong on a monorepo with mixed tooling. Architecture notes — the two or three things you'd genuinely explain out loud to a new engineer on day one: where state lives, how routing is wired, what part of the codebase is generated and should never be hand-edited. Conventions — naming patterns, folder structure, which library is "the" choice when there are three equally valid options in the ecosystem. And guardrails, phrased as rules, not suggestions: "never edit files under /generated," "always add a test when touching /api," "ask before adding a new dependency." These read like instructions to the model because that's exactly what they are.

The mistake on the other side is writing too much. A sprawling AGENTS.md gets loaded into every session whether it's relevant or not — that's context spent before you've typed a word, on things that might matter for one file out of your entire repo. Keep it tight, and one security note worth knowing as of late 2026: Codex skips loading AGENTS.md entirely on projects it doesn't yet trust, as a safety measure against a malicious repo trying to plant instructions for an agent to follow blindly. When Codex gets something wrong specifically because it didn't know a convention, fix the AGENTS.md right then, not just that one conversation — that correction is worth ten times more written down than said once.