16 Claude Code sub-agents run a legacy PHP migration

The author's starting point is scale: a decade-old monolith with hundreds of endpoints and more than 600 shared models is too large for one person to track which API has moved and whether the old logic was copied correctly. Handing the whole job to an AI produced four recurring failures — invented response structures, contaminated context, code written before the spec was fixed, and dependency order broken.

The diagnosis is that the root cause is cramming too many responsibilities and too much information into one context, not a weak model. Extraction agents shown new code drift toward "the old one must work like this"; contract designers allowed to touch code start making well-meaning spec changes. The fix mirrors ordinary team management: separate roles, handoff documents, and review gates, with file handoffs letting each sub-agent start from a clean context and a PreToolUse hook mechanically blocking writes outside defined directories.

Operationally the author caps each pass at 5–10 endpoints and isolates one domain per context, because sub-agents cannot launch other sub-agents nested and delegation must route through the dispatcher. The legacy monolith stays read-only, and a conclusion of "not in the original" requires a fresh fetch since it is still actively updated.