The 8 Rules for Managing an AI Agent Swarm, Revised After a Year of Daily Practice | zach wills

Updated 2026-07-10: these rules, first written after one week with a 20-agent swarm in August 2025, are revised here against a year of daily practice.

Last August I spent a week managing a swarm of 20 AI agents and shipped a working product: roughly 800 commits and 100+ pull requests in seven days. I wrote down the 8 rules that made it work, and that post traveled further than anything else I'd written. I've now run AI agent swarms nearly every working day since, across multiple projects in parallel, and a year of evidence deserves an honest revision.

Most of the original held. The rules about state, isolation, and verification survived daily use; the rules about babysitting got absorbed by better tooling and a management structure that scales past one week of adrenaline; and the one I'd take back is the rule that called a long-running agent a bug.

One idea runs under all eight of them: you manage a swarm through what survives the session: the ticket, the branch, the brief. Never the context window.

Here is what a year did to each of the 2025 rules:

That merging frees a slot, and the year filled it with the rule one week couldn't teach: the swarm amplifies your scope creep (rule 8).

%%{init: {"look": "handDrawn"}}%%
graph TD
    H["You"] --> O1["Orchestrator thread, project A<br/>(long-lived, holds the epic's context)"]
    H --> O2["Orchestrator thread, project B"]
    H --> O3["Orchestrator thread, project C"]
    subgraph ISO["Isolation boundary: one worktree, own ports, own data per worker"]
        W1["Worker<br/>(fresh context)"]
        W2["Worker<br/>(fresh context)"]
        W3["Worker<br/>(fresh context)"]
        W4["Worker<br/>(fresh context)"]
    end
    O1 --> W1
    O1 --> W2
    O2 --> W3
    O3 --> W4
    W1 --> G["One merge gate into main"]
    W2 --> G
    W3 --> G
    W4 --> G

The shape that survived a year: a few long-lived orchestrators manage disposable workers, with isolation on the way out and one gate on the way back in.

Rule 1: Align on the plan, not the goal

This one held without amendment, so it stays first. The cheapest place to fix agent work is still the plan. Iterate with an agent on what you're building before anything gets dispatched, and only hand off once the plan reads like a ticket a stranger could execute: scope, acceptance criteria, what not to touch.

What changed is where the plan lives. In 2025 it lived in the chat. Now it's a durable artifact, because the agent that executes it is usually not the agent that wrote it. One agent produces the written plan; a fresh-context agent picks it up hours later with the instruction to treat the plan as the source of user intent. One of those handoffs ran about six and a half hours and ended in a verified open PR, with the planning agent long gone.

I still dictate most briefs by voice, which the original post recommended and I'd recommend harder now. Speech carries the why, and the why is what keeps a worker from satisfying the letter of a ticket while missing its point.

Rule 2: Manage state, not context

The 2025 post called a long-running agent a bug and prescribed babysitting: checkpoint progress to a markdown file, clear the context, resume. I got that diagnosis half right. What rots is context: a session that has been compacting its memory for hours slowly forgets the intent it started with, and a resumed context loses to a fresh one.

So the rule inverted. My sessions now run long, sometimes overnight, and that's fine, because nothing important lives inside them. State lives in the tracker, the worktree, and the brief. Fresh, self-contained briefs beat resumed contexts every time I've tested the trade.

One hung implementer session got killed and its identical brief re-dispatched into a fresh session, and nothing was lost, because the dead session was never the system of record. Apply that test to every dispatch: if this session dies, does any work die with it? If yes, your state is in the wrong place.

%%{init: {"look": "handDrawn"}}%%
graph TD
    S[Session dies] --> Q{Where did state live?}
    Q -- "in the context window" --> L[Work dies with it]
    Q -- "tracker + worktree + brief" --> R[Re-dispatch the same brief, nothing lost]

The rule 2 test in one picture: kill any session and ask what dies with it.

Rule 3: Isolated worktrees are survival, and the merge is where swarms fail

Commit early and often was 2025's safety net. It survived as the junior clause of a bigger rule: every worker gets its own git worktree outside the repo directory, its own ports, its own database, and commits early inside that isolation. Two agents sharing a checkout will flip branches and git-clean each other's untracked files; that mistake has cost me hours of an agent's in-progress work, once, which was enough.

Isolation covers the way out. The way back in, everything merging into one main, is where parallel work actually breaks. Anything globally sequential is a merge hazard: two of my lanes once claimed the same ADR numbers and needed an explicit renumber commit to untangle. Reserve shared counters and shared files before dispatch, not after the collision.

The part I didn't predict is how much of this the agents now handle themselves. Two of my sessions collided on the same epic, detected it, and coordinated merge windows between themselves. And before any agent closes a duplicate PR, make it prove the surviving PR is a strict superset of the one being retired. Never close concurrent work on an assumption.

Rule 4: Manage orchestrators, not agents

