Decision Journaling: Why Your Agent Needs a Decisions.md

I've had Claude Code re-propose an approach I'd already rejected two sessions earlier. It wasn't wrong to suggest it. It just had no way of knowing I'd tried it, watched it fail, and moved on. The fix took less time to write than the argument I had to re-make.

A decision log is a plain-text file, kept in the repository, that records what you chose, why you chose it, and which alternatives you rejected and why. You write to it once, and every future session, human or agent, reads from it instead of re-deriving the same answer from scratch.

Key Takeaways

• A decision log captures three things per entry: what you chose, why, and what you rejected
• It lives in the repo as a markdown file, never in a wiki or a chat thread
• Agents lose all working memory between sessions, which makes a decision log more valuable for them than it ever was for a human team
• It's the same practice as an Architecture Decision Record (ADR), just lighter and more frequent
• You'll retrofit one onto a real project in this lesson's lab, then prove a fresh agent session can use it

What Is a Decision Log?

A decision log is a dated, running record of the choices made on a project and the reasoning behind each one. Each entry names the decision, the reason it was made, and the alternatives that were considered and turned down.

That last part is the piece most notes files skip. It's easy to write down what you did. It's the rejected column that stops someone from re-proposing an approach you already tried and abandoned. A decision log without rejected alternatives is just a changelog with extra steps.

Entries are short. A typical one looks like this:

Chose: cap the retry window at 24 hours. Why: longer windows kept the job queue backed up during a provider outage, delaying unrelated jobs. Rejected: a 7-day retry window. Tested it first, and it made the backup worse, not better.

That's the whole format. No special tooling required, just a markdown file and the discipline to write three lines when a real decision gets made.

Why Agents "Forget" and Why That's Expensive

Every new agent session starts with no memory of the sessions before it, which is exactly the statelessness problem this path covers in depth later (Module 19). Nothing you argued out with the agent last week carries forward unless it's written somewhere the agent will read again.

That's expensive in a specific way: an agent cannot read your mind, and it will not reliably infer your architecture from the surrounding code. It doesn't know the simpler version was already tried and rejected. So it "fixes" what looks like unnecessary complexity, and lands you right back in the bug you already solved.

This is the same instinct that makes a skill worth writing down explicitly instead of trusting an agent to infer it fresh each time: anything that only lives in your head, or in last week's chat history, doesn't exist to a new session.

A human teammate at least remembers the meeting where you argued about the retry window. A fresh agent session has no meeting to remember. That's not a flaw you can prompt your way around. It's a structural fact about how these sessions work, and it's why a decision log matters more for agent-assisted work than it ever did for an all-human team.

Decisions.md vs Architecture Decision Records: Same Idea, Older Lineage

An Architecture Decision Record (ADR) is the formal ancestor of a decision log: one markdown file per significant decision, capturing the context, the choice, and its consequences. Teams have used ADRs for years to keep a paper trail on major architectural calls, long before agents were writing any of the code. Best practice keeps them stored centrally and updated as decisions evolve, the same rule that makes a decision log useful at all.

A Decisions.md is the same idea made lighter and more frequent. Instead of one file per big decision, it's a single running log with an entry for anything worth remembering, including smaller calls an ADR would feel too heavy for. Some teams call the agent-focused version of this an Agent Decision Record, but the format underneath hasn't really changed: what, why, what got turned down.

One thing worth clearing up: a decision log is not the same file as your CLAUDE.md or AGENTS.md. Those are standing instructions the agent follows every session, things like coding conventions or which commands to run. A decision log is a dated history of specific choices already made. The two complement each other, and a good CLAUDE.md will even tell the agent to go read the decision log before starting work. Mix them up and you end up either bloating your instructions file with one-off history nobody needs every session, or burying a rule the agent should always follow inside a log entry it might never read twice.

Retrofitting Decisions.md Onto an Existing Project

You don't need a clean slate to start one. Pick a real project you're already working on, even mid-build, and add the file today.

Put Decisions.md at the project root if the log covers the whole project, or inside a feature directory if it's specific to that feature. Either way, it goes into source control alongside the code, so it shows up in the same clone every fresh session opens.

Then work backward. You don't need to reconstruct every decision you've ever made, only the ones a future session, yours or the agent's, would otherwise re-argue. Three or four real entries are worth more than twenty vague ones written to look thorough.

Your Lab

## [Short decision title]
**Chose:** [what you did]
**Why:** [the reason]
**Rejected:** [an alternative you considered, and why you didn't use it]