Lesson 5 / 7 · ~10 minutes

AGENTS.md:
project memory

Every task starts with a clean slate — the agent doesn't remember what it did yesterday. The solution is a file called AGENTS.md in the project folder: Codex reads it automatically before every task. It's the handover between yesterday and today.

And it has one extra superpower: AGENTS.md is an open standard — the same file is read by Codex, Cursor and a growing list of other AI tools. Write the rules once and they apply to every agent you let near the project. (If you know CLAUDE.md from Claude Code, this is its standardised sibling — the same philosophy.)

What belongs in it

  • What the project is — a sentence or two.
  • How it runs and tests — "open index.html", "tests: npm test".
  • Rules — the language of the copy, what not to touch, code style.
  • Current state — what's done, what's in progress.

Don't write it by hand: the /init command creates it, and at the end of a work session just say "write the current state into AGENTS.md". The agent keeps its own notebook — you just check it now and then.

Builder: what belongs in AGENTS.md?

Eight blocks for a fictional coffee e-shop. Click the four that belong in AGENTS.md, then evaluate.

"Project: the Zrnko e-shop. Static HTML in the web/ folder, products in data/products.json."

Belongs — what the project is and where things live. The first thing the agent needs for every task.

"Admin panel password: Zrnko2026!"

Doesn't belong — never put passwords in AGENTS.md (lesson 4). The file travels with the project and every tool reads it.

"Run: open web/index.html. Tests: npm test — run them after every change."

Belongs — exactly what the agent needs to check its own work without asking.

"Monday we tried blue, Tuesday green, Kate wanted beige, so maybe beige…"

Doesn't belong — a diary of experiments eats context and doesn't help. History lives in git; keep only standing decisions here.

"Rules: write copy in English. Don't change anything in the photos-original/ folder."

Belongs — rules and prohibitions apply to every task without reminders. And since AGENTS.md is a standard, other tools honour them too.

"Agent, please work thoroughly, creatively, and think like a senior developer."

Doesn't belong — empty incantations improve nothing. Spend context space on facts about the project.

"State: catalogue and cart done. In progress: payment gateway — waiting for test credentials."

Belongs — current state and unfinished work. The next task knows exactly where to pick up.

The entire contents of app.js, copied into AGENTS.md "so the agent doesn't have to look for it".

Doesn't belong — code lives in files and the agent reads it by itself. A copy only goes stale and eats context.

Summary

  • Codex reads AGENTS.md before every task — and other tools understand it too.
  • It holds: what the project is, how it runs and tests, rules, state.
  • Not: passwords, diaries, copied code, incantations.
  • /init creates it; delegate the updates to the agent.
← Previous Final lesson: A task from A to Z →