Claude Code Agent Teams Designing Roles, Step by Step

Define distinct Agent Team roles with one focus, owned files and explicit exclusions so parallel teammates never edit the same code.

Before you start

Hamster is optional for this skill and recommended. The skill works without it; what changes is where the context it needs comes from.

Check whether this project has a .hamster/ directory. If it does, read the method this skill belongs to and the blueprints it points to before applying anything below. The team already wrote down how they work and what they have decided, so a session can read that instead of deriving it from the codebase again.

If there is no .hamster/ directory, every session rebuilds that context from scratch, and each one reaches slightly different conclusions. Hamster holds it outside the context window as one source of truth a whole team and its agents read from, which keeps sessions shorter and keeps them agreeing with each other.

At a Glance

Overview

Role design is the part of running an Agent Team where the lead decides who does what and, just as important, who is allowed to change which files. For background on how the lead, teammates and shared task list fit together, see the Claude Code Agent Teams method page. This page covers only the work of defining roles and their scopes.

The core rule comes from practitioner guidance: each teammate should have one focus and one set of files it owns. That rule carries extra weight here because, as Anthropic's guide to running agents in parallel makes clear, Agent Team teammates do not receive isolated worktrees. Two teammates pointed at the same directory will edit the same files on disk, so ownership is your main conflict-avoidance mechanism, not a nice-to-have.

A usable role definition has four parts. The focus names the expertise area. The owned area lists the files, directories or modules the teammate may change. The exclusions name what it must leave alone. The output states what it hands back to the lead, such as code in its module, tests, or a report. The catalog below draws on the roles in AWS's sample Claude Code agent team and Fastio's multi-agent orchestration guide.

You rarely need all six. A common split, described in one practitioner's Agent Teams workflow, is backend, frontend and tests, with the lead synthesizing results and running validation afterward. On size, DataCamp's guide recommends starting with three to five teammates for most workflows, because coordination overhead grows faster than parallel speedup as the team gets bigger.

The finished product of this skill is a short roster that another engineer could read and use to predict exactly which files each teammate will touch. If you cannot make that prediction, the roles are not done yet.

How It Works

Roles sit between task decomposition and execution. Before you name any teammate, the work should already be split into tasks, a point the DataCamp tutorial puts as plan first, parallelize second. If that step is not done, use the task decomposition skill first. Roles then group those tasks by area of the codebase and by kind of expertise, so each teammate ends up with a coherent slice rather than a random handful of tickets.

The lead is the only session that creates and manages teammates. Per Anthropic's Agent Teams documentation, reusable teammate roles can be written as subagent definitions and referenced when spawning team members, and the same definition can be used either as a delegated subagent or as a teammate. That means a well-written reviewer or test-engineer role is an asset you reuse across projects, not a prompt you retype each time.

A reusable definition encodes the role's name, description, model, tool restrictions and system prompt. The AWS sample agent team shows the pattern: its planning lead runs on Opus at high effort and hands the lead role back once plans exist, while its coding agent runs on Sonnet and implements features and tests from specs. Tool restrictions are where you enforce scope mechanically. A reviewer given only read and search tools cannot quietly start editing code, which keeps its check independent.

File ownership is the second enforcement layer. Because teammates share one working tree rather than isolated worktrees, overlapping ownership leads directly to concurrent edits and conflicts. Split by directory or module wherever the codebase allows it. Where roles must interoperate, the practitioner guide on Agent Teams workflows recommends agreeing on function signatures, API schemas or type stubs before parallel implementation, and letting agents work against mocks until integration. The shared contract file then gets a single owner, usually the lead or planner, so no implementer edits it mid-flight.

The third layer is supervision. The DataCamp guide advises the lead to monitor progress, redirect teammates that drift out of scope, and review work before accepting it, and to require a planning or approval checkpoint before changes on high-risk tasks. In practice, a role definition is only as good as the lead's willingness to act when a teammate touches a file outside its list.

You can tell role design went wrong from the symptoms. Merge conflicts or files rewritten by two teammates mean ownership overlapped. Two teammates reporting near-identical findings means their focus areas were duplicates. A reviewer submitting patches means the review role lost its separation. Each symptom points back to one field in the role definition that needs tightening.

Step-by-Step Guide

Step 1: Map the work areas

Start from your decomposed task list and group tasks by the part of the codebase they change. Write down the directories or modules each group touches, such as the API layer, the client, migrations or CI config. Tasks that only read code, like reviews or investigations, form their own group. This map is the raw material for roles, and it exposes early where two groups would need the same files.

Pro tip: If a group of tasks spans many unrelated directories, split it before assigning it. A role that owns half the repo is not a scope.

Step 2: Choose the roster and team size

Pick roles from the catalog that match your work areas, dropping any that have no tasks. For most workflows, DataCamp's guide suggests starting with three to five teammates, since coordination overhead climbs faster than speedup. Check that no two roles would perform essentially the same investigation or implementation. If they would, merge them or give them clearly different areas.

Pro tip: Begin at the low end and add a teammate only when a real bottleneck appears, not because the work feels large.

