How To Give Claude Code A Decision Record It Reads Before Changing Anything

An engineering lead approves a Claude Code change on Tuesday. The change quietly reverses a decision the team made months ago, for a reason nobody wrote down where the agent could read it. The team finds out in review, or after merge, and someone spends a day working out why the old approach existed.

The cost is rework, a callback to whoever remembers the reason, and reviewer time spent re-litigating settled questions. An agent makes this worse, because it produces consistent work fast, and consistency is what lets one wrong assumption spread. On one client’s integration estate, a set of workflow and infrastructure repositories that change together, our requirement was to change it quickly without letting an unreviewed wrong assumption spread across every repository. Every control below puts a person, or a hard boundary, where a wrong assumption would otherwise propagate.

This is the pattern Sparq uses on client integration work. You can wire the same pattern into your own repositories this week.

1. Why does Claude Code reverse earlier decisions?

Because each session starts without the reasons behind your code. The agent sees the code as it is today. It does not see the ticket that explained a constraint, the decision that chose one design over another, or the attempt that failed last quarter. Anything not in a file the agent reads does not exist for it.

Three kinds of context get lost:

• Tickets. What was asked, and why.
• Decisions. What was chosen, and which options were rejected.
• Failed attempts. What was tried and why it did not work.

Failed attempts are the costly gap. If the record only says what shipped, the agent will propose the approach that already failed, and it will propose it with confidence.

The fix is one rule: the agent reads the record before it changes anything. Put the rule in the file Claude Code loads at the start of every session, then enforce it. In Sparq’s setup, agent instructions require reading the WHY, WHAT and HOW records before changing anything. A new engineer and a new agent onboard through the same material.

2. What goes in a decision record?

If you already keep architecture decision records (ADRs), this extends them with tickets and failed attempts. A structured markdown directory, in the repository, holding tickets, decisions and failed attempts. It is plain files under version control, so context carries across sessions and reviewers see changes to it in the same pull request as the code.

Sparq organizes the record in three layers:

A layout you can copy (illustrative):

docs/
  record/
    tickets/
      TKT-0117-add-vendor-event.md
    decisions/
      DEC-0042-retry-policy-for-vendor-calls.md
    failed-attempts/
      FA-0009-synchronous-retry-loop.md
    known-bad-patterns.md
    review-ledger.md
CLAUDE.md

Here is a sample decision entry. The four fields that matter are context, decision, rejected options and status. The rejected options are what stop the agent from proposing them again.

# DEC-0042: Retry policy for vendor API calls

Status: accepted
Layer: WHAT
Supersedes: none
Related: TKT-0117, FA-0009

## Context
Vendor API calls fail intermittently under load. A failed call that
is silently retried can create a duplicate record in the system of record.

## Decision
Retry at most 3 times with exponential backoff. Every retry reports.
After the third failure, raise an alert and write a failure receipt.
Never retry a call that mutates a record unless it carries an
idempotency key.

## Rejected options
- Unbounded retry loop. Rejected: see FA-0009. Created duplicates.
- Retry inside the workflow with no alert. Rejected: failures end
  quietly, which hides them.

## Consequences
Mutating calls need an idempotency key before they can be retried.

## Status history
- accepted, reviewed by: <engineer name>

Two habits keep the directory useful. Write a failed attempt the day it fails, with the cause. And let the record name the traps found in your own estate. A known-bad-patterns.md file lists the specific traps found there, each with the incident that produced it.

3. How do you point Claude Code at the record first?

Put the rule in repository policy and in a skill, so the agent loads both before it acts. Claude Code loads the CLAUDE.md in your launch directory at the start of every session, and loads a CLAUDE.md in a subdirectory the first time it touches a file there. That makes the root file the right place for the rule, and for the context the agent needs first.

Sparq's setup uses a cascade: a root CLAUDE.md that loads every time and imports the shared standards hub, plus a CLAUDE.md in each repository. When you launch above the repositories, each repository's CLAUDE.md loads the first time Claude touches a file in that repository, not at session start, so the "Before you change anything" block has to live in the root file.

A minimal policy block for the root file (illustrative):

## Before you change anything
1. Read docs/record/known-bad-patterns.md.
2. Search docs/record/decisions and docs/record/failed-attempts for the
   area you are about to touch. Read every match.
3. State which records apply. If none apply, say so and mark the area
   as a gap. Do not guess.
4. If your change conflicts with a decision, stop. Name the decision,
   give your reason, and ask for a ruling. Do not silently comply or
   silently override.
5. Findings in areas you have not covered are hypotheses, not facts.

Add a skill that does the lookup the same way every time. Sparq keeps skills as version-controlled files, so changing the method is a pull request against one file. On Sparq's own platform build, a shared SKILL.md is read by an engineer working interactively and by a deployed agent running the same method. Sparq also treated incident history as instruction: the build guide for a second application encodes the first application's real incidents.

4. How do you keep the record current?

