How to Actually Use Claude Code Sub-Agents: Research, Not Implementation

The mistake everyone makes with Claude Code sub-agents is treating them as workers. They are not workers. They are researchers, and the moment you ask one to write final code, the entire system begins to break down in ways that are extremely difficult to diagnose after the fact.

After more than 20 hours testing sub-agent patterns across a ChatGPT clone build using shadcn UI and the Vercel AI SDK, one architecture produced high-fidelity results in a single implementation pass. Every other pattern produced stale implementation decisions, context fragmentation, or compaction-driven quality drops that required expensive debugging. The pattern that worked is built around one central insight: sub-agents exist for context management, not labor distribution. Here is how to build it.

Map the Research Domains Before You Create a Single Agent

The most common sub-agent architecture mistake is creating agents based on task type: one agent for backend code, one for frontend components, one for tests. This mirrors how a team lead might divide work among human developers. It is exactly wrong for sub-agents.

Sub-agents should be divided by knowledge domain, specifically by the external services, libraries, and APIs whose current documentation and recent breaking changes they need to understand. In a project that uses a UI component library, a streaming AI SDK, an authentication service, and a database ORM, those are four distinct knowledge domains. Each has its own versioning history, its own changelog, and its own set of recent decisions that differ from what a general-purpose AI model's training data would suggest.

Before creating any agent, write out every external dependency the project integrates with. For each one, ask: what do I need to understand about the current state of this integration in order to implement it without discovering errors mid-build? That list of questions defines the knowledge domain for each sub-agent.

A ChatGPT clone build requires knowledge about the current shadcn UI component API (which changes between major versions), the Vercel AI SDK streaming interface (which had significant breaking changes between v2 and v3), the authentication provider's current session management approach, and the deployment environment's environment variable handling. Four distinct domains, four research sub-agents, each responsible for understanding only its own area. This mapping happens before any agent session opens.

Define the Output Contract: What Each Researcher Must Return

Before any sub-agent session begins, decide exactly what it will return. This is the output contract, and it matters more than the agent's instructions. A sub-agent without a defined output contract returns whatever it judges to be useful, which creates synthesis problems for the parent agent who must integrate across multiple sub-agent outputs.

The output contract for a research-only sub-agent is a structured summary of 300 to 500 words, covering four things: the current version of the library or service being researched; the specific implementation pattern required for this project's use case; any breaking changes from previous versions that might cause errors if the parent agent uses outdated patterns; and any non-obvious issues that appear in recent issues, release notes, or community documentation but not in the main API reference.

The contract must explicitly exclude implementation. The sub-agent does not write the component. It does not write the integration code. It writes a summary that the parent agent will use to write the code. This boundary is not bureaucratic caution. It exists because any code a sub-agent writes lives only in that sub-agent's session context. When bugs appear during the parent agent's implementation pass, the parent has no visibility into the decisions the sub-agent made. The sub-agent's reasoning is gone. The parent is left debugging code it did not architect, with no record of why the implementation choices were made.

Keeping sub-agents as pure researchers means the parent agent is always Madhuranjan Kumar of every line of final code. It can reason about every implementation decision because it made every implementation decision.

Build the Shared Context File Before You Open Any Agent Session

The shared context file is the memory layer that makes the entire architecture function. It is a markdown file, stored in the repository, that every agent reads at the start of its session and updates at the end of its session.

Before any sub-agent runs, the parent agent creates this file with the initial state of the build: the project goal stated in one or two sentences, the architecture decisions already made (which libraries, which patterns, which constraints apply), the current build state (what exists, what is broken, what has not been started), and the open questions that sub-agent research will need to resolve.

When a sub-agent finishes its research session, it appends its findings to the shared context file under a labeled section. The next sub-agent that opens reads the entire file before starting its own session. This matters because integration decisions in one domain often affect decisions in another. If the authentication sub-agent discovers that the current version of the auth library handles session tokens differently than the documentation examples suggest, the streaming SDK sub-agent needs to know that before it decides how to pass session credentials to the streaming endpoint. The shared context file is how that information travels between sessions.

The shared context file also eliminates the need to copy-paste sub-agent outputs into subsequent agent conversations. The information is available on disk, accessible to any agent that reads the file, without the context cost of pasting long outputs into the conversation history.

Load Each Sub-Agent with Current Documentation, Not What You Assume the Model Already Knows

The largest source of silent implementation failure in AI-assisted builds is outdated knowledge. The model's training data has a cutoff. Libraries release breaking changes after that cutoff. The model confidently generates code against a previous API because that is what it learned, and the code either fails immediately or produces subtle runtime errors that are difficult to trace to a version mismatch.

