Agent Teams

Why specialist agents

Agents run off their context window. Every concern you load into a single agent — implementation, UX, testing, security — pulls from the same finite attention budget. In practice, the main Claude loop focuses on making the feature work and forgets everything else. Tests get deferred. UX goes unchecked. Adding more to CLAUDE.md doesn't fix this — it just raises the floor of what gets forgotten.

The fix: break concerns into separate agents with narrow system prompts, each with its own fresh context. The main agent implements the feature, then delegates specialist review to sub-agents. Each specialist returns focused findings. The main agent integrates them.

This works for three reasons: context isolation (the UX agent never sees the SQL query you wrote), deeper grooves (homogeneous context = more depth per concern), and parallelization (UX and test review don't block each other). The cumulative effect: concerns that used to get skipped are now caught in the same feature cycle.

Canonical specialists

• UX agent — flows, affordances, empty/loading/error states, keyboard and touch interactions
• Testing agent — project test patterns, behavior-based tests, edge case coverage
• Security agent — auth on new routes, ownership checks, input sanitization, CORS/CSRF
• Performance agent — N+1 queries, re-renders, bundle-size deltas, missing indexes
• Database agent — migration safety, index coverage, rollback plans, lock behavior

Start with the concerns the main loop currently forgets — usually UX and testing.

Two Claude Code features, one pattern

For independent specialist reviews (UX + testing + security), use stable sub-agents. Agent Teams is for when specialists need to coordinate with each other.

Official docs: Sub-agents · Agent Teams

Defining a sub-agent

Sub-agents live in .claude/agents/*.md. Required fields: name, description. Optional: tools, model, permissionMode, maxTurns, skills, mcpServers.

Example: UX reviewer

---
name: ux-reviewer
description: Reviews UI changes for UX issues — flows, affordances, state coverage. Not code style or implementation quality.
tools: Read, Grep, Glob
---

You are a UX specialist. You only care about how the interface
feels to use, not how it's implemented.

For every changed component or route, check:
- Does the user have a clear next action at every step?
- Is there an empty state, a loading state, and an error state?
- Are interactive elements obviously interactive?
- Are touch targets large enough on mobile?
- Labels on form inputs, keyboard reachability, visible focus states.

Output findings as: severity (blocker|concern|nit), file, line, what's
wrong, suggested fix.

Example: Testing reviewer

---
name: test-reviewer
description: Reviews test coverage and alignment with project testing conventions.
tools: Read, Grep, Glob, Bash
---

You are a testing specialist. Read existing tests near the changed
files as reference patterns before you begin.

For every behavioral change in the diff, verify:
- Is there a test that would fail if this change were reverted?
- Are edge cases covered: null, empty, boundary, error paths?
- Does the test name describe the guarantee, not the function?
- Would this test actually catch a regression?

Output findings as: severity (blocker|concern|nit), file, line, what's
missing, concrete test to add.

Lightweight alternatives

Not every project wants durable sub-agent files. Two lighter-weight paths:

Ephemeral sub-agents via --agents JSON — session-scoped, not saved to disk:

claude --agents '{
  "ux-reviewer": {
    "description": "Review UI diffs for UX issues",
    "prompt": "You are a UX specialist. Check flows, states, affordances...",
    "tools": ["Read", "Grep", "Glob"]
  }
}'

In-session prompting — the zero-infrastructure fallback. Prompt the main agent: "Review the diff as if you were a UX specialist. Ignore code quality; only look at flows, states, affordances, and accessibility." This shares the main agent's context window (no isolation benefit), but captures most of the "different perspective" value for small features. Use it to discover which specialists are worth making durable.

Orchestration

1. Main agent implements the feature and runs local checks
2. Main agent delegates to UX and test reviewers in parallel
3. Specialists return structured findings
4. Main agent addresses findings in one focused pass
5. Main agent opens the PR

The review step adds minutes, not hours. The things that used to bounce back in code review are already caught.

When to use

• Features that touch UI + data + infrastructure — multiple specialist concerns
• Recurring concerns the main loop keeps forgetting
• Context-heavy codebases where loading all conventions into one agent would blow the budget
• Research or debugging with competing hypotheses (Agent Teams feature)