Start With One Owner
A coding agent is a chat model connected to tools. Instead of only answering, it can read files, edit them, run tests, inspect command output, and revise its work. A sub-agent is a separate agent run for a narrower task, often with its own context window and instructions. That separation is useful, but it also creates the main risk: several agents can produce several confident, incompatible answers.
Treat the main agent as the owner of the job. It should write the objective, constraints, files in scope, acceptance checks, and decision rules before any sub-agent starts. For example: "Main agent owns the final patch. Sub-agents may research options, review risks, or implement isolated drafts. Do not merge anything until the main agent compares outputs and runs verification." This keeps parallel work from turning into parallel authority.
Split Only Independent Work
Once ownership is clear, split tasks by independence. Good sub-agent jobs have low overlap and clear outputs: inspect one folder, compare two libraries, migrate one section of a docs wiki, review a proposed API, or search for test gaps. Poor sub-agent jobs all touch the same files, depend on each other's choices, or require product taste that cannot be checked mechanically.
Context is the information an agent can currently see and reason over. Sub-agents help because they avoid crowding one chat with every detail. But they can also miss context the main agent has. Give each sub-agent a small brief: goal, relevant files or folders, constraints, output format, and what not to change. Ask for findings, patches, or a structured summary, not a vague opinion.
A useful pattern is research, review, implementation. One sub-agent investigates the current code or docs. Another challenges the plan and looks for failure modes. A third may draft a narrow implementation. The main agent then chooses, edits, and verifies. If two agents disagree, that is signal, not a vote. The main agent should resolve the disagreement against the project constraints and tests.
Use Shared Instructions, Not Shared Assumptions
Sub-agents get messy when each one invents its own map of the project. Give them a shared source of truth. In code, that may be an implementation spec, architecture notes, test commands, and contribution rules. In a knowledge base, it may be a folder standard with metadata such as document type, title, tags, and relationship fields. Predictable indexes and small documents let agents load only the next relevant piece instead of dragging the whole project into context.
This is where MCP fits. MCP, the Model Context Protocol, is a way to expose external tools and data sources to agents through a standard interface. Think repo tools, issue trackers, docs stores, browsers, databases, or internal knowledge bundles. The point is not to add every possible tool. The point is to give agents reliable ways to fetch the right context and take bounded actions.
For a first workflow, keep the shared instructions boring. Create a short spec before work starts. Include the user goal, non-goals, files in scope, commands to run, and validation criteria. If a task has high stakes, mark a human validation zone: payment logic, data deletion, security-sensitive code, production migrations. Agents can prepare evidence there, but a person makes the final call.
Verify Like a Loop
An agent works by a loop: reason about the task, act with a tool, observe the result, then adapt. Sub-agents should fit inside that loop, not replace it. The main agent launches them, observes their outputs, updates the plan, and runs the final checks. If validation fails, it can send a narrow retry: "Fix only the failing test in this file" or "Re-check this assumption against the actual schema."
Verification should be layered. Start with cheap checks: lint, typecheck, unit tests, doc build, grep for expected references. Then add targeted review: does the changed code match the spec, did the docs preserve required metadata, did any sub-agent edit outside scope? For subjective work, such as naming, UI taste, or architectural direction, use sub-agents as reviewers rather than autopilots. Ask them to argue against the plan before code is written.
The common failure mode is accepting the most polished sub-agent output. Do not. Sub-agents can be anchored by incomplete context, overfit to their brief, or produce changes that look clean but break a hidden constraint. The main agent's final job is integration: compare claims to files, reconcile conflicts, run commands, and summarize what changed and what remains risky.
Keep the Harness Clean
Your harness is everything around the model: repository structure, docs, tests, scripts, prompts, local rules, and available tools. A clean harness makes sub-agents useful because each task has obvious boundaries and obvious checks. A messy harness forces agents to guess, which multiplies mistakes when you run several of them at once.
Start small. Ask the main agent to interview you for constraints, write an implementation spec, then launch sub-agents only for independent research or review. After a successful run, turn the pattern into a reusable skill or checklist: when to split work, what prompt template to use, what tests must pass, and what gotchas were discovered.
The goal is not to have many agents doing many things. The goal is controlled parallelism. Sub-agents give you more eyes and more attempts, but one main agent must preserve the thread: decide what matters, merge only what fits, and verify the finished work against the original objective.
Key takeaways
- Keep one main agent responsible for the plan, decisions, merge, and verification.
- Give sub-agents narrow, independent tasks with explicit scope and output formats.
- Use shared specs, indexes, and tool access so agents do not invent project context.
- Treat disagreement between sub-agents as evidence for the main agent to resolve, not as a vote.
- Run layered verification before accepting any sub-agent output.
- Use sub-agents for subjective work as reviewers, not autonomous decision-makers.