The solution is loading each sub-agent with the current documentation before it begins its research session. This means fetching the actual current docs for the specific version of the library you are using, not asking the model what it knows about the library. For a sub-agent researching the Vercel AI SDK, this means pulling the current changelog, the current API reference for the specific methods used in this project, and the migration guide from the previous major version to the current one.

This step adds five to ten minutes per sub-agent session. It prevents entire categories of debugging that can consume hours. The tradeoff is obvious once you have spent an afternoon tracing a runtime error to a method that was renamed in a release three months after the model's training cutoff.

A practical workflow for each sub-agent session: before opening the agent, use a browser or fetch tool to pull the current documentation pages for the target library. Paste the relevant sections into the sub-agent's opening message. Instruct the sub-agent to explicitly note any patterns in the current documentation that differ from patterns it would have used based on its training data alone. That instruction surfaces the version delta explicitly rather than letting the model silently blend old and new patterns in its summary.

Run the First Build and Know Which Signs Indicate the Pattern Is Working

The first build using this architecture will feel slower than simply asking one agent to build everything. The research phase, with its sequential sub-agent sessions and their output files, takes time. The payoff is in the implementation phase, which the parent agent handles alone with current, structured, synthesized information across all integration points.

Signs the pattern is working correctly: the parent agent references the shared context file early in the implementation session, uses library versions and method names that match the current documentation rather than older training data, asks clarifying questions about the build state rather than assuming it knows what already exists, and produces code that passes integration points without immediate runtime errors caused by version mismatches.

Signs the pattern is breaking down: the parent agent starts writing large blocks of code without citing information from the shared context file, begins producing implementation code that was supposed to come from a research summary (meaning the research-to-execution boundary has blurred), or opens the implementation session without referencing what the sub-agent summaries found about the specific libraries involved.

The parent agent's role during implementation is to read, synthesize, and build. It should actively reference the sub-agent summaries throughout the session, not only at the start. When it reaches a decision point about how two services interact, it should re-read the summaries from both relevant sub-agents before choosing the approach. The summaries are living reference material, not a one-time input.

The On-Demand Retrieval Pattern That Keeps Heavy Sources Out of the Main Thread

Not every reference the parent agent might need during implementation should live in the shared context file. The file contains the current build state and the synthesized key findings from each sub-agent. Full API reference pages, complete migration guides, and detailed implementation examples are too heavy to include in a file that every agent reads at the start of each session.

The on-demand retrieval pattern handles this. The shared context file includes a pointers section that lists where heavy reference material was saved, organized by domain (specific file paths in the repository or sub-folders created during the research phase). When the parent agent needs to look up the full shadcn Dialog component API during implementation, it fetches that specific file on demand rather than having the full reference loaded at the start of the session.

This keeps the parent agent's active context focused on the current implementation task. Heavy documentation enters the context window only when it is directly relevant to the decision being made in the next few minutes, not as background material competing for context with the actual code being written. The result is a tighter, more focused implementation session with less context dilution from reference material that may not be needed for another hour.

How This Maps to Real Professional Work, with Illustrative Numbers

Consider an accounting firm building a client portal: secure document upload, AI-assisted review of uploaded financial statements, and a commenting and approval workflow for the firm's reviewers. The build integrates four distinct knowledge domains: the file storage service's current authentication and upload endpoint behavior, the AI processing SDK's current streaming and structured output approach, the database ORM's current transaction and query patterns, and the authentication provider's current session and permission handling.

Without the sub-agent research architecture, the build proceeds with the parent agent making implementation decisions about each integration based on its training data alone. Some of those decisions reflect the current state of the library. Some reflect a version from 6 to 12 months prior. The errors surface during testing, and tracing them requires understanding which patterns the agent used and why, which is difficult because the reasoning was in-context and is no longer accessible.

A senior developer who has worked with this class of multi-integration build estimates 35 hours to complete, with 8 to 10 of those hours likely spent on integration errors stemming from version mismatches and assumption-based implementation decisions.

With the sub-agent research architecture, four research sessions run sequentially. Each session loads current documentation for one domain and produces a 400-word summary covering the current implementation patterns, known issues with the version in use, and version-specific notes. Total research time: approximately 2 hours. The parent agent then enters the implementation session with a shared context file containing structured, current, synthesized information across all four domains and produces the build in approximately 18 hours, with under 2 hours spent on integration debugging. Total time: roughly 20 hours, a reduction of 43 percent.

The reduction does not come from building faster. It comes from eliminating the specific category of time waste that occurs when implementation decisions are based on incorrect information about the current state of a library. The sub-agent architecture front-loads the cost of getting the information right, and eliminates the much larger back-end cost of discovering mid-build that the information was wrong after the code was already written.

This is the same split that defines professional services work at its best: researchers do the knowledge work, and the senior practitioner does the synthesis and execution. The architecture maps to a pattern that has always produced better results than asking one person to simultaneously find the information and make the decisions.