Subagent fan-out for code migration means splitting a large change across specialized agents that explore, implement, test, and review different parts of a repository. It helps with monorepos, TypeScript migrations, internal API changes, and infrastructure updates, but only when the boundaries are explicit.

In 2026, GitLab reported that 85% of respondents see review and validation as the bottleneck after AI adoption in software development (GitLab, "AI Accountability Report", 2026). If agents write more code, orchestration has to reduce review noise instead of multiplying ownerless diffs.

Practical summary

  • Use subagents for parallel reading before parallel editing.
  • Partition work by package, module, contract, or operational risk.
  • Use worktrees when implementation happens in parallel.
  • The final PR must show evidence, commands, and discarded decisions.

Abstract diagram shows coordinated subagents around a code migration without visible text.

Why did fan-out become an engineering skill?

In 2025, Google Cloud's DORA report measured 90% AI use at work and more than 80% of respondents believing it improved productivity (Google Cloud, "Announcing the 2025 DORA Report", 2025). Fan-out became an engineering skill because individual speed does not solve a large migration when validation stays centralized.

The common mistake is treating agents like CPU threads. Agents do not share memory consistently, do not automatically understand each other's intent, and can edit the same file through different assumptions. Without partitioning, parallelism becomes rework.

Use fan-out when the task has real independence. A migration from raw fetch calls to an internal client can be split by package. A logger replacement can be split by layer. A CI change can separate inventory, patching, and validation. If the task is strictly sequential, keep one main agent with checkpoints.

This article extends the cluster around context engineering for coding agents. That post focused on saving context. This one focuses on distributing context across workers without losing the decision trail.

The benefit appears when every subagent returns a short synthesis. The main agent does not need every file that was read. It needs scope, finding, proposed patch, test evidence, and residual risk. That contract keeps context useful.

When should you use subagents, workflows, or agent teams?

In 2026, Claude Code documentation described four ways to parallelize work: subagents, agent view, agent teams, and dynamic workflows (Claude Code Docs, "Run agents in parallel", 2026). The right choice depends on who coordinates, whether workers communicate, and whether they edit the same files.

Subagents are best when the main agent remains in charge. They research, review, or perform a narrow task, then return a summary. For a monorepo migration, use them for module inventory, broken-test analysis, security review, or dependency reading.

Dynamic workflows fit repeatable work. Claude Code documentation cites codebase audits, 500-file migrations, and cross-checked research as cases for dynamic workflows (Claude Code Docs, "Run agents in parallel", 2026). That matches mechanical migrations that need independent verification.

Agent teams cost more coordination. In 2026, Claude Code documentation marked agent teams as experimental and disabled by default, recommending them for parallel exploration, independent modules, competing hypotheses, and cross-layer coordination (Claude Code Docs, "Orchestrate teams of Claude Code sessions", 2026). Use them when workers must talk to each other.

Surface Best migration use Risk signal
Subagent Reading, review, and narrow tasks. Edits too many modules.
Dynamic workflow Repeatable step with cross-checks. Becomes a script without a stop rule.
Agent team Independent layers that must negotiate. Everyone depends on one central file.
Main session Final decision, merge, and PR narrative. Receives raw logs instead of synthesis.

A useful rule is simple. If a worker's result fits in a summary, use a subagent. If the work must be rerun, use a workflow. If workers need to debate frontend, backend, and tests, consider an agent team.

How do you partition a migration without conflict?

In 2025, Stack Overflow found that 69% of agent users reported productivity gains, but only 17% reported better team collaboration (Stack Overflow, "2025 Developer Survey: AI", 2025). Partitioning turns isolated speed into reviewable collaboration.

Abstract diagram shows isolated work lanes for parallel migrations without visible text.

Start with inventory. Before patching, ask a read-only subagent to map affected files, likely tests, module owners, and cross-dependencies. A second subagent can inspect operational risk: authentication, payments, queues, personal data, migrations, and infrastructure.

