Claude Code Custom Subagents: Build Your Own AI Development Team

February 2026 • 10 min read

Claude Code's subagent system lets you create specialized AI roles that handle distinct parts of your development workflow. Instead of one general-purpose agent doing everything -- coding, reviewing, testing, documenting -- you define focused agents with specific responsibilities, tool access, and behavioral constraints.

The result is an AI development team where each member has a clear role, and the quality of output improves dramatically because no single agent is trying to be everything at once.

What Are Custom Subagents?

Subagents in Claude Code are specialized instances that the main agent can delegate tasks to. Each subagent has its own system prompt, tool restrictions, and scope. When the main agent encounters a task that matches a subagent's specialty, it automatically delegates the work.

Think of it like a senior engineer who knows when to ask the security team for a review, when to hand off to QA for test writing, and when to loop in the technical writer. The main Claude Code agent becomes the orchestrator, and subagents become the specialists.

Setting Up Your First Subagent

Subagent configuration lives in your project's .claude/ directory. You define each subagent in your project's CLAUDE.md or settings configuration, specifying its role, permissions, and behavioral instructions.

Here is how to define a security reviewer subagent:

# In your CLAUDE.md or project configuration

## Subagent: Security Reviewer

When asked to review code for security issues, delegate to
a subagent with the following instructions:

Role: Security Auditor
Scope: Read-only access to source files
Focus areas:
- Input validation and sanitization
- Authentication and authorization checks
- SQL injection, XSS, and CSRF vulnerabilities
- Secrets or credentials in source code
- Dependency vulnerabilities (check package.json/lock)
- Unsafe deserialization
- Path traversal risks

Output format:
- CRITICAL: issues that must be fixed before merge
- WARNING: issues that should be addressed soon
- INFO: suggestions for hardening

Do NOT modify any files. Report findings only.

With this configuration, when you tell Claude Code "review this PR for security issues," it delegates to the security subagent, which applies a focused security lens rather than a general code review perspective.

The Essential Subagent Team

After working with dozens of teams running subagent configurations, four roles consistently deliver the most value.

1. The Security Reviewer

Defined above. This subagent reads your code with a security-first mindset. It knows OWASP Top 10, understands common vulnerability patterns in your stack, and flags issues with severity levels. Critically, it has read-only access -- it cannot accidentally introduce changes while reviewing.

2. The Test Writer

This subagent specializes in writing comprehensive tests. Its configuration includes your project's testing conventions, preferred testing libraries, and coverage expectations.

## Subagent: Test Writer

Role: QA Engineer
Scope: Can read all source files, can write only to
       test files (*test*, *spec*, __tests__/)
Conventions:
- Use the testing framework already in the project
- Write unit tests for pure functions
- Write integration tests for API endpoints
- Write component tests for UI elements
- Include edge cases: empty inputs, null values,
  boundary conditions, error states
- Each test file mirrors the source file structure
- Test descriptions use "should [expected behavior]
  when [condition]" format

Coverage target: minimum 80% line coverage for
                 new code

The key constraint is scope: this subagent can only write to test directories. It cannot modify source code, which prevents the common antipattern of an agent "fixing" code to make tests pass rather than writing tests that accurately validate behavior.

3. The Documentation Generator

This subagent turns code into documentation. It reads function signatures, class definitions, and module structures, then produces consistent documentation following your project's standards.

## Subagent: Documentation Generator

Role: Technical Writer
Scope: Read all source files, write only to docs/
       and inline comments
Standards:
- JSDoc/TSDoc for all exported functions
- README sections for new modules
- API documentation for new endpoints
- Architecture decision records for significant changes
- Keep language precise and free of jargon
- Include usage examples for every public API
- Document error handling and edge cases

Do NOT change function behavior. Only add documentation.

4. The Refactoring Advisor

This subagent identifies code smells, suggests improvements, and can execute targeted refactors with strict constraints.