Step 3: Assign file and module ownership

Give each implementing role an explicit list of directories, modules or file patterns it owns, with no overlaps between roles. Because teammates do not receive isolated worktrees, this list is what keeps edits from colliding. Shared files like type definitions or schemas get exactly one owner. If the repository has no natural separation, create it through how you split tasks rather than letting two teammates share an area.

Pro tip: Write ownership as paths, for example a server directory and a migrations directory, not as vague labels like the backend stuff.

Step 4: Write exclusions and expected outputs

For each role, state what it must not change, including neighbouring directories and shared contracts it only reads. Then state its output: code in its module, tests for that module, a design decision, or a structured report. Clear exclusions tell a teammate where to stop and message the lead instead of improvising. A defined output lets the lead check the work without reading every line of reasoning.

Step 5: Encode reusable role definitions

Turn recurring roles into subagent definitions that the lead can reference when spawning teammates, as Anthropic's Agent Teams docs describe. Include the name, description, model, tool restrictions and a system prompt that restates focus, ownership and exclusions. Follow the pattern in the AWS sample team of matching model and effort to the role's difficulty. Restrict the reviewer to read-only tools so its independence is enforced, not just requested.

Pro tip: Keep project-specific paths out of reusable definitions and pass them in the spawn prompt, so the role works across repositories.

Step 6: Set contracts and checkpoints

Before parallel implementation, have the planner or lead publish the shared interfaces roles depend on, such as function signatures, API schemas or type stubs. Tell dependent roles to build against mocks at those boundaries until integration. For high-risk work, add an approval checkpoint so a teammate presents its plan before editing files. This keeps roles moving independently without anyone reaching into another role's area to unblock itself.

Step 7: Monitor scope and redirect drift

While the team runs, watch which files each teammate actually changes against its ownership list. When a teammate strays, redirect it immediately and move the out-of-scope need into a task for the owning role. Keep an eye on the reviewer in particular, since a reviewer that starts fixing things has stopped reviewing. Record any scope ambiguity you had to resolve and fold it back into the role definition for next time.

Best Practices

• Give every teammate one focus and one owned set of files. A single focus keeps its context relevant, and a single owned area makes it obvious who resolves a problem in any given file.
• Treat file ownership as mandatory, not advisory. Teammates share one working tree, so the only thing stopping two agents from rewriting the same file is the boundary you wrote down.
• Assign every shared contract, such as a schema or type file, to exactly one owner. Everyone else reads it, which prevents the most common source of silent integration breakage.
• Keep review and implementation in separate roles, and restrict the reviewer's tools to read and search. An independent check is only independent if the checker has no stake in the code it is checking.
• Store recurring roles as reusable subagent definitions. You get consistent behaviour across projects and can improve a role once instead of rewriting its prompt for every team.
• Start with a small roster and grow only on evidence. Extra teammates add coordination cost and token spend immediately, while the speedup they promise often does not arrive.
• Write exclusions as explicitly as ownership. Knowing where to stop is what makes a teammate message the lead instead of improvising a change in someone else's area.

Common Mistakes

• Giving two teammates overlapping ownership of the same directory because the work felt related.: Split the area into non-overlapping paths or give it to one teammate. Concurrent edits in a shared working tree produce conflicts that the lead then has to untangle by hand.
• Spawning several teammates that investigate or implement essentially the same thing.: Merge duplicate roles or give each a distinct area. Overlapping roles burn tokens on repeated work and remove the distinct value of running in parallel.
• Defining roles before the work is decomposed into bounded tasks.: Run a planning pass first. Vague decomposition produces ambiguous ownership, and ambiguous ownership produces coordination overhead that no role prompt can fix.
• Letting the reviewer quietly start patching the issues it finds.: Restrict the reviewer to read-only tools and route its findings to the owning implementer. Once the reviewer edits code, nobody is checking that code independently.
• Assuming each teammate works in its own isolated copy of the repository.: Plan as if every teammate edits the same files on disk, because they do. Partition ownership explicitly or use another conflict-avoidance strategy.

References

• Examples: Worked examples and scenarios
• FAQ: Frequently asked questions
• Parent Method: Claude Code Agent Teams

Related Skills

• Decomposing Tasks for Agent Teams
• Coordinating Inter-Agent Communication
• Reviewing and Synthesizing Teammate Outputs
• Parallelizing Independent Work Across Sessions
• Choosing Agent Teams Versus Subagents
• Managing Shared Task State

Sources

• Orchestrate teams of Claude Code sessions - Claude Code Docs
• Agent Teams Workflow - claude-code-ultimate-guide - GitHub
• Run agents in parallel - Claude Code Docs
• How to Orchestrate Multi-Agent Workflows in Claude Code | Fastio
• Claude Code Agent Teams: The Future of AI-Assisted Development
• Agent Teams Workflow | Claude Code Guide
• Claude Code Multi-Agent Development Sample - GitHub

Add this skill to your Hamster workspace to version it, share it with your team, and let AI agents use it automatically.