Your team has one repository and a growing list of repeated chores: reviewing pull requests against the same checklist, writing tests for new modules, and scanning diffs for security issues. One developer has a handy subagent on their laptop, another has a slightly different version, and nobody knows which one reflects the team's standards. The result is inconsistent output and prompts that live in private notes.
This guide goes beyond a quick answer by walking through the setup in order, so a team can reproduce it rather than each person improvising. It covers:
- how to decide which tasks deserve their own subagent
- how to write clear role definitions and limit what each one can do
- how to share configurations so everyone works from the same version
- how to review and adjust subagents as the team's needs change
What users report
Users in the r/ClaudeCode community describe two overlapping setups: plain subagents that the main session delegates to, and the experimental agent teams feature. Most agree that subagents are the easier starting point, and that teams add control at the cost of setup friction.
What works
- Delegation can be as simple as asking. One user says you can ask Claude to delegate to parallel subagents, and that this keeps the main agent's context window cleaner because each subagent uses its own context.
- Planning prompts benefit from subagents. Another user suggests telling Claude to use a subagent, and optionally to use Haiku, for a concise planning answer. To the person that recommended using sub shows that thread.
- One user finds agent teams neat for large tasks, and notes that unlike subagents you can message teammates midway or stop them to correct course.
What goes wrong
- Token use rises. A user warns that parallel subagents burn through tokens faster, partly because they sometimes need overlapping context.
- Agent teams need an opt-in. Users enabled them by setting an environment flag in settings.json, and Introducing agent teams (research preview) includes replies from people who could not get it working.
- Nesting is limited. A user reports that team agents currently cannot spawn their own subagents.
Tips shared
- Update Claude Code first, add
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMSset to1underenvin~/.claude/settings.json, then restart the terminal, as laid out in How to Set Up Claude Code Agent. - Ask explicitly for a team in your prompt, and launch with
claude --teammate-mode tmuxto see panes per teammate. - Think of the main session as an orchestrator and subagents as individual roles on an engineering team, as forum users put it.
What Are Claude Code Subagents?
Subagents in Claude Code are specialized assistants that the main Claude Code session can hand tasks to. Each one has its own instructions, its own context window, and a defined set of tools, so it can focus on one kind of job without cluttering the main conversation.
They are typically defined as Markdown files with a short configuration header, which means a team can keep them in a repository and version them like any other project file. That is what makes claude code subagents practical for shared workflows rather than just personal experiments.
Why teams use them
A team usually wants consistent behavior, not a different setup on every laptop. Subagents let you write down how a recurring task should be handled once, then reuse it across people and projects.
Common roles include:
- Code reviewer: checks changes against your team's standards.
- Test writer: drafts and runs tests for new code.
- Debugger: investigates failures and proposes fixes.
- Researcher: explores unfamiliar parts of a codebase and reports back a summary.
Benefits for project execution
- Cleaner context: detailed work happens in the subagent's own context, so the main session stays focused on the larger goal.
- Consistency: shared definitions mean reviews, tests, and debugging follow the same approach.
- Tighter permissions: each subagent can be limited to the tools it needs, which reduces the chance of unintended actions.
- Division of labor: separate tasks can be delegated instead of handled in one long, crowded thread.
The sections below cover how to define these subagents and share them across a team.
How do you set up subagents in Claude Code?
A subagent is a Markdown file with a short YAML header. There is no account dashboard or setup screen: you create the file in your project, and Claude Code picks it up.
Step-by-step setup
- Open Claude Code in your repository and run
/agents. Choose to create a new agent, and pick Project scope so the file is saved in.claude/agents/inside the repo. User-scope agents live in~/.claude/agents/and only apply to you. - Describe the role. You can let Claude draft the agent from a description, or write it yourself. Give it one job, such as reviewing pull requests or writing tests.
- Limit its tools. The
toolsfield lists what the agent may use. A reviewer usually needs read and search tools only; leave out write and shell access unless the job needs them. - Write a precise
description. Claude uses it to decide when to hand a task to the subagent, so say when to use it, for example "Use after any change to files in src/api/". - Try it. Ask for a task the agent should handle, or name it directly ("use the test-writer agent to..."), and check that Claude delegates to it.
- Commit
.claude/agents/. Everyone who clones the repo gets the same subagents, and changes go through normal code review.
What a subagent file looks like
---
name: code-reviewer
description: Reviews changed code for bugs and security issues. Use after any code change.
tools: Read, Grep, Glob
model: sonnet
---
You are a senior reviewer. Read the diff, list problems by severity
with file and line, and suggest the smallest fix for each.Common pitfalls to avoid
- Overlapping descriptions: two agents that both claim "code quality" compete, and Claude picks the wrong one. Give each a distinct trigger.
- Too many tools: broad permissions make an agent harder to trust and review.
- Private copies: agents saved only in a teammate's home folder are invisible to everyone else. Keep shared agents in the repository.
If you would rather not start from a blank file, the Subagent Generator drafts a file in this format that you can paste into .claude/agents/.
How Do I Set Up Multi-Agent Teams in Claude Code?
Create a set of subagents, each with one narrow job, then let the main Claude Code session delegate work to them. Each subagent is defined as a Markdown file with a name, a description and a system prompt, stored in a project folder so the whole team shares the same definitions.
Create the team
Start with the /agents command inside Claude Code, which lets you create and edit subagents interactively. You can also write the files by hand in a .claude/agents/ directory in your repository. Committing that folder to version control means every developer works with the same team of claude code agents.
Keep the first team small. Two to four agents is easier to reason about than a dozen overlapping ones.
Assign roles and responsibilities
Give each agent a single responsibility and write the description so the main session knows when to call it. Limit the tools each agent can use to what its role needs.
| Role | Responsibility | Suggested tool access |
|---|---|---|
| Code reviewer | Check diffs for bugs and style | Read-only |
| Test writer | Add and run tests | Read, edit, shell |
| Researcher | Explore the codebase and summarize | Read-only |
| Refactorer | Make scoped code changes | Read, edit |
Read-only roles reduce the risk of unwanted edits, and clear boundaries prevent two agents from changing the same files.
Manage team dynamics
A few habits keep a multi-agent setup predictable:
- Let the main session coordinate. It decides which agent handles each task and combines the results.
- Write precise descriptions. Vague ones lead to the wrong agent being chosen or none at all.
- Pass context explicitly. Subagents work in their own context, so include the files, goals and constraints they need in the task.
- Chain agents deliberately. For example, have a researcher summarize first, then hand that summary to a refactorer.
- Review and refine. If an agent drifts from its role, tighten its prompt rather than adding another agent.
Treat the agent files like code: review changes to them and update them as your workflow evolves.
How Does Claude Code Handle Subagents?
Claude Code handles subagents as specialized assistants that take on a specific task, work in their own separate context, and return a result to the main session. The main session delegates the work, so its own conversation stays focused on the larger goal.
This matters for teams because each subagent can be given a narrow role and its own instructions, which keeps behavior predictable and repeatable.
Overview of subagent management
Subagents are typically defined as configuration files that describe the agent's purpose, its instructions, and the tools it may use. Because these definitions are plain files, they can be stored alongside a project and shared through version control like any other team resource.
Management usually comes down to a few decisions:
- Scope: which tasks the subagent should take, and which it should leave alone.
- Instructions: a clear description so the main session knows when to delegate.
- Tool access: limiting each subagent to the tools its role requires.
- Ownership: agreeing who reviews and updates shared definitions.
Integration with Claude Code features
Subagents work inside the same environment as the rest of Claude Code, so they operate on the same codebase and follow the project's conventions. Restricting tool permissions per subagent lets a team separate read-only roles, such as review, from roles that edit files.
Since each subagent uses a separate context, long investigations do not crowd the main conversation. Only the summary comes back.
Examples of effective subagent use
Subagents tend to work best on well-bounded, repeatable jobs:
| Use case | Why it fits |
|---|---|
| Code review | A read-only role with a consistent checklist |
| Test writing | A focused task with clear success criteria |
| Codebase research | Heavy file reading kept out of the main context |
| Debugging | Isolated investigation that reports back findings |
Broad, ambiguous tasks are a weaker fit. Teams generally get more reliable results by starting with one or two narrow subagents and refining their instructions over time.
Best Practices for Using Claude Code Subagents
To optimize the use of Claude Code subagents, it's crucial to implement effective communication strategies within teams. Regular updates and feedback loops can help ensure that all team members are aligned on goals and expectations. Utilizing collaborative tools can facilitate discussions and streamline information sharing, making it easier to coordinate efforts across different subagents.
Monitoring and evaluating subagent performance is another essential practice. Establish clear metrics to assess how well each subagent is meeting its objectives. Regular performance reviews can help identify areas for improvement, and adapting strategies based on these evaluations can enhance overall productivity. Consider using analytics tools to gather data on subagent interactions and outcomes, allowing for informed decision-making.
Iterating on subagent roles is also vital for maintaining efficiency. As projects evolve, the needs of the team may change, necessitating adjustments to subagent responsibilities. Regularly reassess each subagent's role to ensure it aligns with current project goals. This flexibility can lead to the best Claude Code subagents being utilized effectively, maximizing their impact on team performance.
By focusing on these best practices, teams can enhance their collaboration and ensure that Claude Code subagents contribute effectively to achieving their objectives.
How Agentsforce Can Help You Set Up Claude Code Subagents
Agentsforce gives you a ready-made team of specialists for Claude Code, so you don't have to write each subagent's role and instructions from scratch. It is one way to shortcut the setup work described above, especially if your team needs several roles at once.
Agentsforce: Claude Code, fully staffed provides specialists including developers, marketers, and experts in WordPress and Shopify. The aim is to streamline project execution by giving each kind of task a dedicated specialist.
What this means for a team setup
- Less configuration work: specialists already exist for common roles, so you can skip drafting every role definition yourself.
- Clear division of labor: developer, marketing, WordPress, and Shopify tasks each map to a specialist.
- Shared starting point: everyone on the team can work from the same set of specialists instead of building personal variations.
Integration with Claude Code
Agentsforce requires no new app and no new habits. It integrates with Claude Code, so your team keeps working in the environment it already uses.
Cost
Access is a one-time payment of $49 for lifetime access to all specialists and updates. That removes recurring subscription math when you are budgeting for a team.
If you prefer full control, the manual setup steps earlier in this article still apply. A pre-built set of specialists simply gives you a faster starting point, which you can then adapt to your own workflows and conventions.
Related articles
Frequently asked questions
How do I create a subagent in Claude Code?
Run /agents inside Claude Code and choose to create a new agent, or add a Markdown file with a YAML header (name, description, tools, optional model) to .claude/agents/ yourself. Start with a narrow job such as code review or test writing, and write the description so Claude knows when to use it.
What is the difference between agent teams and subagents in Claude Code?
Subagents are helpers that one Claude Code session delegates to: each runs in its own context and reports back to the main session. Agent teams, a research preview, run several Claude Code sessions that coordinate with each other. Most teams should start with subagents, which are stable and easy to share through the repository.
Can Claude Code automatically create subagents?
Claude Code can write a subagent for you: in /agents, describe the role and let Claude generate the file, then review and edit it. It does not add subagents to your project on its own, so you decide which ones exist and commit them deliberately.