Make updating the record part of the change, and review it like code. A record that drifts from the code is worse than none, because the agent trusts it.

• Same pull request. A change that adds, reverses or supersedes a decision includes the record edit. Reviewers reject the change without it.
• No direct commits. Sparq's playbook repository states the rule in its CLAUDE.md: never commit directly to main. Context changes go through pull requests the same way code does.
• Supersede, don't delete. Mark the old decision superseded and link the new one. The old reasoning stays readable.
• Log disagreements. When an implementer disagrees with a record, it records the disagreement with the record name and the reason. That entry is an input to the next review.
• One escalation board. In Sparq’s setup, a single docs/record/review-ledger.md indexes every open issue and tags it by who can resolve it: an agent reading code, an agent reconciling documents, or a subject matter expert where the answer is irreducibly human.

Measure it. Pick one number and track it from the start: the share of reviewed changes that reverse a recorded decision. Sparq's own platform story is candid that adoption was not instrumented early, and that was the weakest part of it. Do not repeat that.

5. What review gates should sit between Claude Code and production?

Three gates: a human reviews the change, the record is checked in the same review, and existing CI is the only path to deployment. The agent writes code and infrastructure definitions. It does not ship them.

1. Intake and review. In Sparq’s projects, the intended workflow is: fill in a form, hand it to Claude Code, review the output. Forms cover intake, adding an event and architecture decisions.
2. Record check. The reviewer confirms the change cites the records it relied on and that any new decision is written down.
3. Existing pipelines deploy. In Sparq’s setup, plan runs on pull request and apply runs on merge. Claude Code has no deployment authority. The existing CI pipelines deploy.

One more rule from Sparq's own build applies to every gate: a gate that fails open is a critical bug. A review stage on Sparq's platform returned "ready" whenever its conversion step errored, so an asset that could not be reviewed was treated as reviewed and passed. A gate whose failure mode is approval manufactures confidence that nothing checked the work. Sparq rebuilt it so that a failed reviewer counts as an abstention, not an approval.

6. How does a role-guard hook enforce the rules?

A hook checks every tool call against a versioned ruleset before it runs, fails closed, and writes an append-only log. Instructions ask the agent to behave. A hook makes the behavior checkable.

In Sparq’s setup, an AGENT_ROLE setting sets the role. A role-guard hook blocks the implementer role from editing the WHY, WHAT and pattern records. An implementer that disagrees pushes back, names the record and its reason, and records the disagreement rather than silently complying.

The hook does three things on every tool call:

1. Reads the proposed action and the active role.
2. Applies the first matching rule. No matching rule means deny.
3. Appends one line to the log: the proposed action, the rule applied, and allow or deny.

Illustrative rules (adapt the paths and names to your repositories):

# role-guard rules, evaluated top to bottom, first match wins
default: deny            # fails closed: no rule, no action

rules:
  - id: R1
    role: implementer
    action: edit
    paths: ["docs/record/decisions/**", "docs/record/known-bad-patterns.md"]
    effect: deny
    reason: "Implementer proposes changes to WHY/WHAT records. A human rules."

  - id: R2
    role: implementer
    action: edit
    paths: ["src/**", "infra/**", "docs/record/failed-attempts/**"]
    effect: allow

  - id: R3
    action: bash
    command_class: mutating   # git push, rm, terraform apply, etc.
    effect: deny

  - id: R4
    action: bash
    command_class: read_inspect
    effect: allow

  - id: R5
    action: mcp
    server_not_in: ["approved-docs-server"]
    effect: deny

Set onFailure to “block” on the hook itself (Claude Code v2.1.295 or later). By default a hook that crashes or times out lets the call through.

Each decision appends one line to a log the agent cannot rewrite:

{"ts":"2026-10-27T15:02:11Z","role":"implementer","proposed":"edit docs/record/decisions/DEC-0042.md","rule":"R1","decision":"deny"}

The log is only tamper proof if the agent can’t write to it. Keep the log and the hook script outside every path the agent can write.

The limits Sparq applies to Claude Code

The hook is one layer of several. The full set of controls, including the filesystem boundary, sandbox, command policy, MCP change control, deployment limits and per-occasion grants, is covered in Claude pilot to production playbook.

What can you apply this week?

Do these six things, in this order. Each one takes hours, not weeks.

• Create docs/record/ with decisions/, failed-attempts/ and known-bad-patterns.md.
• Write the five decisions your team re-argues most often, including the rejected options.
• Write the last three failed attempts, with the cause of each.
• Add the "Before you change anything" block to your root CLAUDE.md.
• Add one review rule: a change that touches a recorded area must cite the record.
• Pick your metric: the share of reviewed changes that reverse a recorded decision. Measure it weekly.

Setting up the hook, sandbox and command policy takes more time than a week. Start with the record and the review rule, then add enforcement.

Sparq sets up Claude Code for engineering teams: repository policy, skills, prompt libraries, telemetry and human review gates. See the Anthropic (Claude) implementation work.