All chapters
  1. Start hereOne change, from diff to production
  2. Before stage 1The team setup: what changes when you are not alone
  3. Stage 1Code change: catch it while the agent is still editing
  4. Stage 2Commit: what must be true before a commit exists
  5. Stage 3Pull request: arrive already reviewed, with evidence
  6. Stage 4Review: who reviews what, at hundreds a day
  7. Stage 5CI/CD: spend scarce capacity like a budget
  8. Deep diveCI/CD agents: where they live and how they run
  9. Deep diveBuild the agents: pinpoint the change, then fix it
  10. Stage 6When the change is an agent
  11. OperateVolume and cost: what breaks at 300 a day
  12. AdoptAdopt it in steps
  13. ReferenceHook events: which one, with a script for each
  14. ReferenceGlossary
  15. AboutAbout this site
Stage 3

Pull request: arrive already reviewed, with evidence

Move the review before the pull request. A local review is feedback; a review signed by a trusted runner lets CI verify the work instead of repeating it.

At 09:34 the developer runs the team's ship skill, and pull request #4812 opens. Until this moment the change for ORD-2187 was private: six files and one commit, 8c1f0a4, that only the developer and a coding agent had seen. Now it costs other people something. The required checks start on shared runners, two owner teams are asked to review within a minute, and the pull request joins about 300 others opened at Acme that day.

Times, counts and costs on this page are illustrative.

From here, every problem found is a fix round: a new commit, every check again, another review, another notification. So two questions decide how expensive this stage is. Could the review happen before the pull request opens, while the developer still has the change in mind? And if it did, could CI trust that review, or must it repeat it?

Review before the pull request, not after. A review done on the developer machine is fast feedback. It becomes a passing check only when a trusted system produced it and signed what it reviewed.

1. Why reviewing only after the pull request gets expensive#

The obvious design, and the one most teams start with, is to review in CI only. The pull request opens, a reviewer agent reads the diff, and people read what it found. There is one trusted place for the verdict and nothing else to build. Call it approach A.

Follow #4812 to see what it costs. The reviewer agent posts two findings at 09:40, six minutes after the pull request opened. By then the developer has moved to the next task.

One finding is fixed in a new commit at 09:44, which starts every check again; the other waits for an API owner until 10:20; a second review round runs at 10:31. The Review page follows that loop in full. The point here is where it happens: every round runs at the shared, expensive place, and every round interrupts someone who had already moved on.

At a few pull requests a day, that is fine. At 300, the queue fills with changes nobody has looked at yet, and a large share of CI and reviewer time goes to finding problems a quick look before the push could have found. The cause is not the review itself. It is that the first feedback arrives only after the change has become everyone's cost.

2. Moving the review onto the developer machine#

The fix is to run a review earlier, before anything leaves the machine. Acme does it in the pre-push git hook, the script git runs once per push before it sends commits to the server (what that event is). The hook first runs the affected tests, then starts a review of the branch against main.

The review is a headless run of the coding agent: one non-interactive command, a fixed prompt in, a JSON result out, no chat window. Where the files behind it live and how CI starts the same agent are explained on CI/CD agents. The important choice is that the local run uses the same reviewer as CI: --agent code-reviewer runs it as a subagent (an agent definition with its own tools, model and prompt, in .claude/agents/), here .claude/agents/code-reviewer.md, and that file preloads the skill review-rules. One set of files serves the developer and the pipeline, so the two reviews cannot drift apart because someone edited one copy (why a personal copy must go).

The hook follows four rules, and each one exists for a reason.

The script below is meant to show those four rules working together: what happens on a clean result, on findings, on an override and on a review that could not run. A successful run proves that the hook behaves as described on this machine. It does not prove that the review is right, and it proves nothing to CI.

The local review, in codeThe review part of .githooks/pre-push, its flags and its output schema