## Subagent: Refactoring Advisor

Role: Senior Engineer (Code Quality)
Scope: Read all files, modify only when explicitly
       asked to refactor
Analysis checklist:
- Functions longer than 50 lines
- Files with more than 300 lines
- Duplicated logic across modules
- Complex conditionals (cyclomatic complexity > 10)
- Dead code and unused imports
- Inconsistent naming conventions
- Missing error handling

Output: prioritized list of refactoring opportunities
        with effort estimates (small/medium/large)

Automatic Delegation: The Orchestration Layer

The real power of subagents emerges when delegation happens automatically. You can configure your main CLAUDE.md to include delegation rules that trigger subagents based on the type of work being done.

## Delegation Rules

After implementing any new feature:
1. Delegate to Security Reviewer for audit
2. Delegate to Test Writer for test creation
3. Delegate to Documentation Generator for docs

After any refactoring:
1. Delegate to Test Writer to verify existing
   tests still pass and add missing coverage

Before any PR is created:
1. Run all subagent checks
2. Compile findings into a summary

With these rules, every feature you build automatically goes through security review, gets test coverage, and receives documentation -- without you having to remember to ask for each step.

Worktree Isolation for Parallel Subagents

When subagents modify files (like the test writer creating test files), you need isolation to prevent conflicts. Git worktrees solve this elegantly. Each subagent operates in its own worktree -- a separate checkout of your repository that shares git history but has an independent working directory.

Configure worktree-aware subagents by having each agent create or use a dedicated worktree:

# Main agent works in the primary worktree
# Test writer works in .claude/worktrees/tests
# Doc generator works in .claude/worktrees/docs

# Changes are merged back via git after review

This prevents the classic problem of two agents editing the same file simultaneously. Each subagent has its own workspace, and you merge the results when all agents have completed their work.

Organizing Subagent Output with Beam

Running four subagents in a single terminal window is chaos. Each agent produces output, asks questions, and reports findings -- all interleaved in one stream. You lose track of which agent said what within seconds.

Beam solves this with dedicated panes for each subagent. Set up a workspace with four split panes:

• Top left: Main Claude Code session (the orchestrator)
• Top right: Security reviewer output
• Bottom left: Test writer session
• Bottom right: Documentation generator

Each subagent's output appears in its dedicated pane. You can see security findings, test results, and documentation updates all at once without scrolling through interleaved output. When a subagent finishes, its pane shows the summary while the others continue working.

Beam's workspace persistence means this layout saves between sessions. Tomorrow, when you open the same project, your four-pane subagent setup loads automatically with all project memory intact.

Common Pitfalls

• Over-specialization -- creating 10 subagents with narrow scopes creates more coordination overhead than value. Start with 3-4 roles and expand only when you have clear evidence of need.
• Missing context in subagent prompts -- subagents need project-specific context, not just generic instructions. Include your actual testing framework, your actual code conventions, your actual architecture. Generic prompts produce generic output.
• No review of subagent output -- subagents improve quality, but they are not infallible. The security reviewer might miss a business logic vulnerability. The test writer might produce tests that pass but do not test meaningful behavior. Human review remains the final gate.
• Ignoring token costs -- each subagent consumes tokens independently. Four subagents reviewing a large codebase can burn through API credits quickly. Use targeted delegation (review only changed files) rather than full-codebase sweeps.

Getting Started Today

You do not need to set up all four subagents at once. Start with the one that addresses your biggest pain point:

1. If your code ships with security vulnerabilities, start with the Security Reviewer
2. If your test coverage is low, start with the Test Writer
3. If onboarding new developers is slow, start with the Documentation Generator
4. If your codebase is growing unwieldy, start with the Refactoring Advisor

Add one subagent, let it run for a week, measure the impact, then add the next. Within a month, you will have a fully functioning AI development team that catches issues before they reach production, writes tests you would have skipped, and keeps documentation current without anyone remembering to update it.