This module installs the four levers that turn a coding agent into shipped code: a spec that constrains it, a plan you critique before any edit lands, the intervention points where senior judgment pays, and a review-merge discipline that keeps parallel runs from becoming inventory.
Make POST /orders safe to retry with an idempotency key.
Sana writes one page — the header contract, the four header cases, the concurrency edge — and hands it to a coding agent in plan mode, edits forbidden.
The plan comes back: eight steps, competently written. Two things stop her.
"Add a short-lived cache for stored responses." The agent never found the Redis-backed ResponseStore that orders-api already uses in three other endpoints — so it planned to build a second one.
The concurrency handling — two requests with the same key racing to the payment provider, the part most likely to break in production — sits buried behind the easy work.
She touches no code. She corrects the plan: reuse ResponseStore, move concurrency to step 1.
Vikram, reviewing it later, admits the redirected plan is one he'd have approved as a PR description on its own.
The whole intervention cost a single careful read. Had she let the agent implement the original plan, she'd have discovered the duplicate cache and the fragile race forty minutes deep in a diff she didn't write.
Modules M1 and M2 set the judgment and the environment; this module is the core production loop — turning a ticket into merged code with a coding agent doing most of the typing. The Common Core covered what agents are and how their tool loops work. What it did not cover is the craft that separates engineers who ship with agents from engineers who generate with them.
The evidence says the craft is real: DORA 2025 measured a near-doubling of PRs merged per developer with organizational delivery flat — an entire industry generating faster than it can specify, steer, and review. Birgitta Böckeler's experiments on martinfowler.com reach the blunt conclusion this module operationalizes: unattended agents on non-trivial tasks fail in ways only an experienced engineer can catch, and the developer's leverage has migrated from writing code to specifying, planning, intervening, and reviewing.
Five skills, in the order you'll use them on a real feature: specs that constrain agents, the plan-critique-implement loop and its intervention points, scout runs to de-risk, adversarial critique for API and schema design, and parallel agents with worktree isolation and a review-merge discipline.
With coding agents, the scarce input is no longer typing speed — it is the quality of the constraints you set (spec), the plan you approve, the moments you intervene, and the review you give the result. Every section of this module is one of those four levers.
An agent fills every gap in your spec with the most statistically plausible choice from its training data — not your codebase's choice, not your team's choice. Under-specify and you don't get a smaller feature; you get someone else's feature that compiles. The spec is therefore not bureaucracy; it is the primary control surface, and one page is almost always enough if the page is doing the right work.
A spec that constrains an agent has five parts:
refunds.py; config lives in settings/; use the existing RateLimiter" — three pointers replace three hundred lines of generated convention-guessing.A realistic example, sized for a single agent session:
# Spec: idempotency keys for POST /orders
Goal: clients can retry POST /orders safely by sending an
Idempotency-Key header; duplicate keys return the original result.
Non-goals: no changes to the payment provider integration; no new
dependencies; GET endpoints untouched; no key expiry admin UI (a
72h TTL constant is fine).
Interface: header `Idempotency-Key` (string, 16–64 chars).
Missing header → current behavior (no idempotency). Same key +
same body → replay stored response (200/201, header `Idempotent-Replay: true`).
Same key + different body → 422 `IDEMPOTENCY_KEY_REUSED`.
Edges: two concurrent requests with the same key must not both hit
the provider — take a row lock or fail the second with 409 + Retry-After.
Storage failure → process the payment WITHOUT idempotency and log at
error (availability over dedup), do not 500.
Done: unit tests for all four header cases + a concurrency test;
`pytest -x -q` green; `ruff` + `mypy` clean; reuse the Redis-backed
`ResponseStore`; pattern-match the existing middleware in
`src/api/middleware/`.
Notice what the spec does not contain: no step-by-step implementation plan, no file-by-file instructions. That is the agent's first deliverable, and reviewing it is the next section. Tool note: this spec works identically as the prompt for Claude Code, Copilot agent mode, or Cursor's agent; on a $0 path it also works as the issue body you assign to a cloud coding agent. The technique is the artifact — the tool is interchangeable.
Write the interface and the edge cases yourself; let the agent propose everything else. Interfaces and edge behavior are where errors are expensive and your judgment is irreplaceable; implementation structure is where regeneration is cheap and the agent's speed dominates.
Every serious agent workflow now supports a planning phase — Claude Code's plan mode (read-only analysis before any edit), Copilot's agent-mode plans, Cursor's plan-then-apply flow. The phase exists because of an asymmetry worth internalizing: a wrong plan costs you one careful read; wrong code costs you a debugging session inside a diff you didn't write. Reviewing plans is the cheapest intervention point in the entire loop, and Böckeler's steering experiments identify exactly this — catching misunderstanding at the plan stage — as a place where developer skill decides the outcome.
The loop:
RateLimiter — reuse it. Move the concurrency handling to step 1; it's the part most likely to fail. Add the 422 reuse case to the test list." Iterate until the plan is one you'd approve as a PR description.Approving the plan is not the end of judgment — Böckeler's findings are specifically about when to interrupt an executing agent. The moments that repay attention:
The most dangerous agent behavior is not failure — it is success theater: tests weakened until they pass, errors swallowed until logs are quiet, a completion summary describing work that a diff-read shows was done differently or not at all. Never accept the agent's narration as evidence. The diff and a test run you triggered yourself are the evidence.
Approve plans at the altitude of a senior reviewing a mid-level engineer's design note: you are checking intent-match, reuse, sequencing, and test coverage — not formatting. If you would not approve it as a human's approach description, do not let an agent execute it.
Your first 15 minutes on any agent task: make it produce a plan with edits forbidden, and before you approve, ask the four questions — non-goal violations, reinvented components (the ResponseStore Sana's agent didn't find), the riskiest step's position, and whose edge cases are in the test list. A wrong plan costs one read; wrong code costs a debugging session in a diff you didn't write.
Some tasks resist planning because the risk is unknown unknowns: the dependency upgrade that may or may not cascade, the module extraction that may hide a dozen implicit couplings. For these, borrow Simon Willison's pattern: send out a scout. Point an agent at the task with modest effort and full expectation of throwing the result away — not to get the work done, but to find out where the work is.
The protocol distinguishes a scout from just "trying it":
Example: before committing to a sprint task of swapping your service's serialization library, a 45-minute scout attempt reveals that 80% of call sites convert mechanically but the streaming path depends on a behavior the new library doesn't have. That single finding — bought for one agent-session — converts an "easy upgrade" estimate into a correctly-scoped design conversation. The scout didn't do the work; it priced the work. Scouts pair naturally with the parallel patterns below: they're independent and disposable, so they are the safest thing to run in a background worktree while you do attended work — and the cheapest way to build the supervision instincts parallel agents require.
Feature development keeps arriving at two artifacts where mistakes fossilize: API contracts and database schemas. Both are cheap to change before first use and brutally expensive after — which makes them exactly where an adversarial AI pass pays best. The Common Core taught the sycophancy failure mode: ask "is my design good?" and the model agrees with your framing. The fix is structural — you draft, the model attacks from assigned angles, you judge the findings.
Draft the OpenAPI/proto contract yourself (it's an interface — your job, per the spec section), then:
Attached is a draft OpenAPI spec for our team-invitations API.
Attack it from these angles, one at a time. For each finding:
severity, the concrete failure scenario, and the minimal fix.
1. Versioning & evolution: what breaks the first time we need to
change a field? What should be extensible that isn't?
2. Pagination & limits: which list endpoints will melt at 100k rows?
3. Idempotency & retries: which mutations are unsafe to retry as
specified? Where do we need idempotency keys?
4. Error taxonomy: which failures share a status code but need
different client behavior? What's missing between 400 and 500?
5. Consistency: naming, casing, timestamp formats, enum-vs-string
choices that deviate from the rest of the spec or from our
conventions in <existing spec file>.
Do not compliment the design. Findings only.
The angle-by-angle structure matters: a single "review this" pass produces shallow coverage of everything, while forced lenses produce depth — the same reason security reviews use checklists. Expect roughly a third of findings to be genuinely load-bearing (missing idempotency on a retried mutation, a pagination design that breaks under concurrent writes), a third defensible-but-debatable, and a third noise; the triage is your judgment and takes minutes. This runs fine in any chat-grade assistant on a free tier — no agentic capability needed.
Same structure, different attack surface — and higher stakes, because a bad migration is production downtime:
Here is the current schema (attached), our proposed change (attached),
and our scale: ~40M rows in `orders`, Postgres 15, ~300 writes/sec peak.
Attack the proposal:
1. Locking: which statements take locks that block writes at this
scale? What's the safe sequence (e.g., NOT VALID + VALIDATE,
CREATE INDEX CONCURRENTLY)?
2. Backfill: plan for the new column across 40M rows without a
long transaction — batching, progress tracking, resumability.
3. Rollback: what is the reversal at each step? Which step is the
point of no return?
4. Indexes & queries: which existing queries regress? What breaks
the ORM's assumptions?
5. Contract drift: what must deploy before/after the migration to
keep old and new code both working mid-rollout?
Verification discipline for both critiques splits the findings in two:
ALTER TABLE … SET NOT NULL takes on your Postgres version — are stale-knowledge territory. Verify the load-bearing ones against the official docs for your exact version before you stake a maintenance window on them.Adversarial critique inverts the trust economics of generation. When AI generates a design, every claim in it needs verification. When AI attacks your design, a false-positive finding costs you five minutes of dismissal, while a true positive saves you a versioning mistake you'd live with for years. Skewed payoffs like that are exactly where AI belongs.
Once single-agent sessions are routine, the next capacity unlock is running several at once — the working pattern Willison documented in October 2025 and now common in production teams: independent tasks proceed in parallel while you rotate attention. The gains are real (practitioner writeups report substantial fractions of overnight agent runs arriving merge-ready) — but only with two disciplines: isolation so agents cannot interfere, and a review-merge protocol so integration doesn't become the new bottleneck.
Two agents editing one checkout corrupt each other's runs — shared working tree, shared index, shared build artifacts. git worktree gives each agent its own directory and branch against one shared object store:
git worktree add ../payments-idempotency -b feat/idempotency-keys
git worktree add ../payments-ratelimit -b feat/rate-limit-headers
git worktree add ../payments-scout-serde -b scout/serde-swap # disposable
# one agent per directory, e.g.:
cd ../payments-idempotency && claude # or: copilot agent / cursor session
# ...
git worktree list
git worktree remove ../payments-scout-serde # scout dies at end of day
Cloud agents (Copilot coding agent working from an assigned issue, and its equivalents) achieve the same isolation server-side — each run gets its own environment and comes back as a PR — which is also the practical free-tier path to parallelism if you're not paying for multiple local agent sessions.
Three rules keep parallelism from eating its own gains:
Parallel agents move the bottleneck to exactly where DORA 2025 says the industry is already failing: integration and review. Without a protocol, "three agents finished overnight" means three stale branches by Thursday. The protocol:
The steady state to aim for is unglamorous and effective: two or three attended-or-checkpointed agents during work hours, scouts and low-stakes chores in the background, one disciplined merge window a day — and a personal WIP limit you respect, because the DORA finding is the ceiling on this whole module: PRs you can generate but cannot properly review are inventory, not throughput.
Worktree isolation questions reduce to one fact: worktrees share a repository but not a working directory — so parallel agents can't clobber each other's uncommitted state, while branches still merge through the normal review path. If a scenario shows two agents in one checkout, or agent branches merging without a human gate, that's the planted error.
Check yourself: Your agent reports "all tests pass" after implementing a feature. Name two ways that green suite can be lying to you, and the one thing that actually counts as evidence the work is done.
This module's companion playbooks cover spec-first agentic development, plan-critique-and-intervention practice, scout-run protocols, adversarial API and schema critique, and parallel-agent operations with worktree isolation. Do this at work this week → pb-03 Spec-First Feature Implementation with an Agent in Plan Mode (Sana's plan-critique loop, end to end), pb-05 Adversarial Design Review: API Contracts and Schema Migrations (the angle-by-angle attack before an interface fossilizes), and pb-08 Parallel Coding Agents with Git Worktrees (isolation plus the review-merge discipline). Its labs include the spec-first feature lab (spec → trap-seeded plan review → implementation) and the parallel-agents lab (multi-worktree run through the full review-merge discipline).