When I started using Claude Code for TYPO3 upgrades, I did everything in one session. For a small site like my own hoja.in that works. For a large multi-site installation with several sites and many own extensions, it does not. The agent reads TypoScript of site A, then TCA of extension B, then the changelog, then the error log, and after a while the context is full of things which are no longer relevant. It starts to forget the plan, or worse, it remembers half of it.<\/p>\n
The way out was not a bigger context. It was splitting the work, the same way a team would do it: people who look around, people who change code, and one person who tries to find what everybody else missed. In Claude Code these are subagents.<\/p>\n
A subagent is a separate Claude instance with its own context window, its own system prompt and its own set of tools. The main session hands it a task, the subagent works on it, and only the final report comes back. All the files it read and all the dead ends it tried stay in its own context. That is the whole trick: the main session keeps the conclusions, not the noise.<\/p>\n
You define them as Markdown files with YAML frontmatter. Project subagents live in Before any code changes, I want an inventory of what the next hop breaks. Scouts do this per area: system configuration, site configuration, TypoScript and TSconfig, templates, forms, own extensions. They must not change anything, so they get no edit tools at all:<\/p>\n The The rule “no changelog entry, no finding” is important. A language model knows a lot about TYPO3, but it also remembers APIs from v9 next to APIs from v14. Forcing it to cite the real changelog file from From the scout reports the main session writes a plan with work packages. The key rule for workers: every package gets its own set of files, and no two packages touch the same file. Otherwise two workers edit the same TCA override in parallel and one silently overwrites the other. Finding such a lost edit later costs more time than the parallelism saves.<\/p>\n A worker for “own extension A, Classes and Configuration” and a worker for “sitepackage templates” can run in parallel. Composer changes, database work and upgrade wizards stay in the main session, one at a time, because they touch everything.<\/p>\n The tool list here is wider, so a guard is useful. For my own migrations I use a PreToolUse hook that blocks commands writing the database when there is no fresh dump in the backups folder. The subagent cannot “decide” to skip it, because hooks are enforced by the harness and not by the prompt.<\/p>\n This is the part I would never skip again. After the workers are done and the gate is green (composer validate, cache flush, no pending wizards, smoke test against the baseline), one more subagent reads the whole diff with a single job: find what everybody else missed.<\/p>\n It has Bash for On hoja.in, which is a tiny project, the reviewer still came back with real findings. Two examples from my ledger: the imported pages were owned by the One more honest point: subagents are not free. Each one starts fresh and must read its files again, so for a small upgrade a single session is faster. I start splitting when one session cannot hold the plan and the findings at the same time.<\/p>\n Feedbacks are the champion’s breakfast. If you have a different split that works for you, drop a comment!<\/p>\n One agent context is not enough for a large TYPO3 multi-site upgrade. How I split the work into read-only scouts, workers with disjoint file sets and an adversarial reviewer.<\/p>\n","protected":false},"author":1,"featured_media":145,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[18],"tags":[34,35,38,5,25],"class_list":["post-144","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-ai-engineering","tag-ai-agents","tag-claude-code","tag-code-review","tag-typo3","tag-upgrades"],"yoast_head":"\n.claude\/agents\/<\/code> and are shared with the team through git; personal ones live in ~\/.claude\/agents\/<\/code>. Only name<\/code> and description<\/code> are required. The body of the file becomes the subagent’s system prompt.<\/p>\nStep 1: read-only scouts<\/h2>\n
---\nname: upgrade-scout\ndescription: Read-only sweep of ONE area of a TYPO3 project for what a given upgrade hop breaks. Give it the area, the hop (e.g. 13 -> 14) and where the changelog is. Returns findings with file:line. Use several in parallel.\ntools: Read, Grep, Glob\nmodel: sonnet\n---\n\nYou inspect one area of a TYPO3 project for a single upgrade hop.\n\nRules:\n- You never edit files and never run commands that write anything.\n- Check every suspicion against the core changelog in vendor\/typo3\/cms-core\/Documentation\/Changelog\/<version>\/.\n Name the changelog file for each finding. No changelog entry, no finding.\n- Report: file:line, what breaks, changelog reference, suggested fix in one sentence.\n- If the area is clean, say so. Do not invent work.<\/code><\/pre>\ntools<\/code> field is an allowlist: the scout gets only Read, Grep and Glob. Then I ask the main session something like: “Send one upgrade-scout each for config\/system, config\/sites, the sitepackage TypoScript, the Fluid templates and the forms, in parallel.” They run at the same time, each with a fresh context, and I get five short reports instead of one giant session.<\/p>\nvendor\/<\/code> removes most of the guessing.<\/p>\nStep 2: workers with disjoint file sets<\/h2>\n
---\nname: upgrade-worker\ndescription: Applies the migration fixes of ONE work package from .project-migration\/plan.md inside its assigned file set, and runs the given verification command before returning.\ntools: Read, Edit, Write, Grep, Glob, Bash\n---\n\nYou get: a list of files you own, the target TYPO3 version, the findings to fix,\nand a verification command.\n\nRules:\n- Edit only files on your list. If a fix needs another file, stop and report it.\n- One finding, one small change. Do not refactor what is not broken.\n- Run the verification command at the end and paste its real output.\n- Never touch the database, composer.json or composer.lock.<\/code><\/pre>\nStep 3: an adversarial reviewer at the end of every hop<\/h2>\n
---\nname: upgrade-reviewer\ndescription: Adversarial reviewer for one finished hop of a TYPO3 upgrade. Reads the hop's diff, the gate output, the ledger and the plan, and hunts for what the gate misses. Read-only. Use at the end of every hop.\ntools: Read, Grep, Glob, Bash\n---\n\nAssume the hop is NOT done. Look for:\n- loosened version constraints or ignored platform requirements\n- wizards marked done without migrated data\n- configuration still pointing to old paths\n- features silently dropped (a plugin, a field, a redirect)\n- a runbook that differs from what was actually run\n\nEvery finding: file:line, why it matters, severity (blocker \/ should fix \/ note).\nYou do not fix anything.<\/code><\/pre>\ngit diff<\/code> and git log<\/code>, but its prompt says it fixes nothing, and it reports back to me, not to the workers. Is a prompt enough to stop it from editing? For read-only roles I prefer to leave Edit and Write out of the tool list, as here. Bash can still write files, though, so for the reviewer the prompt and the hook remain the guard. The scout has no Bash at all, and there it is really not a question of good behaviour.<\/p>\n_cli_<\/code> user instead of my admin account, and config\/system\/additional.php<\/code> was missing from git because DDEV was still managing it. Both would have reached production. The tests were green in both cases, because no test looked for them.<\/p>\nWhat I learned<\/h2>\n
\n
Further reading<\/h2>\n
\n