Swarm Coding

🐝 Swarm coding; the practice of coordinating many parallel software agents to execute repeatable change units is emerging as a powerful pattern for large-scale migrations and tech debt projects. When applied thoughtfully, it can compress months of centralized work into weeks of orchestrated, reviewable contributions.

But it’s not a magic bullet. Done poorly, it creates noise rather than velocity.

This article walks through my approach to swarm coding, how I measure, decompose, template, and dispatch work to agents in parallel. We'll use large-scale tech debt migrations as the running example.

Before you start: measure the landscape

This part decides whether swarm coding is even the right move. The goal is to make the work countable. Ideally, preparing a tiny script that you can rerun and trust: “738 mutations remaining,” “241 legacy imports,” “12 endpoints still on v1.”

Swarm coding is a good option when the number is meaningfully large, and the work can be split into small, mostly independent units (the kind that fit in a reviewable PR). If the number is tiny, swarm coding would be over-engineering it. If the change landscape is huge but tightly coupled (you must refactor all at once), or it’s massive but chaotic (no consistent flow, no repeating pattern), a swarm won’t help yet; you’ll spend your time untangling dependencies and re-deciding the approach. In that case, a better first move is often to break the work into a few smaller projects with more precise boundaries, so each one becomes “swarmable.”

Prepare the AI playbook

Once the work is countable, write an AI playbook: a short, repeatable checklist that explains “migrate X” in a predictable set of steps. Where to change the contract, where to change the implementation, what tests to add, what verification to run, and what not to touch.

Also, when you generate/assign tickets to agents, you should track which agent owns each ticket (and where the PR lives). You will almost certainly need follow-ups, clarifying an edge case, addressing team feedback, or finishing the last 10%, and it’s much easier when you know which agent context to return to.

Why tickets? Using Jira/Linear tickets enables a solo migration to become a team migration. They keep the work reviewable, and they make the assignment real: one ticket maps to one unit of work, one PR, and (often) one agent responsible for shipping it.

Two rules that keep the swarm from creating chaos

1. Keep tasks small

Small tasks keep the agent focused on a single task, avoiding attention dilution. They also make reviews easier; the team needs to review many swarm PRs, and we shouldn’t make that more complicated than it needs to be.

2. Don’t generate all tickets at once

Create a small batch (say 5–10), watch what breaks (instructions, imports, edge cases, review expectations), then update the playbook and generate the next batch.

Guardrails (don’t skip these)

• Security: if AI agents have access to privileged tools, treat prompts and outputs as untrusted inputs (prompt injection is real)

• Scope: do the migration and only the migration. (That TODO in the comment? It’s not your problem today. Put it back.)

• Idempotency: ticket generation should be safe to rerun without duplicates.

• Verification: define done in checks, not vibes. Every ticket should have explicit verification steps (typecheck, lint, relevant tests) that can pass or fail; no "seems fine" allowed.
  

Understand the Risks and Failure Modes

Swarm coding does not eliminate:

• merge conflicts,

• semantic drift,

• flaky tests,

• architecture violations,

• or technical debt accumulation, unless explicitly addressed.

Where these risks are material, invest first in dependency boundaries, architecture documentation, and test reliability; then revisit swarming.