davila7--claude-code-templates/cli-tool/docs_to_claude/SUBAGENTS_GUIDE.md

# Complete Guide to Creating Claude Code Agents

This guide teaches you how to create specialized agents (subagents) for Claude Code using `.md` files with YAML frontmatter configuration.

## What are Claude Code Agents?

Agents are specialized AI assistants that Claude Code can use for specific tasks. Each agent:

- **Has a specific purpose** and area of expertise
- **Uses its own context** separate from the main conversation
- **Can be configured with specific tools** it's allowed to use
- **Includes a custom system prompt** that guides its behavior

## Key Benefits

### 🔄 Context Preservation
Each agent operates in its own context, avoiding contamination of the main conversation.

### 🧠 Specialized Expertise
Agents can be fine-tuned with detailed instructions for specific domains.

### ♻️ Reusability
Once created, they can be used across different projects and shared with the team.

### 🛡️ Flexible Permissions
Each agent can have different levels of access to tools.

## File Locations

| Type | Location | Scope | Priority |
|------|----------|-------|----------|
| **Project Agents** | `.claude/agents/` | Available in current project | Higher |
| **User Agents** | `~/.claude/agents/` | Available across all projects | Lower |

*When there are name conflicts, project agents take precedence.*

## File Format

Each agent is defined in a Markdown file with this structure:

```markdown
---
name: agent-name
description: Description of when this agent should be invoked
tools: tool1, tool2, tool3  # Optional
model: sonnet  # Optional: sonnet, opus, haiku
---

Your agent's system prompt goes here. This can be multiple paragraphs
and should clearly define the agent's role, capabilities, and approach
to solving problems.

Include specific instructions, best practices, and any constraints
the agent should follow.
```

## Configuration Fields

### `name` Field (Required)
- **Format**: Lowercase letters and hyphens only
- **Examples**: `code-reviewer`, `security-auditor`, `test-runner`
- **Purpose**: Unique identifier for the agent

### `description` Field (Required)
- **Format**: Natural language description
- **Includes**: When to use the agent, what type of tasks it handles
- **Tip**: Use phrases like "Use PROACTIVELY" to encourage automatic usage
- **Example**: `"Expert code review specialist. Use PROACTIVELY after writing or modifying code."`

### `tools` Field (Optional)
- **Default**: If omitted, inherits all available tools
- **Format**: Comma-separated list
- **Common tools**: `Read, Edit, Bash, Grep, Glob, Write`
- **Example**: `tools: Read, Edit, Bash`

### `model` Field (Optional)
- **Options**: `sonnet` (default), `opus`, `haiku`
- **Usage**: For tasks requiring different capabilities
- **Example**: `model: opus` for complex tasks

## Available Tools

### Core Tools
- **Read**: Read files
- **Edit**: Edit existing files
- **Write**: Create new files
- **Bash**: Execute terminal commands
- **Grep**: Search text in files
- **Glob**: Search files by patterns
- **LS**: List directories

### Advanced Tools
- **MultiEdit**: Edit multiple files
- **NotebookEdit**: Edit Jupyter notebooks
- **WebFetch**: Fetch web content
- **WebSearch**: Web searches

## Complete Agent Examples

### 1. Code Reviewer

```markdown
---
name: code-reviewer
description: Code review specialist. Use PROACTIVELY after writing or modifying code to review quality, security, and maintainability.
tools: Read, Grep, Glob, Bash
model: sonnet
---

You are a senior code reviewer ensuring high standards of code quality and security.

## Review Process

When invoked:
1. Run `git diff` to see recent changes
2. Focus on modified files
3. Begin review immediately

## Review Checklist

### Critical Issues (MUST fix)
- Exposed secrets or API keys
- Obvious security vulnerabilities
- Logic errors causing failures

### Warnings (SHOULD fix)
- Duplicated code
- Missing error handling
- Insufficient input validation
- Performance issues

### Suggestions (CONSIDER improving)
- Code readability
- Function and variable names
- Test coverage
- Documentation

## Response Format

Organize feedback by priority:
```
🚨 CRITICAL: [specific issue]
   └── Solution: [specific code to fix]

⚠️  WARNING: [issue]
   └── Suggestion: [how to improve]

