One Claude Code Tip a Day: Keep a Decision Log in the Thread

This post is part of the “One Claude Code Tip a Day” series — a daily guide to using Claude Code more effectively.

The failure: the patch works, but nobody remembers why

A surprisingly common Claude Code failure appears after the tests pass. The feature works, the diff is not huge, and the session sounds confident. Then a reviewer asks, “Why did we change the cache key instead of the serializer?” or “Why is this validation now client-side?” The answer is somewhere in a long thread: one log line, one rejected hypothesis, one assumption about a flaky endpoint, and three prompts that no longer fit on screen.

Today’s habit is to keep a decision log inside the Claude Code thread. Not a formal architecture decision record. Not a meeting note. Just a compact running ledger of what the session believes, what it ruled out, what it changed, and what evidence proved the change. The log turns a messy AI coding loop into something a maintainer can audit.

Start the session with a ledger, not a patch request

Use this when the task has more than one plausible fix: a frontend bug that could be CSS or data, a webhook failure that could be config or parsing, a migration that could be schema or backfill. Before asking Claude to edit, ask it to maintain the ledger:

Prompt: `We need to fix the checkout totals bug. Read the relevant files first. Do not edit yet. Create a compact Decision Log with columns: assumption, evidence, rejected alternatives, proposed change, verification. Keep updating it whenever you learn something or change direction.`

A good first pass might say: assumption: totals are calculated twice; evidence: CartSummary.tsx formats server totals while useCheckoutTotals recomputes discounts; rejected alternative: pure CSS display bug because API response already contains the wrong amount; proposed change: make UI consume server total; verification: focused checkout test plus manual cart scenario. That is already more useful than “I’ll fix the totals logic.”

Make Claude update the log when reality disagrees

The decision log earns its keep when the first theory fails. Suppose Claude edits the UI to use the server total, but the Playwright checkout test still fails. A shallow session will reach for another patch. A better session stops and records the contradiction:

Prompt: `The test still fails. Before editing again, update the Decision Log. Which assumption was wrong? What evidence did the failed test add? What is the smallest next check that separates a fixture problem from a production-code problem?`

Now Claude has to connect the failure to evidence. It may notice the fixture builds totals with an old helper, or that the API mock is missing the new `discountCents` field. The next edit becomes narrower because the log forces the session to explain why the previous edit did not close the loop. This is the same practical pattern that makes Claude Code valuable: prompt, inspect, find the gap, correct, verify again.

Use commands and file references as evidence

Do not let the log become vibes. Tie each decision to files and commands. In a real repo, I ask for entries like: `Evidence: src/cart/calculateTotals.ts lines 42-71; test: pnpm test -- checkout-totals; browser check: cart with coupon SAVE10 shows $18.00`. If Claude says “the frontend owns the calculation,” make it cite the file that proves it.

Useful command sequence: `!git status --short`, `!git diff --stat`, `!pnpm test -- checkout-totals`, and, for UI bugs, a browser or Playwright check that observes the actual rendered state. Then prompt: `Update the Decision Log using only evidence from the files, diff, logs, and commands above. Mark any unsupported claim as unproven.`

That last sentence matters. Claude is good at filling gaps with plausible engineering stories. The log should punish plausibility and reward evidence. If the entry cannot name a file, command, log line, or visible behavior, it is not ready to guide a patch.

Second pass: review the log against the diff

Before committing or asking for a PR summary, make Claude compare the ledger to the actual patch:

Prompt: `Review the current git diff against the Decision Log. Which changes are directly justified by a logged decision? Which changes are opportunistic cleanup? Which logged decision has no code or test evidence yet? Do not edit until you list the gaps.`

This catches the classic AI residue: a renamed helper that was not needed, a test loosened to make the suite pass, a README sentence that claims a behavior the code does not implement, or a migration note that never got verified. If the log says the fix is server-owned but the diff still changes client calculation paths, ask for a correction pass. If the log mentions a manual browser check but none was run, run it or remove the claim.

Failure modes to watch for

The first failure mode is ceremony. If the decision log is longer than the patch, it becomes another artifact nobody reads. Keep it to five to eight bullets and ask Claude to replace stale entries instead of appending forever. The second failure mode is laundering weak assumptions. A table cell that says “probably a race condition” is not evidence. Mark it as a hypothesis until a log, test, or reproduction confirms it.

The third failure mode is letting the log freeze the session too early. Sometimes the best evidence says the first plan is wrong. That is not a failure; that is the point. Ask Claude to update the rejected alternatives and explain the pivot before it edits again. A good decision log is not a promise to follow the first idea. It is a trail of why the session changed its mind.

Rule of thumb

Use a decision log whenever a Claude Code session crosses from a one-file fix into investigation. If there are competing hypotheses, risky trade-offs, or multiple verification paths, the log keeps the thread honest. My rule: before the final diff review, every meaningful change should answer three questions: what evidence led to this decision, what alternative was rejected, and what check proved the decision was safe. If Claude cannot answer those from the log, do not ship the patch yet.