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

Overview of Claude Code Parallel Capabilities

Claude Code now groups four parallel abilities—Subagents, Agent View, Agent Teams, and Worktrees—into a single interface. Each offers a distinct collaboration structure rather than a simple hierarchy.

Subagents isolate noisy tasks such as search, review, or verification in separate windows, returning only concise conclusions to the main session.

Agent View runs independent backend sessions for tasks that do not need to communicate, allowing the user to monitor status, peek at progress, and attach results.

Agent Teams adds a collaboration layer with a lead, teammates, a shared task list, and direct communication, suitable for cross‑layer work with dependencies.

Worktrees provide file‑system isolation for each teammate.

Parallelism only works when three conditions are met: isolate what can be isolated, coordinate what must be coordinated, and close the loop with a single set of evidence.

When to Use Each Capability

Read‑only research, audit, or call‑graph lookup : use a Subagent to keep the main session clean.

Several independent small tasks : use Agent View; e.g., checking flaky tests, updating docs, reviewing PR comments.

Multiple sessions that must modify code : start with Worktrees to ensure each work surface can build, test, and merge.

Cross‑frontend, backend, test, and security work that shares state : use Agent Teams so that backend interface changes are visible to frontend and test teammates, and security findings can be fed back.

The guiding rule is: Isolate first; add Agent Teams only when shared state, dependency coordination, or member communication is required.

Agent Teams’ Collaboration State

Official documentation describes Agent Teams as an experimental feature (disabled by default). It can be enabled with the environment variable: export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 Each team consists of:

lead:   split, assign, summarize
teammates: execute and communicate
task list: record tasks, dependencies, status
permissions: restrict what each teammate may do
work surface: constrain files or modules each member handles
review gates: evidence used to judge completion

Four Engineering Questions Before Parallelising

Can file boundaries be split? Overlapping file edits cause merge conflicts; Agent Teams does not automatically create worktree isolation.

Is information flow one‑way or bidirectional? Simple read‑only queries fit Subagents; bidirectional dependencies (e.g., backend API change affecting frontend and tests) require Agent Teams.

What evidence proves completion? Gather diff, test results, type‑check output, logs, screenshots, or risk lists and store them in a unified location.

How are permissions and budgets controlled? Explicitly whitelist read/write paths (e.g., src/**, tests/**) and blacklist dangerous actions ( .env, git push, npm publish). Token budget is set with --max-budget-usd in the CLI.

Prompt Design for an Agent Team

Instead of a terse “create four agents for backend, frontend, test, review”, write a concise work specification:

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: wait for stable contract, then add tests.
4. review‑teammate: read‑only audit of credential handling, test coverage, and risk list.

DEPENDENCIES
- frontend depends on backend contract.
- tests depend on both backend and frontend.
- review runs after implementation.

PERMISSIONS
- allow read of repository, write to scoped files, run local tests.
- deny read of .env, deny git push, deny npm publish, deny destructive deletes.

REVIEW GATES
- final diff summary
- test results
- uncovered risks list

STOP
If out‑of‑scope files need changes, pause and explain.

This prompt forces the lead to narrow the goal, split file ownership, expose dependencies, declare permissions, and surface the evidence needed for acceptance.

Pre‑flight Checklist

Goal : a single sentence describing the deliverable.

File boundaries : which teammate can modify which files.

Dependency order : who waits for whose output.

Permission boundaries : allowed reads/writes (e.g., .env, git push).

Budget boundaries : model choice, team size, token limits.

Evidence : diff, test results, logs, screenshots, risk list.

Stop conditions : out‑of‑scope changes, insufficient permissions, missing test environment.

If two or three items cannot be answered, postpone the team launch and first clarify boundaries with a single session or a Subagent.

Practical Roll‑out Steps

Start with research and review: let three read‑only teammates examine security, performance, and test coverage of a large PR.

Move to a small cross‑layer feature with clear file separation (e.g., a login page) using backend, frontend, test, and review teammates.

Only after mastering isolation and evidence collection should you attempt larger feature development, adding worktrees, local test commands, permission rules, task logs, and human review.

The author’s conservative approach is to keep work in a single session as long as possible, only escalating to Subagents, Agent View, or Agent Teams when the engineering problem truly demands isolation, parallel execution, or shared state.

Conclusion

Claude Code Agent Teams provides a structured way to turn AI coding agents into genuine engineering collaborators. The real challenge is not the number of agents but designing clear boundaries, permissions, and evidence streams so that parallel work reduces, rather than creates, hidden coordination costs.