AI coding agents need workflow guardrails

AI coding agents need workflow guardrails before they need more autonomy, and the place that proves it is the review queue: forks from Claude Code, Codex, and Claude land faster than anyone can explain them. A workflow guardrail is a written repo rule that makes an agent's work checkable by a reviewer who never saw the session. We keep meeting this while rehearsing incident aftermath with teams: the shortcut skills that felt clever in the session drift faster than review can absorb.

The question that stalls a merge

Every stalled merge in an agent-heavy repo comes down to one question: why did the agent touch this file? When the answer lives only in chat, the merge waits and the sprint pays.

Counter-thesis: the bottleneck in agentic coding is not model capability, it is the missing written contract a reviewer can check.

The wrong path: We believed reviewers would absorb implicit intent. We let connectors multiply faster than ownership maps and treated parallel agents as free parallelism. Forks without receipts ate the sprint budget before lint ever failed.

Diagnosis: Conway's law explains the trap. The fork structure mirrored our communication structure, and our communication lived in private chat sessions, so the repo inherited boundaries nobody had written down.

Thesis: Explainable forks beat clever forks.

Four failure modes, one pattern

Each failure mode below pairs with a small written contract that travels with the work instead of staying in the operator's head.

Claude permission creep. Run Claude Code on shared laptops and bash approvals become muscle memory. The failure is not tool quality; it is the missing operating contract.

Named fix: CLAUDE.md supremacy clause. The top of CLAUDE.md states which hooks win, which folders require human eyes, and where temporary overrides live. Sessions stop inventing policy mid-run because precedence is written before the run starts.

Codex replay gaps. Rely on Codex CLI long enough and you will merge greens where reviewers never saw the transcript. Commands ran; the narrative did not. That is verification theater.

Named fix: Replay sandwich. AGENTS.md mandates an intent line, then the command transcript, then a diff summary before the PR opens. Review becomes reproducible without standing behind someone's terminal.

MCP blast radius. Wire MCP quickly and you will discover a connector touching data nobody listed on the diagram. Connectors default to capability demos; least privilege needs explicit trust boundaries.

Named fix: Connector card. One markdown card per MCP server: allowed actions, forbidden actions, owner, rollback. Incidents shrink because operators finally know what "off" looks like.

Recursive handoff blur. Chain agents and you will receive summaries that omit child-owned paths. Delegation stacks collapse when summaries replace receipts, and parents green-light mystery diffs.

Named fix: Child receipt block. Every child returns paths touched, commands run, and the tests proving regression guards. This is the one part of a fork a reviewer can verify directly.

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

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

These four contracts are the working core of agentic coding governance, and they anchor in the Review step of our methodology: receipts meet responsibility before anything merges. The same receipts carry work end to end in agentic workflows from PR to merge.

What the reviewer actually checks

A guardrail only counts if a reviewer can test it in under a minute.

Merge check

• Scopes in the PR body match folders in the diff.
• Primary-doc links were smoke-checked after publishing edits.
• MCP connectors mentioned (if any) list owners.
• Verification command output is pasted or linked.

Where autonomy stops

Hard constraints still belong to humans: threat models, customer promises, and blast radius decisions stay off autopilot.

Synthesis: agents are signal amplifiers. They multiply whatever clarity already exists in your files, hooks, and scopes, and they amplify the ambiguity just as faithfully.

Docs to keep open

• Google Search Central: helpful, people-first content
• Google Search Central: generative AI content guidance
• Model Context Protocol specification
• Claude: Agent overview
• Claude Code: getting started
• OpenAI Developers: Codex quickstart
• OpenAI Skills repository

Best ways to use this research

• Best for: engineering teams deciding which workflow guardrails to standardize across Claude, Claude Code, and Codex before granting agents more autonomy.
• Best first artifact: the named fix that matches your loudest failure mode, turned into a repo rule or PR checklist before the next agent run.
• Best comparison angle: weigh the four fixes by review evidence, connector scope, and handoff friction; keep whichever leaves the shortest auditable trail.

Common questions

• What workflow guardrails do AI coding agents like Claude Code and Codex need?

  Four guardrails cover the common failures: a CLAUDE.md supremacy clause, a replay sandwich in AGENTS.md, one connector card per MCP server, and a child receipt block for forked work. Each exists so a reviewer can defend the merge without replaying the chat.

• What is a CLAUDE.md supremacy clause?

  A CLAUDE.md supremacy clause is a block at the top of CLAUDE.md stating which hooks win, which folders require human eyes, and where temporary overrides live. It fixes bash approvals becoming muscle memory, because precedence is written before sessions can invent policy mid-run.

• How do you stop agent forks from eating the sprint budget?

  Make every fork return a child receipt block: paths touched, commands run, and tests proving regression guards. Forks without receipts eat the sprint budget before lint ever fails, and parents keep green-lighting mystery diffs until receipts replace summaries.

• Which decisions stay with humans in agentic coding?

  Threat models, customer promises, and blast radius decisions stay off autopilot. Agents work like signal amplifiers, multiplying whatever clarity already exists in files, hooks, and scopes, so the boundary work has to come before the autonomy does.

What to do next

The fastest way to install these guardrails is to rehearse them on a live repo with the people who review the merges. Our training runs exactly that drill.