claude-code-templates 1.21.0 → 1.21.1

package/cli-tool/docs_to_claude/SUBAGENTS_GUIDE.md

@@ -0,0 +1,566 @@
+# 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.