The Decision Log Pattern That Stops AI Re-Litigating Choices

A decision log is a flat file (usually DECISIONS.md) at the root of your repo that records every architectural choice as one line. Date, decision, one-sentence reason. Reference it from your CLAUDE.md or AGENTS.md so the AI reads it on every conversation. The pattern stops your AI from re-proposing libraries you rejected, re-suggesting deprecated patterns, and re-opening trade-offs you already settled. Twenty seconds of writing today saves an hour of arguing with your AI next month.

This post is a working tutorial. We will walk through what a decision log actually looks like, what to write in it (and what not to), and how it plugs into the memory features that ship with Claude Code, Cursor, and Cline.

Why You Keep Having The Same Argument

Every senior developer who has used AI coding tools for more than a month has had this experience. You spend an hour on Tuesday convincing the AI not to use Prisma because you moved to Drizzle for edge runtime reasons. The conversation ends. Friday rolls around. New chat, new feature. The AI cheerfully suggests adding a Prisma migration. You sigh. You explain again. You move on.

The reason this happens is mechanical, not malicious. The AI has no state between conversations. The "decision" you reached on Tuesday lives only in the chat history of that specific Tuesday session, which is now closed. From the AI's perspective on Friday, no decision was ever made. It is generating from priors: most projects in its training data use Prisma, so Prisma is the safe default to suggest. It does not know about your specific exception until you tell it again.

The amnesia compounds. After three months on a real project, you have probably accumulated 20 to 50 architectural decisions. ORM choice, auth provider, deployment target, state management, styling approach, testing framework, error handling pattern, validation library, dozens more. Without a decision log, every fresh conversation rolls the dice on every one of those choices. The AI is right by accident sometimes; it is wrong and confidently wrong the rest of the time.

The decision log fixes the underlying cause. Once a decision is in DECISIONS.md and DECISIONS.md is referenced from CLAUDE.md, it is in front of the model on every conversation. The AI stops re-suggesting Prisma not because it learned, but because every request now arrives with a line that says "we picked Drizzle over Prisma for the edge runtime." The argument never restarts.

The pattern is borrowed from a long tradition in human engineering: ADRs (architecture decision records) have been around for over a decade, originally as a way to capture team decisions for the sake of new hires and future-you. AI tools are basically the world's most insistent new hire. They benefit from the same artifact, just in a tighter format.

What A Decision Log Actually Looks Like

The format that holds up best is intentionally minimal. One line per decision. Date, decision, reason. No ceremony.

Here is a real example from a small SaaS, names trimmed:

# Decisions

## Active stack
- 2026-01-08: Next.js 16 App Router. Server actions + RSCs over API routes.
- 2026-01-08: Drizzle, not Prisma. Prisma client too heavy on Cloudflare Workers.
- 2026-01-12: Supabase for DB and auth. Want RLS, not rolling our own.
- 2026-01-15: Tailwind v4 + shadcn/ui. Not styled-components, not vanilla extract.
- 2026-01-20: Resend for transactional. Not Postmark, not SES.
- 2026-02-02: Inngest for background jobs. Not Trigger.dev, not BullMQ.
- 2026-02-10: Drizzle migrations via drizzle-kit, never write raw SQL migrations.

## Things we explicitly are not doing
- 2026-01-18: No Redux, no Zustand. Server state in RSCs, client state in URL.
- 2026-01-25: No NextAuth. Supabase Auth handles everything we need.
- 2026-02-04: No GraphQL layer. tRPC if we ever need typed RPC, REST otherwise.

## Hard rules
- All DB writes go through server actions, never client-side.
- Never use any in TypeScript. Use unknown and narrow.
- All env vars validated via env.ts at boot, never inline process.env access.

That is the whole file. About 25 lines. It will grow over time as the project accumulates real decisions, but the bar to keep the file lean is high. If a line has not been load-bearing in three months and the underlying decision is clearly settled in the code, prune it.

The three sections are pulling their weight in different ways. "Active stack" tells the AI what to use. "Things we explicitly are not doing" tells the AI what to avoid (the most valuable section, because rejecting wrong defaults is half the value). "Hard rules" tells the AI invariants that are non-negotiable.

You may notice none of these entries explain themselves at length. That is deliberate. The AI does not need a 200-word essay on why you picked Drizzle. It needs the line. If you want richer context for human readers, fork that into a separate ADR folder; do not bloat DECISIONS.md.

How To Adopt It This Week

You can be running this pattern by the end of today. Five steps.

