AI coding tool rollout without surprise rework

An AI coding tool rollout sticks when the pilot squad's habits travel as files the next team can read, not stories they have to reconstruct. A rollout is the staged move from one squad to every team, with the operating rules written down before the licenses multiply. The pilot proves the tool works. It rarely proves the rollout will, because the discipline that saved the pilot usually lives in people's heads and never makes the slide deck.

Here is the failure I keep watching. The first squad swears by the tool. The next cohort ships duplicated edits nobody reconciled. And the gap between them is invisible on every delivery dashboard, because automation amplifies whatever discipline you already had, including the gaps.

Write down what the pilot squad never said out loud

Most rollout decks copy the squad that survived and skip the implicit habits that made it survive. That is survivorship bias, and it is expensive. Another connector is almost never the missing piece. The costly bug is two people editing the same path with no record that either happened.

So the real question is not "did the pilot like the tool." It is "can a stranger reconstruct what the pilot did from the files alone." If the answer is no, the rollout is carrying folklore, and folklore does not scale past the people who lived it.

Ship four artifacts, not four opinions

Discipline scales as artifacts: short files a new team can read, apply, and be checked against. Here are the four that close the gaps I see most, each tied to the tool that tends to produce it.

Replay gaps with Codex CLI. Lean on Codex CLI and you will merge green PRs where reviewers never saw the transcript. The fix is a replay sandwich in AGENTS.md: an intent line, then the command transcript, then a diff summary, all before the PR opens. Review stays reproducible no matter which cohort ran the agent.

MCP blast radius. Connectors built on the Model Context Protocol ship as capability demos by default, with no notion of what "off" means. Have your platform team read the OWASP LLM Top 10 first, then write one connector card per server: allowed actions, forbidden actions, owner, rollback. Incidents shrink because every team knows the boundary.

Recursive handoff blur. Chained agents hand back summaries that quietly omit the paths a child agent touched. The fix is a child receipt block: every child returns the paths it changed, the commands it ran, and the tests proving the regression guards held. Parents stop green-lighting diffs they cannot see.

Review queue theater. CI is green and a reviewer still asks "why this approach?" with no written answer anywhere. A decision stub in the PR template forces three lines: constraints considered, alternatives rejected, verification proof. The debate moves from taste to tradeoffs.

Here is the boundary snapshot each new team adapts on day one. Copy it, change the globs to match your repo, and you have a starting point a reviewer can audit.

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

The point of all four is the same. A rollout copies licenses in a day and copies discipline only when you write the discipline down. Ship the paperwork with the tool, or ship surprises with it.

Run an audit any cohort can pass

Rollout quality is testable, and the test is simple: hand a merge to a reviewer from a different team and ask four questions. If the merge passes with someone who has no local context, the discipline is real.

Rollouts break at exactly the point where local context stops carrying the work. A cross-team review finds that point before production does. If your repo cannot state its boundaries plainly, agents will guess, and guessing scales badly.

Common questions

• What makes an AI coding tool rollout fail?

  Copying the pilot squad's licenses without the pilot squad's discipline. Survivorship bias hides the implicit habits that made the pilot work, so the next cohort ships duplicated edits nobody reconciled. Rollouts hold when the receipts travel as artifacts: replay sandwiches, connector cards, decision stubs that any reviewer can check.

• Which artifact should a rollout standardize first?

  The replay sandwich in AGENTS.md: intent line, command transcript, diff summary, all before the PR opens. It is the cheapest to audit, because any reviewer can verify it from the PR body alone. It also removes the worst failure mode, merged green builds that nobody can narrate after the fact.

• How do you keep review quality flat as more teams join?

  Use the same four gates everywhere: reviewer path, risk routing, replay proof, receipt match. A merge that clears review with someone from another team is the real benchmark. Rollouts break precisely where local context stops carrying the work, so a cross-team reviewer is the honest test of whether the discipline travels.

• Do rollouts need per-team rules or one global file?

  Both, in layers. The boundary snapshot ships as a template with globs each repo adapts, since paths are local. Connector cards stay local too, because owners and rollbacks are local. What stays global is the requirement that these artifacts exist and pass the same four-gate audit.

Next move

Pick one named fix and turn it into a real file this week: a .mdc rule, an AGENTS.md note, or a connector card, before the next cohort onboards. The rest of the discipline lives under agentic coding governance, and our hands-on training walks teams through writing these artifacts together.