Subagents on a site build: delegate measurement, keep decisions
The limit on a large site build is context, not ability. Four jobs worth delegating, the one that never should be, and why a 210-page site keeps its writing in a single window.
The limit you hit on a large site build is not the agent's ability. It is context. A session that has read forty files, three build logs and a sitemap is a session that has spent most of its window on material it will never refer to again, and quality falls off well before the window is full. Subagents exist to fix exactly that, and on a site with a few hundred pages they are the difference between one good day and three mediocre ones.
What a subagent actually is
A subagent is a separate agent with its own context window, its own system prompt, its own tool access and its own permissions. You delegate a task, it works in isolation, and it returns a summary. The exploration never enters your conversation. The subagents documentation lists the built-in ones, and two are worth knowing by name: a read-only explorer with writes denied, and a general-purpose one with the full tool set.
The part people miss is that this is not parallelism for speed. It is isolation for quality. A subagent that reads thirty files and reports one answer has protected your main conversation from twenty-nine files of noise, and that is the benefit even when nothing ran in parallel at all.
Four jobs worth delegating on a website
| Job | Why it belongs in its own window |
|---|---|
| Finding every place a pattern appears | Returns a list, costs a hundred file reads |
| Auditing content against a rule | Reads everything, reports only the failures |
| Reading build and deploy output | Logs are long and almost entirely irrelevant |
| Reviewing a diff for one specific defect | A fresh reader is not anchored on your reasoning |
The fourth one is the subtlest and the most valuable. An agent you have been reasoning with for an hour will tend to agree with you, because your hypothesis is in its context. Hand the diff to a fresh reader with no history and you get an unanchored read, which is the only kind worth having on a review. The trick is to give it the code and not your conclusion.
The job that should never be delegated
Design and copy decisions. Not because a subagent cannot write a paragraph, but because the thing that makes a page good is consistency with every other page, and consistency is exactly what an isolated context cannot see. We learned this on a run of location pages: delegated in parallel, they each read well and collectively read like five different writers, and fixing that cost more than writing them in one window would have.
The rule we settled on is that a subagent may gather, measure, check and report, and the main conversation decides. Anything where the right answer depends on what the rest of the site already says stays in the window that can see the rest of the site.
Tool restriction is the point, not a side effect
A custom subagent is a short file with frontmatter, and the field that matters most is the tool list. An auditing agent with writes denied cannot accidentally fix what it was asked to find, which means you can run it at full confidence on a repository you care about. A reviewing agent with no network cannot wander. The built-in explorer ships with writes denied for exactly this reason.
The second field worth setting is the model. Searching, listing and counting do not need your most capable model, and routing those to a cheaper one is the documented way to control what a parallel session costs. Keep the strong model for the window that decides.
The handoff is the whole risk
A subagent knows only what is in its prompt and you see only what it chooses to report. Both ends of that lose detail, and neither of you can tell what the other missed. That is the real cost, and it shows up as a confident summary of work that was not done the way you assumed.
Two habits contain it. Write the brief as if to a competent colleague who has never seen the repository, naming the files and stating what you have already ruled out. And ask for numbers rather than adjectives: a count, a list of paths, a pass or fail per item. A report you can check is a report you do not have to trust, which is the same discipline the verification piece argues for in the main session.
Parallel is not free
Each subagent sends its own requests against the same usage limits as your main conversation, so five at once is five times the spend in a burst. That is fine when the work is genuinely independent and wasteful when it is not. The test is whether you would still want the second agent's answer if the first one came back clean. If not, run them in sequence.
How we split a 210-page site
This site has 210 location pages, and the only parts of that work that were delegated were measurement: finding which pages shared an angle, computing similarity between every pair, listing which ones had no incoming links. All of it returned numbers. The writing, the angle assignments and the decisions about which collisions mattered stayed in one window, because every one of those depended on what the other 209 pages already said. That split is the whole method, and the build guide covers the rest of it. If you would rather hand the whole thing over, that is what we do.
Two notes on scope before you build this out. Subagents work within a single session, and the documentation separates them from the other arrangements that look similar: background agents for many independent sessions watched from one place, and agent teams for a supervised group. Picking the wrong one of those three is the most common way this gets expensive. And the instructions a delegated agent starts with are your project's, which makes the CLAUDE.md piece the cheapest lever on delegated quality.
