A diff cannot replay a Claude Code run

A pull request can tell you what Claude Code changed. It cannot tell you why the run took that path.

That gap becomes painful when the patch fails somewhere the test suite did not cover.

The reviewer can inspect the final files, but the first hypothesis has gone. So has the command that failed, the MCP result that changed the plan, and the test the agent chose not to run. The team may not even know which commit or tool versions the run started from.

Now the team has code without execution history. One engineer reads the agent’s final summary. Another searches shell history. Everyone tries to infer decisions from a diff that was never designed to record them.

For production work, that is too weak.

the diff is an output, not the run

Git is good at preserving file changes. It can show that an invoice function gained an idempotency check and that three tests changed with it.

Git cannot tell you that Claude Code first tried to modify a shared retry helper, found that refunds used the same code, and stopped after a human rejected the wider edit. It cannot show that an issue tracker MCP server supplied an old requirement. It will not record a skipped integration test unless someone adds that fact to the review evidence.

A polished final summary does not solve this. Summaries tend to make messy work look linear. They describe the path that succeeded and quietly lose the abandoned paths. Yet those failed attempts often contain the most useful risk information.

I want a compact replay record next to the diff. It should let another engineer reconstruct the control flow without preserving every token in the conversation.

what the replay record should capture

Start with the state the agent received:

run identity
starting commit
runtime and relevant tool versions
task contract
approved file and command scope
allowed MCP servers and external systems

Then record what changed during the run:

commands and tool calls
failed attempts
plan changes and their reasons
scope or permission requests
human decisions
tests run and tests skipped

Finish with the evidence needed to approve or reverse the work:

final diff
remaining risk
rollback command
reviewer decision

This is not a request for a giant transcript. A token dump can bury the one decision a reviewer needs to inspect. Capture the moments that changed the run: a failed hypothesis, a wider tool request, a changed plan, a missing test, or a human approval.

The difference is useful. A transcript tells you everything that was said. A replay record tells you what controlled the result.

a practical record for a real task

Suppose Claude Code is asked to prevent duplicate invoice submission. A useful record might look like this:

run_id: cc-2026-07-22-014
start_commit: 9f3c8d1
task: "Prevent duplicate invoice submission"
approved_scope:
  - src/invoices/**
  - tests/invoices/**
allowed_tools:
  - repository read and edit
  - focused test runner
  - issue tracker MCP, read only
plan_changes:
  - reason: "Existing retry helper is shared with refunds"
    action: "Stopped before editing shared helper"
human_decisions:
  - "Rejected shared helper edit"
  - "Approved local idempotency guard"
tests_run:
  - "pytest tests/invoices/test_submission.py"
tests_skipped:
  - "Full payment integration suite: sandbox unavailable"
remaining_risk:
  - "Cross-service retry path not exercised"
rollback: "git revert <merge_commit>"

That record gives the reviewer something concrete to challenge.

Was the issue tracker allowed to influence the design? Was the old requirement still valid? Did the local guard create a second source of truth? Is the missing integration test acceptable for this release? None of those questions are visible in the final diff alone.

The record also shows where human judgment entered the run. The agent did not simply “choose” the narrower implementation. A named decision rejected one path and approved another. That matters when the same shared helper becomes relevant in a later incident.

make replay part of the task contract

If you ask for evidence after the run, you usually get a reconstruction. The agent writes a tidy story from the context that remains. Commands may be missing. Failed approaches get compressed. Approval boundaries become vague.

Ask for the replay record before work starts instead:

Work only from the named starting commit and inside the approved scope.

Maintain a run record as you work. Record:
- commands and tool calls
- failed attempts that changed the plan
- requests for wider files, tools, or data
- human approvals and rejections
- tests run and skipped
- remaining risk and rollback

Stop if the task requires wider authority.
Return the run record with the final diff.

Now evidence is part of the deliverable rather than an administrative job at the end. The agent has to notice when its plan changes. The human reviewer gets a record written close to the decisions, not a story assembled from memory.

For a shorter preflight check, use my free Claude Code production checklist. It covers scope, permissions, tools, evals, review evidence, and rollback before a serious run begins.

MCP calls belong in the replay

MCP makes the run history more important because the agent can use context and authority that Git never sees.

A ticket, internal document, log query, cloud helper, or policy tool can change the agent’s decision without changing a repository file. If the review packet says only “used MCP for context,” the reviewer still cannot reconstruct the boundary.

Record the server, tool, access mode, purpose, and result that affected the plan. Do not put secrets or customer data into the replay record. Store a reference or redacted result where the team can retrieve it under the right access controls.

server: issue-tracker
operation: read ticket PAY-1842
access: read only
purpose: confirm retry requirement
result_reference: evidence/PAY-1842-redacted.json
plan_effect: added local idempotency guard

This is where engineering observability meets agent security. The engineering team needs enough history to review and debug the patch. The security team needs evidence that the agent used an approved identity, stayed inside the allowed data boundary, and did not turn read access into an unrecorded action.

incidents should become replay cases

Three days after merge, a customer reports a duplicate invoice. Without a replay record, the first hour goes into archaeology. The team tries to rebuild the starting state and guess which context shaped the patch.

With the record, the team can replay the missed boundary. The skipped integration suite is already named. The rejected shared helper path is visible. The MCP evidence can be checked against the requirement that was active at the time.

That trace should become an eval. Recreate the starting state, add the production failure, and test whether the next run notices the cross-service retry path. The point is not to prove that Claude Code can produce the same patch. The point is to check whether the operating controls catch the failure before another merge.

This is how observability earns its keep. It shortens diagnosis and feeds a better regression test.

where the books fit

I wrote Claude Code: Building Production Agents That Actually Scale for teams that need an operating model around agent work: task contracts, permission budgets, MCP boundaries, review packets, evals, observability, cost controls, rollback, and human approval.

The Kindle edition is available on Amazon: Claude Code on Amazon Kindle.

Securing Enterprise AI Agents covers the security side of the same record: identity, tool authority, MCP and RAG boundaries, approval evidence, audit trails, revocation, and incident response.

If you own the delivery loop and the authority model, the Enterprise AI Agents in Production bundle puts both books together.

My merge rule is blunt: if another engineer cannot reconstruct the run, the change is not ready for approval.