This is a simplified demonstration. It reviews HEAD against origin/main and ignores the list of refs git passes on standard input, so a push of several branches at once reviews only the current one. A production hook reads that list, as the pre-push reference does, and reviews each pushed range.

#!/usr/bin/env bash
# .githooks/pre-push: the local review part. It runs after the affected tests.
# Enable once per clone: git config core.hooksPath .githooks
set -u
BASE=$(git merge-base origin/main HEAD)
HEAD_ID=$(git rev-parse HEAD)
RECEIPT=.review/local-receipt.json     # per developer; listed in .gitignore

# The developer read the findings for this exact commit and pushes anyway, with a reason.
if [ -n "${REVIEW_OVERRIDE:-}" ] && [ -f "$RECEIPT" ] \
   && [ "$(jq -r '.head' "$RECEIPT")" = "$HEAD_ID" ]; then
  jq --arg r "$REVIEW_OVERRIDE" '.overridden = $r' "$RECEIPT" > "$RECEIPT.tmp" \
    && mv "$RECEIPT.tmp" "$RECEIPT"
  echo "pre-push: local review findings overridden: $REVIEW_OVERRIDE" >&2
  exit 0
fi

# stdin is git's list of refs, not a prompt: give the agent nothing on stdin.
OUT=$(claude -p "Review the changes in $BASE..HEAD for correctness bugs. Report findings as JSON." \
  --agent code-reviewer \
  --permission-mode dontAsk \
  --allowedTools "Read,Grep,Glob,Bash(git diff *),Bash(git log *)" \
  --max-turns 15 --max-budget-usd 2 \
  --output-format json --json-schema "$(cat .review/findings.schema.json)" </dev/null)
STATUS=$?

# The review could not run: say so, and never block the push for that.
if [ "$STATUS" -ne 0 ] || ! printf '%s' "$OUT" | jq -e '.structured_output' >/dev/null 2>&1; then
  echo "pre-push: local review did not complete; pushing without it" >&2
  exit 0
fi

mkdir -p .review
printf '%s' "$OUT" | jq --arg head "$HEAD_ID" --arg base "$BASE" \
  '.structured_output + {head: $head, base: $base, signed: false}' > "$RECEIPT"
COUNT=$(jq '.findings | length' "$RECEIPT")
if [ "$COUNT" -gt 0 ]; then
  jq -r '.findings[] | "  \(.file):\(.line) \(.severity): \(.message)"' "$RECEIPT" >&2
  echo "pre-push: $COUNT finding(s). Fix them, or push again with REVIEW_OVERRIDE=\"<reason>\"." >&2
  exit 1      # non-zero: git does not push
fi
echo "pre-push: local review: 0 findings" >&2
exit 0

The override is a design on this site, not a git or Claude Code feature. It applies only to the commit that was reviewed: a new commit gets a new review. The receipt file it writes is the local receipt of section 3.

FlagWhy it is there
--agent code-reviewerThe run takes the subagent's tools, model and system prompt from .claude/agents/code-reviewer.md, the same file CI names. Its skills field preloads review-rules.
--permission-mode dontAskAnything not pre-approved is denied at once instead of waiting for a prompt nobody will answer. File reads inside the working folder still run. The flag also overrides a defaultMode from the developer's settings, such as acceptEdits or bypassPermissions, that would let the reviewer edit.
--allowedToolsApproves reading, searching, git diff and git log; no edit tools. A reviewer that can edit is an author. These are permission rules on command text, not a read-only guarantee: git log --output=<file> still matches Bash(git log *).
--max-turns, --max-budget-usdTwo caps on one run: 15 turns and 2 USD. The budget is checked against a client-side estimate, not the invoice, and spend can pass it.
--output-format json with --json-schemaA structured result a script can read, in the field structured_output. When a run ends without valid output, that field is missing, so the script checks for it before using it.
</dev/nullIn headless mode Claude Code reads standard input. Inside a pre-push hook, standard input holds git's list of refs, which must not become part of the prompt.