Then split by stable boundaries. Package, service, route, queue, schema, shared library, and CI pipeline are better boundaries than "the first half of files." If two subagents need the same central abstraction, keep that part with the main session.

Use worktrees when agents edit in parallel. Claude Code documentation recommends worktrees when tasks touch files and notes that parallel sessions can run in separate checkouts (Claude Code Docs, "Run agents in parallel", 2026). This keeps one attempt from corrupting another.

migration:
  inventory:
    role: "read only"
    output: "affected files, tests, and risks"
  patches:
    api_package:
      boundary: "packages/api/**"
      forbidden: "packages/web/**"
    web_package:
      boundary: "packages/web/**"
      forbidden: "packages/api/**"
  consolidation:
    owner: "main session"
    requires: "tests, clean diff, and decision summary"

In practice, I let a subagent edit only when the boundary is objective. If the change crosses a public contract, shared types, or database migration, the subagent can propose a patch, but the main session applies it. That preserves technical authorship.

How do you control context and cost?

In 2026, Claude Code documentation warned that running multiple sessions or subagents at once multiplies token usage (Claude Code Docs, "Run agents in parallel", 2026). Control comes from narrowing input, limiting tools, and requiring short output from every worker.

Give each subagent one question. "Find every billing package impact" is better than "understand the codebase." The output should list files, reason, recommended test, and confidence. If the worker needs more context, it should ask for a narrow tool result instead of dumping the repository into the conversation.

Permissions also control cost. An inventory worker does not need write access. A security reviewer does not need deployment access. A test evaluator may only need files and commands. This mirrors codebase RAG over MCP for agents: narrow tools produce better context.

When a migration crosses many sessions, pieces of evidence, and subagents, I use RemoteCode to extend Claude Code and Codex in long agentic flows as my own resource. The value here is qualitative: reducing context waste when work spans stages without reloading the whole history.

area: authentication package
status: ready_for_patch
files: src/auth/session.ts, src/auth/session.spec.ts
risk: medium
proof: unit test covers expiration and revocation
next_action: apply patch only inside this package

That contract prevents fan-out from becoming a pile of narratives. The main agent can compare results, choose application order, and open a PR that explains the path. Good context is context that fits the next decision.

Where do Codex, MCP, and CI fit?

In 2026, Codex documentation stated that MCP configuration lives in config.toml and can be scoped to a trusted project through .codex/config.toml (OpenAI Developers, "Model Context Protocol - Codex", 2026). That lets the migration use repository-owned tools instead of manual copy and paste.

Codex can participate as an executor or as a tool. In 2026, OpenAI documentation showed Codex CLI running as an MCP server with codex mcp-server, exposing tools for multi-agent workflows with reviewable traces (OpenAI Developers, "Use Codex with the Agents SDK", 2026). That architecture fits migrations that need an audit trail.

CI should remain the deterministic judge. Subagents can propose, but lint, typecheck, tests, build, and contract analysis must run outside the chat. If the project already has a mature CI path, use existing jobs before adding AI-based rubrics.

For backend work, connect the migration to service boundaries. A well-partitioned change respects the architecture discussed in the code agent harness article: the agent can move faster when the system exposes clear gates and module limits.

### Migration evidence
- Inventory: affected packages and out-of-scope files.
- Patches: worktrees used and conflicts resolved.
- Tests: commands run and failures fixed.
- Review: security, type, and regression findings.
- Residual risk: points that require human judgment.

This links fan-out to PR evals for code agents in CI. Agents can perform parallel work, but acceptance should still depend on proof.

What is the smallest useful rollout this week?

In 2026, GitHub reported that Copilot code review grew 10 times since launch and now accounts for more than one in five code reviews on GitHub (GitHub, "60 million Copilot code reviews and counting", 2026). The smallest rollout should reduce review load, not just increase patch volume.

Choose a small but real migration first. Replacing a utility function, updating an internal API, or migrating one TypeScript package is better than attacking the whole monorepo. The goal is to test the fan-out protocol, not to prove bravery.