Step one, create DECISIONS.md. Touch the file at the root of your repo. Empty file is fine. The point is to have somewhere to write.

Step two, seed it with the last five real decisions you made. Walk back through your last two weeks of work. What library did you pick or reject? What architectural call did you settle? What pattern did your team agree on in Slack? Write each as a one-line entry with the approximate date.

Step three, reference it from CLAUDE.md or AGENTS.md. This is the move that actually wires the file into the AI's context. In CLAUDE.md, add a line like Always read @DECISIONS.md before suggesting libraries or patterns. In AGENTS.md, add a similar reference. Claude Code's import syntax (@DECISIONS.md) pulls the file into context automatically. Cursor and Cline will read the reference and follow it. The AI now starts every conversation with your decisions in hand.

Step four, write entries as you go. This is the habit that makes the pattern work long-term. Every time you make a real architectural call ("we are not using Server Actions for the admin pages, going REST"), write a one-line entry. The cost is 20 seconds. The savings show up two weeks later in conversations that do not have to relitigate the choice.

Step five, prune quarterly. Once a quarter, walk through the file and delete entries that are now obvious from the code itself or that have been superseded by a later decision. The file is meant to be a small, current snapshot, not a complete history. The complete history is in git.

The first week of this pattern feels overhead-heavy. By week three you stop noticing the writing step, and you start noticing how often the AI agrees with you on the first try.

How It Connects To Tool Memory Features

Each major editor has shipped some flavor of memory feature in 2025 or 2026. The decision log is not redundant with these; it sits next to them and does a different job.

Claude Code has the /memory command, which writes scratch notes the model retains across sessions, plus first-class support for CLAUDE.md imports. The clean division: /memory is for ephemeral observations the AI accumulates ("user prefers tabs, not spaces, when refactoring"). DECISIONS.md is for the deliberate architectural calls a human writes down. Different purposes, complementary tools.

Cursor has project rules (auto-attached files in .cursor/rules/). The decision log fits naturally as one of those rules files. Configure DECISIONS.md to attach automatically to every conversation, alongside a stack-specific rule for your framework. The combination gives Cursor the same end result as the Claude Code setup: every session arrives with the constraints in hand.

Cline goes a step further with its memory bank, a structured set of files the AI maintains itself across sessions. The decision log plays well with the memory bank as long as you keep them logically separate: the log is human-written and authoritative; the memory bank is AI-written and exploratory. If they conflict, the log wins.

The newer GitHub Copilot Workspace and Continue.dev integrations also support custom rules files, and the decision log slots into them the same way. The general principle: any tool that lets you attach a markdown file to every conversation can run this pattern. Most tools in 2026 do.

The deeper point is that the decision log is not a tool feature. It is a discipline that uses tool features to do its job. Tools come and go; the discipline of writing decisions down survives the migration to whatever editor you use next year.

The other failure mode is letting the file accumulate without ever pruning. After two years, an unpruned DECISIONS.md is 800 lines of mostly-superseded calls that drown the relevant signal. A quarterly review takes 15 minutes and keeps the file load-bearing. Treat the prune like a CI dependency upgrade: small, frequent, mandatory.

What This Means For You

The decision log is the cheapest move in the entire memory layer. No tool to install. No subscription to add. No new editor to learn. Twenty seconds of writing each time you settle a real choice, paired with one line in your CLAUDE.md, and the AI stops fighting you on settled questions.

• If you are a senior developer on a team, propose this pattern in your next standup. The team will adopt it inside a week if you write the first 10 entries yourself. Senior engineers underestimate how much of their daily AI friction comes from the AI reproposing rejected approaches.
• If you are an indie hacker, you are the highest-leverage user of this pattern. You have no team to absorb the cost of context loss. Every "wait, why did I pick this?" thought you have on Sunday is a question DECISIONS.md should be answering for you. Start the file today.
• If you are leading a small team, treat DECISIONS.md as a first-class artifact. Review it on PRs the way you review code. New hires read it on day one. The AI reads it on every conversation. It compounds in a way few other engineering practices do.
• If you are a student or career changer working on portfolio projects, adopt the pattern even on solo work. You will train the habit before joining a team where it is expected, and the projects you ship will look noticeably more thought-through to anyone reviewing your code.

The decision log will not feel transformative on day one. By week four it will feel like one of those obviously-correct practices you cannot believe you used to skip. The AI gets noticeably less argumentative. Your week starts feeling longer because you spend less of it re-explaining choices that were already settled. The quiet efficiency gain compounds for as long as the project lives.