Claude Code: Subagents vs Agent Teams - Complete Practical Guide

Claude Code allows developers to build structured AI coding workflows instead of using a sinlge prompt(NLP)-response system. Two important patterns in Claude Code are SubAgents and Agent Teams.

Both help manage complex development tasks, but they are designed for different levels of structure and scale.

"Subagents are defined within a project to handle specialized responsibilities, while Agent Teams (experimental) support coordinated multi-agent workflows for more complex development tasks".

Subagents

A Subagent in Claude Code is a role-based assistant defined inside your project. It is created manually by adding markdown files in specific directory.

~/.claude/agents/

Each file inside this folder defines one subagent.

For example:

.claude/agents/schema.md
.claude/agents/backend.md
.claude/agents/tester.md

Each files describes:

The agent’s role
Its responsibilities
Allowed tools
Restrictions
Working directory limits

Example Structure of a Backend Subagent .md File

# Backend Agent

You are a senior backend engineer responsible for server-side development.

## Role

Design, implement, and maintain backend systems that are scalable, secure, and production-ready.

## Responsibilities

- Build and modify REST or GraphQL APIs
- Implement business logic
- Handle authentication and authorization
- Integrate with databases and external services
- Optimize performance and error handling
- Maintain clean architecture and modular structure

## Allowed Tools

- Read files
- Write files
- Modify existing backend code
- Run tests
- Execute safe build commands

## Working Directory

- Only work inside `/server`, `/api`, or backend-related folders.
- You may update environment example files but not production secrets.

## Restrictions

- Do not modify frontend/UI files.
- Do not change deployment configurations unless explicitly instructed.
- Do not delete files without clear justification.
- Avoid destructive terminal commands.

## Code Standards

- Follow clean architecture principles.
- Write modular and maintainable code.
- Add meaningful comments when necessary.
- Ensure proper error handling.
- Return production-ready, well-structured code.

Always verify changes for correctness before finalizing your response.

When Claude Code runs, the main agent reads the .claude/agents/ folder and delegates tasks to the appropriate subagent based on the instructions.

Work Flow Architecture

		     User Request
                         │
                         ▼
                Main Claude Agent
                         │
          Spawn      Spawn      Spawn
          Subagent   Subagent   Subagent
             │           │           │
             ▼           ▼           ▼
        Schema Agent  Backend Agent  Tester Agent
             │           │           │
            Work        Work        Work
             │           │           │
             ▼           ▼           ▼
           Result       Result      Result
              └───────────┼───────────┘
                          │
                          ▼
                  Integrated Result
                          │
                          ▼
                     Final Output

Agent Teams

Agent Teams is an experimental feature in Claude Code.

Subagents are short-lived, task-focused helpers that handle specific technical tasks. In contrast, Agent Teams are ongoing, role-based agents that work together as a coordinated multi-agent system (MAS), solving complex problems through parallel work and collaboration between agents.

To enable Agent Teams, you must create and edit:.

~/.claude/settings.json

Add the following setting:

{
  "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
}

Once enabled, Claude uses a structured team-based approach instead of simple delegation.

Operation: Start a session and ask the lead agent to set up a team. For example, you can say, “Create an agent team to build a web application — one agent focused on UI/UX design and another focused backend architecture.”

Interaction: The team works using a shared task list and an internal messaging system. This allows agents to exchange messages, update progress, and coordinate their work efficiently.

Management: Press Ctrl + T (or Cmd + T on Mac) to open the shared task list. Use Shift + arrow keys to switch between different agent views.

Work Flow Architecture

		     User Request
                         │
                         ▼
                      Team Lead
                         │
                    Assign Tasks
                         │
             ───────────────────────────
             │            │            │
             ▼            ▼            ▼
        Backend Agent  Frontend Agent  QA Agent
             │      <──────────────>   │
             │        Communicate      │
             │      <──────────────>   │
             │            │            │
            Work         Work         Work
             │            │            │
             └────────────┼────────────┘
                          │
                          ▼
                      Integration
                          │
                          ▼
                     Final Output

Major Differences

1. Setup Location

Subagents: .claude/agents/ Agent Teams: ~/.claude/settings.json

2. Activation

Subagents: Automatic when defined Agent Teams: Requires experimental flag

3. Scope

Subagents: Project-level Agent Teams: Global-level

4. Structure

Subagents: Task-based delegation Agent Teams: Coordinated multi-agent system (MAS)

5. Complexity

Subagents: Moderate Agent Teams: High

6. Tokens & Cost

Subagents: Medium Agent Teams: Higher

7. Time Consumption

Subagents: Faster Agent Teams: Higher

8. Best For

Subagents: Small to medium tasks Agent Teams: Large, structured systems

When/Where to Use Each

Subagents

Refactoring code
Writing APIs
Generating tests
Working on modular features
Managing small to mid-size projects

Agent Teams

Building full-stack systems
Managing enterprise codebases
Running multi-step production workflows
Needing strict role separation
Collaborative development across multiple modules

Conclusion

Subagents and Agent Teams both enhance how Claude Code manages complex development tasks.

Subagents are lightweight, project-based, and cost-efficient. They are ideal for focused development and medium-scale projects.

Agent Teams introduce a coordinated, structured multi-agent system. They are more powerful but consume more tokens and require more setup. They are best suited for large, complex systems where role separation and structured collaboration are important.

Choosing between them depends on your project size, complexity, token and budget.

The right architecture ensures better performance, lower cost, and cleaner development workflows.