Update all concept README files with comprehensive documentation

Extract and consolidate information from claude_concepts_guide.md into
individual concept folders:

- 01-slash-commands: Add architecture diagrams, features table, lifecycle
  diagram, best practices, and comprehensive examples
- 02-subagents: Add architecture, configuration, tool access hierarchy,
  context management, and practical delegation examples
- 03-memory: Add memory hierarchy, locations table, lifecycle diagram,
  4 practical examples, and features comparison
- 04-mcp: Add MCP architecture, ecosystem, setup process, 4 examples
  (GitHub, Database, Multi-MCP, Filesystem), and security best practices
- 05-skills: Add skill architecture, loading process, 3 complete examples
  with Python scripts (Code Review, Brand Voice, Documentation Generator)
- 06-plugins: Add plugin architecture, marketplace, lifecycle, 3 examples,
  features comparison, and publishing guide
- 07-hooks: Add hook types table, common examples, variables, 5 practical
  examples with code, and best practices
- 08-checkpoints: Add key concepts, all commands, use cases table,
  configuration, 4 practical examples, and troubleshooting
- 09-advanced-features: Add Planning Mode, Extended Thinking, Background
  Tasks, Permission Modes, Headless Mode, Session Management, interactive
  features, and complete configuration examples

All READMEs now include:
- Overview sections with clear explanations
- Mermaid diagrams for visual understanding
- Comprehensive tables and feature comparisons
- Practical code examples and templates
- Installation instructions
- Best practices and troubleshooting
- Cross-references to related concepts

Total changes: +3706 lines of comprehensive documentation

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Luong NGUYEN
2025-11-08 01:51:06 +01:00
parent d17564a9f2
commit 41527aed26
9 changed files with 3776 additions and 657 deletions

View File

