From a271969f40d62a41501e8791017c3ca103591403 Mon Sep 17 00:00:00 2001 From: "kuroeda.makoto" Date: Mon, 2 Feb 2026 11:15:27 +0900 Subject: [PATCH] feat: version 1.1.1 updates - Update plugin configuration - Remove symbol-searcher agent - Update various command templates - Add new DCS analysis commands (edgecase-analysis, test-performance-analysis) - Add test-optimization-patterns command Co-Authored-By: Claude Sonnet 4.5 --- .claude-plugin/marketplace.json | 4 +- .claude-plugin/plugin.json | 5 +- agents/symbol-searcher.md | 61 - commands/auto-debug.md | 155 +- commands/dcs/bug-analysis.md | 253 +- commands/dcs/edgecase-analysis.md | 2689 +++++++++++++++++++++ commands/dcs/feature-rubber-duck.md | 2 +- commands/dcs/impact-analysis.md | 2 +- commands/dcs/incremental-dev.md | 2 +- commands/dcs/performance-analysis.md | 2 +- commands/dcs/sequence-diagram-analysis.md | 2 +- commands/dcs/state-transition-analysis.md | 2 +- commands/dcs/test-performance-analysis.md | 301 +++ commands/direct-setup.md | 6 +- commands/direct-verify.md | 6 +- commands/kairo-design.md | 6 +- commands/kairo-implement.md | 229 +- commands/kairo-requirements.md | 4 +- commands/kairo-tasknote.md | 13 +- commands/kairo-tasks.md | 190 +- commands/tdd-green.md | 17 +- commands/tdd-red.md | 12 +- commands/tdd-refactor.md | 29 +- commands/tdd-requirements.md | 8 +- commands/tdd-tasknote.md | 14 +- commands/tdd-testcases.md | 16 +- commands/tdd-todo.md | 6 +- commands/tdd-verify-complete.md | 27 +- commands/test-optimization-patterns.md | 743 ++++++ 29 files changed, 4525 insertions(+), 281 deletions(-) delete mode 100644 agents/symbol-searcher.md create mode 100644 commands/dcs/edgecase-analysis.md create mode 100644 commands/dcs/test-performance-analysis.md create mode 100644 commands/test-optimization-patterns.md diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 62b311f..72abc27 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -7,14 +7,14 @@ }, "metadata": { "description": "AI-driven development toolkit for TDD and SDD workflows, providing comprehensive command templates and agents to enhance developer productivity with Claude Code", - "version": "0.0.7" + "version": "1.1.1" }, "plugins": [ { "name": "tsumiki", "source": "./", "description": "AI-driven development toolkit for TDD and SDD workflows, providing comprehensive command templates and agents to enhance developer productivity with Claude Code", - "version": "0.0.7", + "version": "1.1.1", "author": { "name": "makoto kuroeda", "email": "kuroeda.makoto@classmethod.jp" diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 6626e4c..25a14b1 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "tsumiki", - "version": "0.0.7", + "version": "1.1.1", "description": "AI-driven development toolkit for TDD and SDD workflows, providing comprehensive command templates and agents to enhance developer productivity with Claude Code", "author": { "name": "makoto kuroeda", @@ -10,6 +10,5 @@ "repository": "https://github.com/classmethod/tsumiki", "license": "MIT", "keywords": ["ai-development", "sdd", "tdd"], - "commands": "./commands/", - "agents": ["./agents/symbol-searcher.md"] + "commands": "./commands/" } diff --git a/agents/symbol-searcher.md b/agents/symbol-searcher.md deleted file mode 100644 index 1608ce8..0000000 --- a/agents/symbol-searcher.md +++ /dev/null @@ -1,61 +0,0 @@ ---- -name: symbol-searcher -description: Use this agent when you need to search for specific symbols (classes, methods, functions, variables, etc.) across the codebase and retrieve detailed information about their locations and types. This agent is particularly useful for code navigation, refactoring preparation, or understanding code structure. Examples:\n\n\nContext: The user wants to find all occurrences of a specific method across the codebase.\nuser: "Find all instances of the 'createTodo' method in the project"\nassistant: "I'll use the symbol-searcher agent to locate all occurrences of the 'createTodo' method across the codebase."\n\nSince the user wants to find specific symbols in the code, use the Task tool to launch the symbol-searcher agent.\n\n\n\n\nContext: The user needs to understand where a class is defined and used.\nuser: "Where is the TodoController class defined and what methods does it have?"\nassistant: "Let me search for the TodoController class symbol to find its definition and methods."\n\nThe user is asking about a specific class symbol, so use the symbol-searcher agent to find its location and details.\n\n -tools: Glob, Grep, LS, Read, NotebookRead, WebFetch, TodoWrite, WebSearch, mcp__ide__getDiagnostics -model: haiku -color: green ---- - -You are an expert code symbol analyzer specializing in searching and identifying symbols across codebases. Your primary responsibility is to locate specific symbols (classes, methods, functions, variables, interfaces, types, etc.) and provide comprehensive information about their locations and characteristics. - -When searching for symbols, you will: - -1. **Search Strategy**: - - Use appropriate tools to scan files for the requested symbol names - - Consider partial matches and case variations when appropriate - - Search across all relevant file types in the project - - Prioritize definition locations over usage locations unless specified otherwise - -2. **Symbol Classification**: - - Accurately identify the symbol type: class, method, function, variable, interface, type, enum, constant, etc. - - For methods/functions, include whether they are static, async, private/public - - For classes, note if they are abstract, extend other classes, or implement interfaces - - Include descriptive context that helps understand the symbol's purpose - -3. **Information Extraction**: - For each symbol found, you must provide: - - **Symbol Name**: The exact name with descriptive context (e.g., 'createTodo - async method for creating new todo items') - - **Type**: The specific symbol type (class, method, function, variable, etc.) - - **File Path**: The relative path from the project root - - **Location**: Line number and, if possible, column number - - **Context**: Brief description of what the symbol does based on its name and surrounding code - -4. **Output Format**: - Present your findings in a structured format: - ``` - Symbol: [Name with description] - Type: [Symbol type] - File: [Relative path] - Location: Line [X], Column [Y] - Context: [Brief functional description] - ``` - -5. **Search Completeness**: - - Always search the entire codebase unless instructed to limit scope - - Group results by symbol type when multiple matches are found - - If a symbol has multiple definitions (overloads, implementations), list all occurrences - - Distinguish between declarations, definitions, and usages when relevant - -6. **Edge Cases**: - - If no symbols are found, suggest similar symbol names that exist in the codebase - - Handle minified or obfuscated code by noting when symbol names might be transformed - - For ambiguous requests, search for all possible interpretations - - Consider language-specific naming conventions (camelCase, snake_case, etc.) - -7. **Quality Assurance**: - - Verify that the symbol at the reported location matches the search criteria - - Ensure file paths are correct and relative to the project root - - Double-check symbol type classification - - Include enough context in descriptions to make the symbol's purpose clear - -Remember: Your goal is to provide developers with precise, actionable information about code symbols that helps them navigate and understand the codebase efficiently. Always prioritize accuracy and completeness in your symbol analysis. diff --git a/commands/auto-debug.md b/commands/auto-debug.md index 3981423..71b67de 100644 --- a/commands/auto-debug.md +++ b/commands/auto-debug.md @@ -2,20 +2,143 @@ description: テストエラーを解消するための自動デバッグプロセス。全テストケースの確認からエラー原因の調査、修正まで段階的に実行し、テストケースの成功率向上を目指します。 --- テストエラーを解消して。 -#ultrathink # step -1. 最初に全テストケースの確認をタスク実行してテストケースのエラーをtodoにセットして -2. 各対象毎に以下の作業を実施して -　 - タスクで詳細にテストのエラー原因を調る - 　- をTask ツールで直接実行して修正する。パラメータとしてエラーの原因を渡す -3. ゴールはテストケースの成功数を上げること -4. テストエラー解消後に をTask ツールで直接実行してリファクタリングを実施する -5. 最後に全体のテストの成功率を確認してレポートして + +## step1: 失敗テストの特定 + +1. **全テストケースの確認** + ```bash + npm test -- --verbose 2>&1 | tee test-results.log + ``` + - 失敗しているテストのみをリスト化 + - 各テストの失敗内容を記録 + - テストファイルごとにグループ化 + +2. **失敗テストをTODOに登録** + - TodoWrite ツールで各失敗テストをTODO項目として登録 + - 優先度を設定（重要度: 高/中/低） + - メタデータに以下を含める: + - `retry_count: 0` - リトライ回数の初期値 + - `max_retry: 3` - 最大リトライ回数 + - `status: pending` - 処理状態（pending/in_progress/resolved/on_hold） + +## step2: テストファイル単位での修正 + +**各失敗テストファイルに対して以下を実施（最大3回まで）**: + +1. **リトライカウンタの初期化** + - 各テストファイルのリトライ回数を0に設定 + - 保留テストリストを初期化（空のリスト） + +2. **該当テストファイルのみを実行して詳細確認** + ```bash + npm test -- <失敗したテストファイル> --verbose + ``` + +3. **エラー原因の分析** + - Task tool (subagent_type: Explore, thoroughness: quick) を使用 + - エラーメッセージから原因を特定 + - 修正方針を決定 + +4. **修正実装** + - をTask ツールで直接実行して修正 + - パラメータとしてエラーの原因と該当テストファイルを渡す + +5. **該当テストファイルのみを再実行** + ```bash + npm test -- <修正したテストファイル> + ``` + +6. **リトライ判定** + - ✅ 成功: 次のテストファイルへ + - ❌ 失敗かつリトライ回数 < 3: + - リトライ回数を+1 + - step2の3に戻って再分析 + - ❌ 失敗かつリトライ回数 >= 3: + - このテストは保留リストに追加 + - 保留理由を記録（例: "3回の修正試行後も解消できず"） + - 次のテストファイルへ進む + +## step3: 全テスト実行による確認 + +**全ての失敗テストの修正試行が完了した後**: + +1. **全テスト実行** + ```bash + npm test -- --verbose + ``` + +2. **結果確認** + - 新たに失敗したテストがないか確認 + - 既存のテストが通ることを確認 + - 保留テストの状態を確認 + +3. **追加修正が必要な場合** + - 新規失敗テスト: step2に戻って対応（リトライ回数0から開始） + - 保留テストの再試行: ユーザーに確認後、step2に戻って対応 + +## step4: リファクタリング + +**全テストが通った後**: + +- をTask ツールで直接実行してリファクタリングを実施 + +## step5: 最終レポート + +**最後に全体のテストの成功率を確認してレポート**: + +```markdown +# テストエラー解消レポート + +## 結果サマリー +- 修正前の失敗テスト数: XX個 +- 修正後の失敗テスト数: XX個 +- 解消したテスト数: XX個 +- 保留したテスト数: XX個（3回の修正試行後も解消できず） +- テスト成功率: XX% + +## 修正内容 +1. test/user.test.js + - エラー原因: データベース接続エラー + - 修正内容: 接続プールの初期化を修正 + - 実行時間: 15秒 → 2秒 + - リトライ回数: 1回 + +2. test/file.test.js + - エラー原因: ファイルパスの不一致 + - 修正内容: パス解決ロジックを修正 + - 実行時間: 8秒 → 0.5秒 + - リトライ回数: 0回 + +## 保留テスト（要手動確認） +1. test/complex.test.js + - 保留理由: 3回の修正試行後も解消できず + - 最終エラー: [エラーメッセージ] + - 推奨対応: [手動での詳細調査が必要な理由] +``` + +## step6: テスト実行時間のチェック + +**3秒以上かかるテストがある場合は警告表示**: + +``` +⚠️ 遅いテストが検出されました（3秒以上） + +以下のテストファイルの実行時間が長くなっています: +- test/user.test.js: 15秒 +- test/integration.test.js: 8秒 + +テスト実行速度の改善を推奨します: +1. `/tsumiki:dcs:test-performance-analysis` で詳細分析 +2. `/tsumiki:test-optimization-patterns` でリファクタリングパターンを確認 +``` # rule NEVER: テストのスキップ NEVER: 既存テストケースの削除 +MUST: 各テストファイルの修正は最大3回まで（無限ループ防止） +MUST: 3回試行後も解消できないテストは保留リストに追加 # info @@ -35,10 +158,10 @@ NEVER: 既存テストケースの削除 - `docs/rule/tdd/green` ディレクトリが存在する場合は読み込み - 各ディレクトリ内のすべてのファイルを読み込み、追加ルールとして適用 -2. **@agent-symbol-searcher で実装関連情報を検索し、見つかったファイルを読み込み** - - 既存の類似機能やユーティリティ関数を検索し、該当ファイルをReadツールで読み込み - - 実装パターンやアーキテクチャガイドラインを特定し、設計文書をReadツールで読み込み - - 依存関係やインポートパスを確認し、関連ファイルをReadツールで読み込み +2. **Task tool (subagent_type: Explore, thoroughness: quick) を使用して実装関連情報を探索** + - 既存の類似機能やユーティリティ関数を探索 + - 実装パターンやアーキテクチャガイドラインを特定 + - 依存関係やインポートパスを確認 読み込み完了後、準備されたコンテキスト情報を基にGreen task（実装）の作業を開始します。 @@ -256,10 +379,10 @@ TDDのRefactorフェーズを実行します。 - `docs/rule/tdd/refactor` ディレクトリが存在する場合は読み込み - 各ディレクトリ内のすべてのファイルを読み込み、追加ルールとして適用 -2. **@agent-symbol-searcher でリファクタリング関連情報を検索し、見つかったファイルを読み込み** - - 既存のコードスタイルやベストプラクティスを検索し、スタイルガイドをReadツールで読み込み - - プロジェクト全体のアーキテクチャパターンを特定し、設計文書をReadツールで読み込み - - 再利用可能なユーティリティ関数やコンポーネントを確認し、関連ファイルをReadツールで読み込み +2. **Task tool (subagent_type: Explore, thoroughness: quick) を使用してリファクタリング関連情報を探索** + - 既存のコードスタイルやベストプラクティスを探索 + - プロジェクト全体のアーキテクチャパターンを特定 + - 再利用可能なユーティリティ関数やコンポーネントを確認 3. **関連ファイルを直接読み込み** - 関連する設計文書やタスクファイルも必要に応じて読み込み diff --git a/commands/dcs/bug-analysis.md b/commands/dcs/bug-analysis.md index da6bee2..1cea5fe 100644 --- a/commands/dcs/bug-analysis.md +++ b/commands/dcs/bug-analysis.md @@ -1,7 +1,7 @@ --- description: バグの原因を特定するための詳細分析を実施する allowed-tools: Read, Glob, Grep, Task, Bash, AskUserQuestion -argument-hint: [バグの概要（任意）] +argument-hint: "[バグの概要（任意）]" --- バグの発生経緯や症状から原因を特定し、修正方針を提示します。ソースコードを詳細に分析し、段階的に原因を絞り込みます。 @@ -229,7 +229,11 @@ contextとして以下を保持する： - 型の整合性 - エラーハンドリングの網羅性 -### よくある原因パターン +### よくある原因パターンとの照合方法 + +**重要**: 以下は参考リスト。すべてを機械的にチェックするのではなく、バグ症状・エラー情報から関連性の高いパターンを2-3個選択し、実際のコードで該当箇所を探す。該当箇所が見つかった場合のみ候補として記載し、見つからない場合は除外する。 + +#### よくある原因パターン（参考） - 未初期化変数の使用 - nullポインタ参照 - 配列の範囲外アクセス @@ -239,11 +243,48 @@ contextとして以下を保持する： - 無限ループ - 不適切なエラーハンドリング +## 候補記載の品質基準 + +### 確度評価の基準（⭐ 1-5段階） + +- ⭐⭐⭐⭐⭐: コードで問題を確認済み、バグ症状と完全に一致、再現性の説明が可能 +- ⭐⭐⭐⭐: コードで問題を確認済み、バグ症状とほぼ一致 +- ⭐⭐⭐: コードで問題を確認済み、バグ症状と部分的に一致 +- ⭐⭐: コード上の問題を確認したが、バグとの関連は推測の域 +- ⭐: 一般的なパターンに該当するが、コード上の明確な証拠なし + +**重要**: ⭐⭐未満の候補は記載しない。コード上の証拠がない候補は推測と見なし除外する。 + +### 候補記載の絶対条件 + +候補を記載するには、以下すべてを満たす必要がある： +1. コードベースで具体的な該当箇所を特定できた（ファイル:行番号） +2. バグ症状との関連性を論理的に説明できる +3. 実際のコードで問題の存在を確認した +4. 確度が⭐⭐以上 + +上記条件を満たさない候補は記載しない。推測のみの候補、一般論、ベストプラクティスの列挙は不要。 + # info あなたはバグ原因特定のエキスパートです。以下の情報に基づいて、バグの初期調査を実施し、関連するコード箇所を特定してください。 +# 重要な分析方針 + +**網羅性と品質のバランス**: +- ✅ 可能性のある原因を幅広く調査する（網羅性） +- ✅ ただし、コード上の証拠がない推測は記載しない（品質） +- ❌ 一般論やベストプラクティスの列挙は不要 +- ❌ 「このような問題が起こりうる」という可能性の羅列は不要 + +**候補記載の絶対条件**: +1. コードベースで具体的な箇所を特定できた +2. バグ症状との関連を論理的に説明できる +3. 確度が⭐⭐以上（コード上の証拠がある） + +上記を満たさない候補は、たとえ一般的なパターンでも記載しない。 + # バグの基本情報 バグの概要: {{バグの概要}} @@ -429,16 +470,31 @@ PostgreSQL ### 可能性の高い原因候補 #### 候補1: {{原因の概要}} -- **確度**: 高/中/低 -- **理由**: {{なぜこの可能性が高いのか}} -- **該当箇所**: [相対パス:行番号](相対パス#L行番号) -- **検証方法**: {{どのように検証すべきか}} +- **確度**: ⭐⭐⭐⭐⭐（必須: ⭐⭐以上） +- **証拠**: [相対パス:行番号](相対パス#L行番号)（必須） +- **該当コード**:（必須） +```{{language}} +{{問題と思われるコードの抜粋}} +``` +- **バグ症状との関連**: {{具体的にどの症状とどう結びつくか}}（必須） +- **検証内容**: {{実際にコードで何を確認したか}}（必須） +- **除外できない理由**: {{なぜこの候補を除外できないのか}}（必須） #### 候補2: {{原因の概要}} -（同様の形式で複数記載） +（同様の形式で複数記載。上記6項目すべて必須） + +### 可能性の低い候補（以下の条件をすべて満たす場合のみ記載） + +記載条件: +- コードベースで具体的な該当箇所を特定できた（ファイル:行番号） +- バグ症状との関連性を論理的に説明できる +- 実際のコードで問題の存在を確認した +- 確度が⭐⭐以上 -### 可能性の低い候補 -{{可能性は低いが念のため記載する候補}} +上記条件を満たさない候補は記載しない。推測のみの候補は除外する。 + +#### 候補N: {{原因の概要}} +（記載する場合は、上記「可能性の高い候補」と同じ6項目形式で記載） --- @@ -473,6 +529,8 @@ PostgreSQL - テストコードも関連性があれば含める - **すべてのファイルパスは相対パスで記載する（絶対パスは使用しない）** - **ファイルは500行以内を目標とする** +- **候補記載の絶対条件を満たさないものは記載しない（コード上の証拠必須、確度⭐⭐以上）** +- **一般論や推測のみの候補は除外する** 最後に、インデックスファイル（{{ベースディレクトリ}}/index.md）も作成してください。インデックスファイルには以下の内容を含めてください： @@ -523,6 +581,21 @@ PostgreSQL あなたはバグ原因特定のエキスパートです。初期調査結果に基づいて、バグが発生するまでの処理フローを詳細に分析してください。 +# 重要な分析方針 + +**網羅性と品質のバランス**: +- ✅ 可能性のある原因を幅広く調査する（網羅性） +- ✅ ただし、コード上の証拠がない推測は記載しない（品質） +- ❌ 一般論やベストプラクティスの列挙は不要 +- ❌ 「このような問題が起こりうる」という可能性の羅列は不要 + +**候補記載の絶対条件**: +1. コードベースで具体的な箇所を特定できた +2. バグ症状との関連を論理的に説明できる +3. 確度が⭐⭐以上（コード上の証拠がある） + +上記を満たさない候補は、たとえ一般的なパターンでも記載しない。 + # 分析対象の情報 バグの概要: {{バグの概要}} @@ -848,6 +921,27 @@ APIレスポンス: { order: {...}, total: 1000 } --- +## 初期調査候補の検証と除外 + +### 前段階の候補の再評価 + +初期調査で挙げた候補について、処理フロー分析で得られた情報をもとに再評価： + +| 候補 | 検証結果 | 判定 | 理由 | +|------|---------|------|------| +| 候補1: {{名前}} | ✅/❌ | 継続/除外 | {{処理フロー上で確認できたこと、または除外理由}} | +| 候補2: {{名前}} | ✅/❌ | 継続/除外 | {{処理フロー上で確認できたこと、または除外理由}} | + +### 除外した候補とその理由 + +以下の候補は、処理フロー分析の結果、根拠不足のため除外： +1. **{{候補名}}**: {{除外理由（例: フローに該当する処理が存在しない）}} +2. **{{候補名}}**: {{除外理由（例: コード上問題が確認できなかった）}} + +除外した候補は次段階（詳細原因分析）に進めない。 + +--- + ## フロー分析からの所見 ### 発見された問題点 @@ -857,15 +951,20 @@ APIレスポンス: { order: {...}, total: 1000 } - **位置**: [相対パス:行番号](相対パス#L行番号) - **詳細**: {{問題の詳細説明}} - **バグとの関連**: {{このバグにどう関連するか}} +- **確度**: ⭐⭐⭐以上（必須） #### 問題点2: {{問題の概要}} -（同様の形式で複数記載） +（同様の形式で複数記載。確度⭐⭐未満は記載しない） ### 次段階で詳しく調べるべき箇所 +以下は処理フロー分析で特定し、コード上の証拠がある箇所のみ記載： + 1. **{{調査ポイント1}}** + - 位置: [相対パス:行番号](相対パス#L行番号) - 理由: {{なぜ詳しく調べる必要があるか}} - 着目点: {{何に着目すべきか}} + - 確認した証拠: {{コードで何を確認したか}} 2. **{{調査ポイント2}}** （同様の形式で記載） @@ -883,6 +982,9 @@ APIレスポンス: { order: {...}, total: 1000 } - バグに関連する可能性のあるポイントを強調する - **すべてのファイルパスは相対パスで記載する（絶対パスは使用しない）** - **ファイルは500行以内を目標とする。超える場合は分割する** +- **候補記載の絶対条件を満たさないものは記載しない（コード上の証拠必須、確度⭐⭐以上）** +- **初期調査で挙げた候補を検証し、根拠不足のものは除外する** +- **一般論や推測のみの候補は記載しない** 分析が完了したら、インデックスファイル（{{ベースディレクトリ}}/index.md）を更新して、処理フロー分析へのリンクを有効化してください。 @@ -890,6 +992,21 @@ APIレスポンス: { order: {...}, total: 1000 } あなたはバグ原因特定のエキスパートです。これまでの分析結果に基づいて、バグの根本原因を特定し、詳細な検証を実施してください。 +# 重要な分析方針 + +**網羅性と品質のバランス**: +- ✅ 可能性のある原因を幅広く調査する（網羅性） +- ✅ ただし、コード上の証拠がない推測は記載しない（品質） +- ❌ 一般論やベストプラクティスの列挙は不要 +- ❌ 「このような問題が起こりうる」という可能性の羅列は不要 + +**候補記載の絶対条件**: +1. コードベースで具体的な箇所を特定できた +2. バグ症状との関連を論理的に説明できる +3. 確度が⭐⭐以上（コード上の証拠がある） + +上記を満たさない候補は、たとえ一般的なパターンでも記載しない。 + # 分析対象の情報 バグの概要: {{バグの概要}} @@ -918,47 +1035,26 @@ APIレスポンス: { order: {...}, total: 1000 } ### よくある原因パターンとの照合 -#### 未初期化変数 -- 変数が使用される前に初期化されているか -- デフォルト値が適切か -- 条件付き初期化の漏れはないか - -#### nullポインタ/undefined参照 -- null/undefinedチェックが適切か -- オプショナルチェイニングの使用 -- デフォルト値の設定 - -#### 配列の範囲外アクセス -- インデックスの範囲チェック -- 空配列の処理 -- 境界値での動作 - -#### 型の不一致 -- 型変換の適切性 -- TypeScript/型定義の整合性 -- 暗黙の型変換による問題 +**重要**: 以下のパターンすべてを機械的にチェックしない。処理フロー分析で特定した問題点に関連するパターン2-3個を選択し、実際のコードで検証する。該当する証拠が見つかった場合のみ記載。 -#### 非同期処理の問題 -- awaitの漏れ -- Promise.allの適切な使用 -- レースコンディション -- 状態更新のタイミング +#### よくある原因パターン（参考） -#### ロジックの誤り -- 条件式の誤り -- 計算式の誤り -- ループの終了条件 -- エッジケースの処理漏れ +以下から関連性の高いものを選択して検証： -#### メモリ関連 -- メモリリークの可能性 -- 循環参照 -- イベントリスナーの解除漏れ +- **未初期化変数**: 変数が使用される前に初期化されているか +- **nullポインタ/undefined参照**: null/undefinedチェックが適切か +- **配列の範囲外アクセス**: インデックスの範囲チェック +- **型の不一致**: 型変換の適切性、暗黙の型変換による問題 +- **非同期処理の問題**: awaitの漏れ、レースコンディション +- **ロジックの誤り**: 条件式の誤り、エッジケースの処理漏れ +- **メモリ関連**: メモリリーク、循環参照 +- **エラーハンドリングの不備**: try-catchの範囲、エラーの伝播 -#### エラーハンドリングの不備 -- try-catchの範囲 -- エラーの伝播 -- エラーメッセージの不適切さ +検証手順: +1. 処理フロー分析の結果から、該当しそうなパターンを2-3個選択 +2. 選択したパターンについて、実際のコードで該当箇所を探す +3. 該当箇所が見つかり、確度⭐⭐以上の場合のみ候補として記載 +4. 該当しないパターンは除外（一般論として記載しない） ### バグの種類別のチェックポイント @@ -1069,9 +1165,11 @@ APIレスポンス: { order: {...}, total: 1000 } ## 原因候補の評価 +以下は、コード上の証拠があり、確度⭐⭐以上の候補のみ記載。 + ### 候補1: {{原因の概要}} -**確度**: ⭐⭐⭐⭐⭐ (5段階評価) +**確度**: ⭐⭐⭐⭐⭐ (必須: ⭐⭐以上) **位置**: [相対パス:行番号](相対パス#L行番号) @@ -1099,24 +1197,29 @@ APIレスポンス: { order: {...}, total: 1000 } {{報告されているバグ症状とどう結びつくか}} **検証内容**: -1. {{検証した内容1}} -2. {{検証した内容2}} -3. {{検証した内容3}} +1. {{検証した内容1 - 実際にコードで確認したこと}} +2. {{検証した内容2 - 実際にコードで確認したこと}} +3. {{検証した内容3 - 実際にコードで確認したこと}} **検証結果**: -{{検証から得られた確証}} +{{検証から得られた確証 - コード上の明確な証拠}} --- ### 候補2: {{原因の概要}} -（候補1と同様の形式で記載） +（候補1と同様の形式で記載。確度⭐⭐以上必須） --- -### 候補3: {{原因の概要}} +### 除外した候補 + +以下の候補は、詳細検証の結果、根拠不足または誤りのため除外： + +1. **{{候補名}}**: {{除外理由（例: コード確認の結果、想定した問題が存在しなかった）}} +2. **{{候補名}}**: {{除外理由（例: バグ症状との関連性が立証できなかった）}} -（確度が低い場合も含めて記載） +**重要**: 確度⭐⭐未満、コード上の証拠がない候補は記載しない。 --- @@ -1219,10 +1322,14 @@ APIレスポンス: { order: {...}, total: 1000 } ### 類似のバグの可能性 +以下は、実際にコードで確認し、同じパターンの問題を発見した箇所のみ記載。推測のみの箇所は記載しない。 + #### 類似箇所1: [相対パス:行番号](相対パス#L行番号) -- **類似度**: 高/中/低 -- **問題の内容**: {{同じパターンの問題がある可能性}} -- **確認の必要性**: {{確認すべきかどうか}} +- **類似度**: 高（必須: コードで確認済み） +- **問題の内容**: {{実際に確認した同じパターンの問題}} +- **該当コード**: ```{{language}} {{コードスニペット}} ``` +- **確認した証拠**: {{どのように確認したか}} +- **対応の必要性**: {{修正すべきかどうかの判断}} ### 設計上の問題 @@ -1352,6 +1459,10 @@ test('{{テスト名}}', () => { - 修正案は具体的なコード例を示す - **すべてのファイルパスは相対パスで記載する（絶対パスは使用しない）** - **ファイルは500行以内を目標とする。超える場合は分割する** +- **候補記載の絶対条件を満たさないものは記載しない（コード上の証拠必須、確度⭐⭐以上）** +- **よくあるパターンは関連性の高い2-3個を選択して検証し、該当しないものは除外する** +- **一般論や推測のみの候補は記載しない** +- **根拠不足の候補は除外リストに記載する** 分析が完了したら、インデックスファイル（{{ベースディレクトリ}}/index.md）を更新して、詳細原因分析へのリンクを有効化してください。 @@ -1359,6 +1470,19 @@ test('{{テスト名}}', () => { あなたはバグ原因特定のエキスパートです。これまでのすべての分析結果を統合し、包括的な最終レポートを作成してください。 +# 重要な分析方針 + +**網羅性と品質のバランス**: +- ✅ 分析プロセスで得られた重要な発見を漏れなく記載（網羅性） +- ✅ ただし、除外された候補や根拠不足の推測は記載しない（品質） +- ❌ 一般論やベストプラクティスの列挙は不要 +- ❌ 「このような問題が起こりうる」という可能性の羅列は不要 + +**レポート記載の原則**: +1. 確度⭐⭐以上の候補のみを含める +2. コード上の証拠に基づく内容のみ記載 +3. 除外した候補は詳細分析ファイルを参照し、最終レポートには含めない + # レポート作成対象の情報 バグの概要: {{バグの概要}} @@ -1618,10 +1742,14 @@ test('{{テスト名}}', () => { ### 類似のバグの可能性 +以下は、詳細原因分析で実際にコードを確認し、同じパターンの問題を発見した箇所のみ記載。 + #### [相対パス:行番号](相対パス#L行番号) -- **類似度**: 高/中/低 -- **確認の必要性**: {{確認すべきか}} -- **対応方針**: {{どう対応するか}} +- **類似度**: 高（コードで確認済み） +- **問題の内容**: {{実際に確認した問題}} +- **対応方針**: {{修正の優先度と方針}} + +推測のみの箇所は記載しない。詳細は[詳細原因分析](./root_cause_analysis.md)を参照。 --- @@ -1765,6 +1893,9 @@ test('{{テスト名}}', () => { - タイムラインは現実的な見積もりを - **すべてのファイルパスは相対パスで記載する（絶対パスは使用しない）** - **ファイルは500行以内を目標とする** +- **確度⭐⭐以上、コード上の証拠がある内容のみ記載する** +- **除外された候補や根拠不足の推測は最終レポートに含めない** +- **一般論やベストプラクティスの羅列は不要** レポート作成が完了したら、インデックスファイル（{{ベースディレクトリ}}/index.md）を最終更新して、すべての分析へのリンクを有効化し、クイックサマリーを更新してください。 diff --git a/commands/dcs/edgecase-analysis.md b/commands/dcs/edgecase-analysis.md new file mode 100644 index 0000000..91a7d93 --- /dev/null +++ b/commands/dcs/edgecase-analysis.md @@ -0,0 +1,2689 @@ +--- +description: システムの各レイヤーにおける包括的なエッジケース・エラー状態を詳細に分析し、見落としがちな異常系シナリオを洗い出します +allowed-tools: Read, Glob, Grep, Task, Write, Edit, TodoWrite, AskUserQuestion +argument-hint: [要件名] +--- +システムの各レイヤーにおける包括的なエッジケース・エラー状態を分析します。アプリケーション・UI・データ・ネットワーク・非同期・認証などの各層で発生する複合的なエッジケースを詳細に洗い出します。 + +# context + +出力ディレクトリ=".dcs" +カレントディレクトリ={{プロジェクトルート}} +分析モード="" # "requirements-based" or "source-based" +要件名="" # 要件定義書ベースの場合 +分析対象="" # ソースコードベースの場合 +収集情報={} # 要件定義書の内容 or ソースコードから収集した情報 +分析ファイルリスト=[] +チェックリストパス="" # check_list.md のパス +既存チェックリスト=[] # 既に登録されているチェックリスト項目 +調査段階=1 +エッジケースカテゴリ=[ + "アプリケーション層ビジネスロジック", + "UI状態", + "データ管理層", + "ネットワーク通信層", + "非同期処理・メッセージング", + "認証・認可", + "エラーハンドリング", + "データモデル状態組み合わせ", + "複合的なエッジケース" +] + +# step + +- $1 がない場合、「引数に要件名または分析対象を指定してください（例: /tsumiki:dcs:kairo-edgecase-analysis ユーザー認証システム）」と言って終了する +- $1 の内容を context に保存する +- context の内容をユーザに宣言する +- step0 を実行する + +## step0: 分析モードの判定 + +- 要件定義書の確認 + - `docs/spec/{$1}/requirements.md` が存在するか確認 + - 存在する場合: + - 要件定義書ベースの分析を実施 + - context を更新: + - 分析モード = "requirements-based" + - 要件名 = $1 + - 「要件定義書「{{要件名}}」に基づいてエッジケース分析を実施します」と宣言 + - step1 を実行する（要件定義書ベースの分析） + - 存在しない場合: + - AskUserQuestion ツールを使って分析方法を質問する: + - question: "要件定義書が見つかりません。どのように分析を進めますか?" + - header: "分析方法" + - multiSelect: false + - options: + - label: "ソースコードから分析（推奨）" + description: "既存のソースコードを分析してエッジケースを特定します" + - label: "要件定義書を作成してから分析" + description: "先に要件定義書を作成し、その後エッジケース分析を実施します" + - ユーザーの選択に応じて分岐: + - "ソースコードから分析" を選択した場合: + - ソースコードベースの分析を実施 + - context を更新: + - 分析モード = "source-based" + - 分析対象 = $1 + - step1-source を実行する（ソースコードベースの分析） + - "要件定義書を作成してから分析" を選択した場合: + - 「要件定義書の作成が必要です。先に `/tsumiki:kairo-requirements {要件名}` を実行してください」とメッセージを表示 + - 終了する + +## step1: 要件情報の収集（要件定義書ベース） + +- 要件定義書の確認 + - `docs/spec/{要件名}/requirements.md` を Read で読み込み + - 読み込んだ内容を一時変数に保存 + +- 設計文書の確認 + - `docs/spec/{要件名}/design.md` が存在する場合は読み込み + - `docs/design/` ディレクトリ内の関連設計文書を検索・読み込み + - 読み込んだ内容を一時変数に保存 + +- タスクノートの確認 + - `docs/spec/{要件名}/note.md` が存在する場合は読み込み + - 読み込んだ内容を一時変数に保存 + +- 既存のエッジケース分析の確認 + - {{出力ディレクトリ}}/{{timestamp}}_*_edgecase/ を検索 + - 既存の分析がある場合は最新のものを参照 + +- 収集した情報のサマリーを作成し、context の収集情報に保存 + - 要件の概要 + - 主要機能リスト + - 既知の制約事項 + - 技術スタック + - 要件定義書の内容 + - 設計文書の内容 + - タスクノートの内容 + +- step2 を実行する + +## step1-source: ソースコードからの対象特定と情報収集 + +- ユーザーに分析内容を確認する + - 「ソースコードから「{{分析対象}}」に関連するエッジケースを分析します」と宣言 + +- Task ツールで関連ファイル・情報の特定を実行する + - subagent_type: "Explore" + - model: "haiku" + - description: "エッジケース分析対象の特定" + - prompt: 以下の内容でエージェントに依頼 + ``` + 「{{分析対象}}」に関連する以下の情報を収集してください： + + 1. 関連するソースコードファイルの特定 + - メインロジック（ビジネスロジック、コントローラー、サービス等） + - データモデル・スキーマ定義 + - API エンドポイント定義 + - UI コンポーネント（該当する場合） + - テストコード + - 設定ファイル + + 2. 技術スタックの把握 + - 使用されているフレームワーク + - ライブラリ・パッケージ + - データベース・ストレージ + - 外部API・サービス連携 + + 3. アーキテクチャパターンの理解 + - レイヤー構造 + - データフロー + - エラーハンドリング方針 + - 非同期処理の有無 + - 認証・認可の仕組み + + 4. 既存のエラーハンドリング状況 + - try-catch の使用箇所 + - バリデーションの実装 + - リトライ・フォールバック処理 + - ログ出力 + + 収集した情報を構造化してまとめてください。 + ``` + +- Explore エージェントの結果を受け取る + +- 収集した情報のサマリーを作成し、context の収集情報に保存 + - 分析対象の概要 + - 関連ファイルリスト（相対パスで記載） + - 技術スタック + - アーキテクチャパターン + - データフロー + - 既存のエラーハンドリング状況 + - 非同期処理の実装状況 + - 認証・認可の仕組み + +- ユーザーに収集結果を報告し、続行確認を得る + - 「以下の情報を収集しました。この内容でエッジケース分析を続行しますか？」 + - サマリーを表示（主要なファイル、技術スタック、識別されたリスク領域など） + +- step2 を実行する + +## step2: 分析スコープの決定 + +- AskUserQuestion ツールを使って分析スコープを質問する： + - question: "エッジケース分析のスコープを選択してください" + - header: "分析スコープ" + - multiSelect: false + - options: + - label: "包括的分析（推奨）" + description: "全レイヤーのエッジケースを網羅的に分析。発生可能性・影響度を詳細評価" + - label: "重点分析" + description: "主要レイヤーのみ分析。Must Have要件に集中" + - label: "カスタム" + description: "分析対象レイヤーを個別に選択" + +- ユーザーの選択を context に保存 + +- カスタムを選択した場合は、AskUserQuestion ツールを使って分析対象レイヤーを質問： + - question: "分析対象のレイヤーを選択してください（複数選択可）" + - header: "対象レイヤー" + - multiSelect: true + - options: + - label: "アプリケーション層" + description: "ビジネスロジックの状態遷移・バリデーション" + - label: "UI層" + description: "画面状態・ユーザー操作の組み合わせ" + - label: "データ管理層" + description: "トランザクション・同期・キャッシュ" + - label: "ネットワーク通信層" + description: "HTTPエラー・タイムアウト・リトライ" + - label: "非同期処理層" + description: "ジョブキュー・ワークフロー・並行処理" + - label: "認証・認可層" + description: "セッション・権限・トークン" + - label: "複合的エッジケース" + description: "複数レイヤーにまたがる複雑なケース" + +- step3 を実行する + +## step3: 初期分析の実行とチェックリスト初期化 + +- 出力ディレクトリの決定 + - Bash ツールで現在のタイムスタンプを取得する + - `date +%Y%m%d%H%M%S` で yyyyMMddHHmmss 形式のタイムスタンプを取得 + - {{出力ディレクトリ}}/{{timestamp}}_*/ を検索して既存の分析を確認 + - 分析対象を英語化する + - 要件定義書ベースの場合: 要件名を英語化（例: "user_auth_edgecase"） + - ソースコードベースの場合: 分析対象を英語化（例: "task_manager_edgecase"） + - **カレントディレクトリからの相対パスとして**ベースディレクトリを決定する + - 相対パス形式: "{{出力ディレクトリ}}/{{timestamp}}_{{英語化名}}_edgecase" + - 例: ".dcs/20251219103045_user_auth_edgecase" + - **絶対パスは使用しない**（例: `/Users/kuroeda.makoto/projects/ensemble/.dcs/...` のような形式は使わない） + +- チェックリストファイルのパス設定 + - チェックリストパス = "{{ベースディレクトリ}}/check_list.md" （相対パス） + +- 既存チェックリストの読み込み（オプション） + - ユーザーが他のチェックリストファイルを指定している場合、Read で読み込む + - 読み込んだチェックリスト項目を 既存チェックリスト に追加 + - 形式: "- [ ] P0 説明 [リンク](path)" + +- 分析結果ファイルのリストを準備する（すべて相対パスで記述） + - インデックスファイル: "{{ベースディレクトリ}}/index.md" + - チェックリストファイル: "{{ベースディレクトリ}}/check_list.md" + - 初期分析ファイル: "{{ベースディレクトリ}}/initial_analysis.md" + - レイヤー別分析ファイル（500行超過時は枝番付き）: + - "{{ベースディレクトリ}}/layer_analysis_app.md" (アプリケーション層) + - "{{ベースディレクトリ}}/layer_analysis_ui.md" (UI層) + - "{{ベースディレクトリ}}/layer_analysis_data.md" (データ管理層) + - "{{ベースディレクトリ}}/layer_analysis_network.md" (ネットワーク通信層) + - "{{ベースディレクトリ}}/layer_analysis_async.md" (非同期処理層) + - "{{ベースディレクトリ}}/layer_analysis_auth.md" (認証・認可層) + - "{{ベースディレクトリ}}/layer_analysis_summary.md" (サマリー) + - 複合分析ファイル（500行超過時は枝番付き）: + - "{{ベースディレクトリ}}/combined_analysis_data_state.md" (データモデル状態組み合わせ) + - "{{ベースディレクトリ}}/combined_analysis_multi_layer.md" (複数レイヤー) + - "{{ベースディレクトリ}}/combined_analysis_cascade.md" (カスケード障害) + - "{{ベースディレクトリ}}/combined_analysis_timing.md" (タイミング依存) + - "{{ベースディレクトリ}}/combined_analysis_summary.md" (サマリー) + - 最終レポートファイル: "{{ベースディレクトリ}}/final_report.md" + +- すべてのファイル名を 分析ファイルリスト に追加する + +- **ベースディレクトリを作成する** + - Bash ツールで `mkdir -p {{ベースディレクトリ}}` を実行して、ベースディレクトリを作成する + - 例: `mkdir -p .dcs/20251219103045_user_auth_edgecase` + +- チェックリストファイルの初期化 + - Write ツールで "{{ベースディレクトリ}}/check_list.md" を作成（**相対パスを使用**） + - 内容: + ```markdown + # エッジケース分析チェックリスト + + **分析対象**: {{分析対象名}} + **分析モード**: {{分析モード}} + **実施日時**: {{実施日時}} + + --- + + ## P0: 即座に対応が必要 + + ## P1: 早急に対応 + + ## P2: 計画的に対応 + + ## P3: 監視 + + --- + + *このチェックリストは分析の進行に伴い自動更新されます* + ``` + +- の内容を context の情報で埋めて、Task ツールで実行する + - subagent_type: "general-purpose" + - model: "opus" + - description: "エッジケース初期分析の実行" + - prompt: テンプレートの内容を以下のように埋めた完全なプロンプト + - **{{ベースディレクトリ}}**: カレントディレクトリからの相対パス（例: ".dcs/20251219103045_user_auth_edgecase"） + - **{{カレントディレクトリ}}**: プロジェクトルートの絶対パス + - 分析モードが "requirements-based" の場合: + - {{分析対象名}} → {{要件名}} + - {{収集済み情報}} → {{収集情報}}（要件定義書、設計文書、タスクノート） + - {{分析モード}} → "requirements-based" + - 分析モードが "source-based" の場合: + - {{分析対象名}} → {{分析対象}} + - {{収集済み情報}} → {{収集情報}}（ソースコードから収集した情報） + - {{分析モード}} → "source-based" + - **重要**: ファイルパスは必ず相対パスで記述すること + +- Task の実行結果を受け取る +- step4 を実行する + +## step4: レイヤー別エッジケース分析の並列実行 + +- 初期分析結果を Read で確認する + +- ユーザに分析状況を報告し、続行確認を得る + - 「6つのレイヤー（アプリケーション、UI、データ管理、ネットワーク、非同期、認証）を並列分析します」 + +- レイヤー別分析を並列実行する（**重要: 1つのメッセージで6つのTask toolを並列実行**） + - 各レイヤーごとに Task ツールを使用: + 1. アプリケーション層: layer_analysis_app.md + - subagent_type: "general-purpose" + - model: "opus" + - description: "アプリケーション層エッジケース分析" + - prompt: の内容 + 2. UI層: layer_analysis_ui.md + - subagent_type: "general-purpose" + - model: "opus" + - description: "UI層エッジケース分析" + - prompt: の内容 + 3. データ管理層: layer_analysis_data.md + - subagent_type: "general-purpose" + - model: "opus" + - description: "データ管理層エッジケース分析" + - prompt: の内容 + 4. ネットワーク通信層: layer_analysis_network.md + - subagent_type: "general-purpose" + - model: "opus" + - description: "ネットワーク通信層エッジケース分析" + - prompt: の内容 + 5. 非同期処理層: layer_analysis_async.md + - subagent_type: "general-purpose" + - model: "opus" + - description: "非同期処理層エッジケース分析" + - prompt: の内容 + 6. 認証・認可層: layer_analysis_auth.md + - subagent_type: "general-purpose" + - model: "opus" + - description: "認証・認可層エッジケース分析" + - prompt: の内容 + +- 各Taskの実行結果を受け取る + +- すべてのレイヤー別分析ファイルが作成されたことを確認 + - Read で各ファイルの存在確認 + +- チェックリストの更新 + - 各レイヤー分析結果からチェックリスト項目を抽出 + - 既存チェックリスト と重複チェック（同じ内容の項目は追加しない） + - 重複していない項目のみを check_list.md に追加 + - Edit ツールで check_list.md を更新 + - フォーマット: "- [ ] P0/P1/P2/P3 説明 [ファイル名](./layer_analysis_*.md#anchor)" + +- レイヤー別サマリーを作成 + - Task ツールで layer_analysis_summary.md を生成 + - subagent_type: "general-purpose" + - model: "opus" + - description: "レイヤー別分析サマリー作成" + - 全レイヤーの統計情報を集約 + +- step5 を実行する + +## step5: 複合エッジケース分析の並列実行 + +- レイヤー別分析結果をすべて Read で確認する + - layer_analysis_*.md のすべてのファイルを読み込む + +- ユーザに分析状況を報告し、続行確認を得る + - 「4つのカテゴリ（データモデル状態、複数レイヤー、カスケード障害、タイミング依存）を並列分析します」 + +- 複合エッジケース分析を並列実行する（**重要: 1つのメッセージで4つのTask toolを並列実行**） + - 各カテゴリごとに Task ツールを使用: + 1. データモデル状態組み合わせ: combined_analysis_data_state.md + - subagent_type: "general-purpose" + - model: "opus" + - description: "データモデル状態組み合わせ分析" + - prompt: の内容 + 2. 複数レイヤーにまたがるケース: combined_analysis_multi_layer.md + - subagent_type: "general-purpose" + - model: "opus" + - description: "複数レイヤーエッジケース分析" + - prompt: の内容 + 3. カスケード障害: combined_analysis_cascade.md + - subagent_type: "general-purpose" + - model: "opus" + - description: "カスケード障害分析" + - prompt: の内容 + 4. タイミング依存の問題: combined_analysis_timing.md + - subagent_type: "general-purpose" + - model: "opus" + - description: "タイミング依存問題分析" + - prompt: の内容 + +- 各Taskの実行結果を受け取る + +- すべての複合分析ファイルが作成されたことを確認 + - Read で各ファイルの存在確認 + +- チェックリストの更新 + - 各複合分析結果からチェックリスト項目を抽出 + - 既存チェックリスト と重複チェック（同じ内容の項目は追加しない） + - 重複していない項目のみを check_list.md に追加 + - Edit ツールで check_list.md を更新 + - フォーマット: "- [ ] P0/P1/P2/P3 説明 [ファイル名](./combined_analysis_*.md#anchor)" + +- 複合分析サマリーを作成 + - Task ツールで combined_analysis_summary.md を生成 + - subagent_type: "general-purpose" + - model: "opus" + - description: "複合分析サマリー作成" + - 全カテゴリの統計情報を集約 + +- step6 を実行する + +## step6: 最終レポートの作成と完了報告 + +- すべての分析結果ファイルを Read で確認する + - initial_analysis.md + - layer_analysis_*.md （全6レイヤー + サマリー） + - combined_analysis_*.md （全4カテゴリ + サマリー） + - check_list.md + +- 最終レポートを Task ツールで作成 + - subagent_type: "general-purpose" + - model: "opus" + - description: "エッジケース分析 最終レポート作成" + - prompt: の内容を context で埋めた完全なプロンプト + - 最終レポートファイル名: "{{ベースディレクトリ}}/final_report.md" + - 重要な指示: + - 500行以内に収めること + - すべての分析結果へのリンクを含めること + - check_list.md へのリンクを含めること + +- index.md を更新する + - Edit ツールで index.md を更新 + - すべての分析ファイルへのリンクを含める + - check_list.md へのリンクを追加 + - 分析結果のサマリーを追加 + - 枝番ファイルがある場合は、すべてのファイルへのリンクを記載 + +- check_list.md の最終確認 + - Read で check_list.md を確認 + - P0/P1/P2/P3 ごとの項目数をカウント + - 重複がないことを確認 + +- 全ての分析ファイルのパスを段階別に整理して表示する + - チェックリスト: check_list.md + - 初期分析ファイル: initial_analysis.md + - レイヤー別分析ファイル（6レイヤー + サマリー）: + - layer_analysis_app.md （枝番ファイルがある場合は _1.md, _2.md... も表示） + - layer_analysis_ui.md + - layer_analysis_data.md + - layer_analysis_network.md + - layer_analysis_async.md + - layer_analysis_auth.md + - layer_analysis_summary.md + - 複合分析ファイル（4カテゴリ + サマリー）: + - combined_analysis_data_state.md （枝番ファイルがある場合は表示） + - combined_analysis_multi_layer.md + - combined_analysis_cascade.md + - combined_analysis_timing.md + - combined_analysis_summary.md + - 最終レポート: final_report.md + - インデックス: index.md + +- エッジケース分析完了をユーザに報告する + - 発見されたエッジケースの総数 + - レイヤー別の内訳 + - 複合エッジケースの内訳 + - 高リスク（影響度:高 かつ 発生可能性:中以上）のケース数 + - チェックリスト項目数（P0/P1/P2/P3 別） + - 推奨される対応優先順位 + - 出力されたファイル数 + - check_list.md のパスを強調表示 + +# rules + +## ファイル名のルール + +### timestamp の形式 +- yyyyMMddHHmmss 形式（例: 20251219103045） + +### 要件名の英語化のルール +- 要件名を簡潔な英語に変換する +- スネークケース（snake_case）を使用 +- 最大30文字程度に収める +- "_edgecase" サフィックスを付ける +- 例: + - "ユーザー認証システム" → "user_auth_edgecase" + - "決済フロー" → "payment_flow_edgecase" + - "データ同期機能" → "data_sync_edgecase" + +### セクション別ファイル名のルール +- 分析結果は段階ごとに分割し、各ファイル500行以内を目標とする +- **500行を超える場合は枝番（_1, _2, _3...）をつけてさらに分割する** +- 枝番ファイルのルール: + - ベース名に `_数字` を付ける（例: `layer_analysis_app_1.md`, `layer_analysis_app_2.md`） + - 各枝番ファイルも500行以内に収める + - 各枝番ファイルの最後に、次のファイルへのリンクを記載する + - サマリーファイルには、すべての枝番ファイルへのリンクを含める +- ファイル一覧: + - `index.md` - インデックス（全体概要とファイル一覧） + - `initial_analysis.md` - 初期分析結果（超過時: initial_analysis_1.md, _2.md...） + - レイヤー別エッジケース分析（レイヤーごとに分割、500行超過時は枝番付き）: + - `layer_analysis_app.md` - アプリケーション層（超過時: _1.md, _2.md, _3.md...） + - `layer_analysis_ui.md` - UI層（超過時: _1.md, _2.md...） + - `layer_analysis_data.md` - データ管理層（超過時: _1.md, _2.md...） + - `layer_analysis_network.md` - ネットワーク通信層（超過時: _1.md, _2.md...） + - `layer_analysis_async.md` - 非同期処理層（超過時: _1.md, _2.md...） + - `layer_analysis_auth.md` - 認証・認可層（超過時: _1.md, _2.md...） + - `layer_analysis_summary.md` - レイヤー別分析サマリー + - 複合エッジケース分析（カテゴリごとに分割、500行超過時は枝番付き）: + - `combined_analysis_data_state.md` - データモデル状態組み合わせ（超過時: _1.md, _2.md...） + - `combined_analysis_multi_layer.md` - 複数レイヤーにまたがるケース（超過時: _1.md, _2.md...） + - `combined_analysis_cascade.md` - カスケード障害（超過時: _1.md, _2.md...） + - `combined_analysis_timing.md` - タイミング依存の問題（超過時: _1.md, _2.md...） + - `combined_analysis_summary.md` - 複合分析サマリー + - `final_report.md` - 最終レポート（500行以内） + +### 完全なファイル名の例 +- `.dcs/20251219103045_user_auth_edgecase/index.md` +- `.dcs/20251219103045_user_auth_edgecase/initial_analysis.md` +- `.dcs/20251219103045_user_auth_edgecase/layer_analysis_app_1.md`（500行超過のため枝番付き） +- `.dcs/20251219103045_user_auth_edgecase/layer_analysis_app_2.md` +- `.dcs/20251219103045_user_auth_edgecase/layer_analysis_app_3.md` +- `.dcs/20251219103045_user_auth_edgecase/layer_analysis_ui.md`（500行以内） +- （以下、各レイヤーのファイル） +- `.dcs/20251219103045_user_auth_edgecase/combined_analysis_data_state_1.md`（500行超過のため枝番付き） +- `.dcs/20251219103045_user_auth_edgecase/combined_analysis_data_state_2.md` +- （以下、各複合分析のファイル） +- `.dcs/20251219103045_user_auth_edgecase/final_report.md` + +## ファイルパスの記載ルール + +- **カレントディレクトリを基準とした相対パスを使用する** +- フルパス（絶対パス）は記載しない +- カレントディレクトリは分析開始時の作業ディレクトリ +- すべてのファイルパスは相対パスで統一する +- 例: + - ❌ `/Users/username/projects/app/src/utils/helper.ts` + - ✅ `src/utils/helper.ts` + - ❌ `/Users/kuroeda.makoto/projects/ensemble/.dcs/20251219103045_user_auth_edgecase/index.md` + - ✅ `.dcs/20251219103045_user_auth_edgecase/index.md` + +## エッジケース分析の観点 + +### アプリケーション層（ビジネスロジック） +- 状態遷移の異常パターン +- ビジネスルールの境界値・例外 +- バリデーションエラーの組み合わせ +- 並行実行時の整合性 +- タイミング依存の問題 + +### UI層 +- 画面状態の不整合 +- ユーザー操作の予期しないシーケンス +- 複数画面間の状態遷移 +- 入力値の境界値・特殊文字 +- デバイス・ブラウザ固有の問題 +- オフライン・オンライン切替時の挙動 + +### データ管理層 +- トランザクション失敗・ロールバック +- デッドロック・競合 +- データ同期の不整合 +- キャッシュの不一致 +- データベース接続エラー +- データ移行時の問題 +- バックアップ・リストア時の問題 + +### ネットワーク通信層 +- HTTPステータスコード（4xx, 5xx） +- タイムアウト（接続・読み取り・書き込み） +- リトライ回数超過 +- ネットワーク分断（パーティション） +- レート制限 +- プロキシ・ファイアウォールの影響 +- DNS解決失敗 + +### 非同期処理・メッセージング +- ジョブキューの失敗・リトライ +- ワークフローの中断・再開 +- メッセージの順序不整合 +- メッセージ重複処理 +- デッドレター処理 +- 並行実行時の競合 + +### 認証・認可層 +- セッションタイムアウト +- トークン有効期限切れ +- 権限不足・権限昇格 +- 多重ログイン +- ログアウト失敗 +- パスワードリセット中の操作 +- 二段階認証失敗 + +### エラーハンドリング +- 未キャッチ例外 +- エラーメッセージの不適切な露出 +- エラーログの欠落 +- リカバリー処理の失敗 +- エラー通知の失敗 + +### データモデル状態の組み合わせ +- 複数エンティティの状態組み合わせ +- マスタデータとトランザクションデータの不整合 +- 論理削除と物理削除の混在 +- バージョニングの問題 +- 親子関係の整合性 + +### 複合的なエッジケース +- 複数レイヤーにまたがる障害 +- カスケード障害 +- タイムゾーン・ロケールの問題 +- パフォーマンス劣化時の挙動 +- リソース枯渇（メモリ・ディスク・CPU） +- システムメンテナンス中の操作 + +## エッジケース評価基準 + +### 発生可能性 +- **高**: 日常的に発生しうる（週次・月次レベル） +- **中**: 稀に発生する（四半期・年次レベル） +- **低**: 極めて稀（複数年に1回程度） + +### 影響度 +- **高**: サービス停止・データ損失・セキュリティ侵害 +- **中**: 機能制限・ユーザー体験悪化・一時的な不整合 +- **低**: 軽微な不便・ログ出力・監視アラート + +### リスクレベル（発生可能性 × 影響度） +- **クリティカル**: 高×高 +- **高**: 高×中、中×高 +- **中**: 高×低、中×中、低×高 +- **低**: 中×低、低×中、低×低 + +## 推奨対応優先度 + +### P0（即座に対応） +- リスクレベル: クリティカル +- 影響度: 高 +- 対応方針: 実装前に必ず対処 + +### P1（早急に対応） +- リスクレベル: 高 +- 影響度: 中以上 +- 対応方針: 初期リリースに含める + +### P2（計画的に対応） +- リスクレベル: 中 +- 影響度: 中以下 +- 対応方針: 次期バージョンで対応 + +### P3（監視） +- リスクレベス: 低 +- 影響度: 低 +- 対応方針: ログ・監視で検知、必要に応じて対応 + +## エッジケース記載の品質基準 + +### 確度評価の基準（⭐ 1-5段階） + +- ⭐⭐⭐⭐⭐: コード/設計書で確認済み、発生メカニズムが明確、影響度評価が完了 +- ⭐⭐⭐⭐: コード/設計書で確認済み、発生メカニズムがほぼ明確 +- ⭐⭐⭐: コード/設計書で確認済み、発生の可能性を特定 +- ⭐⭐: コード/設計書で関連箇所を確認したが、発生条件は推測の域 +- ⭐: 一般的なパターンに該当するが、コード/設計書での明確な証拠なし + +**重要**: ⭐⭐未満のエッジケースは記載しない。コード/設計書での証拠がないものは推測と見なし除外する。 + +### エッジケース記載の絶対条件 + +エッジケースを記載するには、以下すべてを満たす必要がある： +1. コードベース/設計書で具体的な該当箇所を特定できた（ファイル:行番号 または 設計書のセクション） +2. エッジケース発生のメカニズムを論理的に説明できる +3. 実際のコード/設計書でエッジケースの存在を確認した +4. 確度が⭐⭐以上 + +上記条件を満たさないエッジケースは記載しない。推測のみのケース、一般論、ベストプラクティスの列挙は不要。 + +### 網羅性と品質のバランス + +- ✅ 可能性のあるエッジケースを幅広く調査する（網羅性） +- ✅ ただし、コード/設計書での証拠がない推測は記載しない（品質） +- ❌ 一般論やベストプラクティスの列挙は不要 +- ❌ 「このような問題が起こりうる」という可能性の羅列は不要 +- ✅ エッジケース数の上限は設けない（網羅性重視） +- ✅ ただし、各ケースは必ず根拠を持つこと（品質重視） + +# info + + +あなたはエッジケース分析のエキスパートです。以下の情報に基づいて、システムのエッジケース分析の初期調査を実施してください。 + +# 重要な分析方針 + +**網羅性と品質のバランス**: +- ✅ 可能性のあるエッジケースを幅広く調査する（網羅性） +- ✅ ただし、コード/設計書での証拠がない推測は記載しない（品質） +- ❌ 一般論やベストプラクティスの列挙は不要 +- ❌ 「このような問題が起こりうる」という可能性の羅列は不要 + +**エッジケース記載の絶対条件**: +1. コードベース/設計書で具体的な箇所を特定できた +2. エッジケース発生のメカニズムを論理的に説明できる +3. 確度が⭐⭐以上（コード/設計書での証拠がある） + +上記を満たさないエッジケースは、たとえ一般的なパターンでも記載しない。 + +# 分析対象の基本情報 + +分析対象名: {{分析対象名}} # 要件名 or 分析対象 +分析モード: {{分析モード}} # requirements-based or source-based +分析スコープ: {{分析スコープ}} +出力ファイル名: {{ベースディレクトリ}}/initial_analysis.md +カレントディレクトリ: {{カレントディレクトリ}} + +# 収集済み情報 + +{{収集済み情報}} + +# 分析の進め方 + +- 分析モードが "requirements-based" の場合: + - 要件定義書、設計文書、タスクノートの内容を基に分析を進める + - 実装予定の機能のエッジケースを予測的に特定する + - 設計書での記載を証拠として、確度⭐⭐以上のケースを特定 + +- 分析モードが "source-based" の場合: + - ソースコードから収集した情報を基に分析を進める + - 既存の実装を確認しながら、現在のエッジケース対応状況と不足点を特定する + - コードでの実装状況を証拠として、確度⭐⭐以上のケースを特定 + +# 重要な注意事項 + +**すべてのファイルパスは、カレントディレクトリを基準とした相対パスで記載してください。** +**絶対パス（/Users/... や C:\\... など）は使用しないでください。** +**このファイルは500行以内を目標としてください。** +**確度⭐⭐未満のエッジケースは記載しない。推測のみのケースは除外する。** + +# 初期分析の手順 + +## 1. 要件の理解とスコープ確認 + +- 要件定義書から主要機能を抽出 +- 各機能の入出力を特定 +- データフローを把握 +- 外部システム連携を確認 +- 技術スタックとアーキテクチャを理解 + +## 2. 潜在的なエッジケース領域の特定 + +### 使用するツール +- Grep: キーワード検索で関連コードを特定 +- Glob: ファイルパターンで実装ファイルを列挙 +- Read: 特定ファイルの内容確認 + +### 検索キーワードの選定 +- エラーハンドリング: "try", "catch", "throw", "error" +- 非同期処理: "async", "await", "Promise", "setTimeout" +- トランザクション: "transaction", "commit", "rollback" +- バリデーション: "validate", "check", "verify" +- 認証: "auth", "session", "token", "permission" +- ネットワーク: "fetch", "axios", "request", "timeout" + +### 検索の実施 +1. 各キーワードで Grep 検索 +2. 見つかったファイルを Read で確認 +3. 既存のエラーハンドリング状況を把握 +4. 不足している対応を特定 + +## 3. レイヤー別の初期調査 + +### アプリケーション層 +- ビジネスロジックの複雑度 +- 状態遷移の数 +- バリデーションルールの数 + +### UI層 +- 画面数と画面遷移 +- フォーム入力の数 +- ユーザー操作の種類 + +### データ管理層 +- テーブル数と関連 +- トランザクション境界 +- キャッシュ戦略 + +### ネットワーク通信層 +- 外部API呼び出し箇所 +- タイムアウト設定 +- リトライ設定 + +### 非同期処理層 +- ジョブキューの種類 +- ワークフローの複雑度 +- 並行処理の箇所 + +### 認証・認可層 +- 認証方式 +- 権限レベル +- セッション管理方式 + +## 4. 初期分析結果のまとめ + +以下の形式で結果をファイルに出力してください。Write ツールを使用して保存してください。 + +```markdown +# エッジケース分析 - 初期分析結果 + +**実施日時**: {{実施日時}} +**分析者**: Claude Code +**分析対象**: {{分析対象名}} +**分析モード**: {{分析モード}} + +[← インデックスに戻る](./index.md) + +--- + +## 分析対象の概要 + +### 要件サマリー +{{要件の概要}} + +### 主要機能 +1. {{機能1}} +2. {{機能2}} +3. {{機能3}} + +### 技術スタック +- フロントエンド: {{技術}} +- バックエンド: {{技術}} +- データベース: {{技術}} +- インフラ: {{技術}} + +--- + +## レイヤー別の初期調査結果 + +### アプリケーション層 + +#### 状態遷移の複雑度 +- 状態の種類: {{数}}個 +- 遷移パターン: {{数}}パターン + +#### 識別された潜在的エッジケース + +以下は、コード/設計書で確認し、確度⭐⭐以上のエッジケースのみ記載。 + +1. **{{エッジケース名}}** + - **確度**: ⭐⭐⭐⭐⭐（必須: ⭐⭐以上） + - **証拠**: [相対パス:行番号](相対パス#L行番号) または 設計書セクション（必須） + - **発生条件**: {{具体的な発生メカニズムを論理的に説明}}（必須） + - **発生可能性**: 高/中/低 + - **影響度**: 高/中/低 + - **現在の対応**: {{対応状況}} + - **不足している対応**: {{何が不足しているか}} + - **推奨優先度**: P0/P1/P2/P3 + +2. **{{エッジケース名}}** + （同様の形式で複数記載。上記7項目すべて必須） + +**重要**: 確度⭐⭐未満、コード/設計書での証拠がないエッジケースは記載しない。 + +### UI層 + +#### 画面遷移の複雑度 +- 画面数: {{数}}画面 +- 遷移パターン: {{数}}パターン + +#### 識別された潜在的エッジケース + +以下は、コード/設計書で確認し、確度⭐⭐以上のエッジケースのみ記載。 + +1. **{{エッジケース名}}** + - **確度**: ⭐⭐⭐⭐⭐（必須: ⭐⭐以上） + - **証拠**: [相対パス:行番号](相対パス#L行番号) または 設計書セクション（必須） + - **発生条件**: {{具体的な発生メカニズムを論理的に説明}}（必須） + - **発生可能性**: 高/中/低 + - **影響度**: 高/中/低 + - **現在の対応**: {{対応状況}} + - **不足している対応**: {{何が不足しているか}} + - **推奨優先度**: P0/P1/P2/P3 + +**重要**: 確度⭐⭐未満、コード/設計書での証拠がないエッジケースは記載しない。 + +### データ管理層 + +#### データ構造の複雑度 +- テーブル数: {{数}}個 +- リレーション数: {{数}}個 + +#### 識別された潜在的エッジケース + +以下は、コード/設計書で確認し、確度⭐⭐以上のエッジケースのみ記載。 + +1. **{{エッジケース名}}** + - **確度**: ⭐⭐⭐⭐⭐（必須: ⭐⭐以上） + - **証拠**: [相対パス:行番号](相対パス#L行番号) または 設計書セクション（必須） + - **発生条件**: {{具体的な発生メカニズムを論理的に説明}}（必須） + - **発生可能性**: 高/中/低 + - **影響度**: 高/中/低 + - **現在の対応**: {{対応状況}} + - **不足している対応**: {{何が不足しているか}} + - **推奨優先度**: P0/P1/P2/P3 + +**重要**: 確度⭐⭐未満、コード/設計書での証拠がないエッジケースは記載しない。 + +### ネットワーク通信層 + +#### 外部連携の複雑度 +- API呼び出し箇所: {{数}}箇所 +- タイムアウト設定: {{設定状況}} + +#### 識別された潜在的エッジケース + +以下は、コード/設計書で確認し、確度⭐⭐以上のエッジケースのみ記載。 + +1. **{{エッジケース名}}** + - **確度**: ⭐⭐⭐⭐⭐（必須: ⭐⭐以上） + - **証拠**: [相対パス:行番号](相対パス#L行番号) または 設計書セクション（必須） + - **発生条件**: {{具体的な発生メカニズムを論理的に説明}}（必須） + - **発生可能性**: 高/中/低 + - **影響度**: 高/中/低 + - **現在の対応**: {{対応状況}} + - **不足している対応**: {{何が不足しているか}} + - **推奨優先度**: P0/P1/P2/P3 + +**重要**: 確度⭐⭐未満、コード/設計書での証拠がないエッジケースは記載しない。 + +### 非同期処理層 + +#### 非同期処理の複雑度 +- ジョブの種類: {{数}}種類 +- 並行処理箇所: {{数}}箇所 + +#### 識別された潜在的エッジケース + +以下は、コード/設計書で確認し、確度⭐⭐以上のエッジケースのみ記載。 + +1. **{{エッジケース名}}** + - **確度**: ⭐⭐⭐⭐⭐（必須: ⭐⭐以上） + - **証拠**: [相対パス:行番号](相対パス#L行番号) または 設計書セクション（必須） + - **発生条件**: {{具体的な発生メカニズムを論理的に説明}}（必須） + - **発生可能性**: 高/中/低 + - **影響度**: 高/中/低 + - **現在の対応**: {{対応状況}} + - **不足している対応**: {{何が不足しているか}} + - **推奨優先度**: P0/P1/P2/P3 + +**重要**: 確度⭐⭐未満、コード/設計書での証拠がないエッジケースは記載しない。 + +### 認証・認可層 + +#### 認証・認可の複雑度 +- 認証方式: {{方式}} +- 権限レベル: {{数}}レベル + +#### 識別された潜在的エッジケース + +以下は、コード/設計書で確認し、確度⭐⭐以上のエッジケースのみ記載。 + +1. **{{エッジケース名}}** + - **確度**: ⭐⭐⭐⭐⭐（必須: ⭐⭐以上） + - **証拠**: [相対パス:行番号](相対パス#L行番号) または 設計書セクション（必須） + - **発生条件**: {{具体的な発生メカニズムを論理的に説明}}（必須） + - **発生可能性**: 高/中/低 + - **影響度**: 高/中/低 + - **現在の対応**: {{対応状況}} + - **不足している対応**: {{何が不足しているか}} + - **推奨優先度**: P0/P1/P2/P3 + +**重要**: 確度⭐⭐未満、コード/設計書での証拠がないエッジケースは記載しない。 + +--- + +## 関連コードファイル + +### 主要な実装ファイル + +#### [相対パス](相対パス) +- **役割**: {{ファイルの役割}} +- **エッジケース関連度**: 高/中/低 +- **理由**: {{なぜ関連するのか}} + +--- + +## 既存のエラーハンドリング状況 + +### 実装済みの対応 + +#### [相対パス:行番号](相対パス#L行番号) +- **対応内容**: {{エラーハンドリングの内容}} +- **カバー範囲**: {{カバーしているケース}} +- **不足点**: {{不足している点}} + +### 未実装の対応 + +1. **{{未実装のケース}}** + - 必要な対応: {{対応内容}} + - 優先度: P0/P1/P2/P3 + +--- + +## 初期リスク評価 + +### 高リスク領域 + +1. **{{リスク領域}}** + - リスクレベル: クリティカル/高/中/低 + - 理由: {{リスクが高い理由}} + - 推奨対応: {{推奨される対応}} + +### 中リスク領域 + +（同様の形式で記載） + +### 注意が必要な領域 + +（同様の形式で記載） + +--- + +## 次段階の分析方針 + +### レイヤー別分析で確認すべき点 +1. {{確認ポイント1}} +2. {{確認ポイント2}} +3. {{確認ポイント3}} + +### 複合分析で確認すべき点 +1. {{確認ポイント1}} +2. {{確認ポイント2}} + +--- + +*この初期分析結果は自動生成されたものです。次段階のレイヤー別分析でさらに詳細を確認します。* +``` + +最後に、インデックスファイル（{{ベースディレクトリ}}/index.md）も作成してください。インデックスファイルには以下の内容を含めてください： + +```markdown +# エッジケース分析 - インデックス + +**実施日時**: {{実施日時}} +**分析者**: Claude Code +**分析対象**: {{分析対象名}} +**分析モード**: {{分析モード}} + +--- + +## 📋 チェックリスト + +**重要**: 対応が必要なエッジケースの一覧は[チェックリスト](./check_list.md)を参照してください。 + +- [📋 check_list.md](./check_list.md) - **優先対応すべきエッジケース一覧** + +--- + +## 分析対象情報 + +### 分析対象の概要 +{{分析対象の概要}} + +### 分析スコープ +{{分析スコープ}} + +--- + +## 分析結果ファイル一覧 + +### 分析段階 + +#### 初期分析 +- [初期分析](./initial_analysis.md) - レイヤー別の潜在的エッジケース特定 + +#### レイヤー別分析（6レイヤー + サマリー） + +**注意**: 各レイヤーが500行を超えた場合、枝番ファイル（_1.md, _2.md...）に分割されます。その場合は実際のファイル構成に応じてリンクを記載してください。 + +- [アプリケーション層](./layer_analysis_app.md) （500行超過時: [第1部](./layer_analysis_app_1.md) | [第2部](./layer_analysis_app_2.md)...） +- [UI層](./layer_analysis_ui.md) （500行超過時: 枝番ファイルへのリンク） +- [データ管理層](./layer_analysis_data.md) （500行超過時: 枝番ファイルへのリンク） +- [ネットワーク通信層](./layer_analysis_network.md) （500行超過時: 枝番ファイルへのリンク） +- [非同期処理層](./layer_analysis_async.md) （500行超過時: 枝番ファイルへのリンク） +- [認証・認可層](./layer_analysis_auth.md) （500行超過時: 枝番ファイルへのリンク） +- [レイヤー別サマリー](./layer_analysis_summary.md) + +#### 複合エッジケース分析（4カテゴリ + サマリー） + +**注意**: 各カテゴリが500行を超えた場合、枝番ファイルに分割されます。 + +- [データモデル状態組み合わせ](./combined_analysis_data_state.md) （500行超過時: 枝番ファイルへのリンク） +- [複数レイヤーにまたがるケース](./combined_analysis_multi_layer.md) （500行超過時: 枝番ファイルへのリンク） +- [カスケード障害](./combined_analysis_cascade.md) （500行超過時: 枝番ファイルへのリンク） +- [タイミング依存の問題](./combined_analysis_timing.md) （500行超過時: 枝番ファイルへのリンク） +- [複合分析サマリー](./combined_analysis_summary.md) + +#### 最終レポート +- [最終レポート](./final_report.md) - 包括的な分析結果とアクションプラン + +--- + +## クイックサマリー + +### 識別された高リスク領域 +1. {{高リスク領域1}} +2. {{高リスク領域2}} +3. {{高リスク領域3}} + +### 次のアクション +{{次に実施すべきこと}} + +--- + +*分析は段階的に実施されます。各段階の詳細は上記リンクから参照してください。* +``` + + + +あなたはエッジケース分析のエキスパートです。初期分析結果に基づいて、各レイヤーのエッジケースを詳細に分析してください。 + +# 重要な分析方針 + +**網羅性と品質のバランス**: +- ✅ 可能性のあるエッジケースを幅広く調査する（網羅性） +- ✅ ただし、コード/設計書での証拠がない推測は記載しない（品質） +- ❌ 一般論やベストプラクティスの列挙は不要 +- ❌ 「このような問題が起こりうる」という可能性の羅列は不要 + +**エッジケース記載の絶対条件**: +1. コードベース/設計書で具体的な箇所を特定できた +2. エッジケース発生のメカニズムを論理的に説明できる +3. 確度が⭐⭐以上（コード/設計書での証拠がある） + +上記を満たさないエッジケースは、たとえ一般的なパターンでも記載しない。 + +# 分析対象の情報 + +分析対象名: {{分析対象名}} +分析モード: {{分析モード}} +初期分析結果ファイル: {{ベースディレクトリ}}/initial_analysis.md +出力ファイル名: {{ベースディレクトリ}}/layer_analysis.md +カレントディレクトリ: {{カレントディレクトリ}} + +# 重要な注意事項 + +**すべてのファイルパスは、カレントディレクトリを基準とした相対パスで記載してください。** +**絶対パス（/Users/... や C:\\... など）は使用しないでください。** +**各レイヤーを個別のファイルに出力してください。各ファイルは500行以内を目標としてください。** +**500行を超える場合は、枝番（_1, _2, _3...）をつけて複数ファイルに分割してください。** +**確度⭐⭐未満のエッジケースは記載しない。推測のみのケースは除外する。** + +# 出力ファイル構成 + +各レイヤーごとにファイルを作成します。500行を超える場合は枝番ファイルに分割します： + +## 基本ファイル（各レイヤー） +1. `{{ベースディレクトリ}}/layer_analysis_app.md` - アプリケーション層（500行超過時: _1.md, _2.md...） +2. `{{ベースディレクトリ}}/layer_analysis_ui.md` - UI層（500行超過時: _1.md, _2.md...） +3. `{{ベースディレクトリ}}/layer_analysis_data.md` - データ管理層（500行超過時: _1.md, _2.md...） +4. `{{ベースディレクトリ}}/layer_analysis_network.md` - ネットワーク通信層（500行超過時: _1.md, _2.md...） +5. `{{ベースディレクトリ}}/layer_analysis_async.md` - 非同期処理層（500行超過時: _1.md, _2.md...） +6. `{{ベースディレクトリ}}/layer_analysis_auth.md` - 認証・認可層（500行超過時: _1.md, _2.md...） +7. `{{ベースディレクトリ}}/layer_analysis_summary.md` - レイヤー別分析のサマリー + +## 枝番ファイルのルール +- ファイルが500行を超える場合、`_1`, `_2`, `_3`... の枝番をつける +- 例: `layer_analysis_app_1.md`, `layer_analysis_app_2.md`, `layer_analysis_app_3.md` +- 各枝番ファイルの最後に「[次のファイルへ →](./layer_analysis_app_2.md)」のようなリンクを記載 +- サマリーファイルには、すべての枝番ファイルへのリンクを含める + +# レイヤー別エッジケース分析の手順 + +## 1. 初期分析結果の確認 + +- {{ベースディレクトリ}}/initial_analysis.md を Read で読み込む +- 特定された高リスク領域を把握する +- 分析の焦点を明確にする + +## 2. アプリケーション層の詳細分析 + +### ビジネスロジックの状態遷移 +- 正常な状態遷移パス +- 異常な状態遷移パターン +- 状態の不整合が発生する条件 +- ロールバックが必要なケース + +### バリデーションルール +- 入力値の境界値 +- 複数フィールドの組み合わせ +- ビジネスルール違反 +- データ型の不一致 + +### 並行実行 +- 同時実行時の競合 +- トランザクション分離レベル +- デッドロック発生条件 +- 楽観的ロック・悲観的ロック + +## 3. UI層の詳細分析 + +### 画面状態 +- ローディング状態 +- エラー状態 +- 部分的な更新失敗 +- オフライン状態 + +### ユーザー操作 +- 予期しない操作順序 +- 高速連打 +- ブラウザバック +- ページリロード +- タブの切り替え + +### 入力値 +- 空文字・null・undefined +- 最大長超過 +- 特殊文字（SQL injection、XSS） +- 制御文字・絵文字 +- 異常なファイルサイズ・形式 + +## 4. データ管理層の詳細分析 + +### トランザクション +- コミット失敗 +- ロールバック失敗 +- 分散トランザクション +- 長時間トランザクション + +### データ整合性 +- 外部キー制約違反 +- 一意制約違反 +- NOT NULL制約違反 +- CHECK制約違反 + +### キャッシュ +- キャッシュミス +- キャッシュの期限切れ +- キャッシュとDBの不整合 +- キャッシュの破損 + +### データ同期 +- マスタースレーブ遅延 +- レプリケーション失敗 +- コンフリクト解決 +- データロスト + +## 5. ネットワーク通信層の詳細分析 + +### HTTPステータスコード +- 4xx エラー（クライアントエラー） +- 5xx エラー（サーバーエラー） +- 3xx リダイレクト +- タイムアウト + +### リトライ戦略 +- リトライ回数超過 +- 指数バックオフ +- サーキットブレーカー +- べき等性の保証 + +### ネットワーク障害 +- 接続失敗 +- DNSエラー +- プロキシエラー +- ファイアウォールブロック + +## 6. 非同期処理層の詳細分析 + +### ジョブキュー +- ジョブ実行失敗 +- デッドレター処理 +- ジョブの重複実行 +- ジョブの順序保証 + +### ワークフロー +- ステップ失敗 +- 補償トランザクション +- タイムアウト +- 中断と再開 + +### 並行処理 +- 競合状態 +- デッドロック +- リソース枯渇 +- バックプレッシャー + +## 7. 認証・認可層の詳細分析 + +### セッション管理 +- セッションタイムアウト +- セッション固定攻撃 +- CSRF攻撃 +- セッションハイジャック + +### トークン管理 +- トークン有効期限切れ +- トークンの不正使用 +- リフレッシュトークンの失敗 +- トークンの漏洩 + +### 権限管理 +- 権限不足 +- 権限昇格 +- ロールの変更 +- リソースへのアクセス制御 + +## 8. レイヤー別分析結果のまとめ + +以下の手順で各レイヤーを個別のファイルに出力してください。Write ツールを使用して保存してください。 + +### 重要: ファイル分割のルール + +1. **行数カウント**: 各ファイルの内容を作成する際、500行を超えるかどうかを確認する +2. **500行以下の場合**: 通常のファイル名で1つのファイルに出力（例: `layer_analysis_app.md`） +3. **500行を超える場合**: + - 枝番ファイルに分割（例: `layer_analysis_app_1.md`, `layer_analysis_app_2.md`...） + - 各枝番ファイルは500行以内に収める + - 各枝番ファイルの最後に次のファイルへのリンクを追加 + - 最初のファイル（_1.md）のヘッダーに「全X部構成」と記載 + +### ファイル1: layer_analysis_app（アプリケーション層） + +**500行以下の場合**: `layer_analysis_app.md` + +```markdown +# エッジケース分析 - アプリケーション層 + +**実施日時**: {{実施日時}} +**分析者**: Claude Code + +[← インデックスに戻る](./index.md) | [初期分析](./initial_analysis.md) | [サマリーへ](./layer_analysis_summary.md) +``` + +**500行を超える場合**: `layer_analysis_app_1.md`, `layer_analysis_app_2.md`... + +```markdown +# エッジケース分析 - アプリケーション層（第1部 / 全3部） + +**実施日時**: {{実施日時}} +**分析者**: Claude Code + +[← インデックスに戻る](./index.md) | [初期分析](./initial_analysis.md) | [サマリーへ](./layer_analysis_summary.md) + +--- + +## アプリケーション層のエッジケース + +### EDGE-APP-001: {{エッジケース名}} + +**カテゴリ**: ビジネスロジック / バリデーション / 並行実行 + +**発生条件**: +{{このエッジケースが発生する条件}} + +**発生可能性**: 高 / 中 / 低 +**影響度**: 高 / 中 / 低 +**リスクレベル**: クリティカル / 高 / 中 / 低 + +**シナリオ**: +``` +1. {{ステップ1}} + ↓ +2. {{ステップ2}} + ↓ +3. {{エッジケース発生}} +``` + +**影響範囲**: +- ユーザー影響: {{ユーザーへの影響}} +- システム影響: {{システムへの影響}} +- データ影響: {{データへの影響}} + +**現在の対応状況**: +- 実装済み: ✅ / ❌ +- 対応箇所: [相対パス:行番号](相対パス#L行番号) +- 対応内容: {{対応の詳細}} + +**推奨対応**: +- 優先度: P0 / P1 / P2 / P3 +- 対応方針: {{推奨される対応方針}} +- 実装方法: {{具体的な実装方法}} +- テスト方法: {{テストケース}} + +**関連エッジケース**: EDGE-APP-002, EDGE-UI-001 + +--- + +### EDGE-APP-002: {{エッジケース名}} + +（同様の形式で複数記載） + +--- + +**ファイル分割について**: +- このファイルが500行以内の場合: ここで終了 +- このファイルが500行を超える場合: + - 現在のファイルを `layer_analysis_app_1.md` として保存 + - 以下のナビゲーションを最後に追加: + ``` + --- + [← 前のファイル](該当なし) | [インデックス](./index.md) | [次のファイルへ →](./layer_analysis_app_2.md) + ``` + - 続きを `layer_analysis_app_2.md` として作成 + - 2つ目のファイルも500行を超える場合は `layer_analysis_app_3.md` を作成、以降同様 + +**重要**: エッジケースが多い場合でも省略せず、すべて記載してください。ファイル分割で対応します。 +``` + +### ファイル2: layer_analysis_ui.md（UI層） + +```markdown +# エッジケース分析 - UI層 + +**実施日時**: {{実施日時}} +**分析者**: Claude Code + +[← インデックスに戻る](./index.md) | [初期分析](./initial_analysis.md) | [サマリーへ](./layer_analysis_summary.md) + +--- + +## UI層のエッジケース + +### EDGE-UI-001: {{エッジケース名}} + +**カテゴリ**: 画面状態 / ユーザー操作 / 入力値 + +**発生条件**: +{{このエッジケースが発生する条件}} + +**発生可能性**: 高 / 中 / 低 +**影響度**: 高 / 中 / 低 +**リスクレベル**: クリティカル / 高 / 中 / 低 + +**シナリオ**: +{{詳細なシナリオ}} + +**影響範囲**: +{{影響の詳細}} + +**現在の対応状況**: +{{対応状況}} + +**推奨対応**: +{{推奨される対応}} + +**関連エッジケース**: EDGE-UI-002, EDGE-APP-001 + +--- + +### EDGE-UI-002: {{エッジケース名}} + +（同様の形式で複数記載） + +--- + +## データ管理層のエッジケース + +### EDGE-DATA-001: {{エッジケース名}} + +**カテゴリ**: トランザクション / データ整合性 / キャッシュ / データ同期 + +**発生条件**: +{{このエッジケースが発生する条件}} + +**発生可能性**: 高 / 中 / 低 +**影響度**: 高 / 中 / 低 +**リスクレベル**: クリティカル / 高 / 中 / 低 + +**シナリオ**: +{{詳細なシナリオ}} + +**データ状態**: +| データ | 正常状態 | 異常状態 | 影響 | +|--------|---------|---------|------| +| {{データ1}} | {{正常値}} | {{異常値}} | {{影響}} | +| {{データ2}} | {{正常値}} | {{異常値}} | {{影響}} | + +**影響範囲**: +{{影響の詳細}} + +**現在の対応状況**: +{{対応状況}} + +**推奨対応**: +{{推奨される対応}} + +**関連エッジケース**: EDGE-DATA-002, EDGE-APP-003 + +--- + +### EDGE-DATA-002: {{エッジケース名}} + +（同様の形式で複数記載） + +--- + +## ネットワーク通信層のエッジケース + +### EDGE-NET-001: {{エッジケース名}} + +**カテゴリ**: HTTPエラー / タイムアウト / リトライ / ネットワーク障害 + +**発生条件**: +{{このエッジケースが発生する条件}} + +**発生可能性**: 高 / 中 / 低 +**影響度**: 高 / 中 / 低 +**リスクレベル**: クリティカル / 高 / 中 / 低 + +**シナリオ**: +{{詳細なシナリオ}} + +**ネットワークフロー**: +``` +Client → [障害点] → Server +``` + +**影響範囲**: +{{影響の詳細}} + +**現在の対応状況**: +{{対応状況}} + +**推奨対応**: +{{推奨される対応}} + +**関連エッジケース**: EDGE-NET-002, EDGE-ASYNC-001 + +--- + +### EDGE-NET-002: {{エッジケース名}} + +（同様の形式で複数記載） + +--- + +## 非同期処理層のエッジケース + +### EDGE-ASYNC-001: {{エッジケース名}} + +**カテゴリ**: ジョブキュー / ワークフロー / 並行処理 + +**発生条件**: +{{このエッジケースが発生する条件}} + +**発生可能性**: 高 / 中 / 低 +**影響度**: 高 / 中 / 低 +**リスクレベル**: クリティカル / 高 / 中 / 低 + +**シナリオ**: +{{詳細なシナリオ}} + +**タイムライン**: +``` +T0: {{イベント1}} +T1: {{イベント2}} +T2: {{エッジケース発生}} +``` + +**影響範囲**: +{{影響の詳細}} + +**現在の対応状況**: +{{対応状況}} + +**推奨対応**: +{{推奨される対応}} + +**関連エッジケース**: EDGE-ASYNC-002, EDGE-DATA-001 + +--- + +### EDGE-ASYNC-002: {{エッジケース名}} + +（同様の形式で複数記載） + +--- + +## 認証・認可層のエッジケース + +### EDGE-AUTH-001: {{エッジケース名}} + +**カテゴリ**: セッション / トークン / 権限 + +**発生条件**: +{{このエッジケースが発生する条件}} + +**発生可能性**: 高 / 中 / 低 +**影響度**: 高 / 中 / 低 +**リスクレベル**: クリティカル / 高 / 中 / 低 + +**シナリオ**: +{{詳細なシナリオ}} + +**セキュリティ影響**: +{{セキュリティへの影響}} + +**影響範囲**: +{{影響の詳細}} + +**現在の対応状況**: +{{対応状況}} + +**推奨対応**: +{{推奨される対応}} + +**関連エッジケース**: EDGE-AUTH-002, EDGE-APP-001 + +--- + +### EDGE-AUTH-002: {{エッジケース名}} + +（同様の形式で複数記載） + +--- + +**注意**: このファイルは500行以内に収めてください。 +``` + +**重要**: 上記の形式で、データ管理層、ネットワーク通信層、非同期処理層、認証・認可層についても同様に個別ファイルを作成してください。 + +## 7. チェックリスト項目の抽出 + +各レイヤー分析ファイルの作成後、以下の形式でチェックリスト項目を抽出してください： + +**抽出ルール**: +- P0（即座に対応）: リスクレベルがクリティカルのエッジケース +- P1（早急に対応）: リスクレベルが高のエッジケース +- P2（計画的に対応）: リスクレベルが中のエッジケース +- P3（監視）: リスクレベルが低のエッジケース + +**出力フォーマット** (ファイルの最後に追記): +```markdown +--- + +## チェックリスト項目 + +### P0 +- [ ] P0 EDGE-APP-001: {{エッジケース名の要約}} [詳細](./layer_analysis_app.md#edge-app-001) + +### P1 +- [ ] P1 EDGE-APP-005: {{エッジケース名の要約}} [詳細](./layer_analysis_app.md#edge-app-005) + +### P2 +（同様に記載） + +### P3 +（同様に記載） +``` + +**注意**: +- エッジケース名は簡潔に（50文字以内） +- 各項目は1行で記述 +- リンクは必ず含める +- 500行制限内に収めること + +### ファイル7: layer_analysis_summary.md（サマリー） + +```markdown +# エッジケース分析 - レイヤー別サマリー + +**実施日時**: {{実施日時}} +**分析者**: Claude Code + +[← インデックスに戻る](./index.md) | [初期分析](./initial_analysis.md) + +--- + +## レイヤー別ファイル + +**注意**: 各レイヤーが500行を超えて枝番ファイルに分割されている場合は、すべての枝番ファイルへのリンクを記載してください。 + +例（500行以内の場合）: +- [アプリケーション層](./layer_analysis_app.md) + +例（500行超過で枝番ファイルがある場合）: +- アプリケーション層: [第1部](./layer_analysis_app_1.md) | [第2部](./layer_analysis_app_2.md) | [第3部](./layer_analysis_app_3.md) + +**実際のリンク**（各レイヤーの実際の状況に応じて記載）: +- [アプリケーション層](./layer_analysis_app.md) （または枝番ファイルへのリンク） +- [UI層](./layer_analysis_ui.md) （または枝番ファイルへのリンク） +- [データ管理層](./layer_analysis_data.md) （または枝番ファイルへのリンク） +- [ネットワーク通信層](./layer_analysis_network.md) （または枝番ファイルへのリンク） +- [非同期処理層](./layer_analysis_async.md) （または枝番ファイルへのリンク） +- [認証・認可層](./layer_analysis_auth.md) （または枝番ファイルへのリンク） + +--- + +## レイヤー別サマリー + +### 発見されたエッジケース数 + +| レイヤー | 合計 | クリティカル | 高 | 中 | 低 | +|---------|------|------------|----|----|----| +| アプリケーション | {{数}} | {{数}} | {{数}} | {{数}} | {{数}} | +| UI | {{数}} | {{数}} | {{数}} | {{数}} | {{数}} | +| データ管理 | {{数}} | {{数}} | {{数}} | {{数}} | {{数}} | +| ネットワーク | {{数}} | {{数}} | {{数}} | {{数}} | {{数}} | +| 非同期処理 | {{数}} | {{数}} | {{数}} | {{数}} | {{数}} | +| 認証・認可 | {{数}} | {{数}} | {{数}} | {{数}} | {{数}} | +| **合計** | {{数}} | {{数}} | {{数}} | {{数}} | {{数}} | + +### 発生可能性別分布 + +| 発生可能性 | 件数 | 割合 | +|----------|------|------| +| 高 | {{数}} | {{割合}}% | +| 中 | {{数}} | {{割合}}% | +| 低 | {{数}} | {{割合}}% | + +### 影響度別分布 + +| 影響度 | 件数 | 割合 | +|-------|------|------| +| 高 | {{数}} | {{割合}}% | +| 中 | {{数}} | {{割合}}% | +| 低 | {{数}} | {{割合}}% | + +--- + +## 次段階の複合分析で確認すべき点 + +1. {{確認ポイント1}} +2. {{確認ポイント2}} +3. {{確認ポイント3}} + +--- + +*このレイヤー別分析結果に基づいて、次段階で複合エッジケース分析を実施します。* +``` + + + +あなたはエッジケース分析のエキスパートです。これまでの分析結果に基づいて、複数レイヤーにまたがる複合的なエッジケースを分析してください。 + +# 重要な分析方針 + +**網羅性と品質のバランス**: +- ✅ 可能性のあるエッジケースを幅広く調査する（網羅性） +- ✅ ただし、コード/設計書での証拠がない推測は記載しない（品質） +- ❌ 一般論やベストプラクティスの列挙は不要 +- ❌ 「このような問題が起こりうる」という可能性の羅列は不要 + +**エッジケース記載の絶対条件**: +1. コードベース/設計書で具体的な箇所を特定できた +2. エッジケース発生のメカニズムを論理的に説明できる +3. 確度が⭐⭐以上（コード/設計書での証拠がある） + +上記を満たさないエッジケースは、たとえ一般的なパターンでも記載しない。 + +# 分析対象の情報 + +分析対象名: {{分析対象名}} +分析モード: {{分析モード}} +初期分析結果ファイル: {{ベースディレクトリ}}/initial_analysis.md +レイヤー別分析ファイル: {{ベースディレクトリ}}/layer_analysis.md +出力ファイル名: {{ベースディレクトリ}}/combined_analysis.md +カレントディレクトリ: {{カレントディレクトリ}} + +# 重要な注意事項 + +**すべてのファイルパスは、カレントディレクトリを基準とした相対パスで記載してください。** +**絶対パス（/Users/... や C:\\... など）は使用しないでください。** +**各カテゴリを個別のファイルに出力してください。各ファイルは500行以内を目標としてください。** +**500行を超える場合は、枝番（_1, _2, _3...）をつけて複数ファイルに分割してください。** +**確度⭐⭐未満のエッジケースは記載しない。推測のみのケースは除外する。** + +# 出力ファイル構成 + +各カテゴリごとにファイルを作成します。500行を超える場合は枝番ファイルに分割します： + +## 基本ファイル（各カテゴリ） +1. `{{ベースディレクトリ}}/combined_analysis_data_state.md` - データモデル状態組み合わせ（超過時: _1.md, _2.md...） +2. `{{ベースディレクトリ}}/combined_analysis_multi_layer.md` - 複数レイヤーにまたがるケース（超過時: _1.md, _2.md...） +3. `{{ベースディレクトリ}}/combined_analysis_cascade.md` - カスケード障害（超過時: _1.md, _2.md...） +4. `{{ベースディレクトリ}}/combined_analysis_timing.md` - タイミング依存の問題（超過時: _1.md, _2.md...） +5. `{{ベースディレクトリ}}/combined_analysis_summary.md` - 複合分析のサマリー + +## 枝番ファイルのルール +- ファイルが500行を超える場合、`_1`, `_2`, `_3`... の枝番をつける +- 例: `combined_analysis_data_state_1.md`, `combined_analysis_data_state_2.md` +- 各枝番ファイルの最後に「[次のファイルへ →](./combined_analysis_data_state_2.md)」のようなリンクを記載 +- サマリーファイルには、すべての枝番ファイルへのリンクを含める + +# 複合エッジケース分析の手順 + +## 1. これまでの分析結果の統合 + +- {{ベースディレクトリ}}/initial_analysis.md を Read で読み込む +- {{ベースディレクトリ}}/layer_analysis.md を Read で読み込む +- レイヤー間の依存関係を把握する +- 複合的に発生するパターンを特定する + +## 2. データモデル状態の組み合わせ分析 + +### 複数エンティティの状態組み合わせ +- エンティティA × エンティティB の状態マトリクス +- 不整合が発生する組み合わせ +- データ整合性制約 + +### マスタとトランザクションの不整合 +- マスタデータ更新中のトランザクション処理 +- マスタデータ削除後の参照 +- バージョン不整合 + +## 3. 複数レイヤーにまたがるエッジケース + +### UI × アプリケーション × データ +- ユーザー操作 → ビジネスロジック → データ永続化の連鎖 +- 各層での障害伝播 +- 部分的な成功・失敗 + +### アプリケーション × ネットワーク × 非同期 +- API呼び出し → ジョブキュー → 非同期処理の連鎖 +- タイムアウトとリトライの影響 +- 分散トランザクション + +### 認証 × ネットワーク × データ +- セッションタイムアウト中のデータ更新 +- トークン更新中のAPI呼び出し +- 権限変更の伝播 + +## 4. カスケード障害の分析 + +### 障害の連鎖パターン +- 一次障害 → 二次障害 → 三次障害 +- リソース枯渇の連鎖 +- サーキットブレーカーの発動 + +### リカバリーの複雑度 +- 部分的なロールバック +- 補償トランザクション +- 手動介入が必要なケース + +## 5. タイミング依存の問題 + +### 競合状態 +- 複数リクエストの同時処理 +- 読み取り → 更新の間のデータ変更 +- 楽観的ロックの失敗 + +### デッドロック +- リソースの循環待ち +- タイムアウト設定 +- デッドロック検出と解消 + +## 6. 複合分析結果のまとめ + +以下の手順で各カテゴリを個別のファイルに出力してください。Write ツールを使用して保存してください。 + +### 重要: ファイル分割のルール + +1. **行数カウント**: 各ファイルの内容を作成する際、500行を超えるかどうかを確認する +2. **500行以下の場合**: 通常のファイル名で1つのファイルに出力（例: `combined_analysis_data_state.md`） +3. **500行を超える場合**: + - 枝番ファイルに分割（例: `combined_analysis_data_state_1.md`, `combined_analysis_data_state_2.md`...） + - 各枝番ファイルは500行以内に収める + - 各枝番ファイルの最後に次のファイルへのリンクを追加 + - 最初のファイル（_1.md）のヘッダーに「全X部構成」と記載 + +### ファイル1: combined_analysis_data_state（データモデル状態組み合わせ） + +**500行以下の場合**: `combined_analysis_data_state.md` + +```markdown +# エッジケース分析 - データモデル状態組み合わせ + +**実施日時**: {{実施日時}} +**分析者**: Claude Code + +[← インデックスに戻る](./index.md) | [初期分析](./initial_analysis.md) | [レイヤー別サマリー](./layer_analysis_summary.md) | [複合分析サマリー](./combined_analysis_summary.md) +``` + +**500行を超える場合**: `combined_analysis_data_state_1.md`, `combined_analysis_data_state_2.md`... + +```markdown +# エッジケース分析 - データモデル状態組み合わせ（第1部 / 全2部） + +**実施日時**: {{実施日時}} +**分析者**: Claude Code + +[← インデックスに戻る](./index.md) | [初期分析](./initial_analysis.md) | [レイヤー別サマリー](./layer_analysis_summary.md) | [複合分析サマリー](./combined_analysis_summary.md) + +--- + +## データモデル状態の組み合わせ + +### EDGE-COMB-001: {{複合エッジケース名}} + +**関連レイヤー**: データ管理 / アプリケーション + +**関連するエッジケース**: EDGE-DATA-001, EDGE-APP-002 + +**発生条件**: +{{このエッジケースが発生する条件}} + +**データ状態マトリクス**: +| エンティティA | エンティティB | 結果 | 問題 | +|-------------|-------------|------|------| +| 状態1 | 状態1 | ✅ 正常 | なし | +| 状態1 | 状態2 | ⚠️ 警告 | {{問題}} | +| 状態2 | 状態1 | ❌ エラー | {{問題}} | +| 状態2 | 状態2 | ❌ エラー | {{問題}} | + +**発生可能性**: 高 / 中 / 低 +**影響度**: 高 / 中 / 低 +**リスクレベル**: クリティカル / 高 / 中 / 低 + +**複合シナリオ**: +``` +[データ層] +1. エンティティAが状態1 +2. エンティティBが状態2に遷移 + ↓ +[アプリケーション層] +3. ビジネスルール検証でエラー + ↓ +[影響] +4. データ不整合が発生 +``` + +**影響範囲**: +- データ整合性: {{影響}} +- ユーザー体験: {{影響}} +- システム安定性: {{影響}} + +**現在の対応状況**: +{{対応状況}} + +**推奨対応**: +- 優先度: P0 / P1 / P2 / P3 +- 対応方針: {{推奨される対応方針}} +- 実装箇所: [相対パス](相対パス) +- テスト戦略: {{テスト方法}} + +--- + +### EDGE-COMB-002: {{複合エッジケース名}} + +（同様の形式で複数記載） + +--- + +**注意**: このファイルは500行以内に収めてください。 +``` + +### ファイル2～4: 他のカテゴリ + +**重要**: 上記と同様の形式で、以下のファイルも作成してください： +- `combined_analysis_multi_layer.md` - 複数レイヤーにまたがるエッジケース +- `combined_analysis_cascade.md` - カスケード障害 +- `combined_analysis_timing.md` - タイミング依存の問題 + +各ファイルは500行以内に収めてください。 + +## 7. チェックリスト項目の抽出 + +各複合分析ファイルの作成後、以下の形式でチェックリスト項目を抽出してください： + +**抽出ルール**: +- P0（即座に対応）: リスクレベルがクリティカルのエッジケース +- P1（早急に対応）: リスクレベルが高のエッジケース +- P2（計画的に対応）: リスクレベルが中のエッジケース +- P3（監視）: リスクレベルが低のエッジケース + +**出力フォーマット** (ファイルの最後に追記): +```markdown +--- + +## チェックリスト項目 + +### P0 +- [ ] P0 EDGE-COMB-001: {{エッジケース名の要約}} [詳細](./combined_analysis_data_state.md#edge-comb-001) + +### P1 +- [ ] P1 EDGE-MULTI-003: {{エッジケース名の要約}} [詳細](./combined_analysis_multi_layer.md#edge-multi-003) + +### P2 +（同様に記載） + +### P3 +（同様に記載） +``` + +**注意**: +- エッジケース名は簡潔に（50文字以内） +- 各項目は1行で記述 +- リンクは必ず含める +- 500行制限内に収めること + +### ファイル5: combined_analysis_summary.md（サマリー） + +```markdown +# エッジケース分析 - 複合分析サマリー + +**実施日時**: {{実施日時}} +**分析者**: Claude Code + +[← インデックスに戻る](./index.md) | [初期分析](./initial_analysis.md) | [レイヤー別サマリー](./layer_analysis_summary.md) + +--- + +## 複合分析ファイル + +**注意**: 各カテゴリが500行を超えて枝番ファイルに分割されている場合は、すべての枝番ファイルへのリンクを記載してください。 + +例（500行以内の場合）: +- [データモデル状態組み合わせ](./combined_analysis_data_state.md) + +例（500行超過で枝番ファイルがある場合）: +- データモデル状態組み合わせ: [第1部](./combined_analysis_data_state_1.md) | [第2部](./combined_analysis_data_state_2.md) + +**実際のリンク**（各カテゴリの実際の状況に応じて記載）: +- [データモデル状態組み合わせ](./combined_analysis_data_state.md) （または枝番ファイルへのリンク） +- [複数レイヤーにまたがるケース](./combined_analysis_multi_layer.md) （または枝番ファイルへのリンク） +- [カスケード障害](./combined_analysis_cascade.md) （または枝番ファイルへのリンク） +- [タイミング依存の問題](./combined_analysis_timing.md) （または枝番ファイルへのリンク） + +--- + +## 複数レイヤーにまたがるエッジケース + +### EDGE-MULTI-001: {{複合エッジケース名}} + +**関連レイヤー**: UI / アプリケーション / データ管理 + +**関連するエッジケース**: EDGE-UI-001, EDGE-APP-001, EDGE-DATA-001 + +**発生条件**: +{{このエッジケースが発生する条件}} + +**レイヤー間フロー**: +``` +[UI層] +1. ユーザーが操作実行 + ↓ (API呼び出し) +[アプリケーション層] +2. バリデーション通過 +3. ビジネスロジック実行 + ↓ (データベース操作) +[データ管理層] +4. トランザクション開始 +5. ⚠️ 制約違反エラー発生 + ↓ (エラー伝播) +[アプリケーション層] +6. ロールバック試行 +7. ⚠️ ロールバック失敗 + ↓ (エラー伝播) +[UI層] +8. ❌ エラー表示 +9. ⚠️ 画面状態が不整合 +``` + +**発生可能性**: 高 / 中 / 低 +**影響度**: 高 / 中 / 低 +**リスクレベル**: クリティカル / 高 / 中 / 低 + +**影響範囲**: +{{影響の詳細}} + +**現在の対応状況**: +{{対応状況}} + +**推奨対応**: +{{推奨される対応}} + +--- + +### EDGE-MULTI-002: {{複合エッジケース名}} + +（同様の形式で複数記載） + +--- + +## カスケード障害 + +### EDGE-CASCADE-001: {{カスケード障害名}} + +**障害の連鎖**: +``` +[一次障害] +データベース接続プール枯渇 + ↓ +[二次障害] +API呼び出しタイムアウト多発 + ↓ +[三次障害] +リトライによる負荷増大 + ↓ +[四次障害] +システム全体の応答遅延 + ↓ +[最終影響] +サービス停止 +``` + +**発生可能性**: 高 / 中 / 低 +**影響度**: 高 / 中 / 低 +**リスクレベル**: クリティカル / 高 / 中 / 低 + +**トリガー条件**: +{{障害が連鎖するきっかけ}} + +**影響範囲**: +{{影響の詳細}} + +**検知方法**: +{{どのように検知するか}} + +**リカバリー方法**: +{{どのように復旧するか}} + +**現在の対応状況**: +{{対応状況}} + +**推奨対応**: +- サーキットブレーカーの実装 +- バックプレッシャーの実装 +- リソース監視の強化 +- 段階的な縮退運転 + +--- + +### EDGE-CASCADE-002: {{カスケード障害名}} + +（同様の形式で複数記載） + +--- + +## タイミング依存の問題 + +### EDGE-TIMING-001: {{タイミング依存の問題名}} + +**競合条件**: +``` +[Thread A] [Thread B] +1. データ読み取り 1. データ読み取り + value = 100 value = 100 + ↓ ↓ +2. 計算処理 2. 計算処理 + newValue = 100 + 10 newValue = 100 + 20 + ↓ ↓ +3. データ書き込み 3. データ書き込み + value = 110 value = 120 + ↓ ↓ +[結果] +期待値: 130 +実際値: 120 (10が失われる) +``` + +**発生可能性**: 高 / 中 / 低 +**影響度**: 高 / 中 / 低 +**リスクレベル**: クリティカル / 高 / 中 / 低 + +**影響範囲**: +{{影響の詳細}} + +**現在の対応状況**: +{{対応状況}} + +**推奨対応**: +- 楽観的ロックの実装 +- 悲観的ロックの実装 +- トランザクション分離レベルの見直し +- 冪等性の保証 + +--- + +### EDGE-TIMING-002: {{タイミング依存の問題名}} + +（同様の形式で複数記載） + +--- + +## 複合エッジケースサマリー + +### 発見された複合エッジケース数 + +| カテゴリ | 合計 | クリティカル | 高 | 中 | 低 | +|---------|------|------------|----|----|----| | データモデル組み合わせ | {{数}} | {{数}} | {{数}} | {{数}} | {{数}} | +| 複数レイヤー | {{数}} | {{数}} | {{数}} | {{数}} | {{数}} | +| カスケード障害 | {{数}} | {{数}} | {{数}} | {{数}} | {{数}} | +| タイミング依存 | {{数}} | {{数}} | {{数}} | {{数}} | {{数}} | +| **合計** | {{数}} | {{数}} | {{数}} | {{数}} | {{数}} | + +### 最も危険な複合エッジケース Top 5 + +1. **{{エッジケース名}}** - リスクレベル: {{レベル}} + - 理由: {{危険な理由}} + +2. **{{エッジケース名}}** - リスクレベル: {{レベル}} + - 理由: {{危険な理由}} + +（以下同様） + +--- + +## 推奨される対応優先順位 + +### P0（即座に対応） + +- EDGE-COMB-001: {{エッジケース名}} +- EDGE-CASCADE-001: {{エッジケース名}} + +### P1（早急に対応） + +- EDGE-MULTI-001: {{エッジケース名}} +- EDGE-TIMING-001: {{エッジケース名}} + +### P2（計画的に対応） + +（同様にリスト） + +### P3（監視） + +（同様にリスト） + +--- + +*この複合エッジケース分析結果は、最終レポートで総括されます。* +``` + + + +あなたはエッジケース分析のエキスパートです。これまでのすべての分析結果を統合し、包括的な最終レポートを作成してください。 + +# 重要な分析方針 + +**網羅性と品質のバランス**: +- ✅ 分析プロセスで得られた重要なエッジケースを漏れなく記載（網羅性） +- ✅ ただし、除外されたケースや根拠不足の推測は記載しない（品質） +- ❌ 一般論やベストプラクティスの列挙は不要 +- ❌ 「このような問題が起こりうる」という可能性の羅列は不要 + +**レポート記載の原則**: +1. 確度⭐⭐以上のエッジケースのみを含める +2. コード/設計書での証拠に基づく内容のみ記載 +3. 除外したケースは詳細分析ファイルを参照し、最終レポートには含めない + +# レポート作成対象の情報 + +分析対象名: {{分析対象名}} +分析モード: {{分析モード}} +分析ファイルリスト: {{分析ファイルリスト}} +最終レポートファイル名: {{ベースディレクトリ}}/final_report.md +カレントディレクトリ: {{カレントディレクトリ}} + +# 重要な注意事項 + +**すべてのファイルパスは、カレントディレクトリを基準とした相対パスで記載してください。** +**絶対パス（/Users/... や C:\\... など）は使用しないでください。** +**このファイルは500行以内を目標としてください。** +**確度⭐⭐以上、コード/設計書での証拠がある内容のみ記載する。** + +# 最終レポート作成手順 + +## 1. 全分析結果の読み込み + +- {{ベースディレクトリ}}/initial_analysis.md を Read で読み込む +- {{ベースディレクトリ}}/layer_analysis.md を Read で読み込む +- {{ベースディレクトリ}}/combined_analysis.md を Read で読み込む +- 各ファイルの内容を把握し、重要なポイントを抽出する + +## 2. 情報の統合とサマリー作成 + +- 全エッジケースのリスク評価 +- 対応優先順位の決定 +- テスト戦略の策定 +- 監視・運用方針の策定 + +## 3. エグゼクティブサマリーの作成 + +- 非技術者にも理解できる概要 +- 技術的な詳細は別セクションで説明 +- 結論を先に、詳細は後で + +## 4. 最終レポートの出力 + +以下の形式で結果をファイルに出力してください。Write ツールを使用して保存してください。 + +```markdown +# エッジケース分析 - 最終レポート + +**実施日時**: {{実施日時}} +**分析者**: Claude Code +**分析対象**: {{分析対象名}} +**分析モード**: {{分析モード}} + +--- + +## ナビゲーション + +- [インデックス](./index.md) - 全体概要とファイル一覧 +- [📋 チェックリスト](./check_list.md) - **優先対応すべきエッジケース一覧** +- [初期分析](./initial_analysis.md) - 潜在的エッジケース特定 +- レイヤー別分析: + - [アプリケーション層](./layer_analysis_app.md) + - [UI層](./layer_analysis_ui.md) + - [データ管理層](./layer_analysis_data.md) + - [ネットワーク通信層](./layer_analysis_network.md) + - [非同期処理層](./layer_analysis_async.md) + - [認証・認可層](./layer_analysis_auth.md) + - [レイヤー別サマリー](./layer_analysis_summary.md) +- 複合エッジケース分析: + - [データモデル状態組み合わせ](./combined_analysis_data_state.md) + - [複数レイヤー](./combined_analysis_multi_layer.md) + - [カスケード障害](./combined_analysis_cascade.md) + - [タイミング依存](./combined_analysis_timing.md) + - [複合分析サマリー](./combined_analysis_summary.md) + +--- + +## 📋 チェックリスト概要 + +**総チェックリスト項目数**: {{総数}}件 + +| 優先度 | 項目数 | 説明 | +|-------|-------|------| +| P0 | {{P0数}}件 | 即座に対応が必要（リリース前必須） | +| P1 | {{P1数}}件 | 早急に対応（初期リリースに含める） | +| P2 | {{P2数}}件 | 計画的に対応（次期バージョン） | +| P3 | {{P3数}}件 | 監視（ログ・監視で検知） | + +**詳細は [check_list.md](./check_list.md) を参照してください** + +--- + +## エグゼクティブサマリー + +### 分析概要 + +本レポートは、{{分析対象名}}のシステム実装における包括的なエッジケース分析結果です。 + +### 主要な発見事項 + +- **総エッジケース数**: {{総数}}件 +- **クリティカルリスク**: {{数}}件 +- **高リスク**: {{数}}件 +- **即座に対応が必要（P0）**: {{数}}件 + +### リスク評価サマリー + +**最大リスク領域**: {{レイヤー名}} +- クリティカルケース: {{数}}件 +- 主な懸念: {{懸念事項}} + +### 推奨される対応 + +**即座に実施すべき対応（P0）**: {{数}}件 +- {{対応1}} +- {{対応2}} +- {{対応3}} + +**リリースへの影響**: +- P0対応完了前のリリース: ❌ 推奨しない +- P0+P1対応後のリリース: ✅ 推奨 +- 最小構成リリース: {{条件付きで可能かどうか}} + +--- + +## 全体統計 + +### レイヤー別エッジケース分布 + +| レイヤー | 合計 | クリティカル | 高 | 中 | 低 | +|---------|------|------------|----|----|----| | アプリケーション | {{数}} | {{数}} | {{数}} | {{数}} | {{数}} | +| UI | {{数}} | {{数}} | {{数}} | {{数}} | {{数}} | +| データ管理 | {{数}} | {{数}} | {{数}} | {{数}} | {{数}} | +| ネットワーク | {{数}} | {{数}} | {{数}} | {{数}} | {{数}} | +| 非同期処理 | {{数}} | {{数}} | {{数}} | {{数}} | {{数}} | +| 認証・認可 | {{数}} | {{数}} | {{数}} | {{数}} | {{数}} | +| 複合 | {{数}} | {{数}} | {{数}} | {{数}} | {{数}} | +| **合計** | {{数}} | {{数}} | {{数}} | {{数}} | {{数}} | + +### リスクマトリクス + +| | 高影響度 | 中影響度 | 低影響度 | +|----------|---------|---------|---------| +| **高発生可能性** | {{数}}件（クリティカル） | {{数}}件（高） | {{数}}件（中） | +| **中発生可能性** | {{数}}件（高） | {{数}}件（中） | {{数}}件（低） | +| **低発生可能性** | {{数}}件（中） | {{数}}件（低） | {{数}}件（低） | + +--- + +## クリティカルエッジケース詳細 + +### CRITICAL-01: {{エッジケース名}} + +**ID**: {{元のID（例: EDGE-COMB-001）}} +**リスクレベル**: クリティカル +**発生可能性**: 高 +**影響度**: 高 + +**概要**: +{{エッジケースの簡潔な説明}} + +**ビジネスインパクト**: +{{ユーザーやビジネスへの影響}} + +**技術的詳細**: +{{技術的な問題の詳細}} + +**推奨対応**: +- **優先度**: P0（即座に対応） +- **対応方針**: {{対応方針}} +- **実装工数**: {{概算工数}} +- **完了目標**: リリース前必須 + +**参照**: [詳細分析](./layer_analysis.md#{{anchor}}) + +--- + +### CRITICAL-02: {{エッジケース名}} + +（同様の形式で複数記載） + +--- + +## 対応優先順位別アクションプラン + +### P0: 即座に対応（{{数}}件） + +#### 1. {{エッジケース名}} +- **ID**: {{ID}} +- **対応内容**: {{対応内容}} +- **実装箇所**: [相対パス](相対パス) +- **テスト方法**: {{テスト方法}} +- **担当推奨**: {{担当者のスキルセット}} +- **工数**: {{工数}} + +#### 2. {{エッジケース名}} +（同様の形式で複数記載） + +### P1: 早急に対応（{{数}}件） + +#### 1. {{エッジケース名}} +- **ID**: {{ID}} +- **対応内容**: {{対応内容}} +- **実装箇所**: [相対パス](相対パス) +- **テスト方法**: {{テスト方法}} +- **工数**: {{工数}} + +### P2: 計画的に対応（{{数}}件） + +（同様の形式でリスト） + +### P3: 監視（{{数}}件） + +（同様の形式でリスト） + +--- + +## テスト戦略 + +### エッジケーステストの優先順位 + +#### Phase 1: クリティカル・高リスクケース +- **対象**: P0, P1のエッジケース +- **テスト種別**: ユニット、統合、E2E +- **カバレッジ目標**: 100% + +#### Phase 2: 中リスクケース +- **対象**: P2のエッジケース +- **テスト種別**: ユニット、統合 +- **カバレッジ目標**: 80% + +#### Phase 3: 低リスクケース +- **対象**: P3のエッジケース +- **テスト種別**: 主にユニット +- **カバレッジ目標**: 50% + +### レイヤー別テスト推奨事項 + +#### アプリケーション層 +- ユニットテスト: {{推奨事項}} +- 統合テスト: {{推奨事項}} +- Property-based testing: {{推奨事項}} + +#### UI層 +- E2Eテスト: {{推奨事項}} +- ビジュアルリグレッションテスト: {{推奨事項}} +- アクセシビリティテスト: {{推奨事項}} + +#### データ管理層 +- トランザクションテスト: {{推奨事項}} +- 負荷テスト: {{推奨事項}} +- カオステスト: {{推奨事項}} + +#### ネットワーク通信層 +- モック・スタブテスト: {{推奨事項}} +- タイムアウトテスト: {{推奨事項}} +- リトライテスト: {{推奨事項}} + +#### 非同期処理層 +- 並行処理テスト: {{推奨事項}} +- ワークフローテスト: {{推奨事項}} +- 冪等性テスト: {{推奨事項}} + +#### 認証・認可層 +- セキュリティテスト: {{推奨事項}} +- セッション管理テスト: {{推奨事項}} +- 権限テスト: {{推奨事項}} + +### テスト自動化の推奨 + +- CI/CDパイプラインへの組み込み: {{推奨事項}} +- カオスエンジニアリング: {{推奨事項}} +- モニタリングとアラート: {{推奨事項}} + +--- + +## 監視・運用方針 + +### 監視すべきメトリクス + +#### アプリケーション層 +- エラー発生率 +- レスポンスタイム +- トランザクション成功率 + +#### データ管理層 +- データベース接続プール使用率 +- クエリ実行時間 +- デッドロック発生回数 + +#### ネットワーク通信層 +- API呼び出し成功率 +- タイムアウト発生回数 +- リトライ回数 + +#### 非同期処理層 +- ジョブキュー長 +- ジョブ処理時間 +- デッドレター数 + +### アラート設定の推奨 + +| メトリクス | Warning閾値 | Critical閾値 | +|----------|-----------|------------| +| エラー率 | {{閾値}} | {{閾値}} | +| レスポンスタイム | {{閾値}} | {{閾値}} | +| データベース接続率 | {{閾値}} | {{閾値}} | +| ジョブキュー長 | {{閾値}} | {{閾値}} | + +### インシデント対応プロセス + +1. **検知**: {{検知方法}} +2. **トリアージ**: {{優先順位判定基準}} +3. **対応**: {{対応フロー}} +4. **復旧**: {{復旧手順}} +5. **事後分析**: {{振り返りプロセス}} + +--- + +## 実装タイムライン + +### Phase 0: 緊急対応（Week 1） +- [ ] P0-1: {{エッジケース名}} - {{担当者}} +- [ ] P0-2: {{エッジケース名}} - {{担当者}} +- [ ] P0-3: {{エッジケース名}} - {{担当者}} + +### Phase 1: 高優先度対応（Week 2-3） +- [ ] P1-1: {{エッジケース名}} - {{担当者}} +- [ ] P1-2: {{エッジケース名}} - {{担当者}} + +### Phase 2: 中優先度対応（Week 4-5） +- [ ] P2-1: {{エッジケース名}} - {{担当者}} +- [ ] P2-2: {{エッジケース名}} - {{担当者}} + +### Phase 3: 監視体制構築（Week 6） +- [ ] モニタリング設定 +- [ ] アラート設定 +- [ ] ダッシュボード作成 + +--- + +## リスクと課題 + +### 残存リスク + +#### リスク1: {{リスク内容}} +- **発生確率**: 高/中/低 +- **影響度**: 高/中/低 +- **軽減策**: {{軽減策}} + +#### リスク2: {{リスク内容}} +（同様の形式で記載） + +### 技術的負債 + +1. **{{負債項目}}** + - 詳細: {{詳細}} + - 影響: {{影響}} + - 解消計画: {{計画}} + +### 未解決の課題 + +1. **{{課題}}** + - 詳細: {{詳細}} + - 対応方針: {{方針}} + +--- + +## 推奨事項 + +### 開発チームへ + +1. {{推奨事項1}} +2. {{推奨事項2}} +3. {{推奨事項3}} + +### QAチームへ + +1. {{推奨事項1}} +2. {{推奨事項2}} + +### DevOpsチームへ + +1. {{推奨事項1}} +2. {{推奨事項2}} + +### プロダクトオーナーへ + +1. {{推奨事項1}} +2. {{推奨事項2}} + +--- + +## 付録 + +### 用語集 + +- **エッジケース**: {{定義}} +- **リスクレベル**: {{定義}} +- **発生可能性**: {{定義}} +- **影響度**: {{定義}} + +### 参考資料 + +- 分析モードが "requirements-based" の場合: + - [要件定義書](../../spec/{{分析対象名}}/requirements.md) + - [設計文書](../../spec/{{分析対象名}}/design.md) +- 分析モードが "source-based" の場合: + - 分析対象のソースコードファイル（初期分析で特定されたファイル参照） + +### 分析ファイル一覧 + +#### 初期分析 +1. [初期分析](./initial_analysis.md) + +#### レイヤー別分析 +2. [アプリケーション層](./layer_analysis_app.md) +3. [UI層](./layer_analysis_ui.md) +4. [データ管理層](./layer_analysis_data.md) +5. [ネットワーク通信層](./layer_analysis_network.md) +6. [非同期処理層](./layer_analysis_async.md) +7. [認証・認可層](./layer_analysis_auth.md) +8. [レイヤー別サマリー](./layer_analysis_summary.md) + +#### 複合エッジケース分析 +9. [データモデル状態組み合わせ](./combined_analysis_data_state.md) +10. [複数レイヤー](./combined_analysis_multi_layer.md) +11. [カスケード障害](./combined_analysis_cascade.md) +12. [タイミング依存](./combined_analysis_timing.md) +13. [複合分析サマリー](./combined_analysis_summary.md) + +--- + +## 結論 + +{{分析全体の結論を2-3段落でまとめる}} + +**主要な発見**: +- {{発見1}} +- {{発見2}} +- {{発見3}} + +**推奨されるアクション**: +1. {{アクション1}} +2. {{アクション2}} +3. {{アクション3}} + +**リリース判定**: +{{P0対応完了を条件にリリース可能、などの判定}} + +--- + +**分析完了日**: {{日付}} +**分析者**: Claude Code +**レビュー状況**: ⏳ レビュー待ち + +--- + +*このレポートは自動生成されたものです。内容についてはチームでレビューしてください。* +``` + diff --git a/commands/dcs/feature-rubber-duck.md b/commands/dcs/feature-rubber-duck.md index e9ae5d4..c0d6028 100644 --- a/commands/dcs/feature-rubber-duck.md +++ b/commands/dcs/feature-rubber-duck.md @@ -1,7 +1,7 @@ --- description: アイデアを整理して実現可能なPRDを作成する allowed-tools: Read, Glob, Grep, Task, Bash, WebSearch, WebFetch, AskUserQuestion -argument-hint: [機能やアイデアの概要（任意）] +argument-hint: "[機能やアイデアの概要（任意）]" --- 曖昧なアイデアや要望を対話を通じて整理し、実現可能なPRD（Product Requirements Document）を作成します。コードベースの調査、技術検証、要件の具体化を段階的に進めます。 diff --git a/commands/dcs/impact-analysis.md b/commands/dcs/impact-analysis.md index 98612af..2ab278c 100644 --- a/commands/dcs/impact-analysis.md +++ b/commands/dcs/impact-analysis.md @@ -1,7 +1,7 @@ --- description: 影響範囲分析を実施する allowed-tools: Read, Glob, Grep, Task, Bash -argument-hint: [変更対象（ファイルパス/関数名/クラス名/自然言語）] +argument-hint: "[変更対象（ファイルパス/関数名/クラス名/自然言語）]" --- 変更対象の影響範囲を分析し、修正が必要なファイルとリスク評価を提供します。一時ファイルを作成せず直接 Task で実行し、必要に応じて追加調査を繰り返し、最後に全体サマリーを作成します。 diff --git a/commands/dcs/incremental-dev.md b/commands/dcs/incremental-dev.md index ca12332..e1d8fc8 100644 --- a/commands/dcs/incremental-dev.md +++ b/commands/dcs/incremental-dev.md @@ -1,7 +1,7 @@ --- description: 増分開発の計画を立案する allowed-tools: Read, Glob, Grep, Task, Bash, AskUserQuestion, Write -argument-hint: [開発対象（機能名/改善内容/自然言語）] +argument-hint: "[開発対象（機能名/改善内容/自然言語）]" --- 増分開発の対象を分析し、初期調査から追加調査を経て、実装方法毎のPRD（Product Requirements Document）を作成します。すべてのファイルは500行以内に分割して出力します。 diff --git a/commands/dcs/performance-analysis.md b/commands/dcs/performance-analysis.md index f466cc8..5323434 100644 --- a/commands/dcs/performance-analysis.md +++ b/commands/dcs/performance-analysis.md @@ -1,7 +1,7 @@ --- description: 性能問題の原因を調査する allowed-tools: Read, Glob, Grep, Task, Bash, AskUserQuestion, TodoWrite -argument-hint: [調査対象（機能名/エンドポイント/画面/自然言語）] +argument-hint: "[調査対象（機能名/エンドポイント/画面/自然言語）]" --- 性能問題の原因を特定するための包括的な調査を実施します。初期調査、詳細な原因分析、最終サマリーを段階的に作成し、性能問題の根本原因を明らかにします。 diff --git a/commands/dcs/sequence-diagram-analysis.md b/commands/dcs/sequence-diagram-analysis.md index a29862c..16f18db 100644 --- a/commands/dcs/sequence-diagram-analysis.md +++ b/commands/dcs/sequence-diagram-analysis.md @@ -1,7 +1,7 @@ --- description: 機能のシーケンス図を作成する allowed-tools: Read, Glob, Grep, Task, Bash, AskUserQuestion, Write -argument-hint: [機能名または対象(ファイルパス/関数名/クラス名/自然言語)] +argument-hint: "[機能名または対象(ファイルパス/関数名/クラス名/自然言語)]" --- 指定された機能のシーケンス図をmermaid形式で作成します。調査結果を一時ファイルに保存し、Task で参照することでコンテキスト削減を実現します。 diff --git a/commands/dcs/state-transition-analysis.md b/commands/dcs/state-transition-analysis.md index 37d3532..fe45eee 100644 --- a/commands/dcs/state-transition-analysis.md +++ b/commands/dcs/state-transition-analysis.md @@ -1,7 +1,7 @@ --- description: データの状態遷移フローを包括的に分析する allowed-tools: Read, Glob, Grep, Task, Bash, Write -argument-hint: [対象データ名（リソース名/エンティティ名/モデル名）] +argument-hint: "[対象データ名（リソース名/エンティティ名/モデル名）]" --- 対象データの状態遷移に関わる全ての機能を特定し、状態遷移フロー、関連データとの依存関係、リスク評価を提供します。 diff --git a/commands/dcs/test-performance-analysis.md b/commands/dcs/test-performance-analysis.md new file mode 100644 index 0000000..e05b26e --- /dev/null +++ b/commands/dcs/test-performance-analysis.md @@ -0,0 +1,301 @@ +--- +description: テスト実行速度を分析し、遅いテストのリファクタリング提案を行います +--- + +# テスト実行速度分析とリファクタリング + +## 目的 + +テストスイート全体の実行速度を分析し、遅いテスト（2秒以上）を特定してリファクタリング提案を行います。 + +## step + +### step1: 追加ルールの読み込み + +- `docs/rule` ディレクトリが存在する場合は読み込み +- `docs/rule/test-optimization` ディレクトリが存在する場合は読み込み +- `.claude/commands/tsumiki/test-optimization-patterns.md` を読み込み +- 各ディレクトリ内のすべてのファイルを読み込み、追加ルールとして適用 + +### step2: テスト実行時間の計測 + +**全体の実行時間計測**: + +```bash +# Jest の場合 +npm test -- --verbose --runInBand 2>&1 | tee test-timing-before.log + +# その他のテストランナーの場合 +# pytest: pytest -v --durations=0 +# go test: go test -v -timeout 30s ./... +``` + +テスト結果から以下の情報を収集: +- 各テストファイルの実行時間 +- 個別テストケースの実行時間 +- 総実行時間 + +実行時間を記録し、以下の基準で分類: +- 🟢 高速: 100ms未満 +- 🟡 中速: 100ms～500ms +- 🟠 やや遅い: 500ms～2秒 +- 🔴 遅い: 2秒以上 + +### step3: 遅いテストの特定と原因分析 + +**Task tool (subagent_type: Explore, thoroughness: medium)** を使用して、🔴遅いテスト（2秒以上）のファイルを探索し、以下の観点で分析: + +#### 分析チェックリスト + +1. **データベースアクセス** + - [ ] 各テストでDB接続・切断を繰り返していないか + - [ ] beforeEach で毎回データをクリア・再投入していないか + - [ ] トランザクションのロールバックが使えないか + - [ ] beforeAll でデータ共有できないか + +2. **ファイルI/O** + - [ ] 実ファイルへの読み書きを行っていないか + - [ ] 一時ファイルの作成・削除が多くないか + - [ ] mock-fs や jest.mock('fs') が使えないか + +3. **外部依存** + - [ ] 外部APIへの実際のリクエストを行っていないか + - [ ] ネットワーク呼び出しがモック化されているか + - [ ] MSW や jest.mock が使えないか + +4. **非同期処理** + - [ ] 固定時間の sleep/wait を使っていないか + - [ ] 条件ベースの待機に変更できないか + - [ ] 不要な待機処理がないか + +5. **セットアップ/ティアダウン** + - [ ] beforeEach で重い処理をしていないか + - [ ] beforeAll で共有できる処理が beforeEach にないか + - [ ] afterEach で不要なクリーンアップをしていないか + +6. **テストデータ** + - [ ] 必要以上に大きなデータを作成していないか + - [ ] ファクトリーパターンで最小限のデータにできないか + +### step4: リファクタリング提案の作成 + +分析結果に基づき、適用可能なリファクタリングパターンを提案: + +#### パターン1: データベーストランザクション（効果: ★★★★★） + +**適用条件**: beforeEach でデータのクリア・再投入を行っている + +**提案**: +```javascript +// Before +beforeEach(async () => { + await db.query('DELETE FROM users'); + await db.query('INSERT INTO users ...'); +}); + +// After: トランザクションでロールバック +let transaction; +beforeEach(async () => { + transaction = await db.transaction(); +}); +afterEach(async () => { + await transaction.rollback(); +}); +``` + +#### パターン2: ファイルI/Oのモック化（効果: ★★★★★） + +**適用条件**: fs.readFile, fs.writeFile などの実ファイル操作 + +**提案**: +```javascript +// Before +await fs.writeFile('./config.json', data); + +// After: モック化 +jest.mock('fs/promises'); +const fs = require('fs/promises'); +fs.writeFile.mockResolvedValue(); +``` + +#### パターン3: 外部APIのモック化（効果: ★★★★★） + +**適用条件**: fetch, axios などの外部HTTP通信 + +**提案**: +```javascript +// Before +const data = await fetch('https://api.example.com/users'); + +// After: MSWでモック +import { setupServer } from 'msw/node'; +import { rest } from 'msw'; + +const server = setupServer( + rest.get('https://api.example.com/users', (req, res, ctx) => { + return res(ctx.json([{id: 1, name: 'Test'}])); + }) +); +``` + +#### パターン4: beforeEach → beforeAll（効果: ★★★☆☆） + +**適用条件**: 読み取り専用のテストでデータを変更しない + +**提案**: +```javascript +// Before +beforeEach(async () => { + testData = await generateComplexData(); // 各テストで実行 +}); + +// After: 一度だけ実行 +beforeAll(async () => { + testData = await generateComplexData(); // 一度だけ +}); +``` + +#### パターン5: 非同期待機の最適化（効果: ★★★☆☆） + +**適用条件**: setTimeout, sleep などの固定待機時間 + +**提案**: +```javascript +// Before +await new Promise(resolve => setTimeout(resolve, 5000)); + +// After: 条件ベースの待機 +await waitFor(async () => { + const status = await getStatus(); + return status === 'completed'; +}, {timeout: 5000, interval: 100}); +``` + +#### パターン6: テストデータファクトリー（効果: ★★☆☆☆） + +**適用条件**: 複雑なデータ構造を毎回生成している + +**提案**: +```javascript +// Before +const user = { + id: 1, name: 'Test', email: 'test@example.com', + address: { /* 詳細 */ }, preferences: { /* 詳細 */ } +}; + +// After: ファクトリー関数 +function createUser(overrides = {}) { + return { id: 1, name: 'Test', ...overrides }; +} +const user = createUser({ name: 'Custom' }); +``` + +### step5: ユーザーへの確認 + +**AskUserQuestion** ツールを使用して、以下を確認: +- 検出された遅いテストの一覧を表示 +- 提案されたリファクタリングパターンを説明 +- 実施するか、レポートのみで終了するかを選択 + +### step6: リファクタリング実行（ユーザーが実施を選択した場合） + +提案されたパターンを1つずつ適用: + +1. **1つのテストファイルを選択** +2. **提案されたパターンを適用** +3. **テストを実行して確認** + ```bash + npm test -- + ``` +4. **実行時間を記録** +5. **次のファイルへ** + +各改善後: +- ✅ テストが全て通ることを確認 +- ✅ 実行時間が改善されたことを確認 +- ✅ 改善内容をログに記録 + +### step7: 改善効果の測定 + +```bash +# 改善後の実行時間を計測 +npm test -- --verbose --runInBand 2>&1 | tee test-timing-after.log +``` + +改善前後を比較: +- 総実行時間の変化 +- 個別ファイルの実行時間変化 +- 改善率の計算 + +### step8: レポート作成 + +改善レポートを作成し、以下の情報を記録: + +```markdown +# テスト実行速度改善レポート + +## 改善サマリー +- 改善前の総実行時間: XX.X秒 +- 改善後の総実行時間: XX.X秒 +- 短縮時間: XX.X秒（XX%削減） +- 改善対象テスト数: XX個 + +## 遅いテストの詳細 + +### 1. `test/user.test.js` - 15.2秒 → 2.1秒（86%削減） +- **原因**: 各テストでDB接続・切断を繰り返し +- **適用パターン**: トランザクショナルテスト +- **改善内容**: + - beforeEach でトランザクション開始 + - afterEach でロールバック +- **効果**: 13.1秒短縮 + +### 2. `test/file-processor.test.js` - 8.5秒 → 0.3秒（96%削減） +- **原因**: 実ファイルへの書き込み +- **適用パターン**: ファイルI/Oのモック化 +- **改善内容**: + - mock-fs を使用 + - メモリ上でファイル操作 +- **効果**: 8.2秒短縮 + +## まだ遅いテスト（2秒以上） + +### 1. `test/integration.test.js` - 5.3秒 +- **原因**: 統合テストとして複数の処理を実行 +- **推奨**: E2Eテストとして分離を検討 +- **優先度**: 中 + +## 推奨される次のステップ + +1. 統合テストのE2E化の検討 +2. テストデータファクトリーの導入 +3. 並列実行の最適化（--maxWorkers調整） + +## 適用したリファクタリングパターン + +1. データベーストランザクション: 3ファイル +2. ファイルI/Oのモック化: 2ファイル +3. 外部APIのモック化: 1ファイル +4. beforeEach → beforeAll: 2ファイル +``` + +レポートを以下のファイルに保存: +- `docs/test-performance-improvement-report.md` + +## rules + +- **テストの品質を下げない**: 速度のためにテストカバレッジを犠牲にしない +- **段階的な改善**: 一度に全てを変更せず、1ファイルずつ改善 +- **実装コードは変更しない**: テストコードのみをリファクタリング +- **モックは適切に**: 過度なモック化は実際のバグを見逃す可能性 +- **テスト実行で確認**: 各改善後に必ずテストを実行して動作確認 + +## 注意事項 + +### 改善を見送るべきケース + +- **統合テスト・E2Eテスト**: 実際の動作確認が目的なのでモック化は不適切 +- **パフォーマンステスト**: 実行時間の計測が目的 +- **セキュリティテスト**: 実際の環境での動作確認が必要 + +これらは別のテストスイート（`test:e2e`, `test:integration`）として分離を推奨 diff --git a/commands/direct-setup.md b/commands/direct-setup.md index cc305eb..e1b9848 100644 --- a/commands/direct-setup.md +++ b/commands/direct-setup.md @@ -1,7 +1,7 @@ --- description: DIRECTタスクの設定作業を実行します。設計文書に基づいて環境構築、設定ファイル作成、依存関係のインストールなどを行います。 allowed-tools: Read, Glob, Grep, Task, Write, Edit, TodoWrite -argument-hint: [要件名] [TASK-ID] +argument-hint: "[要件名] [TASK-ID]" --- # direct-setup @@ -31,13 +31,13 @@ DIRECTタスクの設定作業を実行します。設計文書に基づいて 3. **設計文書の確認** - 読み込んだ技術スタック定義に基づいて関連ファイルを特定 - - @agent-symbol-searcher で関連設計文書や設定パターンを検索し、見つかったファイルをReadツールで読み込み + - Task tool (subagent_type: Explore, thoroughness: medium) を使用して関連設計文書や設定パターンを探索 - `docs/design/{要件名}/architecture.md` をReadツールで読み込み - `docs/design/{要件名}/database-schema.sql` をReadツールで読み込み - その他関連する設計文書をReadツールで読み込み 3. **設定作業の実行** - - @agent-symbol-searcher で既存の設定ファイルや環境変数を検索し、見つかったファイルをReadツールで読み込み + - Task tool (subagent_type: Explore, thoroughness: quick) を使用して既存の設定ファイルや環境変数を探索 - 環境変数の設定 - 設定ファイルの作成・更新 - 依存関係のインストール diff --git a/commands/direct-verify.md b/commands/direct-verify.md index 5f1f26e..de1eedb 100644 --- a/commands/direct-verify.md +++ b/commands/direct-verify.md @@ -1,7 +1,7 @@ --- description: DIRECTタスクで実行した設定作業の動作確認とテストを行います。設定が正しく適用され、システムが期待通りに動作することを確認します。 allowed-tools: Read, Glob, Grep, Task, Write, Edit, TodoWrite -argument-hint: [要件名] [TASK-ID] +argument-hint: "[要件名] [TASK-ID]" --- # direct-verify @@ -33,7 +33,7 @@ DIRECTタスクで実行した設定作業の動作確認とテストを行い ### 3. 設定の確認 - 読み込んだ技術スタック定義に基づいて検証項目を特定 -- @agent-symbol-searcher で関連設定や検証パターンを検索し、見つかったファイルをReadツールで読み込み +- Task tool (subagent_type: Explore, thoroughness: quick) を使用して関連設定や検証パターンを探索 - `docs/implements/{要件名}/{TASK-ID}/setup-report.md` をReadツールで読み込み、設定作業の結果を確認 - 環境変数の確認 - 設定ファイルの内容確認 @@ -48,7 +48,7 @@ DIRECTタスクで実行した設定作業の動作確認とテストを行い - **エラーが見つかった場合は自動的に修正を試行** ### 5. 動作テストの実行 -- @agent-symbol-searcher で既存のテストケースや検証スクリプトを検索し、見つかったファイルをReadツールで読み込み +- Task tool (subagent_type: Explore, thoroughness: quick) を使用して既存のテストケースや検証スクリプトを探索 - 基本的な動作確認 - 接続テスト - 権限の確認 diff --git a/commands/kairo-design.md b/commands/kairo-design.md index 06e7482..7ccb306 100644 --- a/commands/kairo-design.md +++ b/commands/kairo-design.md @@ -1,7 +1,7 @@ --- description: 承認された要件定義書に基づいて、技術設計文書を生成する。データフロー図、TypeScriptインターフェース、データベーススキーマ、APIエンドポイントを含む包括的な設計を行います。 allowed-tools: Read, Glob, Grep, Task, Write, Edit, TodoWrite, WebFetch, AskUserQuestion -argument-hint: [要件名] +argument-hint: "[要件名]" --- Kairo開発の技術設計を実施し、PRD・EARS要件定義書・既存設計文書を参照しながら技術仕様を明確化します。信頼性レベルを示しながら設計文書を作成します。 @@ -83,7 +83,7 @@ Kairo開発の技術設計を実施し、PRD・EARS要件定義書・既存設 - `docs/design/` ディレクトリ配下の既存設計文書を確認 - 既存のアーキテクチャ設計・データフロー図を読み込み - 既存のTypeScript型定義・DBスキーマ・API仕様を読み込み - - @task agent-symbol-searcher で関連設計文書を検索 + - Task tool (subagent_type: Explore, thoroughness: quick) を使用して関連設計文書を探索 - **既存コードベース・実装の分析**（オプション） - AskUserQuestion ツールを使ってユーザーに確認: @@ -96,7 +96,7 @@ Kairo開発の技術設計を実施し、PRD・EARS要件定義書・既存設 - label: "不要" description: "要件定義と設計文書のみで設計を作成" - 「必要」を選択した場合のみ: - - @task agent-symbol-searcher で既存実装の網羅的調査 + - Task tool (subagent_type: Explore, thoroughness: medium) を使用して既存実装の網羅的調査 - アーキテクチャパターン・実装パターンの確認 - 技術的制約・依存関係の特定 - 既存型定義・インターフェースの確認 diff --git a/commands/kairo-implement.md b/commands/kairo-implement.md index b632a64..ea94235 100644 --- a/commands/kairo-implement.md +++ b/commands/kairo-implement.md @@ -1,6 +1,8 @@ --- description: 分割されたタスクを順番に、またはユーザが指定したタスクを実装します。既存のTDDコマンドを活用して品質の高い実装を行います。 -argument-hint: [要件名（省略可）] [TASK-ID (TASK-00001)] [--hil] +allowed-tools: Read, Glob, Grep, Task, Write, Edit, TodoWrite, AskUserQuestion, TaskList, TaskGet, TaskUpdate +allowed-skills: tsumiki:tdd-tasknote, tsumiki:tdd-requirements, tsumiki:tdd-testcases, tsumiki:tdd-red, tsumiki:tdd-green, tsumiki:tdd-refactor, tsumiki:tdd-verify-complete, tsumiki:direct-setup, tsumiki:direct-verify +argument-hint: "[要件名（省略可）] [TASK-ID (TASK-00001)] [--hil]" --- あなたは実装担当者です。残タスクを調べて 指定されたコマンドを駆使して実装をしてください @@ -13,6 +15,10 @@ argument-hint: [要件名（省略可）] [TASK-ID (TASK-00001)] [--hil] ## オプション - `--hil` (Human-in-the-Loop): テストケース作成後にユーザーの確認を求め、承認後にtdd-red以降のフェーズを実行する +- `--model [defaultModel]` タスク内で利用する最優先のデフォルトのモデルを指定する。設定がない場合はauto(それぞれのデフォルトを優先) sonnet/opusなどの指定が可能 +- `--think-model [thinkModelName]`: requirements/testcasesのモデル名を指定。デフォルトは opus +- `--tdd-model [tddModelName]`: red/green/refactor/verify-complete のモデル名を指定。デフォルトはsonnet +- `--note-model [noteModelName]`: tasknote のモデル名を指定。デフォルトはhaiku ## 前提条件 @@ -21,6 +27,28 @@ argument-hint: [要件名（省略可）] [TASK-ID (TASK-00001)] [--hil] - 既存のTDDコマンドが利用可能である - 実装用のワークスペースが設定されている - task_id は　`TASK-{4桁の数字}` (例 TASK-0001 ) である +- thinkTaskName を コマンド選択ルール で設定する。 thinkModelName , defaultModel, `opus` +- tddTaskName を コマンド選択ルール で設定する。 tddModelName , defaultModel, `sonnet` +- noteTaskName を コマンド選択ルール で設定する。 noteModelName , defaultModel, `haiku` + +## コマンド選択ルール + +### パラメータ +- selectModel +- defaultModel +- commandDefaultModel + +### ルール + +selectModel は　(selectModel == null && defaultModel != null) の場合、 defaultModel +selectModel は　(selectModel == null && defaultModel == null) の場合、 commandDefaultModel + +この時点で selectModel が null の場合は sonnetにする + +selectModelに +- `sonnet` が指定されている場合は `sonnet` を返す +- `opus` が指定されている場合は `opus` を返す +- `haiku` が指定されている場合は `haiku` を返す ## 実行内容 @@ -31,6 +59,26 @@ argument-hint: [要件名（省略可）] [TASK-ID (TASK-00001)] [--hil] - 🟡 **黄信号**: EARS要件定義書・設計文書から妥当な推測の場合 - 🔴 **赤信号**: EARS要件定義書・設計文書にない推測の場合 +0. **Claude Codeタスクシステムの確認** + - TaskList ツールで未完了のタスク（pending/in_progress）を確認 + - タスクのsubjectが "TASK-" で始まるものを抽出 + - 各タスクについて： + - TaskGet でタスクの詳細情報を取得 + - metadata から以下を取得： + - `requirement_name`: 要件名 + - `task_file`: タスクファイルパス（例: docs/tasks/db-migration-tool/TASK-0001.md） + - `phase`: フェーズ情報 + - `task_type`: タスクタイプ（TDD/DIRECT） + - 引数の優先順位： + - **引数で要件名が指定されている場合**: 引数の要件名を使用 + - **引数で要件名が省略されている場合**: Claude Codeタスクのmetadataから要件名を取得 + - **TASK-IDの決定**: + - 引数でTASK-IDが指定されている場合: 引数のTASK-IDを使用 + - 引数でTASK-IDが省略されている場合: + - blockedByが空（依存タスクがない）かつstatus=pendingの最初のタスクを選択 + - 選択したタスクのsubjectからTASK-IDを抽出（例: "TASK-0001: タスク名" → TASK-0001） + - 選択したClaude CodeタスクのIDを記録（後でステータス更新に使用） + 1. **追加ルールの読み込み** - `docs/spec/{要件名}/note.md` が存在する場合は読み込み @@ -40,18 +88,20 @@ argument-hint: [要件名（省略可）] [TASK-ID (TASK-00001)] [--hil] - `docs/tasks/{要件名}/overview.md` or `docs/tasks/{要件名}-overview.md` - タスク全体概要 - `docs/tasks/{要件名}/TASK-{task_id}.md` or `docs/tasks/{要件名}-tasks.md` - 対象タスクファイル - 依存タスクのファイルも読み込み、実装の順序と関連性を理解 + - Claude Codeタスクのmetadataにtask_fileがある場合はそのパスを優先使用 -3. **タスクの選択** - - @agent-symbol-searcher で指定されたタスクID(TASK-0000形式)を検索し、見つかったタスクファイルをReadツールで読み込み - - ユーザが指定したタスクIDを確認 - - 指定がない場合は、依存関係に基づいて次のタスクを自動選択 - - 選択したタスクの詳細を表示 +3. **タスクの選択と実行開始** + - 選択されたタスクの詳細を表示 + - Claude Codeタスクが選択されている場合: + - TaskUpdate でステータスを 'in_progress' に更新 + - 更新内容を表示: "📌 Claude Codeタスク #{task_id} を実行中に設定しました" - 読み込んだ技術スタック定義に基づいて実装方針を決定 4. **依存関係の確認** - - @agent-symbol-searcher で依存タスクの状態を検索し、見つかったタスクファイルをReadツールで読み込み - - 依存タスクが完了しているか確認 + - Claude CodeタスクのblockedByフィールドを確認 + - 依存タスクが完了しているか確認（status=completed） - 未完了の依存タスクがある場合は警告 + - Task tool (subagent_type: Explore, thoroughness: quick) を使用して依存タスクファイルの状態も確認 5. **実装ディレクトリの準備** - 現在のワークスペースで作業を行う @@ -60,12 +110,13 @@ argument-hint: [要件名（省略可）] [TASK-ID (TASK-00001)] [--hil] 6. **実装タイプの判定** - タスクの性質を分析（コード実装 vs 準備作業） - 実装方式を決定（TDD vs 直接作業） + - Claude Codeタスクのmetadata.task_typeも参考にする 7. **実装プロセスの実行** ### A. **TDDプロセス**（コード実装タスク用） - a. **コンテキスト準備** - `@task general-purpose /tsumiki:tdd-tasknote` + a. **コンテキスト準備** - `@Task tool (subagent_type: general-purpose, model: {{noteTaskName}}) /tsumiki:tdd-tasknote` ``` Task実行: TDDコンテキスト準備フェーズ 目的: タスクノートを生成し、開発に必要なコンテキスト情報を収集する @@ -80,7 +131,7 @@ argument-hint: [要件名（省略可）] [TASK-ID (TASK-00001)] [--hil] 出力ファイル: docs/implements/{要件名}/{TASK-ID}/note.md ``` - b. **要件定義** - `@task general-purpose /tsumiki:tdd-requirements` + b. **要件定義** - `@Task tool (subagent_type: general-purpose, model: {{thinkTaskName}}) /tsumiki:tdd-requirements` ``` Task実行: TDD要件定義フェーズ 目的: タスクの詳細要件を記述し、受け入れ基準を明確化する @@ -89,7 +140,7 @@ argument-hint: [要件名（省略可）] [TASK-ID (TASK-00001)] [--hil] 実行方式: 個別Task実行 ``` - c. **テストケース作成** - `@task general-purpose /tsumiki:tdd-testcases` + c. **テストケース作成** - `@Task tool (subagent_type: general-purpose, model: {{thinkTaskName}}) /tsumiki:tdd-testcases` ``` Task実行: TDDテストケース作成フェーズ 目的: 単体テストケースを作成し、エッジケースを考慮する @@ -113,7 +164,7 @@ argument-hint: [要件名（省略可）] [TASK-ID (TASK-00001)] [--hil] - 追加・修正が必要なテストケースはないか ``` - d. **テスト実装** - `@task general-purpose /tsumiki:tdd-red` + d. **テスト実装** - `@Task tool (subagent_type: general-purpose, model: {{tddTaskName}}) /tsumiki:tdd-red` ``` Task実行: TDDレッドフェーズ 目的: 失敗するテストを実装し、テストが失敗することを確認する @@ -121,7 +172,7 @@ argument-hint: [要件名（省略可）] [TASK-ID (TASK-00001)] [--hil] 実行方式: 個別Task実行 ``` - e. **最小実装** - `@task general-purpose /tsumiki:tdd-green` + e. **最小実装** - `@Task tool (subagent_type: general-purpose, model: {{tddTaskName}}) /tsumiki:tdd-green` ``` Task実行: TDDグリーンフェーズ 目的: テストが通る最小限の実装を行い、過度な実装を避ける @@ -129,7 +180,7 @@ argument-hint: [要件名（省略可）] [TASK-ID (TASK-00001)] [--hil] 実行方式: 個別Task実行 ``` - f. **リファクタリング** - `@task general-purpose /tsumiki:tdd-refactor` + f. **リファクタリング** - `@Task tool (subagent_type: general-purpose, model: {{tddTaskName}}) /tsumiki:tdd-refactor` ``` Task実行: TDDリファクタリングフェーズ 目的: コードの品質向上と保守性の改善を行う @@ -137,7 +188,7 @@ argument-hint: [要件名（省略可）] [TASK-ID (TASK-00001)] [--hil] 実行方式: 個別Task実行 ``` - g. **品質確認** - `@task general-purpose /tsumiki:tdd-verify-complete` + g. **品質確認** - `@Task tool (subagent_type: general-purpose, model: {{tddTaskName}}) /tsumiki:tdd-verify-complete` ``` Task実行: TDD品質確認フェーズ 目的: 実装の完成度とテストケースの充足度を確認する @@ -160,13 +211,16 @@ argument-hint: [要件名（省略可）] [TASK-ID (TASK-00001)] [--hil] ``` 品質確認が成功した後の処理: - タスクファイルの完了チェックボックスを更新 + - Claude Codeタスクシステムの更新: + - TaskUpdate でステータスを 'completed' に更新 + - 更新結果を表示: "✅ Claude Codeタスク #{task_id} を完了に設定しました" - 実装サマリーの作成 - - 次のタスクの提案 + - 次のタスクの提案（依存関係が解消された次のタスク） ``` ### B. **直接作業プロセス**（準備作業タスク用） - a. **準備作業の実行** - `@task general-purpose /tsumiki:direct-setup` + a. **準備作業の実行** - `@Task tool (subagent_type: general-purpose, model: {{tddTaskName}}) /tsumiki:direct-setup` ``` Task実行: 直接作業実行フェーズ 目的: ディレクトリ作成、設定ファイル作成、依存関係のインストール、環境設定を行う @@ -178,7 +232,7 @@ argument-hint: [要件名（省略可）] [TASK-ID (TASK-00001)] [--hil] 実行方式: 個別Task実行 ``` - b. **作業結果の確認** - `@task general-purpose /tsumiki:direct-verify` + b. **作業結果の確認** - `@Task tool (subagent_type: general-purpose, model: {{tddTaskName}}) /tsumiki:direct-verify` ``` Task実行: 直接作業確認フェーズ 目的: 作業完了の検証と成果物確認を行う @@ -193,27 +247,38 @@ argument-hint: [要件名（省略可）] [TASK-ID (TASK-00001)] [--hil] ``` 作業確認が成功した後の処理: - タスクファイルの完了チェックボックスを更新 + - Claude Codeタスクシステムの更新: + - TaskUpdate でステータスを 'completed' に更新 + - 更新結果を表示: "✅ Claude Codeタスク #{task_id} を完了に設定しました" - 実装サマリーの作成 - - 次のタスクの提案 + - 次のタスクの提案（依存関係が解消された次のタスク） ``` -8. **全体の完了確認** +7. **全体の完了確認** - タスクのステータスを更新（タスクファイルのチェックボックスにチェックを入れる） + - Claude Codeタスクシステムの更新: + - TaskUpdate でステータスを 'completed' に更新 + - 依存関係が解消された次のタスクを TaskList で確認 - 実装結果をドキュメント化 - - 次のタスクを提案 + - 次のタスクを提案（Claude Codeタスクの依存関係を考慮） ## 実行フロー ```mermaid flowchart TD - A[1. 追加ルール読み込み] --> A1[2. プロジェクト文書読み込み] + A0[0. Claude Codeタスク確認] --> A0_1{タスク存在?} + A0_1 -->|Yes| A0_2[要件名・TASK-ID取得] + A0_1 -->|No| A0_3[引数から取得] + A0_2 --> A0_4[TaskUpdate: in_progress] + A0_3 --> A + A0_4 --> A[1. 追加ルール読み込み] + A --> A1[2. プロジェクト文書読み込み] A1 --> A2[要件定義書・設計文書] - A2 --> B[3. 技術スタック読み込み] - B --> C[4. タスク選択] - C --> D{5. 依存関係OK?} + A2 --> B[3. タスク選択確認] + B --> D{4. 依存関係OK?} D -->|No| E[警告表示] - D -->|Yes| F[6. ディレクトリ準備] - F --> G{7. タスクタイプ判定} + D -->|Yes| F[5. ディレクトリ準備] + F --> G{6. タスクタイプ判定} G -->|コード実装| H[TDDプロセス] G -->|準備作業| M[直接作業プロセス] @@ -240,9 +305,12 @@ flowchart TD M1 --> M2[b. direct-verify] M2 --> M3[c. タスク完了処理] - H8 --> I{9. 他のタスク?} - M3 --> I - I -->|Yes| C + H8 --> H9[TaskUpdate: completed] + M3 --> M4[TaskUpdate: completed] + + H9 --> I{8. 他のタスク?} + M4 --> I + I -->|Yes| A0 I -->|No| J[全タスク完了] ``` @@ -260,6 +328,16 @@ $ /tsumiki:kairo-implement {要件名} TASK-0001 --hil # Human-in-the-Loopモードで全タスクを実装 $ /tsumiki:kairo-implement {要件名} --hil + +# Claude Codeタスクシステムと連携（引数省略） +# - 未完了のClaude Codeタスクから自動的に要件名とTASK-IDを取得 +# - タスク開始時にステータスを in_progress に更新 +# - タスク完了時にステータスを completed に更新 +$ /tsumiki:kairo-implement + +# Claude Codeタスクシステムと連携（要件名のみ指定） +# - 指定した要件名のClaude Codeタスクから最初の未完了タスクを選択 +$ /tsumiki:kairo-implement {要件名} ``` ## 実装タイプ判定基準 @@ -302,30 +380,38 @@ $ /tsumiki:kairo-implement {要件名} --hil ```bash # TDDプロセスの場合 -@task general-purpose /tsumiki:tdd-tasknote {要件名} {TASK-ID} -@task general-purpose /tsumiki:tdd-requirements {要件名} {TASK-ID} -@task general-purpose /tsumiki:tdd-testcases {要件名} {TASK-ID} -@task general-purpose /tsumiki:tdd-red -@task general-purpose /tsumiki:tdd-green -@task general-purpose /tsumiki:tdd-refactor -@task general-purpose /tsumiki:tdd-verify-complete +@Task tool (subagent_type: general-purpose, model: {{noteTaskName}}) /tsumiki:tdd-tasknote {要件名} {TASK-ID} +@Task tool (subagent_type: general-purpose, model: {{thinkTaskName}}) /tsumiki:tdd-requirements {要件名} {TASK-ID} +@Task tool (subagent_type: general-purpose, model: {{thinkTaskName}}) /tsumiki:tdd-testcases {要件名} {TASK-ID} +@Task tool (subagent_type: general-purpose, model: {{tddTaskName}}) /tsumiki:tdd-red {要件名} {TASK-ID} +@Task tool (subagent_type: general-purpose, model: {{tddTaskName}}) /tsumiki:tdd-green {要件名} {TASK-ID} +@Task tool (subagent_type: general-purpose, model: {{tddTaskName}}) /tsumiki:tdd-refactor {要件名} {TASK-ID} +@Task tool (subagent_type: general-purpose, model: {{tddTaskName}}) /tsumiki:tdd-verify-complete {要件名} {TASK-ID} # 直接作業プロセスの場合 -@task general-purpose /tsumiki:direct-setup -@task general-purpose /tsumiki:direct-verify +@Task tool (subagent_type: general-purpose, model: {{tddTaskName}}) /tsumiki:direct-setup {要件名} {TASK-ID} +@Task tool (subagent_type: general-purpose, model: {{tddTaskName}}) /tsumiki:direct-verify {要件名} {TASK-ID} ``` ## 実装時の注意事項 ### 全般 -1. **プロジェクト文書の活用** +1. **Claude Codeタスクシステム連携** + - 実行開始時に TaskList で未完了タスクを確認 + - タスク開始時に TaskUpdate でステータスを 'in_progress' に更新 + - タスク完了時に TaskUpdate でステータスを 'completed' に更新 + - metadata から要件名、タスクファイルパス、タイプを取得 + - 引数が省略された場合は Claude Codeタスクの情報を使用 + - 依存関係（blockedBy）を考慮して次のタスクを提案 + +2. **プロジェクト文書の活用** - 要件定義書（EARS記法）を常に参照し、実装の根拠を明確にする - 設計文書に記載されたアーキテクチャ、データフロー、API仕様に従う - タスクファイルの「関連文書」セクションから必要な文書を確認 - 信頼性レベル（🔵🟡🔴）を参考に、推測が必要な箇所を特定 -2. **ファイル構造の理解** +3. **ファイル構造の理解** - `docs/spec/{要件名}/` - 要件定義書 - `docs/design/{要件名}/` - 設計文書 - `docs/tasks/{要件名}/` - タスク管理 @@ -333,21 +419,21 @@ $ /tsumiki:kairo-implement {要件名} --hil ### TDDプロセス用 -1. **--hilオプション使用時の注意** +4. **--hilオプション使用時の注意** - テストケース作成後、必ずユーザーの確認を待つ - ユーザーが承認するまでtdd-red以降のフェーズを実行しない - 修正指示があった場合は、tdd-testcasesフェーズから再実行 - AskUserQuestion ツールを使用してユーザーの選択を取得 -2. **テストファースト** +5. **テストファースト** - 必ずテストを先に書く - テストが失敗することを確認してから実装 -3. **インクリメンタルな実装** +6. **インクリメンタルな実装** - 一度に全てを実装しない - 小さなステップで進める -4. **品質確認の徹底** +7. **品質確認の徹底** - 各ステップで品質を確認 - 技術的負債を作らない - **テストケース充足度の確認**: @@ -359,7 +445,7 @@ $ /tsumiki:kairo-implement {要件名} --hil - 要件定義書・設計文書に記載された仕様を満たしているか - コード品質（可読性、保守性）が基準を満たしているか -5. **品質確認後の対応** +8. **品質確認後の対応** - テストケース不足の場合: - d. tdd-red に戻り、不足しているテストケースを追加 - e. tdd-green で実装を追加 @@ -370,7 +456,7 @@ $ /tsumiki:kairo-implement {要件名} --hil - f. tdd-refactor でリファクタリング - g. tdd-verify-complete で再確認 -6. **Human-in-the-Loop実行フロー** +9. **Human-in-the-Loop実行フロー** - --hilオプション指定時: 1. c. tdd-testcases でテストケースを作成 2. c-1. 作成されたテストケースの一覧と分析結果を表示 @@ -382,17 +468,17 @@ $ /tsumiki:kairo-implement {要件名} --hil ### 直接作業プロセス用 -1. **作業の段階的実行** - - 依存関係を考慮した順序で実行 - - 各ステップの完了を確認 +10. **作業の段階的実行** + - 依存関係を考慮した順序で実行 + - 各ステップの完了を確認 -2. **設定の検証** - - 作成した設定ファイルの動作確認 - - 環境の正常性チェック +11. **設定の検証** + - 作成した設定ファイルの動作確認 + - 環境の正常性チェック -3. **ドキュメントの更新** - - 実装と同時にドキュメントも更新 - - 他の開発者が理解できるように +12. **ドキュメントの更新** + - 実装と同時にドキュメントも更新 + - 他の開発者が理解できるように ## 出力フォーマット @@ -406,6 +492,7 @@ $ /tsumiki:kairo-implement {要件名} --hil - 依存: {{依存タスクID}} ✅ - 推定時間: 4時間 - 実装タイプ: TDDプロセス +- Claude Codeタスク: #{{claude_task_id}} (in_progress) 🔄 TDDプロセスを開始します... ``` @@ -420,6 +507,7 @@ $ /tsumiki:kairo-implement {要件名} --hil - 依存: {{依存タスクID}} ✅ - 推定時間: 3時間 - 実装タイプ: 直接作業プロセス +- Claude Codeタスク: #{{claude_task_id}} (in_progress) 🔧 準備作業を開始します... ``` @@ -512,6 +600,9 @@ $ /tsumiki:kairo-implement {要件名} --hil ✅ タスクファイルのチェックボックスを更新しました - [ ] **タスク完了** → [x] **タスク完了** +✅ Claude Codeタスク #{{claude_task_id}} を完了に設定しました + - Status: in_progress → completed + 📊 実装サマリー: - 実装タイプ: TDDプロセス (個別Task実行) - 実行Taskステップ: 8個 (全て成功) @@ -523,7 +614,7 @@ $ /tsumiki:kairo-implement {要件名} --hil - 所要時間: 4時間15分 📝 次の推奨タスク: -- {{次のタスクID}}: {{次のタスク名}} +- {{次のタスクID}}: {{次のタスク名}} (Claude Codeタスク: #{{次のclaude_task_id}}) - {{関連タスクID}}: {{関連タスク名}}（依存関係あり） 続けて実装しますか？ (y/n) @@ -537,6 +628,9 @@ $ /tsumiki:kairo-implement {要件名} --hil ✅ タスクファイルのチェックボックスを更新しました - [ ] **タスク完了** → [x] **タスク完了** +✅ Claude Codeタスク #{{claude_task_id}} を完了に設定しました + - Status: in_progress → completed + 📊 実装サマリー: - 実装タイプ: 直接作業プロセス (個別Task実行) - 実行Taskステップ: 2個 (全て成功) @@ -546,7 +640,7 @@ $ /tsumiki:kairo-implement {要件名} --hil - 所要時間: 2時間30分 📝 次の推奨タスク: -- {{次のタスクID}}: {{次のタスク名}} +- {{次のタスクID}}: {{次のタスク名}} (Claude Codeタスク: #{{次のclaude_task_id}}) - {{関連タスクID}}: {{関連タスク名}}（依存関係あり） 続けて実装しますか？ (y/n) @@ -554,13 +648,22 @@ $ /tsumiki:kairo-implement {要件名} --hil ## エラーハンドリング -- 依存タスク未完了: 警告を表示し、確認を求める -- テスト失敗: 詳細なエラー情報を表示 -- ファイル競合: バックアップを作成してから上書き +- **Claude Codeタスク関連**: + - タスクが見つからない: 引数から要件名とTASK-IDを取得して続行 + - タスクステータス更新失敗: 警告を表示するが処理は続行 + - metadataが不完全: 引数またはタスクファイルから情報を補完 +- **依存関係**: + - 依存タスク未完了: 警告を表示し、確認を求める + - blockedByに未完了タスクがある: 依存タスクの一覧を表示 +- **実装エラー**: + - テスト失敗: 詳細なエラー情報を表示 + - ファイル競合: バックアップを作成してから上書き ## 実行後の確認 - 実装したファイルの一覧を表示 - テスト結果のサマリーを表示 -- 残りのタスクと進捗率を表示 -- 次のタスクの提案を表示 +- Claude Codeタスクのステータス更新確認 +- 残りのタスクと進捗率を表示（Claude Codeタスクシステムの情報を含む） +- 次のタスクの提案を表示（依存関係が解消されたタスクを優先） +- TaskList で全体の進捗を確認 diff --git a/commands/kairo-requirements.md b/commands/kairo-requirements.md index 53b9adf..c48cb6c 100644 --- a/commands/kairo-requirements.md +++ b/commands/kairo-requirements.md @@ -1,7 +1,7 @@ --- description: ユーザから提供された要件の概要を分析し、EARS（Easy Approach to Requirements Syntax）記法を使用して詳細な受け入れ基準を含む要件定義書を作成します。 allowed-tools: Read, Glob, Grep, Task, Write, Edit, TodoWrite, WebFetch, AskUserQuestion -argument-hint: [要件名] [PRDファイルパス(optional)] +argument-hint: "[要件名] [PRDファイルパス(optional)]" --- Kairo開発の要件整理を実施し、PRD・EARS要件定義書・設計文書を参照しながら機能仕様を明確化します。信頼性レベルを示しながら要件定義を作成します。 @@ -97,7 +97,7 @@ PRDファイル={{prd_file_path}} - label: "不要" description: "設計文書のみで要件定義を作成" - 「必要」を選択した場合のみ: - - @task agent-symbol-searcher で既存仕様・実装の網羅的調査 + - Task tool (subagent_type: Explore, thoroughness: medium) を使用して既存仕様・実装の網羅的調査 - git status/log で現在の開発状況・進捗確認 - 実装済み機能 vs 設計書の差分分析 - 残タスク・未実装部分の特定 diff --git a/commands/kairo-tasknote.md b/commands/kairo-tasknote.md index 135a598..45af3ff 100644 --- a/commands/kairo-tasknote.md +++ b/commands/kairo-tasknote.md @@ -1,7 +1,7 @@ --- description: Kairo開発のコンテキスト情報を収集してノートにまとめます。技術スタック、追加ルール、関連ファイルの情報を整理します。 allowed-tools: Read, Glob, Grep, Task, Write, TodoWrite, Bash -argument-hint: [要件名] +argument-hint: "[要件名]" --- Kairo開発の前にコンテキスト情報を収集し、開発に必要な情報をノートファイルにまとめます。 @@ -21,9 +21,7 @@ Kairo開発の前にコンテキスト情報を収集し、開発に必要な情 - `{{出力ディレクトリ}}/{要件名}/note.md` が既にある場合: - 既存ファイルの内容を表示 - - ユーザに確認: 「既存のノートファイルがあります。更新しますか？（y/n）」 - - ユーザが「y」と回答した場合: step3 を実行 - - ユーザが「n」と回答した場合: 終了する + - 終了する - 存在しない場合: step3 を実行する ## step3: 開発コンテキストの収集 @@ -53,12 +51,11 @@ Kairo開発の前にコンテキスト情報を収集し、開発に必要な情 - ユーザーに確認: 「既存コードベースの詳細分析が必要ですか？（y/n）」 - 必要な場合のみ実行: - - **@task agent-symbol-searcher で実装関連情報を検索** - - 類似機能の実装例を検索 - - ユーティリティ関数・共通モジュールを検索 + - **Task tool (subagent_type: Explore, thoroughness: medium) を使用して実装関連情報を探索** + - 類似機能の実装例を探索 + - ユーティリティ関数・共通モジュールを探索 - 実装パターンやアーキテクチャガイドラインを特定 - 依存関係やインポートパスを確認 - - 見つかった関連ファイルを Read ツールで読み込み ### Phase 4: Git情報の収集 diff --git a/commands/kairo-tasks.md b/commands/kairo-tasks.md index b13f4f5..da4af4a 100644 --- a/commands/kairo-tasks.md +++ b/commands/kairo-tasks.md @@ -1,7 +1,7 @@ --- description: 設計文書に基づいて実装タスクを1日単位の粒度で分割し、1ヶ月単位のフェーズに整理します。各タスクを個別ファイルで管理し、依存関係を考慮した適切な順序で管理します。 -allowed-tools: Read, Glob, Grep, Task, Write, Edit, TodoWrite, WebFetch, AskUserQuestion -argument-hint: [要件名] +allowed-tools: Read, Glob, Grep, Task, Write, Edit, TodoWrite, WebFetch, AskUserQuestion, TaskCreate, TaskUpdate, TaskList +argument-hint: "[要件名] [--task]" --- # kairo-tasks @@ -24,11 +24,15 @@ argument-hint: [要件名] 要件名={{requirement_name}} 作業規模={{work_scope}} 信頼性評価=[] +claude_code_task登録={{register_to_claude_code_task}} # step - $ARGUMENTS がない場合、「引数に要件名を指定してください（例: ユーザー認証システム）」と言って終了する -- $ARGUMENTS の内容と context の内容をまとめてユーザに宣言する +- $ARGUMENTS から `--task` オプションの有無を確認する + - `--task` が含まれている場合、context の {{register_to_claude_code_task}} を true に設定 + - `--task` を除いた残りを要件名として context の {{requirement_name}} に保存 +- $ARGUMENTS の内容と context の内容をまとめてユーザに宣言する（`--task` オプションが有効な場合はその旨も含める） - step2 を実行する ## step2: 作業規模の確認 @@ -93,8 +97,8 @@ argument-hint: [要件名] - 読み込んだ技術スタック定義に基づいて実装技術を特定 - **既存タスクファイルの確認** - - @agent-symbol-searcher で既存タスクIDを検索し、見つかったタスクファイルをReadツールで読み込み - - 既存の`docs/tasks/{要件名}-TASK-*.md`ファイルをReadツールで読み込み + - Task tool (subagent_type: Explore, thoroughness: quick) を使用して既存タスクIDを探索 + - 既存の`docs/tasks/{要件名}-TASK-*.md`ファイルを確認 - 使用済みタスク番号（TASK-0000形式）を抽出 - 新規タスクで重複しない番号を割り当て @@ -334,8 +338,94 @@ AskUserQuestion ツールを使って、選択された項目に応じた質問 - タスク総数、推定工数、フェーズ数 - 各ファイル内のリンクが正しく設定されていることを確認 +- `--task` オプションが指定されている場合は step6.5 を実行する +- そうでない場合は次のステップ表示へ + 次のステップ表示: 「次のお勧めステップ: `/tsumiki:kairo-implement` でタスクを実装します。特定のタスクを実装する場合は `/tsumiki:kairo-implement TASK-0001` のように指定してください。」 +### 6.5 Claude Codeタスクへの登録（--taskオプション指定時のみ） + +**重要**: このステップは `--task` オプションが指定された場合のみ実行する。 + +#### 6.5.1 タスク情報の収集 + +- 作成した全タスクファイル（`docs/tasks/{要件名}/TASK-*.md`）を読み込む +- 各タスクファイルから以下の情報を抽出： + - タスクID（例: TASK-0001） + - タスク名 + - タスクタイプ（TDD/DIRECT） + - 推定工数 + - フェーズ + - 完了条件 + - 依存タスク（前提タスク） + - 詳細ファイルパス + +#### 6.5.2 既存Claude Codeタスクの確認 + +- TaskList ツールを使用して既存のClaude Codeタスクを確認 +- 同じタスクID（TASK-0001など）が既に登録されているか確認 +- 重複がある場合は警告メッセージを表示し、スキップするか確認 + +#### 6.5.3 タスクの一括登録 + +以下の順序でタスクを登録： + +1. **依存関係のないタスクから登録**: + - 前提タスクがないタスクを最初に登録 + - TaskCreate ツールを使用 + - subject: "{タスクID}: {タスク名}" + - activeForm: "{タスク名}を実装中" + - description: 以下の情報を含める： + ``` + タスクID: {タスクID} + タイプ: {タスクタイプ} + 推定工数: {工数}時間 + フェーズ: {フェーズ} + 詳細ファイル: {ファイルパス} + + 【タスク概要】 + {タスクファイルのタスク概要セクションから抽出} + + 【完了条件】 + {完了条件のリスト} + ``` + - metadata: `{"task_file": "{ファイルパス}", "phase": "{フェーズ}", "task_type": "{タイプ}", "requirement_name": "{要件名}"}` + +2. **依存関係の設定**: + - タスク作成後、TaskUpdate ツールを使用して依存関係を設定 + - 前提タスクがある場合、addBlockedBy に前提タスクのIDを設定 + - 例: タスクファイルに「前提タスク: TASK-0001」がある場合 + → TaskUpdate で該当タスクの addBlockedBy に TASK-0001 を追加 + +3. **登録結果の記録**: + - 登録成功したタスク数 + - スキップしたタスク数（重複など） + - 依存関係設定の成功/失敗 + +#### 6.5.4 登録完了報告 + +- 登録したタスク総数 +- フェーズ別の登録数 +- 依存関係の設定状況 +- TaskList で登録結果を確認・表示 +- 次のステップ表示: + ``` + ✅ {N}件のタスクをClaude Codeタスクシステムに登録しました。 + + タスクの確認: TaskList ツールで確認できます + タスクの開始: TaskUpdate で status を 'in_progress' に変更してください + + 次のお勧めステップ: `/tsumiki:kairo-implement` でタスクを実装します。 + ``` + +#### 注意事項 + +- タスクID（TASK-0001など）はClaude Codeタスクシステムの内部IDとは異なる +- Claude Codeタスクシステムでは自動的に #1, #2, ... の連番が割り当てられる +- タスクファイルのTASK-0001とClaude Codeタスクの#1は必ずしも一致しない +- 依存関係の解決には、タスクID（TASK-0001）からClaude CodeタスクID（#1）への変換マッピングが必要 +- マッピングは metadata の task_file を使って検索可能 + # rules ## ファイル名のルール @@ -428,8 +518,98 @@ AskUserQuestion ツールを使って、選択された項目に応じた質問 1. `/tsumiki:direct-setup` - 直接実装・設定 2. `/tsumiki:direct-verify` - 動作確認・品質確認 +## Claude Codeタスク登録のルール + +### タスクID変換マッピング + +- タスクファイルのタスクID（TASK-0001）とClaude Codeタスクシステムの内部ID（#1）は異なる +- マッピングを作成して管理する： + ``` + TASK-0001 → Claude Codeタスク #X + TASK-0002 → Claude Codeタスク #Y + ... + ``` +- metadata の task_file フィールドを使って逆引き可能にする + +### 依存関係の解決手順 + +1. すべてのタスクをまず登録（依存関係なし） +2. 登録後、各タスクのClaude CodeタスクIDを取得 +3. タスクID（TASK-0001）からClaude CodeタスクID（#X）へのマッピングを作成 +4. マッピングを使用して依存関係を設定 +5. TaskUpdate で addBlockedBy を使って依存関係を追加 + +### タスク情報の構造化 + +``` +subject: "TASK-0001: {タスク名}" +description: | + タスクID: TASK-0001 + タイプ: {TDD/DIRECT} + 推定工数: {工数}時間 + フェーズ: Phase 1 - {フェーズ名} + 詳細ファイル: docs/tasks/{要件名}/TASK-0001.md + + 【タスク概要】 + {タスクの概要} + + 【完了条件】 + - 完了条件1 + - 完了条件2 +activeForm: "{タスク名}を実装中" +metadata: { + "task_file": "docs/tasks/{要件名}/TASK-0001.md", + "phase": "Phase 1", + "task_type": "TDD", + "requirement_name": "{要件名}" +} +``` + +### 重複チェックのルール + +- TaskList で既存タスクを取得 +- subject が "TASK-{番号}:" で始まるタスクを抽出 +- 同じTASK番号が存在する場合は、ユーザーに確認 + - 既存のタスクをスキップ + - または既存のタスクを削除して再登録 + # info +## --task オプションの使用例 + +### 基本的な使用方法 + +``` +/tsumiki:kairo-tasks ユーザー認証システム --task +``` + +このコマンドは以下を実行します： +1. タスクファイルの作成（通常通り） +2. Claude Codeタスクシステムへの自動登録（--taskオプションにより追加） + +### オプションなしの使用方法 + +``` +/tsumiki:kairo-tasks ユーザー認証システム +``` + +タスクファイルのみを作成し、Claude Codeタスクシステムには登録しません。 + +### 登録されるタスク情報 + +各タスクは以下の形式でClaude Codeタスクシステムに登録されます： +- **subject**: "TASK-0001: 依存パッケージ追加とプロジェクト設定" +- **description**: タスクID、タイプ、工数、フェーズ、概要、完了条件を含む詳細情報 +- **activeForm**: "依存パッケージ追加とプロジェクト設定を実装中" +- **metadata**: task_file, phase, task_type, requirement_name を含むメタデータ +- **blockedBy**: 前提タスクとの依存関係 + +### 登録後の確認方法 + +``` +TaskList ツールで登録されたタスクを確認 +``` + ## AskUserQuestion ツールの使用例 すべてのヒアリングは AskUserQuestion ツールを使用して行います。以下は具体的な使用例です。 diff --git a/commands/tdd-green.md b/commands/tdd-green.md index b3fadc0..74a8b38 100644 --- a/commands/tdd-green.md +++ b/commands/tdd-green.md @@ -1,7 +1,7 @@ --- description: TDDのGreenフェーズを実行します。失敗しているテストケースを通すための実装を行い、テストが成功することを確認します。 allowed-tools: Read, Glob, Grep, Task, Write, Edit, TodoWrite -argument-hint: [要件名] [TASK-ID] +argument-hint: "[要件名] [TASK-ID]" --- TDDのGreenフェーズを実行し、Redフェーズで作成したテストを通すための実装を行います。 @@ -47,10 +47,10 @@ Greenフェーズファイル=./docs/implements/{要件名}/{{task_id}}/{feature - `./docs/rule/tdd/green` ディレクトリが存在する場合は読み込み - 各ディレクトリ内のすべてのファイルを読み込み、追加ルールとして適用 -3. **@agent-symbol-searcher で実装関連情報を検索し、見つかったファイルを読み込み** - - 既存の類似機能やユーティリティ関数を検索し、該当ファイルをReadツールで読み込み - - 実装パターンやアーキテクチャガイドラインを特定し、設計文書をReadツールで読み込み - - 依存関係やインポートパスを確認し、関連ファイルをReadツールで読み込み +3. **Task tool (subagent_type: Explore, thoroughness: quick) を使用して実装関連情報を探索** + - 既存の類似機能やユーティリティ関数を探索 + - 実装パターンやアーキテクチャガイドラインを特定 + - 依存関係やインポートパスを確認 4. **関連する外部ファイルを直接読み込み** - 関連する設計文書やタスクファイルも必要に応じて読み込み @@ -75,10 +75,15 @@ Greenフェーズファイル=./docs/implements/{要件名}/{{task_id}}/{feature - ファイルサイズを意識（800行制限） - モック使用の制限を遵守 -- @task でテストを実行し、結果を確認する +- テストを実行し、結果を確認する + - **選択的実行**: 実装したファイルに関連するテストのみを実行（高速） + - Jest: `npm test -- --findRelatedTests <実装ファイル>` + - pytest: `pytest <関連テストファイル>` + - 特定のテストスイート: `npm test -- <テストパターン>` - 全てのテストが通ることを確認 - 失敗した場合は原因を調査し、修正を繰り返す - 既存のテストがエラーになった場合は仕様を元に適切に修正 + - **注意**: 全体のテスト実行は verify-complete フェーズで実施 - 実装内容について、品質判定基準に基づいて以下を評価： - テスト成功状況 diff --git a/commands/tdd-red.md b/commands/tdd-red.md index f120324..ddacbd1 100644 --- a/commands/tdd-red.md +++ b/commands/tdd-red.md @@ -1,7 +1,7 @@ --- description: TDDのRedフェーズを実行します。失敗するテストケースを作成し、実装すべき機能を明確に定義します。 allowed-tools: Read, Glob, Grep, Task, Write, TodoWrite, Edit -argument-hint: [要件名] [TASK-ID] +argument-hint: "[要件名] [TASK-ID]" --- TDDのRedフェーズを実行します。失敗するテストケースを作成し、実装すべき機能を明確に定義します。 @@ -60,12 +60,12 @@ Redフェーズファイル=./docs/implements/{要件名}/{{task_id}}/{feature_n - 生成されたノートファイルを読み込み - ノートには技術スタック、開発ルール、関連実装、設計文書、注意事項が含まれる -**5. @agent-symbol-searcher でテスト実装関連情報を検索し、見つかったファイルを読み込み** +**5. Task tool (subagent_type: Explore, thoroughness: quick) を使用してテスト実装関連情報を探索** - 読み込んだ技術スタック定義に基づいてテストフレームワークを特定 - **UIタスクの場合**: E2Eテストフレームワーク（Playwright等）の設定とサンプルを優先的に確認 -- 既存のテストファイルやテスト関数を検索し、該当ファイルをReadツールで読み込み -- テストセットアップやモックの使用パターンを特定し、関連ファイルをReadツールで読み込み -- **E2Eテスト設定確認**: playwright.config.js、cypress.config.js等の設定ファイルをReadツールで読み込み +- 既存のテストファイルやテスト関数を探索 +- テストセットアップやモックの使用パターンを特定 +- **E2Eテスト設定確認**: playwright.config.js、cypress.config.js等の設定ファイルを確認 **6. 関連する外部ファイルを直接読み込み** - 関連する設計文書やタスクファイルも必要に応じて読み込み @@ -502,7 +502,7 @@ npm test -- --coverage - 設計文書（データモデル・ディレクトリ構造） - 注意事項（技術的制約・セキュリティ要件・パフォーマンス要件） - **追加ルール**（`docs/rule`, `docs/rule/tdd`, `docs/rule/tdd/red`） -- **既存のテスト実装パターン**（symbol-searcherで検索したテストファイル） +- **既存のテスト実装パターン**（Explore agentで探索したテストファイル） - **要件定義・テストケース定義** これらの情報を基に、以下の要件を満たすテストコードを作成してください。 diff --git a/commands/tdd-refactor.md b/commands/tdd-refactor.md index 1372025..ee7d7f1 100644 --- a/commands/tdd-refactor.md +++ b/commands/tdd-refactor.md @@ -1,7 +1,7 @@ --- description: TDDのRefactorフェーズを実行します。テストを通す実装が完了した後、コード品質の改善とリファクタリングを行います。 allowed-tools: Read, Glob, Grep, Task, Write, Edit, TodoWrite -argument-hint: [要件名] [TASK-ID] +argument-hint: "[要件名] [TASK-ID]" --- TDDのRefactorフェーズを実行し、Greenフェーズで作成した実装コードの品質を改善します。 @@ -47,10 +47,10 @@ Refactorフェーズファイル=./docs/implements/{要件名}/{{task_id}}/{feat - `./docs/rule/tdd/refactor` ディレクトリが存在する場合は読み込み - 各ディレクトリ内のすべてのファイルを読み込み、追加ルールとして適用 -3. **@agent-symbol-searcher でリファクタリング関連情報を検索し、見つかったファイルを読み込み** - - 既存のコードスタイルやベストプラクティスを検索し、スタイルガイドをReadツールで読み込み - - プロジェクト全体のアーキテクチャパターンを特定し、設計文書をReadツールで読み込み - - 再利用可能なユーティリティ関数やコンポーネントを確認し、関連ファイルをReadツールで読み込み +3. **Task tool (subagent_type: Explore, thoroughness: quick) を使用してリファクタリング関連情報を探索** + - 既存のコードスタイルやベストプラクティスを探索 + - プロジェクト全体のアーキテクチャパターンを特定 + - 再利用可能なユーティリティ関数やコンポーネントを確認 4. **関連する外部ファイルを直接読み込み** - 関連する設計文書やタスクファイルも必要に応じて読み込み @@ -65,6 +65,19 @@ Refactorフェーズファイル=./docs/implements/{要件名}/{{task_id}}/{feat - 【安全性確保】: 変更による機能破綻の防止 - 【実行方法】: Taskツールを使用してテストを実行し、結果を詳細に分析 +- **テスト実行時間のチェック** + - 【長時間テストの検出】: 2秒以上かかるテストがないか確認 + - 【警告表示】: 遅いテストが見つかった場合は以下を表示 + ``` + ⚠️ 遅いテストが検出されました（2秒以上） + + 詳細な分析とリファクタリング提案が必要な場合: + `/tsumiki:dcs:test-performance-analysis` を実行してください + + テスト実行速度の改善パターン: + `/tsumiki:test-optimization-patterns` を実行してください + ``` + - **コード・テスト除外チェック** - 【.gitignore確認】: 本来確認対象のコードファイルが除外されていないかチェック - 【テスト除外確認】: `describe.skip`, `it.skip`, `test.skip`等でテストが無効化されていないかチェック @@ -121,7 +134,11 @@ Refactorフェーズファイル=./docs/implements/{要件名}/{{task_id}}/{feat - **各改善後にテストを実行** - 【継続的検証】: 改善の度に動作確認 - 【早期発見】: 問題の早期発見と修正 - - 【実行方法】: Taskツールを使用してテストを実行し、改善の影響を確認 + - 【選択的実行】: 変更したファイルに関連するテストのみを実行（高速） + - Jest: `npm test -- --findRelatedTests <変更ファイル>` + - pytest: `pytest <関連テストファイル>` + - 特定のテストスイート: `npm test -- <テストパターン>` + - **注意**: 全体のテスト実行は verify-complete フェーズで実施 - **テストが失敗したら即座に戻す** - 【迅速復旧】: 問題発生時の素早い対応 diff --git a/commands/tdd-requirements.md b/commands/tdd-requirements.md index be4b3e0..b77bbeb 100644 --- a/commands/tdd-requirements.md +++ b/commands/tdd-requirements.md @@ -1,7 +1,7 @@ --- description: TDD開発の要件整理を行います。機能要件を明確化し、テスト駆動開発のための準備を行います。 allowed-tools: Read, Glob, Grep, Task, Write, TodoWrite, Edit -argument-hint: [要件名] [TASK-ID] +argument-hint: "[要件名] [TASK-ID]" --- TDD開発の要件整理を実施し、EARS要件定義書・設計文書を参照しながら機能仕様を明確化します。信頼性レベルを示しながら要件定義を作成します。 @@ -16,6 +16,8 @@ TDD開発の要件整理を実施し、EARS要件定義書・設計文書を参 タスクファイル2=./docs/tasks/{要件名}-phase*.md タスクoverviewファイル1=./docs/tasks/{要件名}/overview.md タスクoverviewファイル2=./docs/tasks/{要件名}-overview.md +出力ファイル=./docs/implements/{要件名}/{{task_id}}/{feature_name}-requirements.md + # step @@ -40,7 +42,7 @@ TDD開発の要件整理を実施し、EARS要件定義書・設計文書を参 - の内容を context の情報で埋めて、要件定義書を直接作成する - 読み込んだコンテキスト情報（タスクノート、追加ルール等）を活用 - 信頼性レベル（🔵🟡🔴）を各項目に記載 - - Write ツールを使用して出力ファイルに保存 + - Write ツールを使用して 出力ファイル に保存 - 作成した要件定義書の内容について、品質判定基準に基づいて以下を評価： - 要件の曖昧さの有無 @@ -227,5 +229,5 @@ TDD開発の要件整理を実施し、EARS要件定義書・設計文書を参 上記のフォーマットに従って、要件定義書を作成してください。 -必ず Write ツールを使用して、{{出力ファイル名}} に結果を保存してください。 +必ず Write ツールを使用して、{{出力ファイル}} に結果を保存してください。 diff --git a/commands/tdd-tasknote.md b/commands/tdd-tasknote.md index 7997a9c..76fa8a7 100644 --- a/commands/tdd-tasknote.md +++ b/commands/tdd-tasknote.md @@ -1,7 +1,7 @@ --- description: TDD開発のコンテキスト情報を収集してノートにまとめます。技術スタック、追加ルール、関連ファイルの情報を整理します。 allowed-tools: Read, Glob, Grep, Task, Write, TodoWrite, Edit -argument-hint: [要件名] [TASK-ID] +argument-hint: "[要件名] [TASK-ID]" --- TDD開発の前にコンテキスト情報を収集し、開発に必要な情報をノートファイルにまとめます。 @@ -17,9 +17,7 @@ noteファイル="./docs/implements/{要件名}/{{task_id}}/note.md" # step - $ARGUMENTS がない場合、「引数に要件名とTASK-IDを指定してください（例: ユーザー認証機能 TASK-0001）」と言って終了する -- {{noteファイル}} が既にある場合、存在しているので更新して良いかをユーザに確認する。 - - ユーザが良いといった場合は再作成をする。 - - ユーザが更新しないとした場合は終了する +- {{noteファイル}} が既にある場合、「すでに完了しています」といって終了する - 開発コンテキストを収集する： **追加ルールの読み込み** - `AGENTS.md` ファイルが存在する場合は読み込み @@ -28,14 +26,14 @@ noteファイル="./docs/implements/{要件名}/{{task_id}}/note.md" - `./docs/rule/tdd/green` ディレクトリが存在する場合は読み込み - 各ディレクトリ内のすべてのファイルを読み込み、追加ルールとして適用 - **@agent-symbol-searcher で実装関連情報を検索し、見つかったファイルを読み込み** + **Task tool (subagent_type: Explore, thoroughness: quick) を使用して実装関連情報を探索** - `./docs/spec/{要件名}-requirements.md`: 統合機能要件と関連文書へ - `./docs/spec/{要件名}-user-stories.md`: 詳細なユーザストーリー - `./docs/spec/{要件名}-acceptance-criteria.md`: 受け入れ基準とテスト項目 - `./docs/spec/{要件名}-*.md`: 受け入れ基準とテスト項目 - - 既存の類似機能やユーティリティ関数を検索し、該当ファイルをReadツールで読み込み - - 実装パターンやアーキテクチャガイドラインを特定し、設計文書をReadツールで読み込み - - 依存関係やインポートパスを確認し、関連ファイルをReadツールで読み込み + - 既存の類似機能やユーティリティ関数を探索 + - 実装パターンやアーキテクチャガイドラインを特定 + - 依存関係やインポートパスを確認 **関連ファイルを直接読み込み** - `./docs/implements/{要件名}/{{task_id}}/*.md` - taskに関係する全てのファイルを読み込み diff --git a/commands/tdd-testcases.md b/commands/tdd-testcases.md index 60f0180..4c44cad 100644 --- a/commands/tdd-testcases.md +++ b/commands/tdd-testcases.md @@ -1,7 +1,7 @@ --- description: TDD開発のためのテストケース洗い出しを行います。整理された要件に基づいて包括的なテストケースを特定します。 allowed-tools: Read, Glob, Grep, Task, Write, TodoWrite, Edit -argument-hint: [要件名] [TASK-ID] +argument-hint: "[要件名] [TASK-ID]" --- TDD開発のテストケース洗い出しを実施し、要件定義書を参照しながら網羅的なテストケースを作成します。信頼性レベルを示しながらテストケースを定義します。 @@ -13,7 +13,7 @@ TDD開発のテストケース洗い出しを実施し、要件定義書を参 要件名={{requirement_name}} 信頼性評価=[] 要件定義ファイル=./docs/implements/{要件名}/{{task_id}}/{feature_name}-requirements.md -既存テストケースファイル=./docs/implements/{要件名}/{{task_id}}/{feature_name}-testcases.md +出力ファイル=./docs/implements/{要件名}/{{task_id}}/{feature_name}-testcases.md タスクファイル1=./docs/tasks/{要件名}/{{task_id}}.md タスクファイル2=./docs/tasks/{要件名}-phase*.md タスクoverviewファイル1=./docs/tasks/{要件名}/overview.md @@ -50,10 +50,10 @@ TDD開発のテストケース洗い出しを実施し、要件定義書を参 - `./docs/rule/tdd/testcases` ディレクトリが存在する場合は読み込み - 各ディレクトリ内のすべてのファイルを読み込み、追加ルールとして適用 - **@agent-symbol-searcher でテスト関連情報を検索し、見つかったファイルを読み込み** - - 既存のテストパターンやテストケースを検索し、該当テストファイルをReadツールで読み込み - - 類似機能のテスト方法やモック戦略を特定し、関連ファイルをReadツールで読み込み - - テストフレームワークの使用方法を確認し、設定ファイルをReadツールで読み込み + **Task tool (subagent_type: Explore, thoroughness: quick) を使用してテスト関連情報を探索** + - 既存のテストパターンやテストケースを探索 + - 類似機能のテスト方法やモック戦略を特定 + - テストフレームワークの使用方法を確認 **関連ファイルを直接読み込み** - `./docs/implements/{要件名}/{{task_id}}/{feature_name}-memo.md` - 既存の開発履歴を確認 @@ -68,7 +68,7 @@ TDD開発のテストケース洗い出しを実施し、要件定義書を参 - の内容を context の情報で埋めて、テストケースを直接作成する - 読み込んだコンテキスト情報（タスクノート、要件定義、追加ルール等）を活用 - 信頼性レベル（🔵🟡🔴）を各テストケースに記載 - - Write ツールを使用して出力ファイルに保存（既存ファイルがある場合は追記） + - Write ツールを使用して 出力ファイル に保存（既存ファイルがある場合は追記） - 作成したテストケースの内容について、品質判定基準に基づいて以下を評価： - テストケース分類: 正常系・異常系・境界値が網羅されている @@ -333,6 +333,6 @@ afterEach(() => { 上記のフォーマットに従って、テストケースを作成してください。 -必ず Write ツールを使用して、{{出力ファイル名}} に結果を保存してください。 +必ず Write ツールを使用して、{{出力ファイル}} に結果を保存してください。 既存ファイルがある場合は、内容を追記してください。 diff --git a/commands/tdd-todo.md b/commands/tdd-todo.md index 0e5e935..7428979 100644 --- a/commands/tdd-todo.md +++ b/commands/tdd-todo.md @@ -26,14 +26,14 @@ description: タスクファイルから実装可能なTODOリストを作成し - 各ディレクトリ内のすべてのファイルを読み込み、追加ルールとして適用 2. **要件定義文書の分析** - - @agent-symbol-searcher で関連要件・設計文書を検索 + - Task tool (subagent_type: Explore, thoroughness: quick) を使用して関連要件・設計文書を探索 - EARS記法による要件の理解 - ユーザストーリーと価値の把握 - 機能要件と非機能要件の確認 - Edgeケースと受け入れ基準の理解 3. **設計文書の分析** - - @agent-symbol-searcher で既存アーキテクチャパターンを検索 + - Task tool (subagent_type: Explore, thoroughness: quick) を使用して既存アーキテクチャパターンを探索 - アーキテクチャ設計の全体像を把握 - データベーススキーマの構造を理解 - APIエンドポイントの仕様を確認 @@ -41,7 +41,7 @@ description: タスクファイルから実装可能なTODOリストを作成し - データフローの設計を理解 4. **タスクファイルの分析** - - @agent-symbol-searcher で関連タスクIDや完了状態を検索 + - Task tool (subagent_type: Explore, thoroughness: quick) を使用して関連タスクIDや完了状態を探索 - 全体のフェーズ構造を把握 - タスクID別の実装内容を確認 - 依存関係と実行順序を理解 diff --git a/commands/tdd-verify-complete.md b/commands/tdd-verify-complete.md index 2b1deca..9f940a4 100644 --- a/commands/tdd-verify-complete.md +++ b/commands/tdd-verify-complete.md @@ -1,7 +1,7 @@ --- description: TDD開発でテストケースの実装が完全に完了しているかを検証します。すべてのテストが通ることを確認し、開発完了を保証します。 allowed-tools: Read, Glob, Grep, Task, Write, Edit, TodoWrite -argument-hint: [要件名] [TASK-ID] +argument-hint: "[要件名] [TASK-ID]" --- TDD開発でテストケースの実装が完全に完了しているかを検証します。 @@ -45,10 +45,10 @@ Refactorフェーズファイル=./docs/implements/{要件名}/{{task_id}}/{feat - `./docs/rule/tdd/verify-complete` ディレクトリが存在する場合は読み込み - 各ディレクトリ内のすべてのファイルを読み込み、追加ルールとして適用 -3. **@agent-symbol-searcher で検証関連情報を検索し、見つかったファイルを読み込み** - - 完了予定のテストケースや機能を検索し、該当ファイルをReadツールで読み込み - - 既存のテストカバレッジや品質基準を確認し、関連ファイルをReadツールで読み込み - - 実装完了タスクのマーキングパターンを特定し、タスクファイルをReadツールで読み込み +3. **Task tool (subagent_type: Explore, thoroughness: quick) を使用して検証関連情報を探索** + - 完了予定のテストケースや機能を探索 + - 既存のテストカバレッジや品質基準を確認 + - 実装完了タスクのマーキングパターンを特定 4. **元タスクファイルを直接読み込み** - `docs/tasks/{taskfile}.md` - タスクの完了状態を確認 @@ -61,6 +61,23 @@ Refactorフェーズファイル=./docs/implements/{要件名}/{{task_id}}/{feat - **必須**: @task で全ての既存テストが成功していることを確認 - **テスト失敗がある場合**: memoファイルに記載し、後の工程で修正対応することを記録 - **この工程では修正禁止**: テスト失敗を発見してもここでは修正しない +- **テスト実行時間の確認**: + - 総実行時間が30秒以上の場合は記録 + - 2秒以上かかるテストファイルを特定して記録 + - 遅いテストがある場合は以下を推奨として記録: + ``` + 📝 推奨事項: テスト実行速度の改善 + + 総実行時間: XX秒（30秒以上） + 遅いテストファイル: + - test/user.test.js: 15秒 + - test/integration.test.js: 8秒 + + 改善方法: + 1. `/tsumiki:dcs:test-performance-analysis` で詳細分析 + 2. `/tsumiki:test-optimization-patterns` でパターンを確認 + 3. 次のTDDサイクルで段階的に改善 + ``` - テスト状態を記録し、step4 に進む ## step4: 実装状況の分析 diff --git a/commands/test-optimization-patterns.md b/commands/test-optimization-patterns.md new file mode 100644 index 0000000..08a7d57 --- /dev/null +++ b/commands/test-optimization-patterns.md @@ -0,0 +1,743 @@ +--- +description: テスト実行速度を改善するためのリファクタリングパターンとベストプラクティス集 +--- + +# テスト最適化パターン集 + +テスト実行速度を改善するためのリファクタリングパターンとベストプラクティスをまとめたドキュメントです。 + +## パターン一覧 + +| パターン | 効果 | 難易度 | リスク | +|---------|------|--------|--------| +| 1. データベーストランザクション | ★★★★★ | 低 | 低 | +| 2. ファイルI/Oのモック化 | ★★★★★ | 低 | 低 | +| 3. 外部APIのモック化 | ★★★★★ | 中 | 低 | +| 4. beforeEach → beforeAll | ★★★☆☆ | 低 | 中 | +| 5. 非同期待機の最適化 | ★★★☆☆ | 中 | 低 | +| 6. テストデータファクトリー | ★★☆☆☆ | 中 | 低 | +| 7. テストの粒度見直し | ★★★☆☆ | 高 | 中 | +| 8. 並列実行可能な設計 | ★★★☆☆ | 中 | 中 | + +--- + +## パターン1: データベーストランザクション + +### 概要 + +各テストでデータベースのクリア・再投入を行うと、I/O待機時間が累積して遅くなります。トランザクションを使ってロールバックすることで、物理的なDELETE/INSERTを避けて高速化できます。 + +### 適用条件 + +- ✅ beforeEach でデータのクリア・再投入を行っている +- ✅ テストごとにクリーンな状態が必要 +- ✅ データベースがトランザクションをサポート + +### Before（遅い実装） + +```javascript +describe('User API', () => { + beforeEach(async () => { + // 毎回DELETE・INSERT（遅い） + await db.query('DELETE FROM users'); + await db.query('DELETE FROM posts'); + await db.query('INSERT INTO users (id, name) VALUES (1, "Test")'); + await db.query('INSERT INTO posts (id, user_id, title) VALUES (1, 1, "Post")'); + }); + + afterEach(async () => { + await db.disconnect(); + }); + + it('should get user', async () => { + const user = await getUserById(1); + expect(user.name).toBe('Test'); + }); + + it('should get posts', async () => { + const posts = await getPostsByUserId(1); + expect(posts).toHaveLength(1); + }); +}); +``` + +### After（高速実装） + +```javascript +describe('User API', () => { + let transaction; + + beforeEach(async () => { + // トランザクション開始 + transaction = await db.transaction(); + + // データ準備（トランザクション内） + await transaction.query('INSERT INTO users (id, name) VALUES (1, "Test")'); + await transaction.query('INSERT INTO posts (id, user_id, title) VALUES (1, 1, "Post")'); + }); + + afterEach(async () => { + // ロールバック（高速） + await transaction.rollback(); + }); + + it('should get user', async () => { + const user = await getUserById(1); + expect(user.name).toBe('Test'); + }); + + it('should get posts', async () => { + const posts = await getPostsByUserId(1); + expect(posts).toHaveLength(1); + }); +}); +``` + +### 期待される効果 + +- **実行時間**: 80-95%削減 +- **具体例**: 15秒 → 2秒 + +### 注意点 + +- トランザクション内のデータは他のトランザクションから見えない（分離レベルによる） +- 外部キー制約などは正しく動作する +- ロールバックは物理削除より圧倒的に高速 + +--- + +## パターン2: ファイルI/Oのモック化 + +### 概要 + +実ファイルへの読み書きはディスクI/Oが発生して遅くなります。メモリ上の仮想ファイルシステムやモックを使うことで高速化できます。 + +### 適用条件 + +- ✅ fs.readFile, fs.writeFile などの実ファイル操作を行っている +- ✅ ファイル内容の検証が目的（実際のファイルシステムの動作確認が不要） + +### Before（遅い実装） + +```javascript +it('should save config', async () => { + const config = { port: 3000, host: 'localhost' }; + + // 実ファイルに書き込み（遅い） + await fs.writeFile('./config.json', JSON.stringify(config)); + + // 実ファイルから読み込み（遅い） + const saved = await loadConfig('./config.json'); + + expect(saved.port).toBe(3000); + + // クリーンアップ + await fs.unlink('./config.json'); +}); +``` + +### After（高速実装） + +**方法A: mock-fs を使用** + +```javascript +const mockFs = require('mock-fs'); + +beforeEach(() => { + // メモリ上に仮想ファイルシステムを作成 + mockFs({ + '/tmp': {}, + }); +}); + +afterEach(() => { + mockFs.restore(); +}); + +it('should save config', async () => { + const config = { port: 3000, host: 'localhost' }; + + // メモリ上のファイルシステムに書き込み（高速） + await saveConfig('/tmp/config.json', config); + const saved = await loadConfig('/tmp/config.json'); + + expect(saved.port).toBe(3000); + // クリーンアップ不要（afterEachで自動） +}); +``` + +**方法B: jest.mock を使用** + +```javascript +jest.mock('fs/promises', () => ({ + readFile: jest.fn(), + writeFile: jest.fn(), +})); + +const fs = require('fs/promises'); + +it('should save config', async () => { + const config = { port: 3000, host: 'localhost' }; + + fs.writeFile.mockResolvedValue(undefined); + fs.readFile.mockResolvedValue(JSON.stringify(config)); + + await saveConfig('./config.json', config); + + expect(fs.writeFile).toHaveBeenCalledWith( + './config.json', + JSON.stringify(config) + ); +}); +``` + +### 期待される効果 + +- **実行時間**: 90-99%削減 +- **具体例**: 8秒 → 0.3秒 + +### 注意点 + +- ファイルシステムの実際の動作（権限、シンボリックリンク等）は検証できない +- そのような検証が必要な場合はE2Eテストとして分離 + +--- + +## パターン3: 外部APIのモック化 + +### 概要 + +外部APIへの実際のHTTPリクエストはネットワーク遅延とサーバー処理時間がかかります。モックを使うことで高速化できます。 + +### 適用条件 + +- ✅ fetch, axios などで外部APIを呼び出している +- ✅ APIのレスポンス処理ロジックのテストが目的 +- ✅ 実際のAPI動作確認は不要 + +### Before（遅い実装） + +```javascript +it('should fetch user data', async () => { + // 実際のAPI呼び出し（遅い） + const user = await fetchUser(1); + expect(user.name).toBe('John'); +}); +``` + +### After（高速実装） + +**方法A: jest.mock でfetchをモック** + +```javascript +global.fetch = jest.fn(); + +beforeEach(() => { + fetch.mockClear(); +}); + +it('should fetch user data', async () => { + // モックのレスポンスを設定（高速） + fetch.mockResolvedValue({ + ok: true, + json: async () => ({ id: 1, name: 'John' }), + }); + + const user = await fetchUser(1); + + expect(user.name).toBe('John'); + expect(fetch).toHaveBeenCalledWith('https://api.example.com/users/1'); +}); +``` + +**方法B: MSW (Mock Service Worker) を使用** + +```javascript +import { rest } from 'msw'; +import { setupServer } from 'msw/node'; + +const server = setupServer( + rest.get('https://api.example.com/users/:id', (req, res, ctx) => { + return res( + ctx.status(200), + ctx.json({ id: Number(req.params.id), name: 'John' }) + ); + }) +); + +beforeAll(() => server.listen()); +afterEach(() => server.resetHandlers()); +afterAll(() => server.close()); + +it('should fetch user data', async () => { + const user = await fetchUser(1); + expect(user.name).toBe('John'); +}); + +it('should handle API errors', async () => { + server.use( + rest.get('https://api.example.com/users/:id', (req, res, ctx) => { + return res(ctx.status(404)); + }) + ); + + await expect(fetchUser(999)).rejects.toThrow('User not found'); +}); +``` + +### 期待される効果 + +- **実行時間**: 90-99%削減 +- **具体例**: 5秒 → 0.1秒 + +### 注意点 + +- 実際のAPIの動作（認証、レート制限等）は検証できない +- API統合テストはE2Eテストとして分離 + +--- + +## パターン4: beforeEach → beforeAll + +### 概要 + +テストデータを変更しない読み取り専用のテストでは、beforeAllでデータを一度だけ準備すれば高速化できます。 + +### 適用条件 + +- ✅ 複数のテストで同じデータを使用 +- ✅ データを変更しない（読み取り専用） +- ✅ テストの独立性が保たれる + +### Before（遅い実装） + +```javascript +describe('User queries', () => { + let testUser; + + beforeEach(async () => { + // 各テストの前に生成（遅い） + testUser = await createComplexTestUser(); + }); + + afterEach(async () => { + await deleteUser(testUser.id); + }); + + // 全て読み取り専用のテスト + it('should get user by id', async () => { + const user = await getUserById(testUser.id); + expect(user.name).toBe(testUser.name); + }); + + it('should get user by email', async () => { + const user = await getUserByEmail(testUser.email); + expect(user.id).toBe(testUser.id); + }); +}); +``` + +### After（高速実装） + +```javascript +describe('User queries', () => { + let testUser; + + beforeAll(async () => { + // 一度だけ生成（高速） + testUser = await createComplexTestUser(); + }); + + afterAll(async () => { + await deleteUser(testUser.id); + }); + + it('should get user by id', async () => { + const user = await getUserById(testUser.id); + expect(user.name).toBe(testUser.name); + }); + + it('should get user by email', async () => { + const user = await getUserByEmail(testUser.email); + expect(user.id).toBe(testUser.id); + }); +}); +``` + +### 期待される効果 + +- **実行時間**: テスト数に比例して削減 +- **具体例**: 10秒（5テスト × 2秒） → 2.5秒（セットアップ2秒 + テスト0.5秒） + +### 注意点 + +- **重要**: データを変更するテストには適用できない +- テストが独立していることを確認 +- 並列実行時は他のテストファイルとの競合に注意 + +--- + +## パターン5: 非同期待機の最適化 + +### 概要 + +固定時間のsleep/waitは最悪ケースを想定した長い時間になりがちです。条件ベースの待機に変更することで、実際に必要な最小時間だけ待機できます。 + +### 適用条件 + +- ✅ setTimeout, sleep などの固定待機時間を使用している +- ✅ 特定の条件が満たされるのを待つ処理 + +### Before（遅い実装） + +```javascript +it('should process async task', async () => { + startAsyncTask(); + + // 5秒待機（実際には1秒で完了していても待つ） + await new Promise(resolve => setTimeout(resolve, 5000)); + + const result = await getTaskResult(); + expect(result.status).toBe('completed'); +}); +``` + +### After（高速実装） + +```javascript +// ヘルパー関数 +async function waitFor(condition, options = {}) { + const { timeout = 5000, interval = 100 } = options; + const startTime = Date.now(); + + while (Date.now() - startTime < timeout) { + if (await condition()) { + return; + } + await new Promise(resolve => setTimeout(resolve, interval)); + } + + throw new Error('Timeout waiting for condition'); +} + +it('should process async task', async () => { + startAsyncTask(); + + // 条件が満たされるまで待機（最小時間） + await waitFor(async () => { + const result = await getTaskResult(); + return result.status === 'completed'; + }); + + const result = await getTaskResult(); + expect(result.status).toBe('completed'); +}); +``` + +### 期待される効果 + +- **実行時間**: 50-80%削減 +- **具体例**: 5秒 → 1秒（実際の完了時間） + +### 注意点 + +- タイムアウト時間は適切に設定（CI環境では長めに） +- ポーリング間隔を短くしすぎるとCPU負荷が高くなる + +--- + +## パターン6: テストデータファクトリー + +### 概要 + +テストデータの準備で不要な詳細まで定義すると時間がかかります。ファクトリー関数で必要最小限のデータを生成することで高速化できます。 + +### 適用条件 + +- ✅ 複雑なデータ構造を毎回定義している +- ✅ テストごとに異なる一部の値だけが必要 + +### Before（遅い実装） + +```javascript +it('should calculate total', () => { + const order = { + id: 1, + createdAt: new Date(), + updatedAt: new Date(), + user: { + id: 1, + name: 'John', + email: 'john@example.com', + address: { + street: '123 Main St', + city: 'Tokyo', + country: 'Japan', + postalCode: '100-0001', + }, + preferences: { + language: 'ja', + currency: 'JPY', + timezone: 'Asia/Tokyo', + }, + }, + items: [ + { + id: 1, + name: 'Product A', + description: 'Description A', + price: 100, + quantity: 2, + taxRate: 0.1, + category: 'Electronics', + }, + { + id: 2, + name: 'Product B', + description: 'Description B', + price: 200, + quantity: 1, + taxRate: 0.1, + category: 'Books', + }, + ], + shippingAddress: { /* ... */ }, + billingAddress: { /* ... */ }, + paymentMethod: { /* ... */ }, + }; + + expect(calculateTotal(order)).toBe(400); +}); +``` + +### After（高速実装） + +```javascript +// ファクトリー関数 +function createOrder(overrides = {}) { + return { + items: [], + ...overrides, + }; +} + +function createItem(overrides = {}) { + return { + price: 0, + quantity: 1, + ...overrides, + }; +} + +it('should calculate total', () => { + // 必要最小限のデータのみ + const order = createOrder({ + items: [ + createItem({ price: 100, quantity: 2 }), + createItem({ price: 200, quantity: 1 }), + ], + }); + + expect(calculateTotal(order)).toBe(400); +}); +``` + +### 期待される効果 + +- **実行時間**: 30-50%削減（可読性向上も） +- **具体例**: 0.5秒 → 0.3秒 + +### 注意点 + +- ファクトリー関数は共通ファイルに定義して再利用 +- デフォルト値は最も一般的なケースを設定 + +--- + +## パターン7: テストの粒度見直し + +### 概要 + +統合テストとして複数の処理を1つのテストで行うと時間がかかります。ユニットテストに分割することで個別の実行時間は短縮できます。 + +### 適用条件 + +- ✅ 1つのテストで複数の機能を検証している +- ✅ 各機能は独立してテスト可能 + +### Before（遅い実装） + +```javascript +// 統合テスト（10秒） +it('should complete user registration flow', async () => { + const user = await registerUser({ email: 'test@example.com' }); + await sendVerificationEmail(user); + await verifyEmail(user.verificationToken); + await setupUserProfile(user); + await sendWelcomeEmail(user); + + const savedUser = await getUser(user.id); + expect(savedUser.verified).toBe(true); + expect(savedUser.profile).toBeDefined(); +}); +``` + +### After（高速実装） + +```javascript +// ユニットテストに分割（各0.5秒） +describe('User Registration', () => { + it('should register user', async () => { + const user = await registerUser({ email: 'test@example.com' }); + expect(user.email).toBe('test@example.com'); + }); + + it('should send verification email', async () => { + const mockEmail = jest.fn(); + await sendVerificationEmail({ email: 'test@example.com' }, mockEmail); + expect(mockEmail).toHaveBeenCalled(); + }); + + it('should verify email', async () => { + const user = { verified: false }; + await verifyEmail(user, 'valid-token'); + expect(user.verified).toBe(true); + }); +}); + +// E2Eテスト（別ファイル: test/e2e/） +describe('User Registration E2E', () => { + it('should complete entire flow', async () => { + // verify-complete フェーズでのみ実行 + }); +}); +``` + +### 期待される効果 + +- **開発時の実行時間**: 大幅削減（ユニットテストのみ実行） +- **CI全体の実行時間**: 変化なし（統合テストも実行） + +### 注意点 + +- 統合テスト・E2Eテストは依然として重要 +- テストの階層化（unit, integration, e2e）を明確に + +--- + +## パターン8: 並列実行可能な設計 + +### 概要 + +グローバル状態に依存するテストは順次実行する必要がありますが、独立したテストは並列実行できます。 + +### 適用条件 + +- ✅ テストがグローバル状態を共有している +- ✅ テストの順序に依存している + +### Before（遅い実装） + +```javascript +// グローバル状態に依存（並列実行不可） +let currentUser = null; + +it('test 1', async () => { + currentUser = { id: 1 }; + const result = await processUser(currentUser); + expect(result.id).toBe(1); +}); + +it('test 2', async () => { + currentUser = { id: 2 }; + const result = await processUser(currentUser); + expect(result.id).toBe(2); +}); +``` + +### After（高速実装） + +```javascript +// 各テストが独立（並列実行可能） +it('test 1', async () => { + const user = { id: 1 }; + const result = await processUser(user); + expect(result.id).toBe(1); +}); + +it('test 2', async () => { + const user = { id: 2 }; + const result = await processUser(user); + expect(result.id).toBe(2); +}); +``` + +### 期待される効果 + +- **実行時間**: 並列実行数に応じて削減（CPUコア数が上限） +- **具体例**: 10秒（10テスト × 1秒） → 2.5秒（4並列） + +### 注意点 + +- データベーステストでは分離レベルに注意 +- CI環境のリソースに応じて並列数を調整 + +--- + +## テスト階層化のベストプラクティス + +``` +test/ +├── unit/ # ユニットテスト（高速・常時実行） +│ ├── utils/ +│ └── services/ +├── integration/ # 統合テスト（中速・リファクタ時実行） +│ ├── api/ +│ └── database/ +└── e2e/ # E2Eテスト（低速・最終検証時実行） + └── scenarios/ +``` + +### package.json設定例 + +```json +{ + "scripts": { + "test": "jest", + "test:unit": "jest test/unit", + "test:integration": "jest test/integration", + "test:e2e": "jest test/e2e --runInBand", + "test:watch": "jest --watch test/unit", + "test:all": "npm run test:unit && npm run test:integration && npm run test:e2e" + } +} +``` + +### 開発フローでの使い分け + +- **開発中（green/refactor）**: `npm run test:unit -- --findRelatedTests` +- **リファクタ完了後**: `npm run test:integration` +- **最終検証**: `npm run test:all` + +--- + +## まとめ + +### 優先度の高いパターン（まず試すべき） + +1. **データベーストランザクション** - 効果大・リスク低 +2. **ファイルI/Oのモック化** - 効果大・リスク低 +3. **外部APIのモック化** - 効果大・リスク低 + +### 次に検討すべきパターン + +4. **beforeEach → beforeAll** - 条件付きで有効 +5. **非同期待機の最適化** - 場合により効果大 +6. **テストデータファクトリー** - 可読性向上も + +### 慎重に検討すべきパターン + +7. **テストの粒度見直し** - 設計レベルの変更 +8. **並列実行可能な設計** - 既存コードの修正が必要 + +これらのパターンを組み合わせることで、テストスイート全体の実行時間を50-80%削減できます。