Local first: why local checks before CI win for agents

Run your verification commands on the laptop, before CI, and save what they print. That is the whole idea. Local checks before CI are the verification steps an agent runs and records where the work happens, so the proof exists before any pipeline gets a vote. A green pipeline reassures you. A local transcript explains what actually happened.

Most retros end with the same line: "CI was green." It tells you the gate passed. It tells you nothing about the run that broke production. When an agent writes the code, that gap is the expensive one. The pipeline can rerun your commands later, but it can never recover the intent, the order, or the story of the run that produced the diff.

So move the evidence upstream. Here is how, with four small artifacts you can adopt one at a time.

Make the agent's run leave a receipt

The Codex CLI, OpenAI's coding agent, makes local runs effortless and, by default, invisible. The agent runs, the diff looks fine, the PR merges, and nobody saw the transcript that justified it.

Fix that with a replay sandwich. In your AGENTS.md, require three things in every PR: an intent line, the command transcript, and a diff summary. Now the local run is the artifact, not someone's memory of it. A reviewer reads the why, the proof, and the shape of the change without standing behind anyone's terminal.

It costs the agent a few extra lines. It saves you the archaeology dig later.

Write down what each connector is allowed to touch

Connectors fail at boundaries CI never exercises. An MCP server reaching data nobody put on the diagram was reachable from a laptop long before it ever showed up in a pipeline. CI has no opinion about which servers fired or whether they should have.

Give each server a connector card: one short markdown file listing allowed actions, forbidden actions, owner, and rollback. The point is that operators learn what "off" looks like while that knowledge is still cheap. You want the blast radius documented before something detonates, not after.

Pass receipts up the chain, not impressions

Chained agents hand work back as summaries. Those summaries quietly drop the paths a child agent owned, and CI will not flag the omission.

So make every child return a receipt block: paths touched, commands run, and the tests that prove the regression guards hold. The parent assembles receipts instead of vibes. When a delegation went three levels deep, you can still trace who changed what.

Here is a snapshot you can drop in to keep delegation boundaries explicit across tools. Adapt the globs to your repo.

---
description: Delegation boundary snapshot (adapt globs to your repo)
globs:
  - "**/*"
alwaysApply: false
---

- Cursor: keep scopes explicit in `.mdc`; forbid undeclared MCP domains.
- Claude Code: cite `CLAUDE.md` precedence before expanding bash scope.
- Codex: ensure `AGENTS.md` carries replay-friendly verification notes for CLI runs.

This belongs in your documentation step, before review, because the handoff has to survive without the original operator in the room. If you want the longer version, it sits at the center of agentic coding governance, and it pairs with the testing half of the argument in stop adding a regression test for every bug.

Ship the why with the what

CI is green and reviewers still ask why this approach. That question is the real review, and a passing gate never answers it. People are good at optimizing for "checks pass," which is exactly why that signal alone is thin.

Add a decision stub: three forced lines in the PR body covering constraints considered, rejected alternatives, and verification proof. Now the reasoning ships alongside the change. A reviewer can replay a document instead of replaying a person.

Two small tools make the review itself faster. A gate table keeps you honest about what to check, and a strip keeps you honest about what is actually present.

Paste this strip into your PR template:

• Verification command output is pasted or linked.
• Forked agent work lists parent and child responsibilities.
• High-risk paths received explicit human acknowledgement.
• Scopes in the PR body match folders in the diff.

A useful drift metric: count how often reviewers have to replay a whole session to understand a change. Every one of those is a receipt that should have been written locally. Drive that number toward zero.

None of this replaces architecture judgement. Agents speed up execution, not ownership. For the risk catalogue itself, keep the OWASP Top 10 for LLM applications and the NIST AI Risk Management Framework within reach.

Common questions

• Why run local checks before CI for agent work?

  Because the transcript is born locally. CI can rerun your commands, but it cannot recover the intent, the sequence, or the narrative of the run that produced the diff. Local checks before CI capture that evidence at the source, while it is still cheap to capture. The pipeline then confirms instead of having to explain after the fact.

• What goes in a replay sandwich?

  Three layers in the PR, required by AGENTS.md: an intent line, the command transcript, and a diff summary. A reviewer gets the why, the proof, and the shape of the change. No standing behind anyone's terminal, no scrolling a session log to reconstruct what an agent did and why it did it.

• Does local-first make CI redundant?

  No. CI stays the slice that catches what local runs miss, and local receipts stay the slice that explains what CI cannot. Treat them as two separate checks. Collapse them into one and the gaps line up, which is exactly the moment an agent's improvisation reaches main with nothing recorded.

• Where do I start if my team has none of this?

  Start with the replay sandwich on your very next agent PR. It is one AGENTS.md rule and three lines per PR, and it pays off immediately because the first hard review will have evidence to read. Add the connector card and child receipt block once the habit sticks.

Try the smallest version first

Pick one open agent PR and add a replay sandwich to it before the pipeline runs. If you want help wiring receipts into a real review flow, our hands-on training walks a team through it in a single working session.