The Decision Log: A Lightweight Artifact for Agentic Coding

Sun, 02 Aug 2026 10:00:00 -0500

Coding agents are remarkably good at reopening decisions you already made.

Imagine a content pipeline where posts live as local Markdown files and a database holds the scheduling metadata. You open a fresh session. Which one does the agent think is authoritative?

It has to guess. And the database looks like the better answer, because databases usually are. So it proposes the obvious cleanup: make the database the source of truth and treat the files as an export format.

It’s wrong, for a reason the code never states. You can rebuild the database from the files. You cannot rebuild the files from the database. Drop the database and you re-index from markdown, losing some operational history on the way. Lose the markdown and the posts are gone.

Some questions are still better answered by the database, scheduling among them. But the authoritative copy is whichever one you could regenerate the other from, and that asymmetry is the entire argument. It appears nowhere in the schema, nowhere in the file layout, and nowhere in the diff.

So you explain it. The agent takes the point immediately, drops the idea, and gets on with the actual work. Good outcome.

Then the session ends, and the next one arrives with the same instincts and the same blank slate. Nothing’s wrong with its reasoning. It’s missing the one piece of context the repository doesn’t contain: that road has already been walked.

That’s what a decision log is for.

Issues and Skills Leave a Gap

Agentic projects tend to accumulate two useful artifacts.

Issues describe work. Add a field, fix the retry logic, move the cache, update the API client. They tell an agent what needs to change and, if the issue is any good, what done looks like.

Skills and project instructions describe process. Use this package manager. Run these tests. Never call this destructive command. They tell an agent how work should happen, repeatedly.

Both matter. Neither is a natural home for, “We considered Redis, rejected it because this service has to run without another dependency, and we’ll reconsider if the process moves to multiple instances.”

Artifact	The question it answers
Issue	What needs to change?
Skill or instruction	How should work be done?
Decision log	Why this path instead of another one?

The code records the result. Git records the diff. A closed issue might contain the discussion, if somebody thinks to go looking for it. The decision log keeps the conclusion and the rejected alternatives somewhere an agent can find them before it starts planning.

The Rejected Option Is the Important Part

I wrote recently about decision debt, the gap created when code gets produced faster than anyone records what it means or why it exists. A decision log is one small way to pay that debt as you go.

The useful part isn’t “We chose SQLite.” The repository already contains a SQLite database. The useful part is why SQLite won, which alternatives lost, and what would have to change before the decision should be reopened.

Without that negative history, an agent sees an absence and treats it as an oversight. No Redis? Add Redis. No abstraction around this HTTP client? Generate one. No Kubernetes deployment? Surely the project just hasn’t matured enough yet.

Sometimes the missing thing is missing on purpose.

Humans do this too, of course. We reopen old arguments when the people who remember them leave, or when the conclusion is buried in a meeting recording. Agents just compress the cycle. Every fresh session is a new developer joining the project with excellent technical instincts and absolutely no institutional memory.

Keep the Entry Small

Architecture Decision Records have been around since Michael Nygard described the pattern in 2011. They preserve the status, context, decision, and consequences of an important architectural choice. Lightweight templates like MADR also capture the options considered, the decision drivers, and why one option won.

That’s the right idea. I just don’t need a formal architecture record for every consequential choice in a personal project.

I’d start with some sort of log file, holding entries like this:

## 2026-07-26: Keep Markdown as the publishing source of truth

**Context:** Posts exist as local files and as database records.
**Decision:** Frontmatter controls publish state. The database owns
scheduling metadata and is not authoritative for publishing.
**Rejected:** Making the database authoritative, or newest-write-wins.
**Why:** The database can be rebuilt from the files. The files cannot be
rebuilt from the database.
**Revisit when:** Editing moves to a multi-user hosted application.
**Links:** the repository module, the publishing documentation.

That’s the whole artifact.

An agent that reads that before it starts planning knows the database-as-source-of-truth idea isn’t a fresh insight. It also knows exactly what would have to change before it becomes one again.

I’ll be honest that I haven’t started doing this yet, but it sounds like a good idea right?

The entry doesn’t need a transcript of the debate. It needs enough context for a future person or agent to understand that the alternative was considered, why it lost, and which changed condition would make it worth discussing again.

What Belongs in the Log

If every choice becomes an entry, the log turns into another file nobody reads. I’d record a decision when at least one of these is true:

Two or more reasonable approaches existed
A future agent is likely to propose the rejected option again
The choice establishes a source of truth, security boundary, schema, dependency, or workflow
Reversing it later would be expensive or dangerous
The reason isn’t obvious from the code

Don’t log naming arguments, routine implementation details, or every library function you picked. “Used a dictionary here” isn’t institutional knowledge. “Kept provider integrations on raw HTTP because the SDK doesn’t support the endpoint we need” might be.

Major decisions can still become full ADRs in docs/decisions/ or whatever. The lightweight log is for the big middle ground between an architectural record and a comment somebody vaguely remembers leaving on a pull request.

Make Agents Read It at the Right Time

Creating the file isn’t enough. The agent needs a retrieval rule. One sentence in the project instructions:

Before proposing changes to architecture, dependencies, data ownership,
security boundaries, or core workflows, search `docs/decisions.md` for
related decisions and revisit conditions.

Then the other half:

After a consequential decision is approved, propose a short decision-log
entry. Do not record a new project policy without human confirmation.

The instruction defines the recurring behavior. The log supplies the project-specific facts. That keeps settled choices out of a giant instruction file while still putting them in the agent’s path when they matter.

When a decision changes, don’t quietly rewrite history. Add a new entry that supersedes the old one and say which revisit condition actually showed up. Version control preserves the edit, but the document should make the change legible without requiring repository archaeology.

Not Another Memory System

A chat transcript contains every false start, tool result, and half-formed idea. It’s too noisy to act as a project constitution. Agent memory can help retrieve past context, but it might be private to one tool, unavailable to a collaborator, or hard to review in a pull request.

A decision log needs to be deliberately boring. Plain text. Searchable. Reviewable. Stored next to the code, or accessible by it. Any human or agent can read the same entry and argue with it in the open.

None of this guarantees an agent will make the right call. It removes one wasteful failure mode: spending another session rediscovering a settled tradeoff and confidently proposing the option the project already rejected.

Issues tell the agent where to go. Skills tell it how to move. The decision log marks the roads we already closed, why we closed them, and when they might be worth opening again.

That feels like context worth keeping.

Sources

Documenting Architecture Decisions — Michael Nygard’s original 2011 ADR proposal.
MADR — a lightweight decision-record format covering options, rationale, consequences, and revisit conditions.
The GDS Way: Documenting architecture decisions — keeping decision rationale in the repository while using issues to track implementation.
How Claude Code works — fresh session context, compaction, project instructions, and persistent memory.

I’d appreciate a follow. You can subscribe with your email below. The emails go out once a week, or you can find me on Mastodon at @logan@llbbl.blog.

Adr on LLBBL Blog