Keep one DECISIONS.md in the repository: one entry per decision, each with an id, what was decided, the date and why. Name it in every agent’s instructions file (AGENTS.md, CLAUDE.md, GEMINI.md), tell agents to ask before breaking a decision, and replace old decisions with new entries instead of deleting them.
What is a decision log for AI agents?
A decision log is a short file of what’s been decided on a project and why, one entry each, with an id that never changes. People have kept them for years as architecture decision records (ADRs). Coding agents need one more than people do, because every new session starts knowing nothing about yesterday. With a log, you can start fresh without losing context.
An ADR is usually one long document per decision, written for a person to read once. An agent reads its instructions at the start of every session, so its log should be the opposite: one file, short entries, newest choices clearly in force. Keep your ADRs if you have them and link each entry to its ADR.
1. Make one file the repository tracks
Create DECISIONS.md at the top of the repository and commit it. Because Git tracks it, every branch and every worktree has the same copy, and a change to it shows up in review like any other change.
2. One decision per entry: what, why, when
Give each entry an id, one line saying what was decided, a date, and the reason. The reason matters most: it’s what stops an agent “improving” the decision away. Log a choice when an agent could reasonably undo it: a library you picked, a rule about your business, something you ruled out.
3. Point every agent at it
Each agent reads its own instructions file at the start of a session. Name the log in each one, so whichever agent you open finds it:
- Codex reads
AGENTS.md. Add: “Read DECISIONS.md before you change anything.” - Claude Code reads
CLAUDE.md. Add the line@DECISIONS.mdand it reads the log too. - Gemini CLI reads
GEMINI.md, which imports a file the same way:@DECISIONS.md.
Using more than one agent on a project, or several at once? The Claude Code and Codex guide shows how to keep their rules in one file as well.
4. Ask before breaking one
Add one rule to the instructions: if a change would go against a decision, stop and ask. An agent that asks costs you a minute. An agent that quietly swaps Polar back to Stripe costs you an afternoon, and you may not notice until later.
Let agents suggest new entries, but read each one before it goes in. A decision is a choice you made; an agent’s guess written down as a decision is how drift gets in. More on that in stopping agents drifting.
5. Replace decisions, never delete them
When you change your mind, add a new entry that says which one it replaces, and mark the old one replaced. Keep the old text. An agent that finds D-012 still saying “Stripe” with nothing next to it will believe it; one that reads “Replaced by D-016” won’t.