Claude Code review receipts

When Claude Code writes a pull request, the fastest way to review it is a receipt: a one-page record of what changed, which context the agent used, what it was allowed to touch, and what evidence backs the merge. A review receipt is a short, copyable note that turns "did this work?" into "was this allowed, and how do we know?" Claude Code, Anthropic's coding agent, can produce a lot of diff quickly, so the bottleneck moves to review. This piece shows a small artifact that keeps that review honest without slowing your team down.

The goal is to make every Claude-authored PR legible in about a minute. You read one page, you trust it or you don't, and the next PR uses the same shape.

Keep CLAUDE.md short so reviewers can trust it

Claude Code reads CLAUDE.md as always-on context, so it earns its place only when it stays durable and short. The moment it starts reading like a wiki, with tribal knowledge, one-off exceptions, and stale instructions in one file, it stops helping reviewers and starts hiding things.

Split memory by scope. Keep global facts in the root file, push repo-local rules into nested CLAUDE.md files closer to the code they govern, and delete anything that is really a one-time task prompt. A good test: if a rule changes every week, it probably does not belong in memory at all.

This matters for review because a reviewer who trusts the memory files can skim them. A reviewer who suspects they are stale has to re-derive intent on every PR, which is exactly the cost the receipt is meant to remove.

Turn repeated review steps into a skill

If you keep pasting the same review steps into chat, you already have a hidden workflow. Skills fix this because they load on demand instead of all the time, and they are built for repeatable procedures. The team gets one named procedure it can invoke, inspect, and improve, rather than a long prompt copied into every PR.

A simple rule keeps this from sprawling: if the same instruction shows up in three reviews, promote it to a skill. After that, the review shape is something you can point at and version, not folklore.

Permissions deserve the same discipline. If Claude Code can read, edit, fetch, or call MCP tools without a clear boundary, review becomes a performance. Write a short Permission Note for the repo: which tools, which directories, which connectors are allowed. Then review that note with the same care you give code. If a reviewer cannot name the allowed surface, the surface is too wide.

Push mechanical checks into hooks

Hooks are where teams get determinism back. They run outside the model loop, which makes them the right home for checks that should never depend on a good prompt: formatting, logging, lifecycle checks, and permission gates. Clever reasoning does not belong here; a hook that blocks a bad state before it reaches a human does.

The payoff is that evidence shows up before the debate starts. A reviewer opening the PR already sees that formatting ran and the gates held, so the conversation can be about the actual change.

MCP connectors need the same scrutiny. The Model Context Protocol connects Claude Code to external systems, which is useful and also widens the blast radius. Treat every new MCP server or .mcp.json edit as a permission review covering scope, least privilege, and data flow, not as a plumbing detail. A connector that changes what the agent can reach changes the review.

Paste this review receipt into the PR

Here is the artifact. Drop it into the pull request description for any Claude-authored change and fill it in.

# Claude Code Review Receipt

## Change summary
- What changed:
- Why it changed:
- Files touched:

## Context used
- Root CLAUDE.md reviewed: yes/no
- Nested repo rules reviewed: yes/no
- Skill used: yes/no
- Hook(s) involved: yes/no
- MCP connector(s) involved: yes/no

## Permission check
- Allowed directories:
- Allowed tools:
- New external access introduced: yes/no
- If yes, reviewed by:

## Review evidence
- Tests run:
- Manual checks:
- Known gaps:
- Follow-up issue:

## Reviewer decision
- Approve / Request changes / Needs follow-up
- Reviewer notes:

The receipt is small on purpose. It gives reviewers one page to trust and gives the team one shape to improve over time. It adds a little process, and that cost is worth paying when Claude Code is touching shared repos, permissions, or connectors. It will not fix bad code on its own, though. It makes the review legible, and the rest still rests on tests, code quality, and human judgment.

Common questions

• What is a Claude Code review receipt?

  A review receipt is a one-page note attached to a Claude-authored pull request. It records the change summary, the context the agent used (CLAUDE.md, skills, hooks, MCP connectors), a permission check listing allowed directories and tools, the review evidence, and the reviewer's decision. It exists so anyone can audit the change in about a minute.

• When should an instruction become a skill?

  When the same instruction shows up in three reviews, promote it to a skill. Skills load on demand and are meant for repeatable procedures, so recurring review checks become one named thing the team can invoke, inspect, and improve. Pasting the same steps into chat every time is a sign you already have a workflow worth naming.

• How wide should Claude Code permissions be?

  Narrow enough that a reviewer can name the allowed surface. Write a Permission Note for the repo listing which tools, directories, and connectors are allowed, then review it like code. If nobody can state the boundary, it is too wide. The Claude Code permissions docs cover tool-specific rules, sandboxing, and managed settings in detail.

• Does a review receipt fix bad code?

  No. A receipt makes the review legible, not the code correct. It is worth the small process cost when Claude Code touches shared repos, permissions, or connectors, because it shrinks every PR to one auditable page. Whether the change is actually good still comes down to tests, code quality, and a human reading the diff.

Start with one repo

Pick a single repo and add the review receipt to its next Claude Code pull request, then keep the shape that leaves the shortest auditable trail. For the broader operating model, see our Claude Code team conventions.

Further reading

• Claude Code: getting started
• Claude Code: skills
• Claude Code: hooks
• Claude Code: permissions
• Model Context Protocol: specification
• Anthropic: Claude Code product page
• GitHub: anthropics/skills
• Claude Code team conventions
• Our methodology