How to Split Tasks, Control Permissions, and Collect Evidence with Claude Code Agent Teams

Overview

Claude Code now bundles Subagents, Agent View, and Agent Teams in a single interface, making a typical development workflow—coding, reviewing, testing, PR, documentation—appear splittable across dedicated agents: one for backend, one for frontend, one for tests, one for security review, and one for documentation.

Three Parallel Capabilities

Subagents isolate noisy context (search, review, verification) into independent windows so the main session only receives conclusions and evidence.

Agent View manages independent backend tasks; each teammate runs a separate session, and the human only checks status, peeks, or attaches results.

Agent Teams adds a collaboration layer with a lead, teammates, a shared task list, and direct communication, suitable for cross‑layer work that requires shared state and dependency coordination.

When to Use Which Tool

Read‑only research, security checks, or call‑graph exploration → Subagent.

Several independent small tasks (e.g., flaky‑test detection, PR comment extraction, documentation updates) → Agent View.

Multiple sessions that must modify code, share state, and coordinate dependencies (backend API change, frontend update, test adjustment, security review) → Agent Teams.

When code changes span multiple files, consider Worktrees for file‑level isolation before promoting to a team.

Enabling Agent Teams

Agent Teams is experimental and disabled by default. Enable it with an environment variable or in settings.json: export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 The team consists of:

lead: split, assign, aggregate
teammates: execute and communicate
task list: record tasks, dependencies, status
permissions: restrict what actions can be taken
work surface: constrain files or modules each member may touch
review gates: final evidence used to judge completion

Four Engineering Questions Before Parallelising

Can the file boundaries be cleanly separated? Overlapping edits (e.g., auth.ts) increase merge cost.

Is the information flow one‑way or bidirectional? Simple audits need only Subagents; full feature changes need a team.

What constitutes acceptance evidence? Diff, test results, logs, screenshots, risk lists must be collected in a single place.

How are permissions and budget controlled? Explicit allow/deny rules (e.g., allow src/**, deny .env, git push, npm publish) and token budget ( --max-budget-usd) are required.

Checklist Before Launching an Agent Team

Goal : Define a single deliverable.

File boundaries : List which files each teammate may modify.

Dependency order : Identify which tasks must wait for others.

Permission boundaries : Specify allowed read/write paths and prohibited actions.

Budget boundaries : Set limits on team size, model choice, and token rounds.

Evidence : Decide which artifacts (diff, test output, logs) prove completion.

Stop conditions : Define when to pause if scope creep or permission errors occur.

Sample Team Prompt

GOAL
Implement a minimal user‑login flow (email/password only).

SCOPE
- backend: src/auth/routes.ts, src/auth/service.ts
- frontend: src/pages/login.tsx, src/components/LoginForm.tsx
- tests: tests/auth/login.test.ts, tests/e2e/login.spec.ts

WORKSTREAMS
1. backend‑teammate: implement API and validation, no frontend changes.
2. frontend‑teammate: build login form and error display, no backend changes.
3. test‑teammate: read backend/frontend contracts, add tests after they stabilise.
4. review‑teammate: read‑only audit of credential handling, input validation, test gaps.

DEPENDENCIES
- frontend depends on backend contract.
- tests depend on final backend and frontend.
- review runs in parallel but must re‑run after implementation.

PERMISSIONS
- allow read of repository, write files in the listed scopes, run local tests.
- deny read of .env, deny git push, deny npm publish, deny destructive deletes.

REVIEW GATES
- provide final diff summary.
- provide test results.
- list uncovered risks.
- lead aggregates only after all teammates finish.

STOP
If a teammate needs to modify files outside its scope, pause and explain why.

This prompt forces the team to narrow the goal, split file ownership, expose dependencies, declare permissions, gather evidence, and define stop conditions.

Conservative Roll‑out Strategy

Start with a single session for simple tasks.

Introduce Subagents for isolated research or read‑only checks.

Use Agent View when tasks are independent but benefit from background sessions.

Only adopt Agent Teams when tasks truly require shared state, dependency coordination, and member communication.

Parallelism does not eliminate review; it merely moves the bottleneck from generation to verification. Mis‑splitting tasks creates hidden coordination costs that outweigh token savings.

Conclusion

Claude Code Agent Teams provides a structured way to decompose engineering work into clear, isolated work surfaces, enforce permission and budget limits, and collect unified evidence. The real challenge lies in designing the collaboration structure—not in merely turning on a flag.

References

Claude Code Agent Teams documentation

Claude Code parallel agents overview

Claude Code Agent View

Claude Code Subagents

Claude Code Worktrees

Claude Code Environment Variables

Claude Code CLI Reference

Claude Code Permissions

Effective Strategies for Asynchronous Software Engineering Agents (arXiv)

Dive into Claude Code (arXiv)

Simon Willison: Embracing the parallel coding agent lifestyle

Simon Willison: Agentic Engineering Patterns

Addy Osmani: Orchestrating Coding Agents (CodeCon 2026)

Kaxil Naik X long post

Daniel San X post