No matter which coding agent you use, here is a recommendation that has been working for me for a while now: a decisions.md file. One file at the project root that records every significant decision from day one. The file is append-only, and every entry carries a date, what was decided, and why.
That is the whole mechanism. It costs one section in your agent's instructions file, the agent maintains it for you, and it pays for itself the first time the agent stops you from walking into a rabbit hole you already climbed out of two months ago.
Doesn't git already do this?
Yes, I know git exists. But git answers "what changed", not "why we decided this way". The commit history will tell you a migration was added in June. It will not tell you that a messaging queue was evaluated that same week and rejected because the overhead was too high for the stage the project was in. Rejected directions never show up in git at all: the whole point is that nothing got committed.
git answers "what changed". decisions.md answers "why we decided".
Two months into a project, when you are staring at something odd in the codebase and cannot remember why it is there, this file is the only place that has an answer.
How does the agent actually use it?
Here is the genuinely strong part: the file is referenced from CLAUDE.md, so Claude reads it. More than once I have asked for something and it stopped me: "We tried this on date X and decided against it, because Y happened." That has already saved me several times from re-entering a rabbit hole I had personally been down before and completely forgotten about.
To be clear, this is not guaranteed. The model ultimately does what it wants, and sometimes it will ignore the log. But like everything in working with agents, it is one more safeguard, and before anything else it is documentation for us, the humans. When I need certainty, I just say it explicitly: "check decisions.md first", or "log what we just decided".
The exact CLAUDE.md setup
You do not manage the file yourself. One section in CLAUDE.md instructs Claude to log every decision, client requirement change, and rejected direction. The project ends up writing its own diary. This is the section from my own CLAUDE.md, copy it as-is:
## Decision Log (decisions.md)
This project maintains a decision log at `decisions.md` in the project root.
**Reading:**
- Read `decisions.md` at the start of any non-trivial task.
- Before proposing an approach, check if it was already tried or explicitly
rejected. If it was, say so and reference the relevant entry instead of
proceeding.
**Writing:**
- Append a new entry whenever any of these happen:
- An architectural or design decision is made
- A requirement or spec changes (client request, scope change)
- An approach is tried and abandoned (include why)
- A constraint or "we don't do X here" rule is established
- The file is APPEND ONLY. Never edit or delete existing entries. If a
decision is reversed, add a new entry that references the old one.
- After appending an entry, confirm it briefly in your response, e.g.:
`Logged to decisions.md: 2026-07-12 - Switched session storage to Redis`
One line only. If you did NOT log anything during a task that involved a
decision, say so explicitly so the user can decide whether to log it
manually.
**Entry format:**
## YYYY-MM-DD - Short title
**Decision:** what was decided
**Context:** why, what triggered it
**Rejected alternatives:** (if relevant)The append-only rule matters more than it looks. If a decision gets reversed, the agent adds a new entry that references the old one instead of rewriting history. The wrong turns stay visible, and the wrong turns are exactly the part you will want later.
What does a real entry look like?
This one is adapted from a vetting-research platform I am currently building for a client, where research stages call paid scraping and data APIs:
## 2026-06-20 - No live paid-API calls without explicit approval
**Decision:** Tests and diagnostics never hit paid external services.
Everything replays recorded fixtures; recording new ones is a separate,
explicitly approved step.
**Context:** A quick "let me just verify the scraper works" call during a
test run triggered real paid actor runs. That instinct is exactly how spend
becomes unpredictable.
**Rejected alternatives:** Mocking at the HTTP-client level. Mocks drift
from real API responses within weeks; recorded fixtures don't.Weeks later, when the agent inevitably suggests "let me run one quick live call to verify", the log is what stops it. Not my memory, and not a lecture I have to repeat every session. That single entry has protected the project budget more reliably than I would have.
What should you take from this?
If you work with a coding agent on anything longer than a weekend project, add the section above to your CLAUDE.md (or your agent's equivalent) today. The cost is a few lines once. The payoff compounds: fewer re-litigated decisions, fewer repeated dead ends, and a project that can explain itself to any new session, human or AI. I now set this up on day one of every project, including the custom AI agents I build for clients.
FAQ
Does this work with agents other than Claude Code?
Yes. The pattern works with any coding agent that reads a project instructions file at the start of a session: Claude Code via CLAUDE.md, Cursor via its rules files, and most other agents via AGENTS.md. Point the instructions at decisions.md and define when to read and when to append.
How is this different from Architecture Decision Records (ADRs)?
Same spirit, much lighter. ADRs are typically a directory of numbered documents that humans have to remember to write. decisions.md is a single append-only file that the agent itself maintains, and it covers more than architecture: requirement changes from the client, rejected directions, and "we don't do X here" rules all get logged.
Won't the file grow too large?
Slower than you would expect. Entries are a few lines each, so months of an intensive project still amount to a small fraction of a modern context window. Because every entry starts with a dated heading, the agent can scan the headings and read only what is relevant. If it ever becomes huge, archive older entries by quarter and keep a pointer to the archive.
This is part one of a series on running an AI-agent project from plain markdown files. The other parts cover progress.md, markdown tickets, and a CI dead man's switch for tech debt. This post started as a tweet in Hebrew; if you read Hebrew, the replies have some good discussion.