Over the same half hour on a Tuesday morning, three pull requests open at Acme. #4822 fixes a typo in docs/orders/README.md. #4819 fixes a rounding bug in services/cart/totals.py, with a test. #4812 adds the optional field delivery_note to the order API: a public contract, a database migration and four files of service code. They are three of about 300 that day.
All three wait for the same thing: someone to say yes. A reviewer who tries to read all 300 closely reads none of them well, and the approvals keep arriving anyway, so nobody can tell which ones were real.
Review has to answer three questions for every change: is it correct, is it wanted, and who is accountable for saying yes. A reviewer agent can do much of the first. The second and third belong to people, and their attention is the scarce part. The numbers on this page are illustrative.
Sort by what a change can break, not by who wrote it. An agent reviews everything. People review the lane that needs them. No agent may edit its own gates, and no gate depends on the agent being right.
1. Why reading everything stops working#
The first answer most teams give is the one they already have: a person reads every pull request and approves it. At a few pull requests a day per reviewer, that works, and accountability is clear. At 300 a day it breaks in a quiet way. Approval becomes a reflex. Real reading still happens on a few changes, but nobody knows which ones, so an approval no longer says anything about the change it is on.
The obvious repair is to put an agent in front of the person. The agent reviews every change and posts findings; the person still approves everything. Findings now arrive on every pull request, which is a real gain.
But the person's attention has not grown. They now read the agent's summary instead of the code, and approve after reading it. It is the same reflex, better dressed, and it moves trust to the agent without anyone deciding that it should.
A third idea feels cautious: give agent-written changes more review than human-written ones. It fails for two reasons. Risk is in the change, not in the author: a one-line typo fix is harmless whoever typed it, and a migration is dangerous whoever typed it. And a rule that punishes agent help teaches developers to stop saying an agent helped. This is a named mistake on this site, lanes by author, and the standard it breaks is the one in the stance above.
| Idea | Why it seems right | What breaks it | The cause underneath |
|---|---|---|---|
| A. A person reads everything | Clear accountability | Approval becomes a reflex; nobody knows which reviews were real | Attention is fixed; the number of changes is not |
| B. An agent reviews, a person approves everything | Findings on every change | The person reads the summary, not the code | The same attention is spread over the same 300 changes |
| C. Lanes by author | Agent code feels riskier | Developers hide agent help; harmless changes get heavy review | Risk is a property of the change, not of who wrote it |
Read down the last column. The fix is not more reading. It is reading in the right place: sort changes by what they can break, let an agent read all of them, send people to the ones where a mistake is expensive, and keep the decisions that need an accountable person out of the agent's reach.
2. Sort by what a change can break#
How much can go wrong, and how far it spreads, if this change is bad? A typo in a Markdown file can mislead a reader. A wrong rounding rule can charge customers the wrong amount. A required field in a public contract can break every client that exists today. That property is called blast radius, and it is the thing to sort by.
Acme sorts every pull request into one of three lanes by blast radius: green, yellow or red. The lane decides how much review and how much proof a change needs. A CI job computes it from the paths in the diff, using rules read from the main branch. The author never chooses it. Paths set the minimum lane; other signals, in the next section, can only raise it.
| Lane | Typical paths | Agent review | Human review | Merge |
|---|---|---|---|---|
| Green | Documentation that is not executed, and other paths on an explicit allow list | Required | None, but sampled weekly | Automatic when checks pass |
| Yellow | Normal product code, test logic, dependency and lock files, generated files used at run time | Required | One approval | After approval and checks |
| Red | Sign-in and access control, payments, database migrations, public API contracts and schemas, infrastructure, and the gate files | Required, and always run in CI | The named owner. The plan is reviewed before the code. | After owner approval, checks, and the proof that fits the change: an end-to-end run for product code; the agent checks agent-smoke and agent-eval for a skill, prompt or agent setting (the evals for a change to an agent; see When the change is an agent) |
The three pull requests from the opening land in the three lanes.
| Pull request | The change | Lane, and why | Agent review | People | Result |
|---|---|---|---|---|---|
#4822 | A typo in docs/orders/README.md | Green. Documentation that is not executed. | No findings | Nobody; the policy app (section 4) approves | Merged 6 minutes after it opened |
#4819 | A rounding bug in services/cart/totals.py, with a test | Yellow. Normal product code. | No findings | One teammate approves | Merged 41 minutes after it opened |
#4812 | The delivery_note field: contract, migration, service code | Red. It changes api/openapi/ and db/migrations/. | Two findings | An API owner and a data owner | Section 6 follows it |
One group of files deserves its own name. The gate files decide how every other change is judged, or what an agent loads and may do. If a pull request could change them without an owner noticing, it could loosen its own review. So they are always red, and every list of them on this site is the same one.
| Gate file or folder | Why it is a gate |
|---|---|
.github/ | Workflows, the lane rules .github/lanes.yml, and the active agent versions .github/agent-versions.yml |
CODEOWNERS | Who must approve which path |
CLAUDE.md, .claude/, .mcp.json | What the coding agent and the reviewer agent load: instructions, settings, hooks, skills, subagents, tool servers |
.githooks/ | The checks on the developer machine |
agents/, ci/ | The pipeline agents and the scripts that run checks, compute lanes and act on verdicts |
Diagram: Three lanes · what each change gets
Each horizontal lane is a level of blast radius. Read across to see what a change in that lane goes through. CI picks the lane from the changed paths; the author cannot.
- Green
- Reviewer agent: Reviews the diff on the server. A signed review receipt can be reused.
- No person now, weekly audit later: No person reviews before merge. Afterwards a person reads a random sample of last week's green merges; each miss becomes a rule fix.
- Automatic merge: The policy app approves when every check passed; it goes through the merge queue with no person.
- Yellow
- Reviewer agent: Reviews the diff on the server. A signed review receipt can be reused.
- One approval: A person reads the intent, the risk note, declined findings and the core logic.
- Merge queue: Tested on top of the changes ahead of it.
- Red
- Plan reviewed first: The named owner agrees the approach before the agent writes code.
- Reviewer agent, always in CI: Never reused from a receipt. Runs in the pull request check every time.
- Named owner: The code owner for those paths approves. For skill files, with the eval result.
- Merge queue + end-to-end run: In the merge queue it gets an e2e-smoke run of its own on one of the 12 environments, never shared in a batch.
The diagram shows where each lane's change goes and who touches it. Notice that the agent review is on every path, and that a person appears only on the yellow and red paths. Notice also when the red lane's end-to-end proof happens: not before review, but in the merge queue, where #4812 runs e2e-smoke on one of the 12 environments (CI/CD). Review approves a red change for the queue; the queue proves it.
3. Why paths alone are not enough#
Paths are a floor, not a verdict. The green lane merges with no person reading it, so it starts small, and a change that looks safe by its paths can still carry risk. A test-only change can weaken the one assertion that mattered. A generated file can ship in the product. So the lane rules also look at what the diff does, and raise the lane when it does something risky.
| Signal in the diff | Effect |
|---|---|
| Tests deleted, skipped or loosened | At least yellow; red when the test guards a gate or a high-risk path |
| Dependency or lock file changed | At least yellow; red for a major version or a new dependency |
| Generated file that is used at run time | Treated as product code |
| Deployment or run-time configuration | Yellow becomes red |
| Unusually wide diff for its lane | Raised one lane; the author is asked to split it |
A signal can raise a lane and never lower it. That one-way rule is what keeps a clever diff from talking its way into green.
4. How a lane becomes a merge rule#
A lane is a word in a file until something enforces it. The repository host has no idea what a lane is. On GitHub, a branch rule says "one approval" for every pull request to main, with no exception for green, and "owner approval" for paths in the owners file. So Acme builds the lanes from parts the host does understand: a required check named lane, the owners file, and an automation identity called the policy app. Each part is a design on this site, built from ordinary GitHub features.
Computing the lane. A workflow, lane.yml, runs when a pull request opens or gets a new commit. It uses the pull_request_target event, which on GitHub runs the workflow file from the base repository's default branch, so a pull request cannot change the rule that judges it. It reads the names of the changed files, never the code, computes the lane from .github/lanes.yml, and sets the label lane:red (or green, or yellow). It does not post the lane status at all: only the policy app does, so the required status has exactly one author. It is the computing half.
Re-evaluating when an approval arrives. The lane's condition is met later, when a person approves, and that moment needs something listening. The obvious choice, a second workflow on the pull_request_review event, is the wrong one: on GitHub that event runs the workflow from the pull request's merge commit, so the pull request under review could rewrite it. Instead, the policy app listens to review events and check results. Each time, it recomputes the lane from the rules on main (never trusting the label, which can be changed by hand), checks that lane's condition (green: every other check passed; yellow: one human approval; red: the named owners approved), and sets the lane status to success or leaves it pending.
| Part | What it does | What it must never do |
|---|---|---|
lane.yml | Computes the lane from file names and sets the label | Post the lane status, or check out or run the pull request's code |
| The policy app | On review and check events, recomputes the lane, sets lane to success when the lane's condition is met, and for green gives the one approval the branch rule asks for | Approve anything that is not green. Its permissions are the most sensitive in the repository. |
| The owners file and the branch rule | Require the named owner for red paths, whatever the lane status says | Depend on the agent |
The alternative is no approval rule on main at all, with the lane check as the only enforcement. That is simpler and puts all the weight on one app. Acme keeps the owner rule as well, so that a bug in the policy app cannot merge a red change: the host itself still refuses it.
5. The reviewer agent#
Lanes decide where people look. They only work if something reads every change, including the green ones nobody else will read. That is the reviewer agent's job, and its design follows from one requirement: it must be useful to people without becoming a gate they rely on.
It starts fresh. The reviewer begins without the author's conversation. It sees the diff, the intent in the pull request body and the repository. That is the point: it does not inherit the author's assumptions. The cost is that it also lacks the author's reasoning, so the intent section of the pull request has to be good.
It has no edit tools. The reviewer is the code-reviewer subagent. It has no edit tools; its shell is limited by permission rules to two git subcommands (why that is not read-only). A separate agent run applies fixes, and only what a person asked for (section 7).
Its rules live in the repository. The reviewer loads the skill review-rules and the subagent file from the checkout. In Acme's workflow, that checkout is the pull request's own code, so a pull request could edit the rules that review it. Its protection is that those files are gate files: any edit to them makes the pull request red and needs @acme/platform-leads. Loading the rules from the base branch instead, so the pull request is only ever the thing being reviewed, is stronger; CI/CD agents section 7 describes it as a design. Claude Code's managed Code Review does that by design with a REVIEW.md file read from the base branch.
It verifies before it posts. A second pass drops any finding it cannot support with a line of code. This costs more per review. Without it, false positives teach people to ignore the reviewer, and an ignored reviewer is worse than none.
It posts few findings, ranked by severity. A cap on the count keeps the review readable. Some real minor issues go unreported, which is the price of people reading the ones that matter.
The workflow that starts it, with its permissions and flags, is on CI/CD agents. Claude Code offers three ways to run a reviewer, each with a different owner.
| Option | Who runs it | What it can do | Drawback |
|---|---|---|---|
Local /code-review | The developer, in their session | Report findings, or apply them to the working tree with --fix | Feedback, not a verdict (the two receipts). It reads CLAUDE.md, not REVIEW.md, so keep project rules in step with the managed service's rules if you use both. |
| GitHub Action | Your workflow, on your runner, with your model choice | Review, comment, and push fix commits when asked | You own the workflow, the secrets and the cost controls |
| Managed Code Review | Anthropic's service, on Team and Enterprise plans | Several agents find, verify and rank; posts inline comments, a summary and a check run | Its repository access is read-only and it never approves or blocks; no model choice |
Acme uses the GitHub Action with its own code-reviewer subagent, because the same files then serve the developer's local review and the CI review.
6. Following #4812 through review#
The design is easier to trust once it has been seen working on a real change. #4812 enters this stage at 09:34, when the pull request opens. It leaves at 10:50, approved and waiting in the merge queue. In between, review ends in each of its three possible ways.
| Time | What happens | Who acts | Result |
|---|---|---|---|
| 09:34 | The pull request opens. The repository host starts the workflows. | The developer's ship skill; then the repository host | Six checks report; five are required. e2e-smoke passes at once here and runs for real in the queue; affected-tests runs but is not required. |
| 09:35 | lane.yml reads the list of changed files and finds two red paths. | A workflow that runs from the base branch | Lane: red. The label lane:red is set; the policy app posts lane as pending. Two owner teams are requested. |
| 09:36 to 09:41 | unit-tests, integration-tests and affected-tests run. | CI jobs on ordinary runners | All three pass |
| 09:40 | The agent-review check finishes. It posts two findings on the lines they concern. | The reviewer agent, which has no edit tools, started by a workflow | Finding 1 and finding 2 |
| 09:41 | The developer reads finding 1 and asks for a fix, in a comment that names it. | The developer | A fix run starts |
| 09:44 | The fix run pushes one commit: a length check and a test for it. Every check starts again on the new commit. | The fix-on-request agent, a separate run with edit rights on this branch | Finding 1 closed |
| 09:44 | agent-review runs again on 3e9b7d2. Finding 2 is still open: the reviewer marked it "needs the API owner", and no agent may fix it. | The reviewer agent; then nobody yet | The pull request waits for a person |
| 10:20 | An API owner answers finding 2: the field must be optional. The developer asks the fix-on-request agent to apply that decision. | The API owner decides; the agent edits | One more commit |
| 10:31 | Review round 2, on the commit that applies the owner's decision. | The reviewer agent | No findings |
| 10:48 | An API owner and a data owner approve. The policy app sees the approvals, checks the red lane's condition, and sets lane to success. | Two people, then the policy app | Every merge condition is met |
| 10:50 | The pull request enters the merge queue. | The repository host | Continues on CI/CD |
The two findingsThe text the reviewer agent posted on the pull request at 09:40
agent-review · 2 findings · commit 8c1f0a4
[1] services/orders/handlers/create_order.py, line 48 severity: medium can be fixed here
The contract (api/openapi/orders.yaml, line 212) sets maxLength: 500 for
delivery_note. This handler stores the value without checking its length.
A 5,000-character note is accepted and saved.
Suggested fix: reject a longer value with status 422, and add a test.
[2] api/openapi/orders.yaml, line 204 severity: high needs the API owner
delivery_note is listed under "required" for POST /v1/orders.
Clients that exist today do not send this field. After this change their
requests fail with status 422. This is a breaking change to a public contract.
I did not change it. Decide: optional field, or a new API version.
The reviewer agent has no edit tools. It reports. A separate run fixes, and only what a person asked it to fix.
The two findings are different in kind, and the difference decided what happened to each. All three possible endings of a review happened to #4812, in this order.
| Outcome | What happened here | What decided it | What happens next |
|---|---|---|---|
| 1. The agent finds an issue, and an agent fixes it | Finding 1: the contract says at most 500 characters, and the code did not check it. | The fix stays inside the diff, a test can prove it, and nobody outside the team depends on the old behavior. | A fix run pushes a commit. The checks and the review run again on it. The fixer never approves. |
| 2. The agent finds an issue, and a person must decide | Finding 2: the field was listed as required. Existing clients do not send it, so their requests would start to fail. | It changes a public contract. Whether to break clients is a product decision, not a code defect. And the path is red, so the owner must approve in any case. | The pull request waits. No agent can open this gate. The owner decides; an agent may then apply the decision. |
| 3. The agent finds nothing | Round 2, after both changes. | No finding survived the reviewer's own verification pass. | Green lane: merge with no person. Yellow: one approval. Red, as here: the owners still approve. |
The second row is the hard gate, and it does not depend on the agent being right. If the reviewer agent had missed finding 2, the pull request would still have stopped, because the owners file requires the API owner for api/openapi/ and the repository host enforces it. The agent made the owner's decision faster to reach. It did not make the decision possible.
7. The fix-on-request loop#
A finding is only useful if fixing it is cheap. At 09:41 the developer did not open an editor. They wrote one comment on the pull request, and three minutes later the fix was on the branch with its test. The agent that did it is the fix-on-request agent, defined in .claude/agents/fix-finding.md. It is a different agent from the reviewer, with edit tools, and it acts only when a person names a finding. (It is also different from the red-build fix agent on Pinpoint and fix agents, which works after main goes red.)
How the fix commit happensA person asks; a second run edits; the checks start again
- The developer writes a comment on the pull request that mentions the agent and names the finding: fix finding 1.
- The repository host starts a second workflow,
agent-fix.yml, which listens for comments that mention the agent. - The fix-on-request agent reads the finding, edits
create_order.pyandtest_create_order.py, runs the affected tests, and pushes one commit tofeat/order-delivery-note. - The repository host starts every required check again on the new commit, the review included.
commit 3e9b7d2 fix(orders): reject a delivery_note longer than 500 characters
services/orders/handlers/create_order.py +4 -0
services/orders/tests/test_create_order.py +11 -0
Refs: ORD-2187
The workflow uses the GitHub Action in the mode that answers mentions. What this sketch is meant to show: the trigger, and that no github_token is passed, so the Action signs in as the Claude GitHub App and its commits start the other workflows. It is assembled from the Action's documented inputs and example, and has not been run against a real repository. It leaves out the turn and spend caps, which belong in claude_args as for the reviewer, and the count of fix rounds, which is Acme's own logic, not an Action feature.
# .github/workflows/agent-fix.yml (sketch)
name: agent-fix
on:
issue_comment:
types: [created]
pull_request_review_comment:
types: [created]
permissions:
contents: write
pull-requests: write
issues: write
id-token: write # used by the Action's default GitHub App sign-in
jobs:
fix:
if: contains(github.event.comment.body, '@claude')
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6
- uses: anthropics/claude-code-action@v1
with:
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
claude_args: "--agent fix-finding"
With no prompt input, the Action waits for its trigger phrase, @claude by default, and answers that request. It also refuses to start for a user without write access to the repository, and for a bot unless the bot is listed. The model key comes from the CI secret store, the simpler start; the credentials standard is on CI/CD agents.
Letting an agent push commits to a pull request is useful and has obvious ways to go wrong. Each rule below closes one of them.
| Rule | Why |
|---|---|
| The fixer never approves | Separation of duties: whoever wrote a change, person or agent, does not approve it. The fix commit is reviewed again like any other. |
| It pushes with an app identity | On GitHub, a commit made with the workflow's default token does not start other workflows. The checks would not run again on the fix. |
| It writes to the pull request's branch only | The branch rule refuses direct pushes to main. If it edits a gate file, the lane turns red and the platform owners must approve, so that edit cannot pass unseen. |
| Three rounds at most | After three fix rounds on one finding, a person takes over. Two agents can disagree forever. |
| A fix commit invalidates any review receipt | The head tree changes, so the review runs again (receipts). |
Which findings may go to the agent at all is the rule that sorted finding 1 from finding 2.
Agent fix, or a person?The rule that sorted finding 1 from finding 2, with ten more cases
An agent may fix a finding when all four are true: the fix stays inside the diff, a test can prove it, nobody outside the team depends on the old behavior, and no gate file changes. Otherwise a person decides first.
| # | Finding | Who | Why |
|---|---|---|---|
| 1 | A missing check for a null value, with a failing test to prove it | Agent | Local, and a test proves it |
| 2 | A wrong status code in a new handler | Agent | Local; the contract already states the right code |
| 3 | A test that asserts nothing | Agent | Local; the fix is a real assertion |
| 4 | A field removed from a public response | Person | Clients depend on it |
| 5 | A migration that drops a column | Person | Data is lost; there is no undo |
| 6 | A slower query on a large table | Person | The trade-off needs someone who knows the data size |
| 7 | A new dependency | Person | Licence and supply-chain review |
| 8 | A change to who may call an endpoint | Person | Access control is a red path |
| 9 | A skipped test that used to pass | Person | Someone must say why it may be skipped |
| 10 | An edit to a CI workflow or the owners file | Person | A gate file: the change edits its own judge |
8. How it is wired on GitHub#
Everything above is four pieces of configuration. Sections 4 to 7 explained why each exists; the box shows them together, as they sit in Acme's repository. GitLab and other hosts have an equivalent for each: a pipeline on merge requests, a code owners file, approval rules and merge trains.
How it is wired on GitHubFour parts: the review workflow, the lane workflow, the owners file, the branch rule
Part 1. The review workflow. The full file, .github/workflows/agent-review.yml, is on CI/CD agents: it starts on pull_request (opened, new commit, ready for review, reopened), runs the code-reviewer subagent, and allows reading, searching, two git subcommands and the tool that posts a comment on a line. Two parts of that file matter for this page. A concurrency block makes a new commit cancel the review of the old one instead of paying for both. And a merge_group trigger reports the agent-review check as passed at once in the merge queue, because a required check that never reports in the queue blocks the merge. The concurrency group is keyed on the pull request number, falling back to the ref in the queue, so queue runs do not cancel each other:
concurrency: # a new commit cancels the review of the old one
group: agent-review-${{ github.event.pull_request.number || github.ref }}
cancel-in-progress: true
With the pull_request event, the workflow file, the subagent, the skill and the CLAUDE.md the reviewer reads all come from the pull request's own merge commit. This workflow does not load them from the base branch. Its protection is that they are gate files, red in the lane rules and owned in Part 3. Loading them from the base branch is the stronger design (CI/CD agents, section 7).
Part 2. The lane workflow. What it is meant to show: the computing half of the lane check. It runs from the default branch, reads only file names, and sets the label. It posts no status: the lane status is posted only by the policy app, pending until the lane's condition is met, then success. The job is named compute-lane, not lane, so that the lane requirement means one thing: the policy app's status. A job's check run appears under the job's name (observed behavior), and GitHub's documentation says that when a check and a commit status have the same name and that name is required, both must pass. A job named lane would only add a second thing to pass and blur what the name means. ci/lane.py is Acme's script and is not shown.
The name does not stop a forged status. GitHub's documentation says any person or integration with write permissions to a repository can set the state of any status check, and a workflow token can be given statuses: write. The guard is in the branch rule (Part 4): a required status check can name an app as its expected source, so only a lane status from the policy app, a design on this site, can satisfy it. GitHub requires that app to be installed with statuses: write and to have recently submitted a check run.
# .github/workflows/lane.yml
name: lane
on:
pull_request_target:
types: [opened, synchronize, reopened]
permissions:
contents: read
pull-requests: write
jobs:
compute-lane:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6 # the default branch, with the lane rules
- env: { GH_TOKEN: "${{ github.token }}" }
run: |
pr="${{ github.event.pull_request.number }}"
gh pr diff "$pr" --name-only > changed.txt
lane=$(python3 ci/lane.py .github/lanes.yml changed.txt) # prints green, yellow or red
gh pr edit "$pr" --add-label "lane:$lane" # the policy app posts the lane status
The policy app (section 4) is the other half. It sets the same lane status to success when the lane's condition is met.
Part 3. The owners file. It names who must approve a path. Every gate file is listed, with the platform team as owner, and the pipeline agents with the team that runs them. Other red paths, such as payments, have owners too; they are left out here.
# CODEOWNERS
/api/openapi/ @acme/api-owners
/db/migrations/ @acme/data-owners
/.github/ @acme/platform-leads
/CODEOWNERS @acme/platform-leads
/CLAUDE.md @acme/platform-leads
/.claude/ @acme/platform-leads
/.mcp.json @acme/platform-leads
/.githooks/ @acme/platform-leads
/ci/ @acme/platform-leads
/agents/ @acme/platform-leads
/agents/triage/ @acme/triage-owners
Part 4. The branch rule on main. Set once by an administrator, in the repository settings.
| Setting | Value | What it does for #4812 |
|---|---|---|
| Require a pull request before merging | On, one approval | Nobody pushes to main directly, person or agent, except actors on the rule's bypass list |
| Require review from Code Owners | On | The API owner and the data owner must approve. This is the hard gate. |
| Required status checks | unit-tests, integration-tests, lane, agent-review, e2e-smoke | Merge is blocked until all five pass. e2e-smoke runs only in the merge queue; on the pull request it reports success at once, so it does not hold the pull request back, and in the queue it is what the merge waits for. affected-tests runs on every pull request but is not required, because a wrong dependency map can skip a test; nightly-full is its net. |
Expected source for lane | The policy app | Only the policy app's lane status counts. A lane status posted by any other identity, such as a workflow token with statuses: write, cannot open the merge. |
| Dismiss stale pull request approvals when new commits are pushed | On | An approval given before the 10:20 commit does not count for it |
| Require merge queue | On | The change is tested together with the changes ahead of it before main moves |
Every required check must also report in the merge queue, or each queued entry waits until the queue times out. Each required workflow gets a merge_group trigger. unit-tests and integration-tests run again there; lane and agent-review report success at once, because their condition was met on the pull request.
9. What people read, and how the team knows the lanes are right#
With the wiring in place, a person's day changes shape. They no longer read every diff. What they read depends on the lane.
| Lane | The person reads |
|---|---|
| Green | Nothing, until the weekly sample |
| Yellow | Intent, the risk note, findings the agent declined to fix, and the diff of the core logic |
| Red | The plan before the code exists, then everything |
That leaves one question open: is the green lane really safe to merge with no person? Nothing above measures it.
So Acme adds a weekly audit: a person reads a fixed sample of last week's green-lane merges, and every incident is traced back to its lane. A green change that should not have been green becomes a fix to the lane rules. The audit does not protect any single change; the required checks, the reviewer and the deploy rule do that. It measures whether the rules deserve the trust they get.
Here are the ideas from section 1, together with the two that hold, as a summary.
| Approach | What it buys | What goes wrong | Use it when |
|---|---|---|---|
| A. A person reads everything | Clear accountability | At volume, approval becomes a reflex. Real review happens on a few, and nobody knows which. | Under about 30 pull requests a day per team |
| B. An agent reviews, a person approves everything | Findings on every change | The person now reads the agent's summary instead of the code | A transition step |
| C. Lanes by author | Feels cautious | Developers stop saying an agent helped. Risk is in the change, not the author. | Avoid |
| D. Lanes by blast radius | People spend time where a mistake is expensive | Rules need upkeep. A dangerous change can hide in a safe-looking path, so paths are a floor and other signals raise the lane. | High volume |
| E. Lanes plus a weekly audit sample | Measures whether the green lane deserves to be green, against both the sample and real incidents | Someone must do the audit and act on it | With D, always |
Recommended default: D and E. The audit turns "we trust the green lane" into a number.
| Question | Short answer |
|---|---|
| How do people review without checking out each branch? | The evidence is on the pull request: tests run, findings, a preview environment where one exists. Checkout is for the red lane and for doubt. |
| What if a path rule is wrong? | The weekly audit finds green-lane changes that should not have been green. Each one becomes a rule fix. |
| Can the reviewer agent be fooled by text in the diff? | Yes. Treat the diff as untrusted input: no edit tools, a shell limited to two git subcommands, no secrets in the reviewer's environment beyond the model key, and rules the pull request cannot change unseen. Loading the rules from the base branch is the strongest form. |
| Who is accountable for a green-lane defect? | The owner of the lane rules. That is why changing them is red. |
| Is a weekly audit too late? | For one defect, yes. It is a measure of the rules, not a protection for a change. |
The three pull requests from the opening got three different reviews, and that is the point. #4822 took no person's time. #4819 took one teammate's. #4812 took two owners, and the reviewer agent made their decision faster by naming it at 09:40.
But the decision that mattered, whether to break every existing client, never depended on the agent: if the agent had missed it, the owners file would still have stopped the merge. That is the test for any review design at volume. Let the agent make people faster everywhere, and make sure no gate needs it to be right.
At 10:50 #4812 has both owner approvals, both findings are closed, and every check that can judge one pull request on its own has passed. What nothing has done yet is run it on a complete copy of the system, together with the changes that will merge beside it. That run needs one of Acme's 12 end-to-end environments, and 300 changes a day want one too. Next: the merge queue and the build on main.