Skip to content

Claude Code Complete Guide

Claude Code Subagent Feature: Hands-On Practical Tutorial

Introduction

"I understand how to create subagents, but when and how do I actually use them?"

To answer this question, this article provides step-by-step practical workflows using the subagent feature in real projects.

How Subagents Work

Critical Understanding: Manual Trigger Approach

Subagents are not scheduled executions. They operate in the following manner:

sequenceDiagram
    participant User as Developer
    participant Main as Main Claude
    participant Analysis as Analysis Engine

    User->>Main: "Perform structured analysis from 3 perspectives"
    Main->>Analysis: 1. Start security perspective analysis
    Analysis-->>Main: Security analysis results

    Main->>Analysis: 2. Start performance perspective analysis
    Analysis-->>Main: Performance analysis results

    Main->>Analysis: 3. Start code quality perspective analysis
    Analysis-->>Main: Quality analysis results

    Main->>Main: Consolidate results & generate comprehensive report
    Main->>User: Integrated improvement recommendations

Practical Tutorial 1: Pull Request Review

Step 1: Try Basic Parallel Review

Command you can actually try:

# With Claude Code running, execute:
"Review this pull request in parallel from 3 perspectives:
1. Security perspective
2. Performance perspective  
3. Code quality perspective"

Expected output:

Task(Performing task: Security review in progress...)
Task(Performing task: Performance analysis in progress...)
Task(Performing task: Code quality check in progress...)

Step 2: How to Verify Operation

While each task is running, you'll see:

Task(Performing task: Checking security vulnerabilities...)
└── Currently analyzing auth.js
└── Detected potential XSS vulnerability
└── Verifying CSRF protection

Task(Performing task: Running performance analysis...)  
└── Measuring bundle size
└── Identifying unnecessary dependencies
└── Preparing optimization suggestions

Step 3: Utilizing Results

Each agent returns concrete results like:

## Security Analysis Results
- ❌ auth.js:42 - Unsanitized user input
- ❌ api/login.js:28 - SQL injection vulnerability
- ✅ HTTPS enforcement properly implemented

## Performance Analysis Results  
- ⚠️ bundle.js (2.3MB) - Too large
- ⚠️ Importing entire lodash - Recommend importing only needed functions
- ✅ Image optimization is appropriate

## Code Quality Analysis Results
- ❌ 12 functions with high complexity detected
- ❌ Test coverage 45% (target: 80%)
- ✅ ESLint rules properly applied

Practical Tutorial 2: Design Review for New Features

Real-World Scenario

A practical example when developing new user authentication functionality.

Step 1: Parallel Considerations at Design Stage

"We are considering implementing a new OAuth authentication feature. Please analyze in parallel from the following perspectives:
1. Security architecture validation
2. Database design feasibility confirmation
3. Frontend integration complexity evaluation
4. Test strategy formulation"

Step 2: Specific Instruction Examples

# When specifying roles more concretely
"For OAuth implementation, analyze in parallel with the following specialized agents:

Agent 1: As a security expert
- Check OAuth flow vulnerabilities
- Verify token management best practices
- Evaluate PKCE implementation necessity

Agent 2: As a database expert  
- Validate user table design
- Optimize session management
- Propose index strategy

Agent 3: As a frontend expert
- Evaluate React integration complexity
- Suggest UX improvements
- Error handling strategy"

Step 3: Screen Display During Execution

🤖 Running 3 tasks in parallel...

Task(Performing task: OAuth security analysis in progress...)
├── Validating PKCE flow
├── Verifying token lifecycle
└── Cross-referencing vulnerability databases

Task(Performing task: Database design review in progress...)
├── Checking table relationship consistency
├── Evaluating performance impact  
└── Validating scalability

Task(Performing task: Frontend integration analysis in progress...)
├── Evaluating React Router integration complexity
├── Considering state management patterns
└── Creating error screen design proposals

✅ All tasks completed - Generating integrated report...

Practical Tutorial 3: Large-Scale Refactoring

Concrete Instructions You Can Use

# Structured analysis of legacy code
"We want to modernize this legacy JavaScript codebase.
Perform structured analysis from the following 6 perspectives:

1. TypeScript migration priority evaluation
2. Identification of areas lacking test code
3. Comprehensive security vulnerability investigation
4. Performance bottleneck identification
5. Dependency update impact investigation
6. Architecture improvement proposal creation

