Plain-English agent updates reviewers can replay

If a reviewer has to reopen your chat session to understand a PR, the PR is unfinished. A plain-English agent update fixes that: it is a short, three-part note that travels with the pull request and explains the agent's work in writing. The three parts are an intent line, a command transcript, and a diff summary. Get those into the PR and review speed comes back, because intent stops hiding in a chat log nobody else can read.

The agents themselves are familiar. Claude Code, Anthropic's coding agent, runs in your terminal. Codex CLI, OpenAI's coding agent, does too. Both can ship green CI all day. Neither leaves a trail a teammate can follow unless you ask it to.

Why green CI still leaves reviewers stuck

CI tells you the commands passed. It does not tell you why the agent chose this approach over the obvious alternative. That "why" is what a reviewer is actually waiting on, and on agent-heavy teams it is where review time quietly disappears.

The pattern is predictable. Coordination happens in chat, chat scrolls away, and the repo ends up with explanations shaped like the conversation that produced them, which is to say almost none. Pull requests mirror how the team communicates, so if the communication is ephemeral, the record is too.

The fix is a habit, not a tool. Treat the written update as part of the change. An agent diff with no narrative is half-done, the same way code with no tests is half-done.

Standardize four agent updates

You do not need a heavy process. You need four small artifacts that each kill a specific failure mode. Here are the ones worth writing down.

Claude permission creep. On shared machines, bash approvals in Claude Code turn into muscle memory and scope quietly widens. Fix it with a supremacy clause at the top of CLAUDE.md: state which hooks win, which folders need human eyes, and where temporary overrides live. When precedence is written down, sessions stop inventing policy mid-run.

Codex replay gaps. Codex CLI runs merge green while reviewers never see the transcript. The Codex quickstart gets you running, not reviewable. Close it with a replay sandwich: have AGENTS.md require an intent line, then the command transcript, then a diff summary before any PR. Review becomes reproducible without standing behind someone's terminal.

MCP blast radius. Connectors built on the Model Context Protocol ship as capability demos, and one eventually touches data nobody put on the diagram. Close it with a connector card: one markdown card per server listing allowed actions, forbidden actions, owner, and rollback. Incidents shrink because operators know what "off" looks like.

Recursive handoff blur. Chained agents hand back summaries that quietly drop the paths a child agent owned. Close it with a child receipt block: every child returns paths touched, commands run, and the tests proving its regression guards hold. Parents stop green-lighting diffs they cannot see.

Here is a boundary snapshot you can drop in as a starting point and adapt 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.

In our methodology this is the review gate: parallel agent output must be inspectable without replaying sessions. The same receipts power the rest of agentic coding governance.

Run the four-question reviewer gate

Before a merge, a reviewer who never saw the chat should be able to defend it. Four questions test whether your update format is good enough.

If your repo cannot answer these in writing, agents will guess at the boundaries, and guessing scales badly.

Common questions

• What is a plain-English agent update?

  It is a three-part note attached to agent work: an intent line, the command transcript, and a diff summary. The format lets a reviewer follow what the agent did and why without replaying the session, which is exactly where review time disappears on agent-heavy teams. Keep it short and keep it in the PR.

• Why do agent PRs need a narrative when CI is green?

  Green CI confirms the commands ran, not that the reviewer understands them. The narrative answers "why this approach?" in writing, so debate happens against stated constraints instead of vibes. That written answer is the thing reviewers are actually waiting for before they approve.

• Where should the update live, chat or repo?

  In the repo, every time. Chat scrolls away, while AGENTS.md notes, connector cards, and child receipt blocks survive the session and reach whoever reviews next. Durable contracts beat fast summaries the moment more than one person owns a merge, which is every merge that matters.

• What goes in a connector card?

  Four fields per MCP server: allowed actions, forbidden actions, owner, and rollback. The card turns a capability demo into an operated dependency. It is also the first thing to check when an agent update mentions a connector that nobody on the team recognizes.

Start with one artifact

Pick a single failure mode you have actually hit and turn its fix into a real file this week: a CLAUDE.md clause, an AGENTS.md replay note, or a connector card. If your reviewers still replay chats to defend merges, book a 15-minute sync and we will pressure-test your update format against real PRs.