Write three roles. Start with an inventory subagent, a test subagent, and a review subagent. Add editing workers later. This order keeps the team from confusing parallelism with missing process.

Run with a limit. Two or three subagents are enough at first. If they find clear boundaries, move to worktrees. If they reveal unexpected coupling, stop and adjust the architecture before multiplying sessions.

Abstract diagram shows subagent flows converging into final verification without visible text.

Save the learning in the repository. Put commands, boundaries, sensitive areas, and evidence format in AGENTS.md, CLAUDE.md, or an equivalent file. That helps Claude Code, Codex, Copilot, and future agents repeat the workflow.

The success signal is smaller, sharper review. If the PR arrives with scope, tests, and discarded decisions, fan-out helped. If it arrives with five incompatible narratives, you automated confusion.

FAQ about subagent fan-out

In 2026, GitLab said 92% report some governance challenge with AI-generated code (GitLab, "AI Accountability Report", 2026). These answers help apply fan-out without losing traceability.

Does fan-out fit every migration?

No. In 2026, Claude Code documentation recommends choosing the approach based on coordination, communication, and touched files (Claude Code Docs, "Run agents in parallel", 2026). Use fan-out when boundaries are independent. For a sequential change or one central file, use one main agent with checkpoints.

Should subagents edit code or only review?

It depends on the boundary. In 2026, Claude Code documentation explained that subagents have their own context, tools, and permissions (Claude Code Docs, "Create custom subagents", 2026). They can edit when scope is narrow. For shared contracts, prefer patch proposals applied by the main session.

Is a worktree mandatory for fan-out?

No, but it helps with parallel edits. In 2026, Claude Code documentation recommends worktrees to isolate file-touching tasks (Claude Code Docs, "Run agents in parallel", 2026). If subagents only read and summarize, a worktree is too much. If they edit, it reduces conflict.

How do you measure better orchestration?

Measure review rework. In 2026, GitHub said high-signal comments matter more than volume and that 71% of Copilot code reviews surface actionable feedback (GitHub, "60 million Copilot code reviews and counting", 2026). Locally, look for fewer repeated comments, conflicts, and post-merge failures.

Closing

In 2026, GitLab reported that only 28% say their software development lifecycle tools are fully integrated with shared data and workflows (GitLab, "AI Accountability Report", 2026). Subagent fan-out is a practical response when teams need large code migrations with traceability.

Start small: inventory, tests, and review. Then allow patches inside clear boundaries. Use worktrees for parallel edits, MCP when the agent needs narrow tools, and CI to validate the result. The goal is not more agents. The goal is a migration the team can understand, verify, and maintain.

Sources consulted

  • GitLab, "AI Accountability Report", retrieved 2026-07-03, https://ir.gitlab.com/news/news-details/2026/GitLab-Research-Reveals-Organizations-Are-Generating-AI-Code-Faster-Than-They-Can-Control-It/default.aspx
  • Google Cloud, "Announcing the 2025 DORA Report", retrieved 2026-07-03, https://cloud.google.com/blog/products/ai-machine-learning/announcing-the-2025-dora-report
  • Claude Code Docs, "Run agents in parallel", retrieved 2026-07-03, https://code.claude.com/docs/en/agents
  • Claude Code Docs, "Orchestrate teams of Claude Code sessions", retrieved 2026-07-03, https://code.claude.com/docs/en/agent-teams
  • Stack Overflow, "2025 Developer Survey: AI", retrieved 2026-07-03, https://survey.stackoverflow.co/2025/ai
  • OpenAI Developers, "Model Context Protocol - Codex", retrieved 2026-07-03, https://developers.openai.com/codex/mcp
  • OpenAI Developers, "Use Codex with the Agents SDK", retrieved 2026-07-03, https://developers.openai.com/codex/guides/agents-sdk
  • GitHub, "60 million Copilot code reviews and counting", retrieved 2026-07-03, https://github.blog/ai-and-ml/github-copilot/60-million-copilot-code-reviews-and-counting/