Claude Code diffs need review packets, not trust

The weakest way to review a Claude Code run is to open the diff and guess what happened.

That is still how a lot of agent work lands. The patch appears. Some tests are green. The reviewer scrolls through changed files and tries to reconstruct the task, the allowed scope, the commands that ran, the assumptions the agent made, and the risk it left behind.

That is too much archaeology for production work.

A serious agent run should finish with a review packet. I want the packet before I look at the diff, because it tells me what I am supposed to verify.

the diff is a weak audit trail

A diff answers one question: what changed?

It does not answer the questions that decide whether the change is safe enough to merge:

What did the agent think the task was?
What scope was it allowed to touch?
Which files changed, and why?
Which commands ran?
Which checks did not run?
What risk did the agent notice?
Where should the human spend attention?
How do we reverse this if it is wrong?

Those questions matter more as the agent gets more useful. A small typo fix can survive a thin explanation. A change to payments, authentication, CI, deployment config, data migration code, customer workflows, or an MCP tool cannot.

The reviewer should not have to infer all of that from a clean patch.

Green tests help, but they are not a full explanation. A test can prove the path the agent remembered to check. It cannot prove the task boundary was right, that no sensitive file was touched, that skipped checks were harmless, or that rollback is easy.

the review packet should be boring

The packet does not need theatre. Plain text is fine. YAML is fine. A pull request comment is fine. The format matters less than the habit.

This is the minimum shape I would ask Claude Code to return before merge:

review_packet:
  task_contract: "Add retry handling for payment reconciliation imports"
  allowed_scope:
    write_paths:
      - "src/payments/reconciliation/**"
    blocked_paths:
      - "auth/**"
      - "infra/**"
      - "migrations/**"
  files_changed:
    - path: "src/payments/reconciliation/importer.ts"
      reason: "Added bounded retry around transient provider failures"
    - path: "src/payments/reconciliation/importer.test.ts"
      reason: "Covered retry and permanent failure paths"
  commands_run:
    - command: "npm test -- reconciliation"
      result: "passed"
    - command: "npm run lint"
      result: "passed"
  tests_not_run:
    - name: "full integration suite"
      reason: "requires staging provider credentials"
  risk_notes:
    - "Retry count changes provider call volume during incident windows"
    - "No migration or auth change made"
  human_review_focus:
    - "Confirm retry condition does not hide permanent provider errors"
    - "Confirm log message does not expose payment metadata"
  rollback:
    - "Revert importer.ts and importer.test.ts"
    - "No data migration to reverse"

This is not paperwork. It is review leverage.

The packet gives the human a claim to test. If the agent says it only changed reconciliation code, check that first. If it says the full integration suite did not run, decide whether the merge can wait. If it says rollback is a simple revert, verify that no migration or external state change sneaked in.

ask for the packet at the start

Do not ask for the review packet as a polite summary after the run. Put it in the task contract before Claude Code starts work.

A useful instruction looks like this:

Work only inside the approved paths.
If you need broader scope, stop and ask.
At the end, return a review packet with:
- approved task
- files changed and why
- files inspected but not changed
- commands run
- checks skipped
- risk notes
- rollback path
- human review focus
Do not hide skipped checks behind a generic "tests pass" summary.

That last line matters. The most useful part of a packet is often the thing the agent did not prove.

I do not mind a skipped check when the reason is clear. Maybe the integration suite needs credentials. Maybe the service is slow. Maybe the test environment is broken. Fine. What I do not want is a confident merge note that makes the missing evidence invisible.

read the packet before the patch

The review order changes the quality of the review.

If you read the diff first, you get pulled into style, naming, and line level mechanics. Those details matter, but they are rarely the first risk with an agent run.

Read the packet first instead.

Start with the task contract. Was the delegated job small enough? Then check scope. Did the changed files stay inside the boundary? Then check skipped tests and risk notes. Are they honest? Are they proportional to the change? Then read the human review focus and decide whether the agent pointed you to the right danger.

Only then open the diff.

This does not make the review slower. It usually makes it faster, because the reviewer stops reading every line with the same level of suspicion and starts inspecting the parts that carry real risk.

review packets connect delivery and security

There is a security angle here too.

A coding agent with repo access is already exercising authority. If it can call MCP tools, run commands, update configuration, open a pull request, or trigger a workflow, the review packet is part of the control surface.

That is where Claude Code practice and enterprise agent security meet. The engineering side needs a clear delivery record. The security side needs to know what authority the agent used, where evidence lives, who approved the next step, and how access gets stopped or narrowed when the run crosses a line.

The same habit works outside code. An enterprise agent should leave a run record that names the identity it used, data it touched, tools it called, actions it took, approvals it requested, and restart or rollback conditions. A clean answer is not enough if the authority behind it is hidden.

where to start

If your team is moving Claude Code from experiments into shared repositories, start with the free production checklist. It forces the boundary, evidence, and rollback questions before the run starts: Claude Code production checklist.

If you want the full operating model for Claude Code in production work, my book covers task contracts, permission budgets, review packets, MCP and tool governance, evals, observability, rollback, and human approval. Start with the book page here: Claude Code: Building Production Agents That Actually Scale.

Kindle readers can go straight to Amazon: Claude Code on Amazon Kindle.

If your problem is broader than the repository, pair it with the security model. Securing Enterprise AI Agents covers identity, MCP boundaries, permission budgets, audit evidence, incident response, and bounded autonomy. Teams that own both delivery and risk can start with the Enterprise AI Agents in Production bundle.

The rule is simple enough to use tomorrow: no review packet, no merge.

The agent can write code. It can also bring the receipt.