The schema the result must match. The reviewer's own prompt asks for the same fields.

{
  "type": "object",
  "required": ["findings", "verdict"],
  "properties": {
    "verdict": { "enum": ["pass", "changes-needed"] },
    "findings": {
      "type": "array",
      "items": {
        "type": "object",
        "required": ["file", "line", "severity", "message"],
        "properties": {
          "file": { "type": "string" },
          "line": { "type": "integer" },
          "severity": { "enum": ["high", "medium", "low"] },
          "message": { "type": "string" },
          "fix": { "type": "string" }
        }
      }
    }
  }
}

Three cautions come with this step. The tool list is a permission filter, not a sandbox; an unattended reviewer should also get a read-only file system and no network beyond the model provider. The review adds a wait before every push, so measure that wait and its cost before claiming a saving. And a developer can skip the whole hook with git push --no-verify, which is one more reason the hook can only ever give feedback.

Inside an interactive session the same kind of review is one command in Claude Code, /code-review, with effort levels from low to max, and --fix to apply the findings to the working tree.

3. Why the local review can never be the verdict#

On #4812, the local review printed "0 findings". Both problems the CI review found at 09:40 were already in the diff: create_order.py did not check the limit of 500 characters, and orders.yaml listed delivery_note under required. The same reviewer, with the same rules, found them six minutes later in CI.

That is not a sign that local reviews are careless. The same agent, run twice on the same input, does not always take the same path or reach the same answer; When the change is an agent measures this. In this illustrative day, the local run happened to miss and the CI run happened to find. On another day it could be the other way round.

But even a local review that found everything could not count as the verdict, and this is the real reason. Nobody can prove what it ran on. The developer machine is controlled by the person, or the agent, whose work is being judged.

A file that says "pass" next to the right diff hash proves only which diff the file describes, not that a review ran, which reviewer ran it, or with which rules. Anyone can write that file, and so can an agent asked to make the push go through.

So the file the hook writes needs a precise name and a precise strength. A local receipt records what a local review looked at and what it concluded. It is feedback for the developer and evidence a human reviewer may read. It proves nothing to CI, because what matters to CI is not whether the review was good, but where it came from.

4. Local feedback, CI verdict: the first step for most teams#

Put the two halves together and you get approach C. The local review gives fast feedback while the change is fresh. The CI review, which runs where the contributor cannot change it, gives the verdict. This needs no new infrastructure: one hook script and the reviewer files the team already has.

Its cost is honest and easy to miss. A clean diff is reviewed twice, once on the laptop and once in CI. The saving is not fewer CI reviews. It is fewer fix rounds on the pull request: problems the local review catches are fixed before the pull request exists, so they never cost a CI run, a second review or a reviewer's attention.

That leaves one waste. When the local review and the CI review would say the same thing, CI repeats work it could have reused, if only it could trust where the first review came from. That is a narrower problem, and it has a design.

5. A review CI can trust: the attested receipt#

To be trusted, the review must run somewhere the contributor does not control, and the result must be bound to exactly what was reviewed. An attested receipt does both. Like the local receipt, it is a pattern on this site, not a product feature. The table shows how the two strengths differ.

PropertyLocal receipt (approach C)Attested receipt (approach D)
Produced byThe developer machineA trusted review runner the contributor does not control
ProvesNothing to CI. A hash shows which diff a file describes, not that a review ran.That this reviewer, with these rules, reviewed exactly these inputs
Used forFeedback to the developer; evidence a human reviewer can readPassing the required review check without a second review
CI doesRuns its own reviewVerifies the signature and the inputs

The mistake to avoid is treating the first as the second. A contributor, or an agent, can write a local receipt with the correct diff hash and the word "pass". Checking the hash does not catch that. Only a signature from a key the contributor cannot reach does.

#4812 cannot show this step, because it is a red-lane change, and an attested receipt is never reused for the red lane (section 6). The example is its yellow sibling from the same day, #4819, a rounding fix on branch fix/cart-rounding. Its local review reported two findings; the coding agent fixed both, and the next push was clean.

