← Back to Guides · CLAUDE CODE
Claude Code Agent Teams vs. Subagents: What Actually Changed in 2026
Short answer: "subagents" and "Agent Teams" are two different things that search results keep flattening into one. A subagent is Claude Code's delegation mechanism — a single-responsibility worker with its own context window and a scoped tool list, invoked via the Task tool, used for one bounded job like "review this diff" or "find where auth is handled." Agent Teams are a parallel multi-agent workflow — several agents (subagents or full sessions) working the same codebase at once, usually in separate git worktrees, coordinated toward one feature or migration. You can run a team built entirely out of subagents, which is exactly why the two terms blur together in roundup posts that treat them as synonyms. They aren't — one is a unit, the other is an arrangement of units.
Why the confusion exists
Several 2026 roundups — on tembo.io, eesel.ai, and similar sites — use "subagents" and "Agent Teams" interchangeably, usually because both solve "split a big thing into smaller agent-run pieces" and the authors didn't distinguish the mechanism from the workflow built on top of it. That's a real gap: a founder reading three different blogs gets three different claims about what "team size" even refers to — number of subagent invocations in one Task call, or number of parallel worktree sessions. Those are not the same number, and conflating them leads to the wrong decision (spinning up five parallel sessions for a task one scoped subagent would have handled in a tenth of the tokens).
Subagents: single-responsibility delegation
A subagent is a sub-conversation Claude Code starts via the Task tool, with its own context window, its own system prompt, and (critically) its own restricted tool list. The point isn't parallelism — it's isolation. A code-reviewer subagent that only has read access can't accidentally edit the file it's reviewing. A test-automator subagent scoped to the test directory can't wander into production migration files. You define one in .claude/agents/<name>.md with YAML frontmatter (name, description, tools) and a body that's the system prompt for that role.
When to reach for a subagent:
- The task has a clear, bounded scope — "review this PR," "find all callers of this function," "write tests for this module."
- You want tool restriction as a safety boundary, not just an organizational nicety — a reviewer that literally cannot call
Edit. - The job's output (a report, a diff, a list) gets consumed by the main conversation, which keeps driving.
- Context isolation matters — you don't want a sprawling exploration (reading forty files to answer one question) bloating your main thread's context.
What it costs: a subagent starts cold, with none of your conversation's history — so the delegating prompt has to carry whatever context it needs, written as a self-contained directive rather than "based on what we discussed." Get that wrong and you get a generic, shallow result instead of a targeted one.
Agent Teams: parallel multi-agent development
Agent Teams is the workflow pattern — not a single feature flag — of running multiple agents against the same repo concurrently, each usually in its own git worktree so file edits don't collide, working toward one larger goal: shipping a feature end to end, or migrating a library across a codebase in parallel chunks. A team can be built from subagents dispatched together (several Task calls fired in one message, each scoped narrowly), from independent full Claude Code sessions each with broader autonomy, or from a mix — a planner session that forks off scoped subagent reviewers as it goes.
Team size guidance: more agents is not more throughput once the work has shared dependencies. Two to four agents on genuinely independent slices (separate files, separate services, separate test suites) scales close to linearly. Beyond that, coordination overhead — merge conflicts across worktrees, duplicate edits, one agent's output gating another's start — eats the gain. A team sized for "parallelize everything" usually produces more integration work than it saves; size the team to the number of truly independent slices the task actually has, not to how many agents you're willing to spin up.
When to reach for a team: a feature that decomposes cleanly into independent pieces (frontend + backend + migration, run in parallel worktrees), or a mechanical change that needs to happen identically across many files/services at once. Not for anything with a single shared critical path — that's one agent working linearly, possibly delegating bounded subagent reviews along the way.
Decision table
| Task | Use | Why |
|---|---|---|
| Review a PR or diff for bugs | Subagent (code-reviewer, scoped to read) | Bounded, single output, needs isolation not parallelism |
| Find where a function/pattern is used | Subagent (Explore-type, read-only) | Isolates a big exploration from your main context |
| Ship one feature end-to-end (schema → API → UI → tests) | One agent, delegating bounded subagent reviews along the way | Single shared critical path — parallelizing it just adds merge conflicts |
| Migrate a dependency across 15 independent services | Agent Team, one worktree per service | Independent slices — this is where parallel teams actually pay off |
| Audit security across the whole repo | Subagent per concern (auth, secrets, deps), dispatched together | Scoped tool access per concern, results merge into one report |
| Build and launch a new feature with marketing copy alongside | Agent Team: one engineering-side session, one marketing-side session, same feature | Different skill domains, genuinely independent workstreams |
Where AgenticKit's 34-agent team fits both models
AgenticKit's 34 agents — 22 engineering, 12 marketing — are defined as individual .claude/agents/*.md files with scoped tools, which makes every one of them usable as a subagent: a bounded code-reviewer or security-auditor invocation for a single PR. The same roster is also what a team scales out of when a task actually decomposes — /ship on a full feature routes through tech-lead as the planner, which delegates to backend-architect, api-engineer, and test-automator as needed rather than forking all 34 at once. That's the practical answer to "which model do I use": most day-to-day work is a single agent delegating bounded subagent reviews, and the team pattern is reserved for the genuinely parallel slices — which the engineering org map is built to make legible before you reach for either one. /ship itself is just a .claude/commands/ship.md file naming that pipeline explicitly — see the full command catalog list for the other 11 worth having alongside it. For more on why that roster is split the way it is rather than one generalist agent, see how 34 agents got structured into two workforces.
FAQ
Are Agent Teams a specific Claude Code feature, or just a pattern? It's a workflow pattern built on existing primitives — subagents, the Task tool, and git worktrees for isolation — rather than one dedicated feature with a fixed API. That's part of why descriptions of it vary across blogs: people are describing their own assembly of the same underlying pieces.
Can a subagent spawn its own subagents? In practice, delegation is typically one level deep from the main conversation — a subagent's job is to do bounded work and return a result, not to keep forking further. Treat nested forking as something to avoid by design, not a feature to lean on.
Does a bigger team finish faster? Only if the work is actually independent. If two agents end up editing the same file or waiting on each other's output, you've added worktree-merge overhead without adding real parallelism — check for independent slices before sizing the team up.
Do I need to choose one model for a whole project? No — most real work mixes both. A single session plans and ships a feature, delegating a scoped subagent for the review step, and only switches to a full parallel team when a task genuinely splits into independent chunks (a multi-service migration, a feature with separate frontend/backend/marketing workstreams).
Is this the same as what tools like Cursor call "multi-agent"? Cursor's multi-agent features are a parallel concept but not identical in mechanics — this guide describes Claude Code's subagent/Task-tool model specifically; don't assume a 1:1 mapping if you're moving between the two.
Next steps
If most of your work this week is bounded single-purpose tasks — a review, a search, a test pass — reach for a scoped subagent and skip the worktree overhead entirely. If you've got a task that actually splits into independent slices, size a team to the number of real independent pieces, not to how many agents you're willing to run. Either way, the engineering org map shows which of AgenticKit's 34 agents are built for narrow delegation versus planning a larger piece of work, and the subagent setup audit covers the overlap and over-permissioning mistakes that show up once you've got more than a couple of these running. The 12 marketing roles in that roster — SEO, growth, lifecycle, launch — get the same ranked breakdown in 20 Claude Code Agent Teams for Marketing, SEO, and Growth.
Related Tools & Agents
See which agents actually fire for your task
Type a feature and watch whether Agent Chain routes it to one planner with scoped subagent reviews or a genuinely parallel team.
Open Agent Chain →