shirokuma-docs 0.1.0-alpha.1

package/plugin/shirokuma-skills-en/skills/managing-agents/best-practices-advanced.md

@@ -0,0 +1,326 @@
+# Advanced Agent Patterns
+
+Advanced patterns for testing, optimization, and security. For core principles and design, see [best-practices.md](best-practices.md).
+
+## Table of Contents
+
+- [Common Anti-Patterns](#common-anti-patterns)
+- [Testing Agents](#testing-agents)
+- [Performance Optimization](#performance-optimization)
+- [Security Considerations](#security-considerations)
+
+---
+
+## Common Anti-Patterns
+
+### 1. The Kitchen Sink Agent
+
+**Problem**: Agent does too many things
+
+```yaml
+# ❌ Bad
+name: super-agent
+description: Reviews code, writes tests, generates docs, debugs issues, and deploys.
+tools: All
+```
+
+**Fix**: Split into focused agents
+
+```yaml
+# ✅ Good
+name: code-reviewer
+description: Reviews code quality. Use for code reviews only.
+tools: Read, Grep, Glob
+
+name: test-generator
+description: Generates test suites. Use for test creation only.
+tools: Read, Write, Bash
+```
+
+### 2. The Vague Workflow
+
+**Problem**: Instructions too generic
+
+```markdown
+## Workflow
+1. Analyze the code
+2. Find issues
+3. Report findings
+```
+
+**Fix**: Specific, actionable steps
+
+```markdown
+## Workflow
+1. **Locate Files**: Use Glob("src/**/*.ts") to find source files
+2. **Check Each File**:
+   - Load with Read tool
+   - Search for `console.log` patterns
+   - Flag files with production console statements
+3. **Generate Report**: List each finding as `file:line: description`
+```
+
+### 3. The Over-Privileged Agent
+
+**Problem**: More tools than needed
+
+```yaml
+# ❌ A reviewer that can modify code
+name: code-reviewer
+tools: Read, Write, Edit, Bash, WebFetch
+```
+
+**Fix**: Minimum necessary tools
+
+```yaml
+# ✅ Read-only reviewer
+name: code-reviewer
+tools: Read, Grep, Glob, Bash
+```
+
+### 4. The Invisible Agent
+
+**Problem**: Poor description, never invoked
+
+```yaml
+# ❌ No triggers
+description: Handles TypeScript stuff
+```
+
+**Fix**: Clear triggers and purpose
+
+```yaml
+# ✅ Clear invocation
+description: Migrates JavaScript files to TypeScript. Use when user asks to "convert to TypeScript" or "add types to JS files".
+```
+
+### 5. The Missing Output Format
+
+**Problem**: Inconsistent, unpredictable output
+
+```markdown
+## Workflow
+...
+4. Report the findings
+```
+
+**Fix**: Explicit output structure
+
+```markdown
+## Output Format
+
+\```
+# Review Report: [Component]
+
+## Summary
+- Files analyzed: X
+- Issues found: Y
+
+## Critical Issues
+1. [file:line] - [issue description]
+
+## Recommendations
+- [actionable suggestion]
+\```
+```
+
+### 6. Framework Over-Reliance
+
+**Problem**: Using frameworks without understanding underlying code
+
+> "If you do use a framework, ensure you understand the underlying code. Incorrect assumptions about what's under the hood are a common source of customer error." — Anthropic
+
+```markdown
+# ❌ Black-box framework usage
+agent = SomeFramework.create_agent(config)
+# No understanding of what happens inside
+```
+
+**Fix**: Start with LLM APIs directly
+
+```markdown
+# ✅ Direct implementation
+# Many patterns require just a few lines of code
+response = await llm.call(prompt)
+# Clear, debuggable, understandable
+```
+
+---
+
+## Testing Agents
+
+### Manual Testing Checklist
+
+1. **Trigger Testing**
+   - [ ] Direct invocation: "Use the [agent] agent"
+   - [ ] Keyword triggers from description
+   - [ ] Edge case phrases
+
+2. **Workflow Testing**
+   - [ ] Each step executes correctly
+   - [ ] Tools used appropriately
+   - [ ] Error handling works
+
+3. **Output Testing**
+   - [ ] Format matches specification
+   - [ ] Content is accurate
+   - [ ] Actionable recommendations
+
+### Test Scenarios
+
+Create test cases for each agent:
+
+```markdown
+## Test Cases for code-reviewer
+
+### Case 1: Clean Code
+Input: Well-written TypeScript file
+Expected: No issues, positive feedback
+
+### Case 2: Security Vulnerability
+Input: File with SQL injection
+Expected: Critical issue flagged with CWE reference
+
+### Case 3: Style Issues
+Input: Inconsistent formatting
+Expected: Medium priority suggestions
+```
+
+### Iteration Process
+
+1. Create agent
+2. Test with sample inputs
+3. Identify gaps in workflow/output
+4. Update system prompt
+5. Repeat until consistent
+
+---
+
+## Performance Optimization
+
+### Research-Plan-Execute Workflow
+
+From [Claude Code Best Practices](https://www.anthropic.com/engineering/claude-code-best-practices):
+
+> "Asking Claude to research and plan first significantly improves performance for problems requiring deeper thinking upfront."
+
+```markdown
+## Workflow
+1. **Research**: Explore codebase, understand context
+2. **Plan**: Design approach before coding
+3. **Execute**: Implement with plan as guide
+```
+
+### Lightweight vs Heavy Agents
+
+| Agent Type | Token Usage | Impact |
+|------------|-------------|--------|
+| **Lightweight** (<3k tokens) | Low | Fluid orchestration, fast chainability |
+| **Heavy** (25k+ tokens) | High | Bottlenecks in multi-agent workflows |
+
+**Recommendation**: Start with lightweight agents (minimal tools). Add complexity only when needed.
+
+### Subagent Strategy
+
+> "Strong use of subagents is recommended, especially for complex problems." — Anthropic
+
+- Use subagents to verify details early in conversation
+- Preserves context availability
+- Minimal efficiency downside
+
+### Reduce Token Usage
+
+**Use directory format** for complex agents:
+- Core prompt in AGENT.md (< 500 lines)
+- Details loaded only when needed
+
+**Link instead of inline**:
+```markdown
+# ❌ Inline everything
+## Security Checks
+[2000 lines of OWASP details]
+
+# ✅ Link to reference
+## Security Checks
+Apply OWASP Top 10 checks. See [reference.md](reference.md#owasp) for complete list.
+```
+
+### Model Selection
+
+| Task | Model | Reason |
+|------|-------|--------|
+| Simple file operations | haiku | Fast, cheap |
+| Standard analysis | sonnet | Balanced |
+| Complex reasoning | opus | Higher quality |
+
+### Parallel Execution
+
+For orchestrator agents:
+```markdown
+## Workflow
+1. **Parallel Analysis**: Launch these agents simultaneously:
+   - security-auditor
+   - performance-analyzer
+   - code-reviewer
+2. **Aggregate**: Combine results after all complete
+```
+
+### Multi-Context Window Workflows
+
+For projects that can't be completed in a single context window:
+
+1. **Initializer Agent**: Sets up environment on first run
+2. **Coding Agent**: Makes incremental progress
+3. **Artifacts**: Leave clear artifacts for next session (TODOs, state files)
+
+---
+
+## Security Considerations
+
+### Tool Access Principles
+
+1. **Read-only by default**: Start with Read, Grep, Glob
+2. **Add Write only when needed**: Generation tasks
+3. **Bash access carefully**: Only for running tests/linters
+4. **Never bypassPermissions**: Unless absolutely necessary
+
+### Permission Modes
+
+| Mode | Use Case | Risk Level |
+|------|----------|------------|
+| `default` | Most agents | Low |
+| `acceptEdits` | Trusted transformers | Medium |
+| `bypassPermissions` | Automated pipelines only | High |
+
+### Sensitive Operations
+
+Guard in system prompt:
+```markdown
+## Safety Rules
+
+1. **Never modify**:
+   - .env files
+   - Credential files
+   - Production configs
+
+2. **Always confirm** before:
+   - Deleting files
+   - Running destructive commands
+   - Modifying authentication code
+
+3. **Log all changes**:
+   - Report every file modified
+   - Include before/after for edits
+```
+
+### Input Validation
+
+For agents accepting user input:
+```markdown
+## Input Validation
+
+Before processing user-provided paths:
+1. Verify path is within project directory
+2. Reject paths containing `..`
+3. Reject absolute paths outside workspace
+```

package/plugin/shirokuma-skills-en/skills/managing-agents/best-practices.md

@@ -0,0 +1,276 @@
+# Agent Best Practices
+
+Core patterns based on [Anthropic's "Building Effective Agents"](https://www.anthropic.com/engineering/building-effective-agents) and [Claude Code Best Practices](https://www.anthropic.com/engineering/claude-code-best-practices).
+
+## Table of Contents
+
+- [Core Principles](#core-principles)
+- [ACI: Agent-Computer Interface](#aci-agent-computer-interface)
+- [System Prompt Design](#system-prompt-design)
+- [Tool Selection Strategy](#tool-selection-strategy)
+- [Description Optimization](#description-optimization)
+- [Quick Reference](#quick-reference)
+
+For advanced topics, see [best-practices-advanced.md](best-practices-advanced.md):
+- Common Anti-Patterns
+- Testing Agents
+- Performance Optimization
+- Security Considerations
+
+---
+
+## Core Principles
+
+Three fundamental principles from Anthropic:
+
+### 1. Simplicity
+> "Success isn't about building the most sophisticated system—it's about building the right system for your needs."
+
+- Start with the simplest solution
+- Add complexity only when results justify it
+- Many applications need just "optimizing single LLM calls with retrieval and in-context examples"
+
+### 2. Transparency
+- Explicitly show planning steps
+- Make agent reasoning visible
+- Enable human review and intervention
+
+### 3. Agent-Computer Interface (ACI)
+- Design tools as carefully as prompts
+- Test tools extensively
+- Iterate based on model mistakes
+
+---
+
+## ACI: Agent-Computer Interface
+
+> "Think about your agent-computer interface (ACI) the same way you think about a human-computer interface (HCI)."
+
+### Tool Design Guidelines
+
+| Guideline | Example |
+|-----------|---------|
+| **Clear names** | `read_file` not `rf` |
+| **Descriptive docs** | Include when to use, edge cases |
+| **Usage examples** | Show input/output pairs |
+| **Error messages** | Actionable, not cryptic |
+| **Poka-yoke** | Prevent errors before they happen |
+
+### Tool Documentation Template
+
+```markdown
+## tool_name
+
+**Purpose**: [One sentence]
+
+**When to use**: [Specific scenarios]
+
+**Parameters**:
+- `param1` (required): [Description]
+- `param2` (optional): [Description, default: X]
+
+**Returns**: [Format and structure]
+
+**Examples**:
+\```
+Input: { "param1": "value" }
+Output: { "result": "..." }
+\```
+
+**Edge cases**:
+- If X happens, returns Y
+- Does NOT handle Z (use other_tool instead)
+```
+
+### Common Tool Design Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Vague descriptions | Specific use cases |
+| Missing examples | Input/output pairs |
+| No error handling docs | Document failure modes |
+| Overlapping tools | Clear boundaries |
+| Complex parameters | Simple, intuitive inputs |
+
+### Token Efficiency
+
+**Prioritize token efficiency over readability.**
+
+| Avoid | Prefer |
+|-------|--------|
+| ASCII art / box diagrams | Markdown tables, bullet lists |
+| Decorative separators | Headers only |
+| `Last Updated:` stamps | Git history |
+| Verbose explanations | Concise instructions |
+
+- Keep format close to natural text
+- Eliminate formatting overhead (line counting, escaping)
+- Provide sufficient context for reasoning
+
+---
+
+## System Prompt Design
+
+### Structure for Clarity
+
+```markdown
+# Agent Name
+
+[One-sentence role description]
+
+## Core Responsibilities
+- [Specific task 1] (not vague)
+- [Specific task 2]
+
+## Workflow
+1. **Step Name**: [Action] using [Tool]
+   - Decision point: If X, then Y
+   - Output: [Expected result]
+
+## Quality Criteria
+- [Measurable criterion 1]
+- [Measurable criterion 2]
+
+## Output Format
+[Exact structure with example]
+```
+
+### Writing Effective Instructions
+
+**Do**:
+```markdown
+## Workflow
+1. **Scan Files**: Use Glob("**/*.ts") to find TypeScript files
+2. **Check Imports**: For each file, verify imports are used
+3. **Report Unused**: List file:line for each unused import
+```
+
+**Don't**:
+```markdown
+## Workflow
+1. Look at the files
+2. Check for problems
+3. Report findings
+```
+
+### Prompt Length Guidelines
+
+| Agent Complexity | Recommended Length |
+|------------------|-------------------|
+| Simple, focused | 100-300 lines |
+| Standard | 300-500 lines |
+| Complex (use directory) | 500+ split across files |
+
+---
+
+## Tool Selection Strategy
+
+### Principle: Minimum Necessary Access
+
+| Agent Type | Recommended Tools | Avoid |
+|------------|-------------------|-------|
+| Read-only reviewer | Read, Grep, Glob | Write, Edit |
+| File generator | Read, Write | Edit (use Write for new files) |
+| Code transformer | Read, Edit | Write (prefer Edit for changes) |
+| Debugger | Read, Bash, Grep | Write, Edit |
+
+### Tool Combinations
+
+**Analysis agents**:
+```yaml
+tools: Read, Grep, Glob, Bash
+```
+- Bash for running tests/linters only
+- No file modification capability
+
+**Generation agents**:
+```yaml
+tools: Read, Write, Bash
+```
+- Read to understand context
+- Write for new files
+- Bash to run generators/tests
+
+**Transformation agents**:
+```yaml
+tools: Read, Edit, Bash
+```
+- Edit for targeted changes
+- Bash to verify after changes
+
+### Web Access
+
+Only add when specifically needed:
+```yaml
+# Documentation fetcher
+tools: Read, Write, WebFetch
+
+# Research agent
+tools: Read, WebSearch, WebFetch
+```
+
+---
+
+## Description Optimization
+
+### Trigger Phrase Placement
+
+**Good**: Triggers at the end
+```yaml
+description: Reviews code for security vulnerabilities following OWASP Top 10. Use when user asks to "security review", "audit security", or "check vulnerabilities".
+```
+
+**Better**: Rich format with examples
+```yaml
+description: Security auditor for OWASP Top 10 vulnerabilities.
+
+<example>
+Context: User wants security review
+user: "Check auth module for vulnerabilities"
+assistant: "I'll use the security-auditor to analyze the authentication code."
+<Task tool call to security-auditor agent>
+</example>
+```
+
+### Disambiguation
+
+When multiple agents could match:
+
+```yaml
+# Agent 1: code-reviewer
+description: Reviews code for quality, style, and maintainability. Use for general code reviews, NOT security-specific.
+
+# Agent 2: security-auditor
+description: Reviews code for security vulnerabilities (OWASP). Use specifically for security audits, NOT general code quality.
+```
+
+### Proactive Invocation
+
+To encourage automatic use:
+```yaml
+description: Use PROACTIVELY after any feature implementation to ensure code quality. MUST BE USED when PR is ready for review.
+```
+
+---
+
+## Quick Reference
+
+### Agent Quality Checklist
+
+- [ ] Single, clear responsibility
+- [ ] Specific workflow steps
+- [ ] Minimum necessary tools
+- [ ] Clear invocation triggers
+- [ ] Defined output format
+- [ ] Error handling included
+- [ ] Tested with sample inputs
+- [ ] Under 500 lines (or directory format)
+
+### File Size Guidelines
+
+| File | Target Lines |
+|------|-------------|
+| SKILL.md / AGENT.md | < 500 |
+| reference.md | < 800 |
+| examples.md | < 600 |
+| best-practices.md | < 400 |