@@ -1,74 +1,663 @@
# Subagents Examples
# Subagents - Complete Reference Guide
This folder contains example subagent configurations for Claude Code.
Subagents are specialized AI assistants with isolated context windows and customized system prompts. They enable delegated task execution while maintaining clean separation of concerns.
## Installation
## Table of Contents
Copy these files to your project's `.claude/agents/` directory:
1. [Overview](#overview)
2. [Architecture](#architecture)
3. [Configuration](#configuration)
4. [Tool Access Hierarchy](#tool-access-hierarchy)
5. [Practical Examples](#practical-examples)
6. [Context Management](#context-management)
7. [When to Use Subagents](#when-to-use-subagents)
8. [Best Practices](#best-practices)
9. [Available Subagents in This Folder](#available-subagents-in-this-folder)
10. [Installation Instructions](#installation-instructions)
11. [Related Concepts](#related-concepts)
```bash
cp *.md /path/to/your/project/.claude/agents/
---
## Overview
Subagents enable delegated task execution in Claude Code by:
- Creating **isolated AI assistants** with separate context windows
- Providing **customized system prompts** for specialized expertise
- Enforcing **tool access control** to limit capabilities
- Preventing **context pollution** from complex tasks
- Enabling **parallel execution** of multiple specialized tasks
Each subagent operates independently with a clean slate, receiving only the specific context necessary for their task, then returning results to the main agent for synthesis.
### Key Benefits
- **Separation of Concerns** - Each agent focuses on their specialty
- **Clean Context** - No interference from unrelated information
- **Scalability** - Multiple agents work on different aspects simultaneously
- **Quality** - Specialized prompts improve output for domain-specific tasks
- **Control** - Granular tool permissions prevent unintended modifications
---
## Architecture
### High-Level Architecture
```mermaid
graph TB
User["👤 User"]
Main["🎯 Main Agent<br/>(Coordinator)"]
Reviewer["🔍 Code Reviewer<br/>Subagent"]
Tester["✅ Test Engineer<br/>Subagent"]
Docs["📝 Documentation<br/>Subagent"]
User -->|asks| Main
Main -->|delegates| Reviewer
Main -->|delegates| Tester
Main -->|delegates| Docs
Reviewer -->|returns result| Main
Tester -->|returns result| Main
Docs -->|returns result| Main
Main -->|synthesizes| User
```
## Available Subagents
### Subagent Lifecycle
### 1. Code Reviewer (`code-reviewer`)
Comprehensive code quality and maintainability analysis.
```mermaid
sequenceDiagram
participant User
participant MainAgent as Main Agent
participant CodeReviewer as Code Reviewer<br/>Subagent
participant Context as Separate<br/>Context Window
User->>MainAgent: "Build new auth feature"
MainAgent->>MainAgent: Analyze task
MainAgent->>CodeReviewer: "Review this code"
CodeReviewer->>Context: Initialize clean context
Context->>CodeReviewer: Load reviewer instructions
CodeReviewer->>CodeReviewer: Perform review
CodeReviewer-->>MainAgent: Return findings
MainAgent->>MainAgent: Incorporate results
MainAgent-->>User: Provide synthesis
```
---
## Configuration
### Subagent Configuration Table
| Configuration | Type | Purpose | Example |
|---------------|------|---------|---------|
| `name` | String | Agent identifier | `code-reviewer` |
| `description` | String | Purpose & trigger terms | `Comprehensive code quality analysis` |
| `tools` | List/String | Allowed capabilities | `read, grep, diff, lint_runner` |
| `system_prompt` | Markdown | Behavioral instructions | Custom guidelines |
### Configuration File Format
Subagents are defined in YAML front matter followed by the system prompt:
```yaml
---
name: agent-name
description: Brief description of purpose
tools: read, grep, diff
---
# System Prompt (Markdown)
You are an expert in [domain]...
```
### Tool Configuration Options
**Option 1: Inherit All Tools from Main Thread**
```yaml
---
name: full-access-agent
description: Agent with all available tools
tools: *
---
```
**Option 2: Specify Individual Tools**
```yaml
---
name: limited-agent
description: Agent with specific tools only
tools: read, grep, diff
---
```
**Option 3: Conditional Tool Access**
```yaml
---
name: conditional-agent
description: Agent with filtered tool access
tools: read, bash(npm:*), bash(test:*)
---
```
---
## Tool Access Hierarchy
```mermaid
graph TD
A["Subagent Configuration"] -->|Option 1| B["Inherit All Tools<br/>from Main Thread"]
A -->|Option 2| C["Specify Individual Tools"]
B -->|Includes| B1["File Operations"]
B -->|Includes| B2["Shell Commands"]
B -->|Includes| B3["MCP Tools"]
C -->|Explicit List| C1["read, grep, diff"]
C -->|Explicit List| C2["Bash(npm:*), Bash(test:*)"]
```
### Common Tool Combinations
**Code Review Agent**
```yaml
tools: read, grep, diff, lint_runner
```
**Implementation Agent**
```yaml
tools: read, write, bash, grep, edit, glob
```
**Documentation Agent**
```yaml
tools: read, write, grep
```
**Security Auditor**
```yaml
tools: read, grep
```
---
## Practical Examples
### Example 1: Complete Subagent Setup
#### Code Reviewer Subagent
**File**: `.claude/agents/code-reviewer.md`
```yaml
---
name: code-reviewer
description: Comprehensive code quality and maintainability analysis
tools: read, grep, diff, lint_runner
---
# Code Reviewer Agent
You are an expert code reviewer specializing in:
- Performance optimization
- Security vulnerabilities
- Code maintainability
- Testing coverage
- Design patterns
## Review Priorities (in order)
1. **Security Issues** - Authentication, authorization, data exposure
2. **Performance Problems** - O(n²) operations, memory leaks, inefficient queries
3. **Code Quality** - Readability, naming, documentation
4. **Test Coverage** - Missing tests, edge cases
5. **Design Patterns** - SOLID principles, architecture
## Review Output Format
For each issue:
- **Severity**: Critical / High / Medium / Low
- **Category**: Security / Performance / Quality / Testing / Design
- **Location**: File path and line number
- **Issue Description**: What's wrong and why
- **Suggested Fix**: Code example
- **Impact**: How this affects the system
## Example Review
### Issue: N+1 Query Problem
- **Severity**: High
- **Category**: Performance
- **Location**: src/user-service.ts:45
- **Issue**: Loop executes database query in each iteration
- **Fix**: Use JOIN or batch query
```
#### Test Engineer Subagent
**File**: `.claude/agents/test-engineer.md`
```yaml
---
name: test-engineer
description: Test strategy, coverage analysis, and automated testing
tools: read, write, bash, grep
---
# Test Engineer Agent
You are expert at:
- Writing comprehensive test suites
- Ensuring high code coverage (>80%)
- Testing edge cases and error scenarios
- Performance benchmarking
- Integration testing
## Testing Strategy
1. **Unit Tests** - Individual functions/methods
2. **Integration Tests** - Component interactions
3. **End-to-End Tests** - Complete workflows
4. **Edge Cases** - Boundary conditions
5. **Error Scenarios** - Failure handling
## Test Output Requirements
- Use Jest for JavaScript/TypeScript
- Include setup/teardown for each test
- Mock external dependencies
- Document test purpose
- Include performance assertions when relevant
## Coverage Requirements
- Minimum 80% code coverage
- 100% for critical paths
- Report missing coverage areas
```
#### Documentation Writer Subagent
**File**: `.claude/agents/documentation-writer.md`
```yaml
---
name: documentation-writer
description: Technical documentation, API docs, and user guides
tools: read, write, grep
---
# Documentation Writer Agent
You create:
- API documentation with examples
- User guides and tutorials
- Architecture documentation
- Changelog entries
- Code comment improvements
## Documentation Standards
1. **Clarity** - Use simple, clear language
2. **Examples** - Include practical code examples
3. **Completeness** - Cover all parameters and returns
4. **Structure** - Use consistent formatting
5. **Accuracy** - Verify against actual code
## Documentation Sections
### For APIs
- Description
- Parameters (with types)
- Returns (with types)
- Throws (possible errors)
- Examples (curl, JavaScript, Python)
- Related endpoints
### For Features
- Overview
- Prerequisites
- Step-by-step instructions
- Expected outcomes
- Troubleshooting
- Related topics
```
### Example 2: Subagent Delegation in Action
#### Scenario: Building a Payment Feature
**User Request**:
```
"Build a secure payment processing feature that integrates with Stripe"
```
**Main Agent Flow**:
1. **Planning Phase**
- Understands requirements
- Determines tasks needed
- Plans architecture
2. **Delegates to Code Reviewer Subagent**
- Task: "Review the payment processing implementation for security"
- Context: Auth, API keys, token handling
- Reviews for: SQL injection, key exposure, HTTPS enforcement
3. **Delegates to Test Engineer Subagent**
- Task: "Create comprehensive tests for payment flows"
- Context: Success scenarios, failures, edge cases
- Creates tests for: Valid payments, declined cards, network failures, webhooks
4. **Delegates to Documentation Writer Subagent**
- Task: "Document the payment API endpoints"
- Context: Request/response schemas
- Produces: API docs with curl examples, error codes
5. **Synthesis**
- Main agent collects all outputs
- Integrates findings
- Returns complete solution to user
### Example 3: Tool Permission Scoping
#### Restrictive Setup - Limited to Specific Commands
**File**: `.claude/agents/secure-reviewer.md`
```yaml
---
name: secure-reviewer
description: Security-focused code review with minimal permissions
tools: read, grep
---
# Secure Code Reviewer
Reviews code for security vulnerabilities only.
This agent:
- ✅ Reads files to analyze
- ✅ Searches for patterns
- ❌ Cannot execute code
- ❌ Cannot modify files
- ❌ Cannot run tests
This ensures the reviewer doesn't accidentally break anything.
```
#### Extended Setup - All Tools for Implementation
**File**: `.claude/agents/implementation-agent.md`
```yaml
---
name: implementation-agent
description: Full implementation capabilities for feature development
tools: read, write, bash, grep, edit, glob
---
# Implementation Agent
Builds features from specifications.
This agent:
- ✅ Reads specifications
- ✅ Writes new code files
- ✅ Runs build commands
- ✅ Searches codebase
- ✅ Edits existing files
- ✅ Finds files matching patterns
Full capabilities for independent feature development.
```
---
## Context Management
```mermaid
graph TB
A["Main Agent Context<br/>50,000 tokens"]
B["Subagent 1 Context<br/>20,000 tokens"]
C["Subagent 2 Context<br/>20,000 tokens"]
D["Subagent 3 Context<br/>20,000 tokens"]
A -->|Clean slate| B
A -->|Clean slate| C
A -->|Clean slate| D
B -->|Results only| A
C -->|Results only| A
D -->|Results only| A
style A fill:#e1f5ff
style B fill:#fff9c4
style C fill:#fff9c4
style D fill:#fff9c4
```
### Key Points
- Each subagent gets a **fresh context window** without the main conversation history
- Only the **relevant context** is passed to the subagent for their specific task
- Results are **distilled** back to the main agent
- This prevents **context token exhaustion** on long projects
---
## When to Use Subagents
| Scenario | Use Subagent | Why |
|----------|--------------|-----|
| Complex feature with many steps | ✅ Yes | Separate concerns, prevent context pollution |
| Quick code review | ❌ No | Not necessary overhead |
| Parallel task execution | ✅ Yes | Each subagent has own context |
| Specialized expertise needed | ✅ Yes | Custom system prompts |
| Long-running analysis | ✅ Yes | Prevents main context exhaustion |
| Single task | ❌ No | Adds latency unnecessarily |
---
## Best Practices
### Design Principles
**Do:**
- Create subagents for distinct specializations
- Use clear, focused system prompts
- Limit tools to what's necessary
- Design for isolation and independence
- Return structured results to main agent
**Don't:**
- Create overlapping subagents with same roles
- Give subagents unnecessary tool access
- Use subagents for simple, single-step tasks
- Mix concerns in one subagent's prompt
- Forget to pass necessary context
### System Prompt Best Practices
1. **Be Specific About Role**
```
You are an expert code reviewer specializing in [specific areas]
```
2. **Define Priorities Clearly**
```
Review priorities (in order):
1. Security Issues
2. Performance Problems
3. Code Quality
```
3. **Specify Output Format**
```
For each issue provide: Severity, Category, Location, Description, Fix, Impact
```
4. **Set Expectations**
```
Focus on issues that matter. Ignore formatting unless critical.
```
### Tool Access Strategy
1. **Start Restrictive**: Begin with only essential tools
2. **Expand Only When Needed**: Add tools as requirements demand
3. **Read-Only When Possible**: Use read/grep for analysis agents
4. **Sandboxed Execution**: Limit bash commands to specific patterns
---
## Available Subagents in This Folder
### 1. Code Reviewer (`code-reviewer.md`)
**Description**: Comprehensive code quality and maintainability analysis
**Tools**: read, grep, diff, lint_runner
**Use Case**: Automated code reviews focusing on security, performance, and quality.
**Specialization**:
- Security vulnerability detection
- Performance optimization identification
- Code maintainability assessment
- Test coverage analysis
- Design pattern evaluation
### 2. Test Engineer (`test-engineer`)
Test strategy, coverage analysis, and automated testing.
**Use When**: You need automated code reviews with focus on quality and security
**Example**: Review pull requests before merging
---
### 2. Test Engineer (`test-engineer.md`)
**Description**: Test strategy, coverage analysis, and automated testing
**Tools**: read, write, bash, grep
**Use Case**: Creating comprehensive test suites with high coverage.
**Specialization**:
- Unit test creation
- Integration test design
- Edge case identification
- Coverage analysis (>80% target)
- Performance benchmarking
### 3. Documentation Writer (`documentation-writer`)
Technical documentation, API docs, and user guides.
**Use When**: You need comprehensive test suite creation or coverage analysis
**Example**: Generate tests for a new feature with high coverage
---
### 3. Documentation Writer (`documentation-writer.md`)
**Description**: Technical documentation, API docs, and user guides
**Tools**: read, write, grep
**Use Case**: Generating and maintaining project documentation.
**Specialization**:
- API endpoint documentation
- User guide creation
- Architecture documentation
- Code comment improvement
- Changelog generation
### 4. Secure Reviewer (`secure-reviewer`)
Security-focused code review with minimal permissions.
**Use When**: You need to create or update project documentation
**Tools**: read, grep (read-only)
**Example**: Generate complete API documentation from code
**Use Case**: Security audits without modification capabilities.
---
### 5. Implementation Agent (`implementation-agent`)
Full implementation capabilities for feature development.
### 4. Secure Reviewer (`secure-reviewer.md`)
**Description**: Security-focused code review with minimal permissions
**Tools**: read, grep
**Specialization**:
- Security vulnerability detection
- Authentication/authorization issues
- Data exposure risks
- Injection attack identification
- Secure configuration verification
**Use When**: You need security audits without modification capabilities
**Example**: Security-only code review with read-only access
---
### 5. Implementation Agent (`implementation-agent.md`)
**Description**: Full implementation capabilities for feature development
**Tools**: read, write, bash, grep, edit, glob
**Use Case**: End-to-end feature implementation.
**Specialization**:
- Feature implementation
- Code generation
- Build and test execution
- File operations
- Codebase modification
## How Subagents Work
**Use When**: You need a subagent to implement features end-to-end
Subagents are specialized AI assistants with:
- **Isolated context windows** - Clean slate for each task
- **Customized system prompts** - Specialized expertise
- **Tool access control** - Only necessary capabilities
**Example**: Implement a complete feature from specification
## Usage Example
---
Main agent delegates work to subagents:
## Installation Instructions
```markdown
User: "Build a new authentication feature"
### Method 1: Copy to Project
Main Agent:
1. Delegates implementation to implementation-agent
2. Delegates security review to secure-reviewer
3. Delegates testing to test-engineer
4. Delegates documentation to documentation-writer
5. Synthesizes all results
Copy the agent files to your project's `.claude/agents/` directory:
```bash
# Navigate to your project
cd /path/to/your/project
# Create agents directory if it doesn't exist
mkdir -p .claude/agents
# Copy all agent files
cp /path/to/02-subagents/*.md .claude/agents/
```
### Method 2: Manual Setup
If you prefer to set up individually:
```bash
# Copy specific agents you need
cp 01-code-reviewer.md .claude/agents/code-reviewer.md
cp 02-test-engineer.md .claude/agents/test-engineer.md
cp 03-documentation-writer.md .claude/agents/documentation-writer.md
cp 04-secure-reviewer.md .claude/agents/secure-reviewer.md
cp 05-implementation-agent.md .claude/agents/implementation-agent.md
```
### Method 3: Create from Guide
Copy the configuration from this README and create new files in your `.claude/agents/` directory.
### Verification
After installation, verify the agents are recognized:
```bash
# List agents in Claude Code
/agents list
# Should show:
# - code-reviewer
# - test-engineer
# - documentation-writer
# - secure-reviewer
# - implementation-agent
```
---
## File Structure
```
@@ -80,15 +669,143 @@ project/
│ ├── documentation-writer.md
│ ├── secure-reviewer.md
│ └── implementation-agent.md
└── README.md
```
## When to Use Subagents
---
| Scenario | Use Subagent | Why |
|----------|--------------|-----|
| Complex feature with many steps | ✅ Yes | Separate concerns |
| Quick code review | ❌ No | Unnecessary overhead |
| Parallel task execution | ✅ Yes | Independent contexts |
| Specialized expertise needed | ✅ Yes | Custom prompts |
| Long-running analysis | ✅ Yes | Prevent context exhaustion |
| Single simple task | ❌ No | Adds latency |
## Usage Example
### Delegating Work to Subagents
**User Request**:
```
"Build a new authentication feature"
```
**Main Agent Workflow**:
```markdown
Main Agent receives: "Build a new authentication feature"
1. Delegates to implementation-agent:
"Implement JWT-based authentication with refresh tokens"
2. Delegates to code-reviewer:
"Review the auth implementation for security issues"
3. Delegates to test-engineer:
"Create comprehensive tests for auth flows"
4. Delegates to documentation-writer:
"Document the authentication API"
5. Synthesis:
Combines all results:
- ✅ Implementation complete
- ✅ Security reviewed
- ✅ Tests created (85% coverage)
- ✅ Documentation generated
Returns to user: Complete authentication feature with all components
```
---
## Related Concepts
### Related Features
- **[Slash Commands](../01-slash-commands/)** - Quick user-invoked shortcuts
- **[Memory](../03-memory/)** - Persistent cross-session context
- **[MCP Protocol](../04-mcp-protocol/)** - Real-time external data access
- **[Agent Skills](../05-agent-skills/)** - Reusable autonomous capabilities
- **[Plugins](../06-plugins/)** - Bundled extension packages
### Comparison with Other Features
| Feature | User-Invoked | Auto-Invoked | Persistent | External Access | Isolated Context |
|---------|--------------|--------------|-----------|------------------|------------------|
| **Slash Commands** | ✅ Yes | ❌ No | ❌ No | ❌ No | ❌ No |
| **Subagents** | ❌ No | ✅ Yes | ❌ No | ❌ No | ✅ Yes |
| **Memory** | ❌ Auto | ✅ Auto | ✅ Yes | ❌ No | ❌ No |
| **MCP** | ❌ Auto | ✅ Yes | ❌ No | ✅ Yes | ❌ No |
| **Skills** | ❌ No | ✅ Yes | ❌ No | ❌ No | ❌ No |
### Integration Pattern
```mermaid
graph TD
User["User Request"] --> Main["Main Agent"]
Main -->|Uses| Memory["Memory<br/>(Context)"]
Main -->|Queries| MCP["MCP<br/>(Live Data)"]
Main -->|Invokes| Skills["Skills<br/>(Auto Tools)"]
Main -->|Delegates| Subagents["Subagents<br/>(Specialists)"]
Subagents -->|Use| Memory
Subagents -->|Query| MCP
Subagents -->|Isolated| Context["Clean Context<br/>Window"]
```
---
## Quick Reference
### Create a Custom Subagent
```yaml
---
name: my-specialist
description: What this agent does
tools: read, grep
---
# My Specialist Agent
You are specialized in [domain].
## Your Role
[Detailed role description]
## Guidelines
[Key guidelines and constraints]
```
### Delegate to a Subagent
```markdown
Main agent asks subagent:
"Please [task description] with focus on [specific goals]"
Context provided:
- Relevant code files
- Project context
- Specific requirements
```
### Subagent Returns
```markdown
Subagent provides:
- Analysis or implementation
- Structured findings
- Recommendations
- Code examples or output
```
---
## Resources
- [Claude Code Documentation](https://docs.claude.com/en/docs/claude-code/overview)
- [Subagents in Claude Concepts Guide](../claude_concepts_guide.md#subagents)
- [Agent Skills Guide](../05-agent-skills/)
- [Memory and Context](../03-memory/)
---
*Last updated: November 8, 2025*
*This guide covers complete subagent configuration, delegation patterns, and best practices for Claude Code.*