The developer then pushes the branch to a review ref: a branch name pattern that starts a review but opens no pull request. A trusted runner reviews it with the same reviewer files, returns any findings to the developer, and, when the verdict is pass, signs a manifest of everything that went into the review. This is the shape of that manifest; the values are descriptions, not real hashes.

{
  "head_tree": "tree hash of the reviewed commit",
  "base_tree": "tree hash of the base it was compared with",
  "rules_digest": "hash of the review rules, read from the base branch",
  "prompt_digest": "hash of the review prompt and the output schema",
  "model": "model and version",
  "tool_policy_digest": "hash of the tools the reviewer was allowed",
  "run_status": "completed",
  "lane": "yellow",
  "verdict": "pass",
  "signed_by": "the review service, with a key contributors cannot reach"
}

When pull request #4819 opens, the required review check does four cheap things instead of a review:

  1. Verify the signature against the review service's public key.
  2. Recompute the inputs from the pull request: head tree, base tree, rules digest, lane. Nothing is read from the contributor's copy.
  3. Compare every field with the review CI would run now, including the prompt, model and tool-policy digests. All equal, the run completed, and the lane allows reuse: the check passes and the findings are attached. A missing field counts as different.
  4. Otherwise run the review in CI, as in approach A.

Diagram: The attested review receipt · review before the pull request, verify after

Time runs down the page. The top half is feedback on the developer machine; nothing there is trusted. The middle is a trusted runner that reviews the pushed branch and signs what it reviewed. The bottom is the pull request check, which verifies the signature and recomputes every input itself.

  1. Developer machine: Local review: 2 findings, fixed. A headless review with no edit tools, for fast feedback. Its result proves nothing to anyone else.
  2. Developer machine to Trusted review runner: Push to a review ref. A branch name pattern that starts a review and opens no pull request.
  3. Trusted review runner to Developer machine: Findings, or pass. The developer still has the change in mind. Findings are fixed and pushed again.
  4. Trusted review runner: Sign the run record. Head tree, base tree, digests of the rules, the prompt and the tool policy, model version, run status, lane and verdict, signed with a key contributors cannot reach.
  5. Developer machine to Pull request: Open the pull request. It starts with its evidence attached.
  6. Pull request to Required check: New pull request. The required check starts.
  7. Required check: Verify signature, recompute inputs. Nothing is read from the contributor's copy. A red-lane path, a changed tree, a moved base, newer rules, another prompt or model, or a missing field all mean: review here.
  8. Required check to Pull request: All equal: review check passes. No second agent review. The human approval for the lane is still required.
  9. Required check to Pull request: Otherwise: run the review in CI. The fallback is the ordinary CI review. An unsigned receipt never passes a check.

The top of the diagram is the developer machine, where nothing is trusted. The middle is the trusted runner, the only place a signature is made. The bottom is the pull request check, which trusts the signature only after recomputing every input itself.

The receipt replaces the second agent review. It does not replace the teammate's approval that the yellow lane still requires.

6. What can go wrong with a receipt#

A signed receipt moves trust from "the review ran here" to "the review ran there, on these inputs". Each way that claim can become false needs a guard, and one of them, a base branch that keeps moving, decides whether the design pays off at all.

