Master Claude Code in a Week (Part 9): Subagents

· 5 min read
#claude-code #ai #developer-tools #tutorial #series

This is the ninth part of the "Master Claude Code in a Week" series. In this article, we'll explore Subagents — specialized AI assistants for specific tasks.

What are Subagents?

Subagents are specialized AI assistants with isolated contexts and custom prompts. The main agent can delegate tasks to subagents with specific expertise, like a tech lead assigning tasks to specialized developers.

┌────────────────────────────────────────────────────────────────┐
│                        SUBAGENTS                                │
├────────────────────────────────────────────────────────────────┤
│                                                                 │
│                    ┌─────────────────┐                         │
│                    │   Main Agent    │                         │
│                    │   (Orchestrator)│                         │
│                    └────────┬────────┘                         │
│                             │                                  │
│              ┌──────────────┼──────────────┐                  │
│              │              │              │                   │
│              ▼              ▼              ▼                   │
│    ┌─────────────┐ ┌─────────────┐ ┌─────────────┐           │
│    │Code Reviewer│ │Test Engineer│ │ Doc Writer  │           │
│    │  Subagent   │ │  Subagent   │ │  Subagent   │           │
│    └─────────────┘ └─────────────┘ └─────────────┘           │
│    - Security     - Unit tests    - API docs                 │
│    - Performance  - Integration   - Guides                   │
│    - Code style   - E2E tests     - Comments                 │
│                                                                 │
└────────────────────────────────────────────────────────────────┘

Installing Subagents

Location

Project-specific:

.claude/agents/

From claude-howto

cp claude-howto/04-subagents/*.md .claude/agents/

File Structure

.claude/
└── agents/
    ├── code-reviewer.md
    ├── test-engineer.md
    ├── documentation-writer.md
    └── secure-reviewer.md

Example Subagents

1. Code Reviewer Subagent

File: .claude/agents/code-reviewer.md

---
name: code-reviewer
description: Comprehensive code quality analysis expert
tools:
  - Read
  - Grep
  - Glob
---

# Code Reviewer Agent

You are a senior code reviewer with expertise in software quality,
design patterns, and best practices.

## Expertise Areas

- Clean code principles
- SOLID principles
- Design patterns
- Performance optimization
- Security best practices

## Review Process

When reviewing code:

### 1. Initial Assessment
- Understand the code's purpose
- Identify architecture/patterns used
- Note the language and framework

### 2. Quality Analysis
- [ ] Meaningful variable/function names
- [ ] Single responsibility principle
- [ ] DRY (Don't Repeat Yourself)
- [ ] Proper error handling

### 3. Generate Report

## Code Review Summary

### Overall Score: X/10

### Critical Issues (Must Fix)
- [Issue with file:line reference]

### Recommendations
1. [Actionable suggestion]

## Constraints

- DO NOT modify code
- Focus on review and recommendations only
- Be constructive, not critical

2. Test Engineer Subagent

File: .claude/agents/test-engineer.md

---
name: test-engineer
description: Testing expert for test strategy and implementation
tools:
  - Read
  - Write
  - Bash
---

# Test Engineer Agent

You are a QA engineer expert in test strategy, test design,
and test implementation.

## Expertise Areas

- Unit testing
- Integration testing
- End-to-end testing
- Test-driven development (TDD)
- Test coverage analysis

## Responsibilities

### 1. Analyze Code for Testability
- Identify testable units
- Note dependencies to mock
- Find edge cases

### 2. Design Test Strategy
- Determine test types needed
- Plan test coverage
- Identify critical paths

### 3. Write Tests

```php
public function test_{action}_{condition}_{expected_result}(): void
{
    // Arrange
    // Act
    // Assert
}

Constraints

  • Write tests that are independent
  • Use meaningful test names
  • Follow project testing conventions

### 3. Security Reviewer Subagent (Read-only)

**File**: `.claude/agents/secure-reviewer.md`

```markdown
---
name: secure-reviewer
description: Security expert for vulnerability assessment
tools:
  - Read
  - Grep
# Note: No Write, Bash to ensure read-only mode
---

# Security Reviewer Agent

You are a security expert specializing in code vulnerability
assessment and security best practices.

## ⚠️ READ-ONLY MODE

This agent operates in READ-ONLY mode for safety.
You can only read and analyze code, NOT modify it.

## Security Checklist

### Injection Vulnerabilities
- [ ] SQL injection
- [ ] Command injection
- [ ] XSS

### Authentication
- [ ] Password storage (hashing)
- [ ] Session management

### Data Protection
- [ ] Sensitive data encryption
- [ ] Secure transmission (TLS)

## Output Format

## Security Assessment Report

### Risk Level: HIGH/MEDIUM/LOW

### Critical Vulnerabilities
1. **[Vulnerability Name]**
   - Location: file:line
   - Impact: [What could happen]
   - Remediation: [How to fix]

## Constraints

- DO NOT modify any code
- DO NOT execute any commands
- Report findings only

Using Subagents

Automatic Delegation

Main agent automatically delegates when appropriate:

User: "Review this code for security issues"

Main Agent: [Recognizes security review task]
            [Delegates to @secure-reviewer]

Secure Reviewer: [Analyzes code]
                 [Returns security report]

Main Agent: [Synthesizes and presents findings to user]

Explicit Delegation

You can request a specific subagent:

User: "Use @test-engineer to create tests for UserService"

Main Agent: [Delegates to @test-engineer]

Test Engineer: [Creates comprehensive test suite]

Multi-agent Workflow

User: "Complete code review for this PR"

Main Agent: 
1. Delegates to @code-reviewer for quality review
2. Delegates to @secure-reviewer for security scan
3. Delegates to @test-engineer for test coverage analysis
4. Synthesizes all findings
5. Presents comprehensive PR review

Custom Subagent Teams

Create your own team:

DevOps Team

.claude/agents/
├── infra-specialist.md
├── ci-engineer.md
└── monitoring-expert.md

Frontend Team

.claude/agents/
├── react-developer.md
├── ui-designer.md
└── accessibility-expert.md

Best Practices

1. Clear Role Definition

# ❌ Bad - Vague role
You are a helpful assistant.

# ✅ Good - Specific role
You are a senior security engineer with 10 years of experience
in application security, specializing in OWASP vulnerabilities.

2. Explicit Tool Permissions

# ❌ Bad - Too many permissions
tools:
  - Read
  - Write
  - Bash
  - Network
  - Admin

# ✅ Good - Minimal permissions
tools:
  - Read    # Code reviewer only needs read
  - Grep    # For pattern search

3. Structured Output

# ✅ Good - Structured template
## Output Format

### Summary
[One paragraph overview]

### Findings
1. **[Category]**: [Finding]
   - Location: [file:line]
   - Impact: [Description]

Summary

Subagents enable specialization:

  • ✅ Isolated contexts for focused work
  • ✅ Domain-specific expertise
  • ✅ Automatic delegation
  • ✅ Customizable tool permissions
  • ✅ Team-based workflows

Next Up

In the final part, we'll explore Plugins and Advanced Features — how to bundle all features and use advanced capabilities.

References

This series is translated and expanded from claude-howto — MIT License.

Comments