How not to use sub-agents!

What a 500-script migration taught me about when agent parallelism actually makes sense I recently started working on a migration involving roughly 500 scripts. The goal was to migrate legacy logging calls to a newly implemented structured logging engine, with unique logging channels for tracing and observability through Grafana, Loki, Tempo, and Alloy. The new logging engine was already implemented and available through a common include path. What remained was the tedious part: updating hundreds of existing scripts. My first thought was simple: "There are 500 files. Why not use 10 sub-agents and finish this faster?" It sounded like a perfect use case for agentic coding. It wasn't. The problem wasn't the number of files. It was what I was asking the agents to do. 1. The Initial Approach: More Agents = More Speed? The idea was to divide the files into batches and give each batch to a mini-model. Main Agent │ ┌─────────────┼─────────────┐ ▼ ▼ ▼ Agent 1 Agent 2 Agent 3 50 files 50 files 50 files │ │ │ └─────────────┼─────────────┘ ▼ Migration Each agent received essentially the same instructions: find legacy logging replace it with the new structured logger use the correct channel preserve business logic complete its assigned files The files were independent, so the approach looked reasonable. But each agent was doing much more than the actual migration. It was also rediscovering the repository, figuring out what needed changing, deciding channel names, and keeping track of its own progress. That repeated work became the real cost. 2. What Actually Happened The problems were not primarily with the code changes. They were with the work surrounding them. Problem 1: Tracking completed work With multiple agents, someone needs to know: which files are pending which are being processed which are completed which failed which should be skipped That is workflow state. A JSON file, database, or task queue is designed for this. An LLM context isn't. Problem 2: Finding what actually needs to change Each agent had to discover the logging statements itself. The process looked something like: Open file ↓ Understand file ↓ Search for logging ↓ Find legacy calls ↓ Inspect context ↓ Decide what to change ↓ Perform migration But if a simple command can already tell us: ExampleScript.py:42 ExampleScript.py:87 ExampleScript.py:131 ExampleScript.py:164 there is little value in asking ten different model contexts to discover those same locations. That is a job for tooling. Problem 3: Channel generation consumed reasoning Each script needed a unique channel. For example: ExampleScript.py ↓ example_channel This was another decision I had unnecessarily delegated to the model. Channel generation can be deterministic: file path ↓ channel generator ↓ validated channel map Once generated, the channel can simply be given to the model. No need to make the model reconsider naming conventions and uniqueness for every file. 3. The Important Distinction: Work vs. Reasoning This was the point where my thinking changed. I initially saw: 500 independent files But that doesn't necessarily mean: 500 independent reasoning problems. Those are different things. The migration itself was mostly: Find legacy logging ↓ Replace with known API ↓ Use known channel ↓ Preserve everything else The work was repeated hundreds of times, but the reasoning was mostly the same. Now compare that with a debugging problem: Why did API latency increase? ├── Database? ├── Cache? ├── Network? ├── AWS infrastructure? └── Application code? Those are genuinely different reasoning paths. That is where sub-agents become useful: Problem │ ┌──────────┼──────────┐ ▼ ▼ ▼ Agent A Agent B Agent C Database Network Application │ │ │ └──────────┼──────────┘ ▼ Synthesis Each agent can investigate a substantial hypothesis independently. That is meaningful parallelism. In my migration, I was parallelizing work, not reasoning. 4. The Better Approach: Remove Decisions Before Calling the Model The obvious improvement was to move deterministic work outside the model. Instead of asking agents to discover everything, preprocess the repository first. Repository │ ▼ Preprocessing │ ┌──────────────┼──────────────┐ ▼ ▼ ▼ Inventory Log locations Channel map │ │ │ └──────────────┼──────────────┘ ▼ index.json │ ▼ Single Claude Code │ ▼ Migration │ ▼ Verification The preprocessing stage determines: which files contain legacy logging which files contain no logging where the legacy calls are what channel belongs to each file what has already been completed For example: { "file": "ExampleScript.py", "status": "pending", "legacy_log_count": 4, "channel": "example_channel" } Now the model doesn't need to discover the problem. It receives the problem. 5. The Model's Task Becomes Much Smaller Instead of: Explore the repository and migrate this file. the model can receive: File: ExampleScript.py Channel: example_channel Legacy logging locations: 47 82 119 153 Expected migrations: 4 Task: Replace the identified legacy logging statements with the structured logging implementation. Do not modify business logic. Do not change the assigned channel. Do not modify unrelated code. The model now focuses on the part that actually benefits from reasoning: How should this existing logging statement be expressed using the new API while preserving its meaning? Everything else has already been established. This is a much better task boundary. 6. Why the Single Session Is Better Here For this migration, a single Claude Code session has some simple advantages: one shared migration context no duplicated instructions no inter-agent coordination external state for progress deterministic tools for deterministic work The workflow becomes: index.json │ ▼ Next pending file │ ▼ Prepare file context │ ├── locations ├── channel └── rules │ ▼ Single agent │ ▼ Verification │ ┌─────┴─────┐ ▼ ▼ PASS FAIL │ │ ▼ ▼ completed review This isn't less sophisticated than a multi-agent system. It's simply better matched to the problem. 7. So When Are Sub-Agents Actually Useful? The experience led to a better question. Instead of asking: "How many tasks do I have?" ask: "How many independent reasoning problems do I have?" That distinction makes the useful cases much clearer. Independent research For an architectural investigation, different agents can explore different areas: Agent A → AWS architecture Agent B → database architecture Agent C → observability Agent D → security The main agent can then combine the findings. Competing debugging hypotheses For a performance problem: Performance issue │ ┌────────────┼────────────┐ ▼ ▼ ▼ Database Network Application hypothesis hypothesis hypothesis │ │ │ └────────────┼────────────┘ ▼ Synthesis Each agent investigates a different explanation. Independent code reviews A change can be reviewed from different perspectives: Agent A → correctness Agent B → security Agent C → performance Agent D → maintainability These agents aren't simply doing the same job. Each has a different analytical objective. Independent feature implementation If a system has clearly separated components: API Worker Infrastructure Observability and their interfaces are already defined, separate agents can work independently. The important condition is low coupling. 8. The Cost of Sub-Agents Sub-agents aren't free parallel threads. Every additional agent brings its own: context instructions tool calls reasoning coordination result synthesis failure handling Conceptually: Single agent: shared context + sequential reasoning N agents: N × context + N × reasoning + coordination + synthesis So parallelism only helps when the reasoning saved is greater than the overhead introduced. A useful way to think about it is: Sub-agent benefit = parallel reasoning saved - duplicated context - coordination cost - synthesis cost If the difference is small, adding agents is mostly adding machinery. 9. A Practical Decision Framework Before creating a sub-agent, ask: Is the task deterministic? If yes: Use a script or tool. Does it require substantial reasoning? If no: A single agent is usually enough. Is the reasoning independent? If no: Keep it in one session. Would a fresh context provide meaningful value? If yes: A sub-agent may be worthwhile. A simple decision tree: Is it deterministic? │ ┌─────┴─────┐ YES NO │ │ TOOL Substantial reasoning? │ ┌────┴────┐ NO YES │ │ SINGLE AGENT Independent? │ ┌─────┴─────┐ NO YES │ │ SINGLE SUB-AGENTS SESSION 10. What I Learned From the 500-File Migration The migration changed how I think about agent orchestration. 1. The number of files doesn't determine the number of agents. Five hundred files can still represent one reasoning pattern. 2. Context is a resource. Duplicating the same context across ten agents has a cost. 3. Preprocessing can be more valuable than parallelism. Finding the relevant information before invoking the model can save more effort than adding more workers. 4. External state beats model memory. A model shouldn't have to remember the status of hundreds of files. 5. Deterministic decisions belong outside the LLM. Channel generation, classification, searches, counts, and validation can be automated. 6. Agent orchestration has a cost. More agents do not automatically mean faster or cheaper execution. 7. Agents are best used for reasoning. Not bookkeeping. Not counting. Not maintaining workflow state. Not performing searches that a deterministic tool can perform more reliably. 11. The General Principle The biggest lesson wasn't: "Don't use sub-agents." It was: Don't parallelize merely because work can be divided. Parallelize when reasoning can be divided. A hundred deterministic transformations may be better handled by a script. A hundred small reasoning tasks may still be better handled by one well-contextualized agent. Five difficult, independent investigations may be perfect for five sub-agents. The number of tasks is only one part of the problem. The structure of the reasoning should determine the architecture. Conclusion My initial assumption was: 500 files ↓ many agents ↓ faster migration The better approach turned out to be: 500 files ↓ deterministic preprocessing ↓ external state ↓ bounded context ↓ single agent ↓ deterministic verification The lesson is not that sub-agents are bad. It's that parallelism should have a reason. Before spawning another agent, ask: Where is the independent reasoning? If there isn't much, more agents may simply mean more context, more tokens, more coordination, and more things to clean up afterward. Use sub-agents when they let you explore different substantial reasoning paths at the same time. Otherwise, fewer agents with better boundaries usually win.