FailureGuard
A forged local receiptIt has no signature, so it never passes a check. This is why the local receipt is feedback only.
The code changed after the reviewThe head tree differs. CI runs the review.
The base branch movedThe base tree differs. On a busy repository the base moves every few minutes, so a receipt bound to the whole tree is almost always stale. The practical binding is narrower: the changed files plus the files they depend on, taken from the build graph. A merge elsewhere then leaves the receipt valid, and the merge queue still tests the combination. The cost is trust in the dependency graph; a missing edge means a stale review is reused.
The review rules changed sinceThe rules digest differs. CI runs the review.
A red-lane path is in the diffAttested receipts are not reused for the red lane. See Review.
The contributor edits the review workflowOn GitHub, a workflow started by a push is read from the pushed commit, so a branch can rewrite the job that reviews it. The review and the signing must run from a workflow pinned to main, which the pushed branch only calls.
The signing key leaksEvery receipt becomes forgeable. Keep the key in the review service only, rotate it, and log every signature.
The reviewer itself is wrongA receipt proves a review ran, not that it was right. A fixed sample of reused receipts is re-reviewed to measure quality. Sampling is a quality measure, not an authenticity control.

Read the table as a list of what the signature cannot do. It proves where a review came from and what it covered. It says nothing about whether the review was right, and nothing once any input has changed.

7. The four approaches side by side#

With the failures in view, the choice is easier to see. Each approach buys something and pays for it.

ApproachWhat it buysWhat goes wrongUse it when
A. Review in CI onlyOne trusted place. Simple.Findings arrive after the developer has moved on. Each fix is another push and another review. The queue grows.Low volume
B. Review locally onlyFast feedback while the context is freshNobody can prove it ran, or what it ran on. Anyone can write "pass" into a file.Never as the only review
C. Local review for feedback, CI review for the verdictFast feedback and a trusted verdict. No new infrastructure.The clean diff is reviewed twice. The saving is fewer fix rounds on the pull request, not fewer CI reviews.The right first step for most teams
D. Attested review before the pull requestThe trusted review itself moves before the pull request. CI verifies a signature instead of repeating the work.A signing service to build and protect. More inputs that can go stale.High volume, after C has been measured

The recommended path is C first, then D only if the numbers ask for it. D pays only when receipts are still valid when the pull request opens, so measure the reuse rate under approach C's conditions before building a signing service.

8. #4812 at this stage, from push to open pull request#

Here is the stage as it actually ran for the change we follow, using approach C. What enters: the local commit 8c1f0a4 on the branch feat/order-delivery-note. What must leave: pull request #4812, with a body that tells a reviewer what the change is, what it can break and what was already checked.

TimeWhat happensWho actsResult
09:34The developer runs the team's ship skill. It calls git push.The developer, then the model; the agent's push guard (guard-push.sh) allows a push to a feature branchGit starts the pre-push hook before anything leaves the machine
09:34The affected tests run once for the whole pushThe pre-push git hook, through tools/affected-tests.sh14 tests pass
09:34The local review reads the diff against mainThe same hook starts a headless run as code-reviewer, with read and search tools and two git subcommands; no edit toolsNo findings. This is feedback, not a verdict.
09:34The branch is pushed. Then gh pr create, with the body from the template.Git, then the modelThe repository host accepts the branch, opens pull request #4812 and starts the required checks
09:35The lane check reads the changed pathsThe CI job, from the base branchLane red: the diff touches the API contract and a migration. The author did not choose this. The check stays pending until the owners approve (how).

The line the pre-push hook printed:

pre-push: affected tests 14 passed (4s). local review: 0 findings (41s, $0.38). pushing feat/order-delivery-note

The body of pull request #4812, as the agent filled it from the template:

Intent
  Let a customer add delivery instructions to an order (ORD-2187).
  Adds the optional field delivery_note (string, at most 500 characters)
  to POST /v1/orders, stores it, and returns it on the order.

Lane
  (filled by the lane check, not by the author)

Risk note
  Public contract: api/openapi/orders.yaml gets a new field on the request
  and the response. Clients that do not send it should see no difference.
  Migration: adds a nullable column delivery_note to orders. No backfill.
  The old code ignores the column, so a revert is safe.
  Event: order.created now carries the field.
  How a problem would be noticed: the contract tests in integration-tests.

Evidence
  Tests run: services/orders/tests/test_create_order.py, 14 passed
  (Stop hook 09:31, pre-push hook 09:34).
  Local review: code-reviewer, before the push, 0 findings.
  Local receipt, not signed.

