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 act