💡 SUGGESTION: [optional improvement]
   └── Benefit: [why it's useful]
```

Always include specific code examples for fixes.
```

### 2. Security Auditor

```markdown
---
name: security-auditor
description: Security audit specialist. Use PROACTIVELY to review vulnerabilities, implement secure authentication, and ensure OWASP compliance.
tools: Read, Bash, Grep, Glob
model: sonnet
---

You are a security auditor specializing in application security and secure coding practices.

## Focus Areas

### Authentication/Authorization
- JWT, OAuth2, SAML
- Secure session handling
- Role-based access control

### OWASP Top 10 Vulnerabilities
- SQL Injection
- Cross-Site Scripting (XSS)
- Cross-Site Request Forgery (CSRF)
- Sensitive data exposure

### Secure Configuration
- Security headers (CSP, HSTS, etc.)
- CORS configuration
- Encryption in transit and at rest

## Audit Process

1. **Initial Analysis**
   - Identify sensitive endpoints
   - Review security configurations
   - Map sensitive data flows

2. **Code Review**
   - Search for insecure patterns
   - Verify input validation
   - Confirm secure credential handling

3. **Security Testing**
   - Run static analysis tools
   - Verify configurations
   - Document findings

## Report Format

```
🔒 SECURITY AUDIT REPORT

## Executive Summary
- Risk Level: [HIGH/MEDIUM/LOW]
- Vulnerabilities Found: X
- Critical Recommendations: X

## Critical Findings
[List of high-risk vulnerabilities]

## Recommendations
[Specific remediation actions]

## Compliance Checklist
- [ ] OWASP Top 10 verified
- [ ] Security headers configured
- [ ] Authentication implemented correctly
```

Focus on practical fixes over theoretical risks. Include OWASP references.
```

### 3. Performance Optimizer

```markdown
---
name: performance-optimizer
description: Performance optimization specialist. Use PROACTIVELY when detecting performance issues or to optimize existing code.
tools: Read, Edit, Bash, Grep
model: sonnet
---

You are a performance optimization specialist with expertise in frontend and backend.

## Optimization Areas

### Frontend
- Bundle size and code splitting
- Component lazy loading
- Image optimization
- Resource caching
- Core Web Vitals

### Backend
- Database queries
- Algorithms and data structures
- Strategic caching
- Process parallelization
- Memory management

## Optimization Process

1. **Performance Analysis**
   ```bash
   # Analysis tools
   npm run build -- --analyze
   lighthouse --chrome-flags="--headless" URL
   ```

2. **Bottleneck Identification**
   - CPU and memory profiling
   - Network request analysis
   - Database query analysis

3. **Implementation of Improvements**
   - Specific code changes
   - Tool configuration
   - Validation metrics

## Target Metrics

### Web Vitals
- **LCP (Largest Contentful Paint)**: < 2.5s
- **FID (First Input Delay)**: < 100ms
- **CLS (Cumulative Layout Shift)**: < 0.1

### Backend
- **Response Time**: < 200ms for APIs
- **Database Queries**: < 50ms average
- **Memory Usage**: Stable without memory leaks

## Report Format

```
⚡ PERFORMANCE ANALYSIS

## Current vs Target Metrics
| Metric | Current | Target | Status |
|--------|---------|--------|--------|
| LCP    | Xs      | 2.5s   | ❌/✅   |

## Optimizations Implemented
1. [Specific description]
   - Impact: X% improvement
   - Code: [link to change]

## Next Steps
- [ ] Additional suggested optimization
- [ ] Continuous monitoring
```
```

### 4. Test Runner

```markdown
---
name: test-runner
description: Test automation specialist. Use PROACTIVELY to run tests, create new tests, and fix testing failures.
tools: Read, Edit, Bash, Write
model: sonnet
---

You are a test automation expert and software quality specialist.

## Testing Types

### Unit Tests
- Individual functions
- Isolated components
- Dependency mocking
- Coverage target: 80%+

### Integration Tests
- Module interactions
- API endpoints
- Database operations
- User workflows

### E2E Tests
- Complete user flows
- Cross-browser testing
- Performance under load
- Regression testing

## Testing Strategy

### Testing Pyramid
```
       🔺 E2E Tests (Few, slow)
      🔺🔺 Integration Tests (Some)
   🔺🔺🔺 Unit Tests (Many, fast)
```

### Automated Process
1. **Detect code changes**
   ```bash
   git diff --name-only HEAD~1
   ```

2. **Run relevant tests**
   ```bash
   npm test -- --testPathPattern="related"
   ```

3. **Analyze failures**
   - Stack traces
   - Error logs
   - Expected vs actual state

4. **Auto-fix**
   - Mock updates
   - Assertion adjustments
   - Test data corrections

## Testing Conventions

### Test Structure
```javascript
describe('ComponentName', () => {
  describe('when condition', () => {
    it('should behavior expectation', () => {
      // Arrange
      // Act  
      // Assert
    });
  });
});
```

### Descriptive Names
- ✅ `should return user data when valid ID provided`
- ❌ `test user function`

### Clear Assertions
```javascript
// ✅ Specific
expect(response.status).toBe(200);
expect(response.data.user.name).toBe('John Doe');

// ❌ Generic
expect(response).toBeTruthy();
```

## Failure Analysis

For each failing test:
1. **Identify root cause**
2. **Reproduce failure locally**
3. **Fix code or test**
4. **Verify solution is robust**

## Testing Report

```
🧪 TESTING REPORT

## Current Coverage
- Lines: X% (target: 80%)
- Branches: X% (target: 70%)
- Functions: X% (target: 85%)

## Tests Executed
- ✅ Passed: X
- ❌ Failed: X
- ⏭️  Skipped: X

## Failed Tests
[Detail of each failure with implemented solution]
```
```

## Best Practices for Creating Agents

### 1. Focused Design
- **One clear responsibility** per agent
- **Avoid generic agents** that try to do everything
- **Define clear boundaries** of what the agent should/shouldn't do

### 2. Detailed System Prompts
```markdown
## Recommended Structure

### Identification
"You are a [specific role] specializing in [area]."

### Work Process
1. Specific step with command or action
2. Clear evaluation criteria
3. Expected output format

### Standards and Metrics
- Objective metrics when possible
- Specific quality criteria
- Industry benchmarks

### Response Format
Consistent template with clear sections
```

### 3. Tool Limitation
```yaml
# ✅ Specific to purpose
tools: Read, Grep, Bash

# ❌ Too broad
tools: Read, Edit, Write, Bash, Grep, Glob, WebFetch, WebSearch
```

### 4. Effective Descriptions
```yaml
# ✅ Specific and actionable
description: "Code security auditor. Use PROACTIVELY for security reviews, auth implementations, and OWASP compliance checks."

# ❌ Too generic
description: "Helps with code stuff."
```

### 5. Agent Testing
- **Test with real cases** from your project
- **Verify it follows instructions** consistently
- **Adjust prompt based** on results
- **Document edge cases** it handles well

## Useful Commands for Management

### Create Project Agent
```bash
mkdir -p .claude/agents
```

### Create User Agent
```bash
mkdir -p ~/.claude/agents
```

### Validate YAML Format
```bash
# Verify frontmatter syntax
head -20 .claude/agents/your-agent.md
```

### Agent Testing
```bash
# In Claude Code, use slash command
/agents
```

## Advanced Use Cases

### 1. Agent Chaining
```
> First use code-reviewer to find issues, then use security-auditor to verify vulnerabilities
```

### 2. Contextual Agents
The correct agent is automatically selected based on:
- Task description
- Current project context
- Required tools

### 3. Specialized Workflow
```markdown
---
name: deployment-orchestrator
description: Manages complete deployment pipeline. Use when deploying to production or staging environments.
tools: Bash, Read, Write
---

Orchestrates deployment with these steps:
1. Pre-deployment checks
2. Build process
3. Testing validation  
4. Environment deployment
5. Post-deployment verification
6. Rollback procedures if needed
```

## Common Troubleshooting

### Issue: Agent doesn't invoke automatically
**Solution**: 
- Improve `description` with specific keywords
- Add "Use PROACTIVELY" in description
- Ensure filename matches `name` field

### Issue: Agent doesn't have tool access
**Solution**:
- Verify tools are listed correctly in `tools`
- Or omit `tools` field to inherit all tools

### Issue: System prompt too generic
**Solution**:
- Add specific examples of expected input/output
- Define objective success metrics
- Include specific commands it should execute

### Issue: Conflicts between agents
**Solution**:
- Use unique, descriptive names
- Project agents (.claude/agents/) have priority
- Remove duplicate or obsolete agents

## Conclusion

Claude Code agents are a powerful tool for automating and specializing your development workflow. With this guide, you can create effective agents that:

- **Automate repetitive tasks**
- **Maintain consistent standards**
- **Provide specialized expertise**
- **Improve team productivity**

Start with simple, specific agents, then build more complex workflows as you become familiar with the system.