Agent involvement
  All six files were written by a coding agent. The developer read the diff.

Notice the evidence line. It says what ran and how strong it is: a local receipt, not signed. A human reviewer can read it as context. CI does not read it at all.

The same stage, three ways it can end#

The table above is what happened. The two rows after it are labelled variants of the same change, to show the other outcomes of the hook.

OutcomeWhat happenedWhat happens next
It passesThis is what happened at 09:34. Tests green, no local findings, the push accepted, the body complete.Pull request #4812 is open. CI and the review start.
A check stops it and the agent fixes it by itselfSuppose the local review reports that create_order.py never checks the limit of 500 characters. The hook exits non-zero; nothing is pushed.The model adds the check and a test, commits and pushes again. The new commit gets a new review. The pull request opens a few minutes later, with the finding listed as fixed.
A check stops it and a person must decideSuppose the local review reports that orders.yaml lists the field under required. Clients that do not send it would start to fail. Whether that is acceptable is not the agent's decision.The developer decides before the pull request opens: make the field optional, or push with an override whose reason says the question is going to an API owner. The reason appears in the pull request's evidence.

In the real run the local review found neither problem, and both were in the diff. The CI review finds them six minutes later. Nothing went wrong because of the miss, because nothing depended on the local review being right.

The local review does not run again on #4812. The fix for finding 1 at 09:44 and the change that makes the field optional after the 10:20 decision are both pushed by the fix-on-request agent in CI, not from the developer machine, so no pre-push hook fires. Round 2 at 10:31 is the CI review on the new commit.

9. What the pull request carries#

A pull request that arrives reviewed needs less reading, but only if the reviewer can see what was already done. The template makes that visible. The agent fills most of it, and CI checks it.

SectionContentWho fills it
IntentOne paragraph: what and why, with the work item linkDeveloper, or agent from the task
LaneGreen, yellow or red, computed from the changed pathsCI, never the author
EvidenceAffected tests run, the review receipt (local or attested), findings fixed and findings declined with a reasonAgent
Risk noteWhat this change could break, and how it would be noticedAgent, read by the human reviewer
Agent involvementWhich parts were written by an agentCommit trailers

Two rows are deliberately out of the author's hands. The lane is computed, because an author who chooses the lane chooses how much review the change gets. And the receipt's strength is stated, because "reviewed" means nothing until it says by whom and where.

10. Side questions#

QuestionShort answer
Is the local reviewer the same model that wrote the code?It can be, in a fresh context with a review prompt. A different model for review catches different mistakes, at the cost of a second vendor to manage.
What about developers who do not use the agent?Their pull requests have no receipt, so CI reviews them. Nothing breaks.
What if a developer skips the hook?git push --no-verify skips it, together with the affected tests. The pull request then arrives without local evidence, and CI reviews it as in approach A. The hook can save time; it cannot enforce anything.
Does the attested receipt save real money?Only if receipts are still valid when the pull request opens, which depends on how narrowly they are bound to the base. Measure the reuse rate, the added wait before a push and the cost of both reviews. If most receipts are stale, stay with approach C.
Why not sign on the laptop?A key on a developer machine is controlled by the person, or the agent, whose work is being judged. That is not an independent review.
Stacked pull requests?Each one gets its own diff hash against its own base. Small stacked changes make every later stage cheaper.

The local review on #4812 said "0 findings" and was wrong, and nothing broke, because nothing had to believe it. That is the rule this stage is built on. A review is worth what its origin can prove, not what it says: feedback may come from anywhere, but a verdict counts only when CI can show where it came from and exactly what it covered.

At 09:35 #4812 is open, its 14 affected tests pass, and the server has put it in the red lane. Nothing trusted has reviewed it yet, and two mistakes are still in the diff. Finding them is now the CI reviewer's job, and deciding what to do about them belongs to the people who own those paths: the review.