Your team is shipping faster with AI. That part is real. What you can't easily see is whether that speed is a durable win or a liability you're accruing quietly. By the time it surfaces, it's a production incident, an unexplained regression, or a refactor nobody can justify.
I'm a software architect. I've spent about 26 years building and running production systems, and for the last stretch I've been running fleets of AI agents against real codebases: not as a demo, but as the way the work gets done. This is the method I use to get the speed without the liability. It isn't a prompt pack or a set of tricks. It's the boring, load-bearing parts of software engineering (separation of concerns, test-first, written decisions, adversarial review) applied to how you drive the agent.
I've packaged the skeleton of it as a public template, agent-team-starter, so this isn't hand-waving: you can read every line. This piece is the why behind it.
The default is free-solo, and free-solo is the problem
The default way to use an AI coding agent is what I call free-solo: one long chat that researches, designs, writes the code, and approves its own work in the same breath. It feels fantastic. It's fast. And it quietly accumulates exactly the failures a real engineering team exists to prevent:
- No design record. The plan lived in a chat that's now gone. Nobody can reconstruct why the code is shaped the way it is.
- Happy-path-only tests. The agent wrote the code and the tests together, so the tests assert what the code already does, not what it should do at the edges.
- No independent check. The same context that wrote the code reviewed it. An author is the worst reviewer of their own work; an agent author is no exception, and it will confidently wave through its own mistakes.
- Evaporating "why." Every non-obvious decision (the trade-off, the thing you didn't do and the reason) vanishes when the session ends.
- Unbounded blast radius. A single agent with broad file and shell access can, on a bad turn, "fix" far more than you asked.
None of these are AI-specific failures. They're the failures that made professional software engineering invent code review, testing, and design docs in the first place. AI didn't repeal them. It just made it very easy to skip them at speed.
So the goal isn't to slow the agent down. It's to put the discipline back, mechanically, so it doesn't depend on anyone remembering to be careful.
The core move: orchestrator-first
Real teams don't let the person writing a change also be the one who approves it. My agent setup works the same way. There is one rule everything else hangs off:
A coordinator plans and decides at the gates; specialists execute in isolation; the coordinator never writes the code it is judging.
Concretely, a feature runs through a small team of role-scoped agents:
| Agent | Job | Writes code? |
|---|---|---|
| orchestrator | plans, delegates, decides at gates, threads results | no |
| researcher | read-only scout: maps the code and the constraints | no |
| architect | approach, contracts, and a written decision record; orders the work into slices | docs only |
| implementer | strict test-first: red → green → refactor, one slice at a time | yes |
| reviewer | adversarial verification and the quality gate | no |
The loop is deliberately unremarkable:
/feature <goal>
└─ researcher → architect → implementer → reviewer → retro
(plan gate) (TDD) (block on High)
Two gates matter. There's a human gate at the plan: I see the approach and the slices before a line of code is written, and I can kill a bad direction when it's cheap. And there's a hard gate on High-severity review findings: the work does not proceed while a serious problem is open. Everything else is designed to make those two gates trustworthy.
Least privilege isn't security theatre. It's how you get honest work
Look again at that table's last column. I call it capability-slicing: every agent gets only the tools its job needs, and nothing more.
Be precise about what that actually enforces, though. This is where most write-ups oversell, and the distinction is the whole point. The researcher and orchestrator are capability-locked: they hold no write tools at all, so they literally cannot touch code. The reviewer and architect each keep one broader tool because their job needs it (Bash to run tests, Write for ADRs), and they're held to their lane by prompt plus the absence of editing tools. Claude Code grants tools all-or-nothing (there is no path-scoping), so neither of those two is hard-sandboxed to a subtree. That's the honest limit. Naming it is worth more than the cleaner-sounding claim.
The rule still pays for itself:
- A small blast radius. The smaller each role's capability set, the less it can wreck on a bad turn. You're bounding failure by construction, the same way you scope a service account or an API token, not by hoping the model behaves.
- Honest verification. The reviewer is given no edit tools and one job: report, don't fix. Remove the easy path to quietly patch-and-pass and the review stops being performative. It's the same reason your org doesn't let authors approve their own pull requests.
This is the part most "AI coding" advice skips entirely, and it's the part a production engineer feels in their gut. Permissions are a design tool. Use them, and be straight about where the tooling stops.
Test-first, enforced by the tooling, not by good intentions
The implementer works test-first: a failing test, then the code to pass it, then a refactor. And it operates under one non-negotiable rule: never weaken or delete a test to make it pass. That single rule is what stops the most common AI failure mode I see: the agent, asked to make things green, "fixing" the test instead of the bug.
But a rule in a prompt is a suggestion. So it's backed by tooling. A PostToolUse hook runs a fast check after every edit and feeds any failure straight back to the agent to fix: an automatic gate, not a polite reminder. (The gate the template ships is a TypeScript example that only fires when a local tsc is actually there; you wire the fast check that fits your stack.) Keep it fast; leave the full suite to review and CI. The effect is that the loop can't drift far from green before something drags it back.
The principle underneath: make the discipline mechanical. Anything that depends on a human (or an agent) remembering to be careful will eventually be skipped under deadline. Wire it into the tools and it holds.
Decisions are artifacts, not chat history
When the architect makes a non-obvious choice (a trade-off, a boundary, a thing deliberately not done) it writes a one-page Architecture Decision Record into the repo. Not a paragraph in a transcript that's gone tomorrow; a file, in version control, next to the code.
This sounds like bureaucracy until the first time someone (maybe you, in three months) asks "why is it built this way?" and the answer is right there instead of lost. ADRs turn the most valuable and most perishable output of the whole process, the reasoning, into something reviewable. In an AI workflow, where the "thinking" happens in an ephemeral context window, this is worth more, not less.
And there's a governance dividend that lands hard in regulated shops: the gates, the ADR trail, and a plain-text audit log are your human-oversight evidence. If you ever have to show that a human was in the loop and decisions were recorded (for a customer, an auditor, or the EU AI Act's oversight expectations) you already have it, as a by-product of building well rather than a compliance project bolted on after.
The method improves itself
After a feature ships, I run a short retro that turns process friction into edits to the agents and commands themselves. A role prompt was too vague? Tighten it. A gate kept missing a class of bug? Add the check. The setup you start with is a posture, not a cage. It gets a little better every time you use it, with the changes recorded so the improvement compounds instead of resetting.
Five roles is the starting point, not the target. Add a sixth (a security-reviewer, a docs-writer) only when a real gap shows up, and write down why. Discipline about adding discipline matters too.
When not to use any of this
I'd distrust anyone selling a method with no failure modes, so here are mine.
The overhead has a break-even. For a one-line change, a config tweak, a throwaway script: skip the whole apparatus and just make the edit. Orchestration, gates, and ADRs earn their keep on non-trivial work with real consequences; below that line they're friction for its own sake. Part of the skill is knowing where that line is.
This does not make the model correct. Agents still hallucinate APIs, misread requirements, and produce confident nonsense. The method doesn't prevent that; it catches it, through the independent reviewer and the tests, before it reaches production. The discipline is the safety net, not the acrobat. If you're expecting the structure to make a weak model reliable, you'll be disappointed; what it does is make a capable model's mistakes visible and cheap to fix.
It's a workflow, not a religion. The moment a gate is pure ceremony for your context, cut it. The goal is shipped, trustworthy software. Everything here is in service of that, and nothing here is sacred.
What it actually buys you
Strip away the mechanism and this is what changes for a team that adopts it: your fast AI-driven changes now come with a design record, edge-case tests, an independent review, a written rationale, a bounded blast radius, and an audit trail, by default, because the workflow produces them, not because someone had the discipline to add them after. Your senior engineers stop firefighting agent output and start setting the guardrails once. Your mid-level engineers ship agent-driven work the seniors can actually trust. And the practice survives the one person who was "good with AI" leaving, because it lives in the repo, not in their head.
That's the difference between using AI to code and running an engineering practice that happens to use AI. The first is a personal productivity hack. The second is something you can build a team on.
The starter template is open source and MIT-licensed: agent-team-starter. Read it, use it, make it yours. I write about what survives production; follow along if that's useful.