How to clean up agent-written code

To clean up agent-written code, you restore the scope, ownership, and verification evidence that a reviewer needs, then throw away the chat transcript nobody saved. Cleaning up agent-written code is the work of turning chat-only context into artifacts a stranger can check from the pull request alone. The diff usually stays the same. What changes is how much of the reasoning is visible.

This matters because the moment that breaks you is predictable. The branch is ready, the reviewer asks why it touched a file, and the honest answer lives in a session you closed an hour ago. If you cannot narrate scope, you cannot delegate safely.

Understand why agent diffs fail review

A clean prompt does not produce a clean diff. The mess is not a model-quality problem, so a sharper prompt will not fix it. Better receipts will.

Here is the shape of the trap. The interface is one chat message. The change underneath spans files, permissions, and connectors. John Ousterhout's complexity vocabulary has a name for this: a shallow surface hiding deep coordination. The reviewer sees the surface and has to guess at the rest.

So review stalls. The reviewer cannot answer why a file changed, and they either rubber-stamp the diff or block it. Neither is good. Trust stops scaling the moment the receipts stay in chat, and the incidents that follow were all foreseeable.

Apply four cleanup moves that survive review

Each common failure has a small, file-backed fix. None of these needs a new tool. They need a written contract.

Claude permission creep is the first. Run Claude Code, Anthropic's coding agent, on a shared laptop and bash approvals turn into muscle memory. Hooks help, but precedence has to live in a file people read. Put a supremacy clause at the top of CLAUDE.md: which hooks win, which folders require human eyes, where temporary overrides live. Sessions stop inventing policy mid-run because the policy is written down.

Codex replay gaps are the second. Lean on Codex CLI, OpenAI's coding agent, and you will eventually merge a green build that no reviewer actually watched run. The fix is a replay sandwich: AGENTS.md requires an intent line, then a command transcript, then a diff summary before any PR. Now the review reproduces without anyone standing behind a terminal.

MCP blast radius is the third. Wire up a connector fast and you will find it touching data nobody put on the diagram, because connectors ship as capability demos by default. Write a connector card per server: allowed actions, forbidden actions, owner, rollback. The trust boundary is spelled out in the MCP specification, and the card is where you make it concrete.

Recursive handoff blur is the fourth. Chain agents together and the parent summary quietly drops paths the children owned. Make every child return a receipt block: paths touched, commands run, and the tests that prove the regression guards held. Parents stop green-lighting diffs they did not see.

Here is a delegation boundary you can drop into a repo and adapt:

---
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.

Cursor's agent documentation describes what the harness can do. The snapshot above decides what it may do. The team version of this argument is in agent boundaries for teams, and the wider AI coding governance cluster works the same seam.

Pass the reviewer's gate

A cleanup is done when a stranger can answer four questions from the PR alone. If any answer still requires opening a chat log, the cleanup is not finished.

Paste this checklist at the bottom of the PR description:

• MCP connectors mentioned (if any) list owners.
• Verification command output is pasted or linked.
• Forked agent work lists parent and child responsibilities.
• Red-folder paths received explicit human acknowledgement.

Know where cleanup stops

None of this replaces architecture judgement. Agents speed up execution, not ownership, and a tidy receipt does not make a bad design good. If leadership wants governance language for the same habit, NIST's AI Risk Management Framework supplies it. Reliability here is layered: intent, scope, verification. Skip a layer and the stack tips over.

Common questions

• What does it mean to clean up agent-written code?

  It means restoring the evidence a reviewer needs: which paths the agent was allowed to touch, which commands verified the change, and who owns the merge. The diff itself usually stays. The chat-only context is the part you replace with artifacts a stranger can read straight from the pull request.

• Why do agent diffs fail code review?

  They fail when intent lives only in a session transcript. The reviewer cannot say why a file changed, so they rubber-stamp or stall. A replay sandwich in AGENTS.md, an intent line then a command transcript then a diff summary, makes the review reproducible without the original operator standing by.

• What should a child agent report back after a delegated task?

  A child receipt block: paths touched, commands run, and the tests that prove the regression guards held. Without it, parent agents summarize work they did not perform and drop paths the children owned. That gap is how a mystery diff gets green-lit by people acting in good faith.

• How do you keep MCP connectors from widening the blast radius?

  Write a connector card per MCP server before it ships: allowed actions, forbidden actions, owner, rollback. Connectors default to capability demos, so least privilege has to be stated out loud. Incidents shrink once operators know what "off" looks like and who is allowed to press it.

• Which artifact should I build first?

  Pick one named fix and ship it before the next automated run. A .mdc rule, an AGENTS.md note, or a child receipt template all work. OpenAI's skills repository shows the same file-over-vibes pattern, and one small file beats a perfect plan you never write.

Start with one diff

Take a single agent diff that was hard to review and add the missing receipt to it today. If you want this drilled as a habit rather than read as a memo, our training runs these patterns against your own repos.