The original post described me watching four terminals in a state of constant situational awareness, and admitted three hours of it left me burnt. That mode does not survive a year. What replaced it is one long-lived orchestrator thread per project: it holds the epic's context, decomposes the work, dispatches the workers, and takes my feedback the way a lead engineer would. Is this done? I have notes on that one. Redo this. It redispatches with the context intact.

So I talk to three or four orchestrators, not to twenty workers. A normal day is 3-4 projects with a handful of workers each, somewhere around 12 to 16 top-level agents, more counting the subagents they spawn. From the outside that sounds like a swarm. From the inside it's really just like managing four people, and my ceiling stopped being attention and became hardware; the machine taps out before I do.

If you run Claude Code and want the mechanics of the worker layer, I keep a separate guide: how to use Claude Code subagents to parallelize development.

Rule 5: Health-check the workers, and restart without mercy

Be ruthless about restarting survived word for word. It just got cheaper, and it now starts before the work does. Before dispatching anything real, ping every worker session with an instruction to reply with exactly MODEL_OK. It feels beneath the technology. It once caught two dead sessions out of three in about a minute each, instead of letting them surface as multi-hour silent failures.

Mid-run, a quiet worker gets a forced-choice ping: researching, blocked, or about to edit? A healthy agent answers instantly; a wedged one can't, and gets killed and re-dispatched. Put a watchdog on your dispatches so hung ones get detected without you noticing first.

%%{init: {"look": "handDrawn"}}%%
graph TD
    P["Quiet worker gets the ping:<br>researching, blocked, or about to edit?"] --> A{Answers instantly?}
    A -- yes --> C[Healthy. Leave it alone]
    A -- no --> K[Kill it, fix the brief,<br>re-dispatch fresh]

The forced-choice ping sorts a busy worker from a wedged one in seconds.

None of this is fire and forget, and it never has been. In an early coordinator experiment of mine, about a third of the workers needed an interrupt at some point. The 2025 instinct to let a wandering agent finish its thought is still pure waste: kill it, fix the brief, restart. Restarts cost nothing once rule 2 holds.

Rule 6: Trust the loop, verify the exit

The autonomous loop kept the trust the 2025 post gave it. Agents iterating against tests, a browser, or a live API until the thing works is where the throughput comes from. But a loop's exit condition can lie. An implementation once passed all 41 of its own tests while rendering against real data showed two visual defects; a second agent doing review caught what the green checkmarks missed. Tests green is not the same as looks right.

Supervision at swarm scale mostly collapses into two words: show me. Show me the screenshot, the token counts, the diff. When I doubted a polished demo was making real model calls, the agent proved it with the returned token counts, then proved the calculation engine was real by perturbing an input and checking the output moved by exactly the expected amount. Cheap, decisive, and much better than trust.

I've since pushed this all the way into the PR contract, with evidence attached to every acceptance criterion, but that's its own post.

Rule 7: Automate the system, not just the code

Of the original eight, this aged best, and the ecosystem gave it a name: skills. The self-updating CLAUDE.md and self-refining commands from 2025 grew into markdown files that encode whole workflows, one that turns a rambling idea into a spec and ticket, one that builds a feature with proof attached, one that drains a backlog. Agents execute the process; the process itself is versioned, reviewable text.

When an agent misses, the correction goes into the skill instead of the chat, so it applies to every future run instead of once. And skills are portable: the same markdown files have moved between agent harnesses in minutes. Harnesses are swappable. The encoded process is the thing you own.

Rule 8: The swarm amplifies your scope creep

Agents pattern-match to enterprise checklists by default: hand one a prototype-stage ticket and it will spec encryption-at-rest and an automated mechanism to siphon off a data holdout, for a system whose honest requirements are a directory and a hand-kept manifest. One agent doing that is a code review comment. Twenty doing it in parallel is a codebase you don't recognize by Friday.

So deciding what not to build became a daily job, maybe the highest-value one I do inside a swarm. Every plan gets the same question before dispatch: what is the simpler version of this? None of the twenty will tell you a ticket is too ambitious for the stage the product is in. That call stays human, and at swarm throughput it compounds faster than any other call you make.

The 2025 toolkit is mostly table stakes now

The original post ended with a toolkit: a semantic code-editing layer, a browser-automation MCP, branched databases, a forced-planning tool. A year later I'd send you shopping for almost none of it, because the harnesses absorbed the list. Isolated environments, browser control, and planning modes come standard now, and the custom parallelization tool I built for that week has native equivalents everywhere.

The durable layer is the process: the rules above and the skill files that encode them. The tools rotate underneath.

What this does to the job

The 2025 post predicted that engineering value would shift from implementation to direction. A year of daily practice moved that from prediction to job description. If you're shipping software with agents, your day trends toward scheduler and reviewer, and an agent swarm is really just a team you staff, brief, and audit.

If you'd rather test these rules than take them, start small: one project, one orchestrator thread, two workers in isolated worktrees, briefs written so a fresh session could execute them cold. Run that for a week. The rules you'd revise will find you, which is how this post got written.