Each agent works independently and finally presents an integrated migration plan."

Detailed Display During Execution

🔄 Starting large-scale parallel analysis...

Task(Performing task: TypeScript migration priority evaluation...)
├── 📁 src/utils/ - 23 type errors detected
├── 📁 src/components/ - Can convert from JSDoc to type definitions
├── 📁 src/api/ - External API type definitions needed
└── 🎯 Priority: Recommended execution order utils → components → api

Task(Performing task: Identifying test-deficient areas...)
├── 📊 Current coverage: 34% (target: 80%)
├── 🚨 Untested: Authentication-related features (high risk)
├── 🚨 Untested: Payment processing (high risk)
└── 📝 Creating priority test target list

Task(Performing task: Executing security audit...)
├── 🔍 Scanning known vulnerabilities in dependencies
├── 🔍 Searching for hardcoded credentials
├── 🔍 Static analysis for XSS/CSRF vulnerabilities
└── ⚠️ Found 3 high-severity issues

Practical Daily Development Usage

1. Morning Code Review

# Daily morning routine
"Review yesterday's commits in parallel from 3 perspectives:
- Security check
- Performance impact evaluation  
- Code quality and best practice compliance"

2. Pre-Implementation Consideration

# Before new feature development
"Planning to implement XX feature. Please consider the following in parallel:
- Technical implementation difficulty evaluation
- Impact analysis on existing system
- Identification of required test cases
- Organization of security considerations"

3. Impact Scope Confirmation During Bug Fixes

# During bug fixes
"Investigate in parallel the impact this bug fix has on the following:
- Side effects on other features
- Performance impact
- Need for test case updates
- Necessity of documentation updates"

Common Issues and Solutions

Issue 1: Agent Doesn't Work as Expected

Symptom:

# Vague instruction example (doesn't work well)
"Check the code"

Solution:

# Specific and clear instruction (works well)
"Check the src/auth.js file in parallel from the following 3 perspectives:
1. Security vulnerability detection
2. ESLint rule violation confirmation  
3. Performance improvement identification"

Issue 2: Unclear if Running in Parallel

Verification method: - Check for Task(Performing task: ...) display - If multiple tasks are displayed simultaneously, parallel execution is in progress - Each task's progress is displayed individually

Issue 3: Results Not Consolidated

Symptom:

# Scattered results are returned
Agent 1: "No security issues"
Agent 2: "Performance issues found"  
Agent 3: "Code quality is good"

Solution:

# Explicitly instruct consolidation
"Consolidate results and create a prioritized action plan"

How to Introduce in Actual Projects

Phase 1: Start Small

# Start with simple tasks
"Review this function from 2 perspectives:
- Potential bugs
- Readability improvements"

Phase 2: Gradually Expand

# Expand scope as you get comfortable
"Analyze this entire module from 4 perspectives:
- Security
- Performance
- Maintainability
- Testability"

Phase 3: Team-Wide Adoption

# Establish as team standard
"Check pull request #XX in parallel with standard review items:
- Coding standard compliance
- Security best practices
- Performance impact
- Test coverage adequacy
- Documentation update necessity"

Success Tips

1. Clear and Specific Instructions

❌ Bad example: "Check the code" ✅ Good example: "Analyze auth.js in parallel from 3 perspectives (security, performance, quality)"

2. Setting Appropriate Parallelism

  • 2-3 tasks: Daily reviews
  • 4-5 tasks: Pre-feature development considerations
  • 6-8 tasks: Large-scale refactoring
  • 9-10 tasks: Emergency comprehensive investigation

3. How to Utilize Results

# Instruct next actions based on results
"Based on the analysis results, implement the 3 most important improvements.
Provide specific fix code in order of priority."

Summary

The Claude Code subagent feature is a tool for parallel analysis from multiple perspectives based on situational judgment.

  • Manual trigger, not scheduled execution
  • Specific and clear instructions are crucial
  • Can be integrated into daily development workflows
  • Gradual adoption is recommended

Actually try it in your project and see for yourself!

Next Steps

  1. Try it now: Execute the concrete examples above as-is
  2. Customize: Adjust instructions to fit your project
  3. Team adoption: Share successful patterns with the team
  4. Continuous improvement: Accumulate effective instruction patterns

Tags

ClaudeCode #Subagent #PracticalTutorial #HandsOn #ParallelProcessing #DevelopmentEfficiency #RealExamples