# Agent Best Practices Design principles and patterns for creating effective sub-agents. ## Core Design Principles ### 1. Single Responsibility Principle **Do**: Create focused agents with one clear purpose ```markdown --- name: sql-query-reviewer description: Review SQL queries for performance issues and suggest optimizations --- ``` **Don't**: Create catch-all agents ```markdown --- name: database-helper description: Help with any database-related tasks --- ``` **Why**: Focused agents trigger correctly and produce better results. ### 2. Explicit Trigger Conditions **Do**: Use specific, action-oriented descriptions with trigger keywords ```markdown description: Use PROACTIVELY after writing tests to check for common testing anti-patterns like mocking implementation details ``` **Don't**: Use vague descriptions ```markdown description: A testing expert ``` **Why**: Claude's routing mechanism uses description to decide when to invoke agents. ### 3. Principle of Least Privilege **Do**: Grant only necessary tools ```markdown # Read-only security auditor tools: Read, Grep, Glob ``` **Don't**: Give all tools by default ```markdown # Unnecessary full access tools: Read, Write, Edit, Bash, Grep, Glob ``` **Why**: Limits blast radius if agent behaves unexpectedly. ### 4. Detailed Instructions **Do**: Provide step-by-step guidance ```markdown ## Analysis Process 1. Read the error message and stack trace 2. Identify the failing line of code 3. Read surrounding context (10 lines before/after) 4. Check recent changes using git blame 5. Propose specific fix with explanation ``` **Don't**: Give vague guidance ```markdown Debug the error and fix it. ``` **Why**: Detailed instructions yield consistent, high-quality results. ### 5. Output Structure **Do**: Define explicit output format ```markdown ## Output Format # Bug Analysis ## Root Cause [One sentence summary] ## Details [Full explanation] ## Proposed Fix ```[language] [exact code change] ``` ## Verification [how to test the fix] ``` **Don't**: Leave output format unspecified ```markdown Analyze the bug and suggest a fix. ``` **Why**: Consistent outputs are easier to act on and integrate. ## Naming Conventions ### Good Agent Names - `rails-code-reviewer` - Specific technology and task - `sql-query-optimizer` - Clear action and domain - `security-vulnerability-scanner` - Explicit purpose - `test-coverage-analyzer` - Measurable outcome - `api-doc-generator` - Clear deliverable ### Bad Agent Names - `helper` - Too generic - `my-agent` - Not descriptive - `agent1` - No indication of purpose - `CodeAgent` - Not lowercase-with-hyphens - `do-everything` - Violates single responsibility ### Naming Pattern ``` [technology/domain]-[action/purpose] Examples: - docker-container-optimizer - python-type-hint-generator - kubernetes-manifest-validator - git-commit-message-writer ``` ## Description Patterns ### Pattern 1: Trigger Keywords Include specific words that signal when agent should activate: ```markdown description: Use when encountering SQL queries with EXPLAIN showing high cost or missing indexes ``` **Triggers**: "SQL", "EXPLAIN", "high cost", "missing indexes" ### Pattern 2: Proactive Invocation Use "PROACTIVELY" or "MUST BE USED" for automatic triggering: ```markdown description: Use PROACTIVELY after code changes to review for security vulnerabilities ``` **Effect**: Claude invokes automatically after code modifications. ### Pattern 3: Conditional Use Specify when agent applies vs doesn't: ```markdown description: Use for Python code performance optimization, especially when profiling shows bottlenecks. Do not use for Go or Rust code. ``` **Effect**: Clear boundaries prevent misuse. ### Pattern 4: Input/Output Signal Describe inputs and expected outputs: ```markdown description: Analyze git diff output to generate semantic, conventional commit messages following Angular style guide ``` **Triggers**: "git diff", "commit messages", "Angular style" ## Tool Selection Guidelines ### Read-Only Agents (Security/Audit) ```yaml tools: Read, Grep, Glob ``` **Use for**: Security auditing, code review, analysis **Rationale**: Can't accidentally modify code ### Code Modifiers ```yaml tools: Read, Edit, Bash ``` **Use for**: Refactoring, fixing bugs, applying changes **Rationale**: Can read context and make surgical edits ### Exploratory Agents ```yaml tools: Read, Grep, Glob, Bash ``` **Use for**: Debugging, investigation, running tests **Rationale**: Needs to explore codebase and run commands ### Full Access Agents ```yaml # Omit tools field to inherit all tools ``` **Use for**: Complex workflows, multi-step tasks **Rationale**: Needs flexibility for varied tasks ### Restricted Agents ```yaml tools: Bash ``` **Use for**: Infrastructure tasks, running specific commands **Rationale**: Focused on execution, not code manipulation ## Model Selection ### When to Use Haiku - Simple, repetitive tasks - Fast turnaround needed - Lower cost priority - Clear, deterministic workflows **Examples**: Formatting, linting, simple validation ### When to Use Sonnet (Default) - Balanced performance and speed - Most general-purpose tasks - Standard code review/debugging - Moderate complexity **Examples**: Code review, debugging, optimization ### When to Use Opus - Complex reasoning required - Critical decisions - Security-sensitive tasks - High accuracy needed **Examples**: Security audits, architectural decisions, complex refactoring ### When to Inherit - Agent should match main conversation capability - User may switch models - No specific model requirement **Examples**: General helpers, documentation ## System Prompt Patterns ### Pattern 1: Process-Oriented Define step-by-step workflow: ```markdown ## Process 1. **Gather Context**: Read all relevant files 2. **Identify Issues**: List problems found 3. **Prioritize**: Order by severity 4. **Propose Solutions**: Specific fixes 5. **Document**: Clear explanation ``` **Use for**: Agents with clear workflows ### Pattern 2: Checklist-Based Provide systematic checks: ```markdown ## Security Checklist - [ ] No SQL injection vulnerabilities - [ ] Authentication on protected routes - [ ] Input validation present - [ ] Secrets not in code - [ ] HTTPS enforced ``` **Use for**: Audit and validation agents ### Pattern 3: Example-Driven Show examples of good outputs: ```markdown ## Example Output ### Good Example **Input**: User implements login endpoint **Output**: ✅ Strengths: Proper password hashing ⚠️ Issue: Missing rate limiting 💡 Suggestion: Add rack-attack gem ``` **Use for**: Agents where output format is crucial ### Pattern 4: Constraint-First Lead with what NOT to do: ```markdown ## Constraints - NEVER modify tests to make them pass - DO NOT suggest rewrites without justification - AVOID proposing multiple solutions - pick best - NO generic advice - be specific ``` **Use for**: Agents that might overstep bounds ## Common Pitfalls ### Pitfall 1: Too Generic **Problem**: Agent never triggers or triggers too often **Solution**: Add specific trigger keywords and domain constraints ### Pitfall 2: Unclear Output **Problem**: Agent responses are inconsistent **Solution**: Define explicit output format with examples ### Pitfall 3: Scope Creep **Problem**: Agent tries to do too much **Solution**: Split into multiple focused agents ### Pitfall 4: Missing Context **Problem**: Agent doesn't have enough information **Solution**: Specify what context to gather first ### Pitfall 5: Over-Engineering **Problem**: Agent is too complex **Solution**: Start simple, add complexity only when needed ## Testing Your Agent ### Test Cases to Cover 1. **Happy Path**: Agent works as expected 2. **Edge Cases**: Unusual but valid inputs 3. **Error Handling**: Invalid or missing inputs 4. **Scope Boundaries**: When agent should NOT trigger 5. **Tool Limitations**: Agent lacks necessary permissions ### Testing Checklist - [ ] Test with explicit invocation: "Use [agent-name] to..." - [ ] Test with implicit trigger: Describe task without naming agent - [ ] Test with minimal input - [ ] Test with complex input - [ ] Test when agent shouldn't trigger - [ ] Test with insufficient permissions (if tools limited) - [ ] Verify output format matches specification - [ ] Check output quality and usefulness ### Iteration Process 1. **Initial Test**: Try basic functionality 2. **Identify Gaps**: What doesn't work? 3. **Refine Prompt**: Add missing instructions 4. **Add Examples**: Show what good looks like 5. **Test Again**: Verify improvements 6. **Repeat**: Until agent is reliable ## Documentation Standards ### Minimum Documentation Every agent should include: ```markdown --- name: agent-name description: When to use this agent --- # Agent Purpose [What it does] ## Core Responsibilities [Main tasks] ## Approach [How it works] ## Output Format [What it produces] ## Constraints [What it won't do] ``` ### Enhanced Documentation For complex agents, add: - Input validation rules - Error handling approach - Edge case handling - Examples (good and bad) - Troubleshooting tips - Related agents - Version history ## Performance Considerations ### Context Window Management - Agents start with fresh context - May need to re-read files - Consider token costs for large codebases **Optimization**: Provide clear file paths in description ### Token Efficiency - Concise system prompts are faster - But clarity > brevity - Use examples judiciously **Balance**: Detailed enough to work, concise enough to load quickly ### Caching Benefits - Repeated invocations may benefit from caching - System prompt is cacheable - Frequently accessed files may be cached **Note**: Implementation-specific, but generally beneficial ## Version Control Best Practices ### Project Agents ✅ **Do Commit**: - `.claude/agents/*.md` - All project agents - Document in README when to use each agent ❌ **Don't Commit**: - User-specific agents from `~/.claude/agents/` - API keys or secrets (should be in env vars) ### User Agents - Keep in `~/.claude/agents/` for personal use - Back up separately (not in project repos) - Share via documentation/templates if useful to others ## Sharing Agents ### With Your Team 1. Commit to `.claude/agents/` in project 2. Document in project README 3. Add trigger examples 4. Provide test cases ### With Community 1. Create template repository 2. Include: - Agent file with clear comments - README with usage examples - Test cases or fixtures - License information 3. Share on forums/communities ## Maintenance ### When to Update - Agent triggers incorrectly (too often/rarely) - Output format changes - New tool becomes available - Domain knowledge evolves - Team feedback indicates issues ### Update Checklist - [ ] Update description/triggers - [ ] Revise system prompt - [ ] Add new examples - [ ] Update tool permissions - [ ] Test thoroughly - [ ] Document changes - [ ] Notify team (if shared) ### Deprecation When agent is no longer needed: 1. Add deprecation notice to file 2. Suggest replacement agent (if any) 3. Set sunset date 4. Remove after team transitions 5. Archive for reference ## Advanced Patterns ### Chained Agents Design agents that work in sequence: 1. `code-analyzer` → identifies issues 2. `code-fixer` → applies fixes 3. `test-runner` → verifies fixes **Use for**: Complex multi-step workflows ### Specialized + General Pair specific and general agents: - `rails-code-reviewer` (specific) - `code-reviewer` (general fallback) **Use for**: Covering multiple domains ### Hierarchical Agents Create parent-child relationships: - `security-auditor` (parent) - `sql-injection-scanner` (child) - `xss-scanner` (child) - `auth-checker` (child) **Use for**: Breaking down complex domains --- ## Quick Reference ### Agent Creation Checklist - [ ] Name: lowercase-with-hyphens, descriptive - [ ] Description: specific triggers, action-oriented - [ ] Tools: minimal necessary permissions - [ ] Model: appropriate for task complexity - [ ] System prompt: detailed, structured - [ ] Examples: show good outputs - [ ] Constraints: explicit boundaries - [ ] Output format: clearly defined - [ ] Tested: multiple scenarios - [ ] Documented: usage and purpose ### Common Patterns | Pattern | When to Use | |---------|-------------| | Process-oriented | Clear workflow steps | | Checklist-based | Systematic validation | | Example-driven | Output format matters | | Constraint-first | Agent might overstep | ### Tool Combinations | Combination | Use Case | |-------------|----------| | Read, Grep, Glob | Analysis/audit only | | Read, Edit | Surgical code changes | | Read, Edit, Bash | Refactoring + testing | | Bash | Infrastructure/ops | | All tools (inherited) | Complex workflows | --- **See Also**: - [Configuration Guide](./configuration-guide.md) - [Agent Examples](./agent-examples.md) - [Troubleshooting](./troubleshooting.md)