192 lines
3.3 KiB
Markdown
192 lines
3.3 KiB
Markdown
# Agent Patterns & Best Practices
|
|
|
|
Design patterns and quality guidelines.
|
|
|
|
## Best Practices
|
|
|
|
### Single Responsibility
|
|
|
|
```yaml
|
|
# ✅ Focused
|
|
description: SQL injection vulnerability detector
|
|
|
|
# ❌ Too broad
|
|
description: Security expert for all issues
|
|
```
|
|
|
|
**Why:** Easier to invoke correctly and maintain.
|
|
|
|
### Clear Boundaries
|
|
|
|
```markdown
|
|
## Scope
|
|
|
|
**I handle:**
|
|
- ✅ Security vulnerability detection
|
|
- ✅ Secure coding recommendations
|
|
|
|
**I don't handle:**
|
|
- ❌ Implementation of fixes
|
|
- ❌ Performance optimization
|
|
```
|
|
|
|
**Why:** Prevents confusion, improves invocation accuracy.
|
|
|
|
### Consistent Output
|
|
|
|
```markdown
|
|
## Output Format
|
|
|
|
**For each finding:**
|
|
- Severity: critical|high|medium|low
|
|
- Location: file:line
|
|
- Description: What's vulnerable
|
|
- Remediation: How to fix
|
|
```
|
|
|
|
**Why:** Predictable, parseable results.
|
|
|
|
### Safety First
|
|
|
|
```markdown
|
|
## Safety Protocol
|
|
|
|
Before modifying production:
|
|
1. ✅ Backup verified
|
|
2. ✅ Tested in staging
|
|
3. ✅ Rollback plan ready
|
|
4. ⚠️ Get explicit approval
|
|
```
|
|
|
|
**Why:** Prevents accidents and data loss.
|
|
|
|
### Document Examples
|
|
|
|
```markdown
|
|
## Example Tasks
|
|
|
|
**Good:**
|
|
- "Review auth.service.ts for security issues"
|
|
- "Check JWT implementation"
|
|
|
|
**Not ideal:**
|
|
- "Review everything" (too broad)
|
|
- "Fix bugs" (not my role)
|
|
```
|
|
|
|
**Why:** Helps users work effectively with agent.
|
|
|
|
## Multi-Agent Patterns
|
|
|
|
### Sequential Processing
|
|
|
|
```
|
|
User: "Prepare this code for production"
|
|
|
|
1. Security Agent → Issues found
|
|
2. Fixer Agent → Code updated
|
|
3. Test Agent → Tests created
|
|
4. Quality Agent → Approved
|
|
```
|
|
|
|
**When:** Steps depend on previous results.
|
|
|
|
### Parallel Review
|
|
|
|
```
|
|
User: "Comprehensive code review"
|
|
|
|
┌─ Security Agent → Security report
|
|
├─ Performance Agent → Performance report
|
|
├─ Quality Agent → Quality report
|
|
└─ Test Agent → Coverage report
|
|
|
|
Aggregate → User
|
|
```
|
|
|
|
**When:** Independent reviews, faster results.
|
|
|
|
### Specialist Consultation
|
|
|
|
```
|
|
Main Claude implementing feature
|
|
↓
|
|
Question about security pattern
|
|
↓
|
|
Task(security-expert, "Best pattern for X?")
|
|
↓
|
|
Answer received
|
|
↓
|
|
Continue implementation
|
|
```
|
|
|
|
**When:** Need expert input mid-task.
|
|
|
|
### Iterative Refinement
|
|
|
|
```
|
|
1. Implementation Agent → Creates initial
|
|
2. Review Agent → Finds issues
|
|
3. Implementation Agent → Fixes
|
|
4. Review Agent → Verifies
|
|
5. Repeat until approved
|
|
```
|
|
|
|
**When:** High-quality requirements.
|
|
|
|
## Anti-Patterns
|
|
|
|
### Over-Restriction
|
|
|
|
```yaml
|
|
# ❌ Unnecessary restriction
|
|
tools: Read # Can't even search!
|
|
|
|
# ✅ Appropriate baseline
|
|
tools: Glob, Grep, Read, Skill, Task, TaskCreate, TaskUpdate, TaskList, TaskGet
|
|
```
|
|
|
|
### Vague Description
|
|
|
|
```yaml
|
|
# ❌ Hard to invoke
|
|
description: Helps with code stuff
|
|
|
|
# ✅ Clear triggers
|
|
description: |
|
|
SQL injection detector for user input handling.
|
|
Triggers on query security, input validation, parameterization.
|
|
```
|
|
|
|
### Missing Examples
|
|
|
|
```yaml
|
|
# ❌ No examples
|
|
description: Security reviewer
|
|
|
|
# ✅ With examples
|
|
description: |
|
|
Security reviewer for authentication code.
|
|
|
|
<example>
|
|
user: "Check the login flow"
|
|
assistant: "I'll use security-reviewer agent."
|
|
</example>
|
|
```
|
|
|
|
### Scope Creep
|
|
|
|
```markdown
|
|
# ❌ Does too much
|
|
- Reviews code
|
|
- Fixes issues
|
|
- Writes tests
|
|
- Deploys changes
|
|
- Monitors production
|
|
|
|
# ✅ Focused
|
|
- Reviews code for security issues
|
|
- Reports findings with severity
|
|
- Suggests remediation
|
|
```
|