shirokuma-docs 0.1.0-alpha.1

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

@@ -0,0 +1,318 @@
+# エージェントの高度なパターン
+
+テスト、最適化、セキュリティの高度なパターン。基本原則と設計は [best-practices.md](best-practices.md) を参照。
+
+## 目次
+
+- [よくあるアンチパターン](#よくあるアンチパターン)
+- [エージェントのテスト](#エージェントのテスト)
+- [パフォーマンス最適化](#パフォーマンス最適化)
+- [セキュリティに関する考慮事項](#セキュリティに関する考慮事項)
+
+---
+
+## よくあるアンチパターン
+
+### 1. 何でもエージェント
+
+**問題**: エージェントの責務が多すぎる
+
+```yaml
+# ❌ 悪い例
+name: super-agent
+description: Reviews code, writes tests, generates docs, debugs issues, and deploys.
+tools: All
+```
+
+**修正**: 責務ごとにエージェントを分割
+
+```yaml
+# ✅ 良い例
+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. 曖昧なワークフロー
+
+**問題**: 指示が汎用的すぎる
+
+```markdown
+## Workflow
+1. Analyze the code
+2. Find issues
+3. Report findings
+```
+
+**修正**: 具体的でアクション可能なステップに
+
+```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. 過剰な権限
+
+**問題**: 必要以上のツールアクセス
+
+```yaml
+# ❌ コード変更できるレビューア
+name: code-reviewer
+tools: Read, Write, Edit, Bash, WebFetch
+```
+
+**修正**: 必要最小限のツール
+
+```yaml
+# ✅ 読み取り専用レビューア
+name: code-reviewer
+tools: Read, Grep, Glob, Bash
+```
+
+### 4. 見えないエージェント
+
+**問題**: 説明が不十分で呼び出されない
+
+```yaml
+# ❌ トリガーなし
+description: Handles TypeScript stuff
+```
+
+**修正**: 明確なトリガーと目的
+
+```yaml
+# ✅ 明確な呼び出し条件
+description: Migrates JavaScript files to TypeScript. Use when user asks to "convert to TypeScript" or "add types to JS files".
+```
+
+### 5. 出力形式の未定義
+
+**問題**: 不安定で予測不能な出力
+
+```markdown
+## Workflow
+...
+4. Report the findings
+```
+
+**修正**: 明示的な出力構造
+
+```markdown
+## Output Format
+
+\```
+# Review Report: [Component]
+
+## Summary
+- Files analyzed: X
+- Issues found: Y
+
+## Critical Issues
+1. [file:line] - [issue description]
+
+## Recommendations
+- [actionable suggestion]
+\```
+```
+
+### 6. フレームワークへの過度な依存
+
+**問題**: 内部コードを理解せずフレームワークを使用
+
+> "フレームワークを使用する場合、内部のコードを理解すること。フレームワーク内部への誤った前提はエラーの一般的な原因。" -- Anthropic
+
+**修正**: LLM API を直接使用することから始める
+
+```markdown
+# ✅ 直接実装
+# 多くのパターンは数行のコードで十分
+response = await llm.call(prompt)
+# 明確、デバッグ可能、理解しやすい
+```
+
+---
+
+## エージェントのテスト
+
+### 手動テストチェックリスト
+
+1. **トリガーテスト**
+   - [ ] 直接呼び出し: "Use the [agent] agent"
+   - [ ] 説明文のキーワードトリガー
+   - [ ] エッジケースのフレーズ
+
+2. **ワークフローテスト**
+   - [ ] 各ステップが正しく実行される
+   - [ ] ツールが適切に使用される
+   - [ ] エラー処理が機能する
+
+3. **出力テスト**
+   - [ ] 形式が仕様に一致
+   - [ ] 内容が正確
+   - [ ] 実行可能な推奨事項
+
+### テストシナリオ
+
+```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
+```
+
+### イテレーションプロセス
+
+1. エージェント作成
+2. サンプル入力でテスト
+3. ワークフロー/出力のギャップを特定
+4. システムプロンプトを更新
+5. 安定するまで繰り返し
+
+---
+
+## パフォーマンス最適化
+
+### Research-Plan-Execute ワークフロー
+
+[Claude Code Best Practices](https://www.anthropic.com/engineering/claude-code-best-practices) より:
+
+> "リサーチと計画を先に行うことで、深い思考が必要な問題のパフォーマンスが大幅に向上する。"
+
+```markdown
+## Workflow
+1. **Research**: Explore codebase, understand context
+2. **Plan**: Design approach before coding
+3. **Execute**: Implement with plan as guide
+```
+
+### 軽量 vs 重量エージェント
+
+| タイプ | トークン使用量 | 影響 |
+|--------|-------------|------|
+| **軽量** (<3k tokens) | 低 | スムーズなオーケストレーション、高速な連携 |
+| **重量** (25k+ tokens) | 高 | マルチエージェントワークフローのボトルネック |
+
+**推奨**: 軽量エージェント（最小限のツール）から始め、必要に応じて複雑さを追加。
+
+### サブエージェント戦略
+
+> "サブエージェントの積極的な使用が推奨される。特に複雑な問題で。" -- Anthropic
+
+- サブエージェントで会話の早い段階で詳細を確認
+- コンテキストの可用性を維持
+- 効率面のデメリットは最小限
+
+### トークン使用量の削減
+
+**ディレクトリ形式を使用**（複雑なエージェント向け）:
+- コアプロンプトは AGENT.md (< 500行)
+- 詳細は必要時のみ読み込み
+
+**インラインではなくリンクで参照**:
+```markdown
+# ❌ すべてインライン
+## Security Checks
+[2000行の OWASP 詳細]
+
+# ✅ 参照にリンク
+## Security Checks
+Apply OWASP Top 10 checks. See [reference.md](reference.md#owasp) for complete list.
+```
+
+### モデル選択
+
+| タスク | モデル | 理由 |
+|--------|--------|------|
+| 単純なファイル操作 | haiku | 高速、低コスト |
+| 標準的な分析 | sonnet | バランス型 |
+| 複雑な推論 | opus | 高品質 |
+
+### 並列実行
+
+オーケストレータエージェント向け:
+```markdown
+## Workflow
+1. **Parallel Analysis**: Launch these agents simultaneously:
+   - security-auditor
+   - performance-analyzer
+   - code-reviewer
+2. **Aggregate**: Combine results after all complete
+```
+
+### マルチコンテキストウィンドウワークフロー
+
+単一のコンテキストウィンドウで完了できないプロジェクト向け:
+
+1. **初期化エージェント**: 初回実行時に環境をセットアップ
+2. **コーディングエージェント**: 段階的に進捗
+3. **アーティファクト**: 次のセッションのために明確な成果物を残す（TODO、状態ファイル）
+
+---
+
+## セキュリティに関する考慮事項
+
+### ツールアクセスの原則
+
+1. **デフォルトは読み取り専用**: Read, Grep, Glob から始める
+2. **Write は必要時のみ追加**: 生成タスク向け
+3. **Bash は慎重に**: テスト/リンターの実行のみ
+4. **bypassPermissions は使わない**: 絶対に必要な場合を除く
+
+### パーミッションモード
+
+| モード | ユースケース | リスクレベル |
+|--------|------------|------------|
+| `default` | ほとんどのエージェント | 低 |
+| `acceptEdits` | 信頼できるトランスフォーマ | 中 |
+| `bypassPermissions` | 自動化パイプラインのみ | 高 |
+
+### 機密操作
+
+システムプロンプトでガード:
+```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
+```
+
+### 入力バリデーション
+
+ユーザー入力を受け取るエージェント向け:
+```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-ja/skills/managing-agents/best-practices.md

@@ -0,0 +1,267 @@
+# エージェントのベストプラクティス
+
+[Anthropic の "Building Effective Agents"](https://www.anthropic.com/engineering/building-effective-agents) と [Claude Code Best Practices](https://www.anthropic.com/engineering/claude-code-best-practices) に基づくパターン。
+
+## 目次
+
+- [基本原則](#基本原則)
+- [ACI: エージェント-コンピュータインターフェース](#aci-エージェント-コンピュータインターフェース)
+- [システムプロンプト設計](#システムプロンプト設計)
+- [ツール選択戦略](#ツール選択戦略)
+- [説明文の最適化](#説明文の最適化)
+- [クイックリファレンス](#クイックリファレンス)
+
+高度なトピックは [best-practices-advanced.md](best-practices-advanced.md) を参照:
+- よくあるアンチパターン
+- エージェントのテスト
+- パフォーマンス最適化
+- セキュリティに関する考慮事項
+
+---
+
+## 基本原則
+
+Anthropic の3つの基本原則:
+
+### 1. シンプルさ
+> "成功とは最も洗練されたシステムを構築することではなく、ニーズに合った適切なシステムを構築すること。"
+
+- 最もシンプルなソリューションから始める
+- 結果が正当化する場合のみ複雑さを追加
+- 多くのアプリケーションは「単一の LLM 呼び出しの最適化と検索・インコンテキスト例」で十分
+
+### 2. 透明性
+- 計画ステップを明示
+- エージェントの推論を可視化
+- 人間のレビューと介入を可能に
+
+### 3. エージェント-コンピュータインターフェース (ACI)
+- ツール設計はプロンプトと同等に重視
+- ツールを徹底的にテスト
+- モデルの誤りに基づいてイテレーション
+
+---
+
+## ACI: エージェント-コンピュータインターフェース
+
+> "ACI を HCI（ヒューマン-コンピュータインターフェース）と同じように考えよ。"
+
+### ツール設計ガイドライン
+
+| ガイドライン | 例 |
+|------------|-----|
+| **明確な名前** | `read_file`（`rf` ではない） |
+| **詳細なドキュメント** | 使用タイミング、エッジケースを含む |
+| **使用例** | 入出力ペア |
+| **エラーメッセージ** | アクション可能で分かりやすい |
+| **ポカヨケ** | エラーを事前に防止 |
+
+### ツールドキュメントテンプレート
+
+```markdown
+## tool_name
+
+**Purpose**: [一文で説明]
+
+**When to use**: [具体的なシナリオ]
+
+**Parameters**:
+- `param1` (required): [説明]
+- `param2` (optional): [説明, default: X]
+
+**Returns**: [形式と構造]
+
+**Examples**:
+\```
+Input: { "param1": "value" }
+Output: { "result": "..." }
+\```
+
+**Edge cases**:
+- If X happens, returns Y
+- Does NOT handle Z (use other_tool instead)
+```
+
+### よくあるツール設計の誤り
+
+| 誤り | 修正 |
+|------|------|
+| 曖昧な説明 | 具体的なユースケース |
+| 例の欠如 | 入出力ペア |
+| エラー処理ドキュメントなし | 失敗モードを文書化 |
+| ツールの重複 | 明確な境界 |
+| 複雑なパラメータ | シンプルで直感的な入力 |
+
+### トークン効率
+
+**読みやすさよりトークン効率を優先。**
+
+| 避ける | 推奨 |
+|--------|------|
+| ASCII アート / ボックス図 | Markdown テーブル、箇条書き |
+| 装飾的セパレータ | ヘッダーのみ |
+| `Last Updated:` スタンプ | Git 履歴 |
+| 冗長な説明 | 簡潔な指示 |
+
+---
+
+## システムプロンプト設計
+
+### 明確な構造
+
+```markdown
+# Agent Name
+
+[一文の役割説明]
+
+## Core Responsibilities
+- [具体的なタスク 1]
+- [具体的なタスク 2]
+
+## Workflow
+1. **Step Name**: [アクション] using [ツール]
+   - Decision point: If X, then Y
+   - Output: [期待される結果]
+
+## Quality Criteria
+- [測定可能な基準 1]
+- [測定可能な基準 2]
+
+## Output Format
+[例付きの正確な構造]
+```
+
+### 効果的な指示の書き方
+
+**良い例**:
+```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
+```
+
+**悪い例**:
+```markdown
+## Workflow
+1. Look at the files
+2. Check for problems
+3. Report findings
+```
+
+### プロンプト長のガイドライン
+
+| 複雑さ | 推奨行数 |
+|--------|---------|
+| シンプル、集中型 | 100-300行 |
+| 標準 | 300-500行 |
+| 複雑（ディレクトリ使用） | 500行以上を分割 |
+
+---
+
+## ツール選択戦略
+
+### 原則: 必要最小限のアクセス
+
+| エージェントタイプ | 推奨ツール | 避ける |
+|-----------------|-----------|-------|
+| 読み取り専用レビューア | Read, Grep, Glob | Write, Edit |
+| ファイル生成 | Read, Write | Edit（新規ファイルは Write） |
+| コード変換 | Read, Edit | Write（変更は Edit 推奨） |
+| デバッガ | Read, Bash, Grep | Write, Edit |
+
+### ツールの組み合わせ
+
+**分析エージェント**:
+```yaml
+tools: Read, Grep, Glob, Bash
+```
+- Bash はテスト/リンター実行のみ
+- ファイル変更機能なし
+
+**生成エージェント**:
+```yaml
+tools: Read, Write, Bash
+```
+
+**変換エージェント**:
+```yaml
+tools: Read, Edit, Bash
+```
+
+### Web アクセス
+
+必要な場合のみ追加:
+```yaml
+# ドキュメント取得
+tools: Read, Write, WebFetch
+
+# リサーチエージェント
+tools: Read, WebSearch, WebFetch
+```
+
+---
+
+## 説明文の最適化
+
+### トリガーフレーズの配置
+
+**良い例**: トリガーを末尾に
+```yaml
+description: Reviews code for security vulnerabilities following OWASP Top 10. Use when user asks to "security review", "audit security", or "check vulnerabilities".
+```
+
+**より良い例**: `<example>` ブロック付きリッチ形式
+```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>
+```
+
+### 曖昧さの解消
+
+複数のエージェントがマッチしうる場合:
+
+```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.
+```
+
+### プロアクティブな呼び出し
+
+自動使用を促進する:
+```yaml
+description: Use PROACTIVELY after any feature implementation to ensure code quality. MUST BE USED when PR is ready for review.
+```
+
+---
+
+## クイックリファレンス
+
+### エージェント品質チェックリスト
+
+- [ ] 単一の明確な責務
+- [ ] 具体的なワークフローステップ
+- [ ] 必要最小限のツール
+- [ ] 明確な呼び出しトリガー
+- [ ] 定義された出力形式
+- [ ] エラー処理を含む
+- [ ] サンプル入力でテスト済み
+- [ ] 500行未満（またはディレクトリ形式）
+
+### ファイルサイズのガイドライン
+
+| ファイル | 目標行数 |
+|---------|---------|
+| SKILL.md / AGENT.md | < 500 |
+| reference.md | < 800 |
+| examples.md | < 600 |
+| best-practices.md | < 400 |