claude-code-templates 1.21.1 → 1.21.2

package/cli-tool/docs_to_claude/SUBAGENTS_GUIDE.md

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