diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 79f8828..62b311f 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.6" + "version": "0.0.7" }, "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.6", + "version": "0.0.7", "author": { "name": "makoto kuroeda", "email": "kuroeda.makoto@classmethod.jp" diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 8c18ef1..6626e4c 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "tsumiki", - "version": "0.0.6", + "version": "0.0.7", "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", diff --git a/DCS_README.md b/DCS_README.md new file mode 100644 index 0000000..9886204 --- /dev/null +++ b/DCS_README.md @@ -0,0 +1,337 @@ +# DCS ドキュメント + +## 全体概要 + +DCSは、ソフトウェア開発の各フェーズにおける様々な分析・計画作業を支援するコマンドスイートです。各コマンドは対話的に必要な情報を収集し、`.dcs/` ディレクトリ配下に構造化された分析結果を出力します。 + +### 開発フェーズ別コマンド一覧 + +#### **企画・要件定義フェーズ** +- `/tsumiki:dcs:feature-rubber-duck` - アイデア整理とPRD作成 + +#### **設計・分析フェーズ** +- `/tsumiki:dcs:sequence-diagram-analysis` - シーケンス図作成 +- `/tsumiki:dcs:state-transition-analysis` - 状態遷移分析 +- `/tsumiki:dcs:impact-analysis` - 影響範囲分析 + +#### **実装計画フェーズ** +- `/tsumiki:dcs:incremental-dev` - 増分開発計画 + +#### **デバッグ・保守フェーズ** +- `/tsumiki:dcs:bug-analysis` - バグ原因分析 +- `/tsumiki:dcs:performance-analysis` - 性能問題調査 + +--- + +## コマンド詳細 + +### 1. feature-rubber-duck + +**用途** +曖昧なアイデアや要望を対話を通じて整理し、実現可能なPRD（Product Requirements Document）を作成します。 + +**概要** +ラバーダック法のように、対話を重ねながら機能アイデアを具体化していきます。コードベース調査、技術検証、要件の具体化を段階的に進め、最終的に実装可能なPRDを作成します。 + +**使うタイミング** +- 新機能のアイデアを整理したいとき +- 機能要件が曖昧で具体化が必要なとき +- 既存コードベースへの組み込み方を検討したいとき +- 技術的実現可能性を検証しながら要件を詰めたいとき + +**主な出力ファイル** +``` +.dcs/{{timestamp}}_{{feature_name}}/ +├── index.md # セッション情報のインデックス +├── conversation.md # 対話履歴 +├── context.md # 収集したコンテキスト情報 +├── research.md # 調査結果（コードベース、技術検証など） +└── prd.md # 最終的なPRD（Product Requirements Document） +``` + +**特徴** +- 最大10イテレーションの対話セッション +- コードベース調査とWeb検索を活用した技術検証 +- 段階的な要件の具体化 +- 実装可能性を考慮したPRD作成 + +--- + +### 2. sequence-diagram-analysis + +**用途** +指定された機能のシーケンス図をmermaid形式で作成します。 + +**概要** +機能の処理フローを視覚化し、コンポーネント間の相互作用を明確にします。コードベースを分析し、関数呼び出し、データフロー、外部システムとの連携を図示します。 + +**使うタイミング** +- 複雑な処理フローを理解したいとき +- 既存機能の動作を可視化したいとき +- リファクタリングやデバッグの前にフローを把握したいとき +- ドキュメント作成や設計レビューのため + +**主な出力ファイル** +``` +.dcs/{{timestamp}}_{{feature_name}}/ +├── index.md # 分析情報のインデックス +├── tmp/ # 一時調査結果（コンテキスト削減用） +│ ├── initial_survey.md +│ └── detailed_survey.md +└── sequence_diagram.md # Mermaidシーケンス図とフロー説明 +``` + +**特徴** +- 一時ファイルを活用したコンテキスト削減 +- 複数シナリオ（正常系・異常系）のサポート +- 詳細レベルの調整可能（概要・詳細・実装レベル） +- Mermaid形式での出力 + +--- + +### 3. state-transition-analysis + +**用途** +対象データの状態遷移に関わる全ての機能を特定し、状態遷移フロー、関連データとの依存関係、リスク評価を提供します。 + +**概要** +エンティティやリソースの状態管理を包括的に分析し、状態遷移図、遷移表、機能別分析、データ依存関係、リスク評価を作成します。 + +**使うタイミング** +- 状態管理ロジックを理解したいとき +- ワークフローや承認フローを可視化したいとき +- データの状態変更に関わる機能を一覧化したいとき +- 状態遷移の一貫性やリスクを評価したいとき + +**主な出力ファイル** +``` +.dcs/{{timestamp}}_{{data_name}}/ +├── index.md # 分析情報のインデックス +├── summary.md # 分析サマリー +├── diagram.md # Mermaid状態遷移図 +├── transitions.md # 状態遷移表 +├── functions.md # 機能別分析 +├── dependencies.md # データ依存関係分析 +├── risks.md # リスク評価 +└── recommendations.md # 推奨事項 +``` + +**特徴** +- 状態フィールドの自動検出 +- Mermaid状態遷移図の生成 +- 網羅的な機能特定 +- 関連データの依存関係分析 +- リスク評価と推奨事項 + +--- + +### 4. impact-analysis + +**用途** +変更対象の影響範囲を分析し、修正が必要なファイルとリスク評価を提供します。 + +**概要** +ファイル、関数、クラス、または自然言語で指定された変更対象について、影響を受ける全てのコード箇所を特定し、層別に整理します。リスク評価と推奨事項も提供します。 + +**使うタイミング** +- コード変更前に影響範囲を把握したいとき +- リファクタリングの影響を評価したいとき +- API変更やモデル変更の影響を調査したいとき +- レビューやテスト計画の策定時 + +**主な出力ファイル** +``` +.dcs/{{timestamp}}_{{target_name}}/ +├── index.md # 分析情報のインデックス +├── summary.md # 全体サマリー +├── core.md # コア層の影響 +├── api.md # API層の影響 +├── service.md # サービス層の影響 +├── data.md # データ層の影響 +├── ui.md # UI層の影響 +├── test.md # テストへの影響 +├── config.md # 設定ファイルへの影響 +├── other.md # その他の影響 +├── external.md # 外部システムへの影響 +├── recommendations.md # 推奨事項 +└── details.md # 詳細情報 +``` + +**特徴** +- 層別の影響範囲分析 +- リスクレベルの評価 +- 修正の優先順位付け +- テスト戦略の提案 + +--- + +### 5. incremental-dev + +**用途** +増分開発の計画を立案し、実装方法毎のPRD（Product Requirements Document）を作成します。 + +**概要** +開発対象を分析し、初期調査から追加調査を経て、複数の実装アプローチを提示します。各アプローチについて詳細なPRDを作成し、段階的な実装計画を立案します。 + +**使うタイミング** +- 新機能の実装計画を立てたいとき +- 複数の実装アプローチを比較検討したいとき +- 段階的なリリース計画を作成したいとき +- 既存システムへの機能追加を計画するとき + +**主な出力ファイル** +``` +.dcs/{{timestamp}}_{{feature_name}}/ +├── index.md # 分析情報のインデックス +├── survey_summary.md # 初期調査サマリー +├── existing_impl.md # 既存実装調査 +├── tech_stack.md # 技術スタック +├── dependencies.md # 依存関係分析 +├── complexity.md # 複雑度評価 +├── constraints.md # 課題と制約 +├── additional_research/ # 追加調査結果 +│ └── {{research_topic}}.md +└── approaches/ # 実装アプローチ毎のPRD + ├── approach_1_{{name}}.md + ├── approach_2_{{name}}.md + └── approach_3_{{name}}.md +``` + +**特徴** +- 初期調査での包括的な情報収集 +- 複数の実装アプローチの提示 +- 各アプローチの詳細PRD作成 +- 段階的な実装計画 +- 500行以内のファイル分割 + +--- + +### 6. bug-analysis + +**用途** +バグの原因を特定するための詳細分析を実施します。 + +**概要** +バグの発生経緯や症状から原因を特定し、修正方針を提示します。ソースコードを詳細に分析し、段階的に原因を絞り込みます。初期調査、処理フロー分析、根本原因分析を経て、最終レポートを作成します。 + +**使うタイミング** +- バグの原因が不明なとき +- 複雑な不具合を調査したいとき +- 再現性の低いバグを分析したいとき +- 根本原因を特定して恒久対策を立てたいとき + +**主な出力ファイル** +``` +.dcs/{{timestamp}}_{{bug_name}}/ +├── index.md # 分析情報のインデックス +├── initial_investigation.md # 初期調査結果 +├── flow_analysis.md # 処理フロー分析 +├── root_cause_analysis.md # 根本原因分析 +└── final_report.md # 最終レポート +``` + +**特徴** +- 対話的な情報収集 +- 段階的な原因の絞り込み +- 処理フローの詳細分析 +- 根本原因の特定 +- 修正方針の提示 + +--- + +### 7. performance-analysis + +**用途** +性能問題の原因を調査します。 + +**概要** +性能問題の原因を特定するための包括的な調査を実施します。初期調査、詳細な原因分析、最終サマリーを段階的に作成し、性能問題の根本原因を明らかにします。 + +**使うタイミング** +- パフォーマンスが劣化しているとき +- レスポンスが遅い機能を調査したいとき +- スケーラビリティの問題を特定したいとき +- 最適化の優先順位を決めたいとき + +**主な出力ファイル** +``` +.dcs/{{timestamp}}_{{target_name}}/ +├── index.md # 分析情報のインデックス +├── initial.md # 初期調査結果 +├── causes.md # 原因分析 +└── recommendations.md # 推奨対応 +``` + +**特徴** +- TodoWriteによるタスク管理 +- 症状と発生状況の詳細ヒアリング +- 複数の原因候補の特定 +- 優先順位付けされた推奨対応 +- パフォーマンスボトルネックの特定 + +--- + +## 共通の出力構造 + +すべてのコマンドは `.dcs/` ディレクトリ配下にタイムスタンプ付きのディレクトリを作成し、以下のような構造で結果を出力します： + +``` +.dcs/ +└── {{timestamp}}_{{target_name}}/ + ├── index.md # 分析の概要とメタ情報 + ├── (各種分析結果ファイル) + └── (サブディレクトリ) +``` + +### タイムスタンプ形式 +`YYYYMMDD_HHMMSS` 形式（例: `20251030_143022`） + +### 重複防止 +同一タイムスタンプ・同一内容のディレクトリが存在する場合、末尾に連番が付与されます。 + +--- + +## 使用可能なツール + +各コマンドで使用可能なツールは、ファイルヘッダーの `allowed-tools` に記載されています： + +- **Read, Glob, Grep**: ファイル検索・読み込み +- **Task**: サブタスクの実行（コンテキスト削減） +- **Bash**: シェルコマンド実行 +- **AskUserQuestion**: 対話的な情報収集 +- **Write**: ファイル書き込み +- **TodoWrite**: タスク管理（performance-analysisで使用） +- **WebSearch, WebFetch**: Web検索・情報取得（feature-rubber-duckで使用） + +--- + +## 実行例 + +### バグ分析の実行 +``` +/tsumiki:dcs:bug-analysis カート内の商品合計金額が正しく計算されない +``` + +### 影響範囲分析の実行 +``` +/tsumiki:dcs:impact-analysis src/models/User.ts +``` + +### シーケンス図作成の実行 +``` +/tsumiki:dcs:sequence-diagram-analysis 注文確定処理 +``` + +### 増分開発計画の実行 +``` +/tsumiki:dcs:incremental-dev ユーザー認証機能の追加 +``` + +--- + +## 注意事項 + +1. **対話型コマンド**: すべてのコマンドは対話的に情報を収集します。質問に答えることで、より正確な分析が可能になります。 + +2. **出力ディレクトリ**: すべての出力は `.dcs/` ディレクトリに集約されます。gitignoreに追加することを推奨します。 + diff --git a/MANUAL.md b/MANUAL.md index ddc3277..bb82e0d 100644 --- a/MANUAL.md +++ b/MANUAL.md @@ -284,7 +284,7 @@ Kairoは各タスクに対して内部的にTDDコマンドを使用して以下 ## ディレクトリ構造 ``` -/projects/ai/test18/ +./ ├── .claude/ │ └── commands/ # Kairoコマンド ├── docs/ diff --git a/commands/auto-debug.md b/commands/auto-debug.md index bcc19c3..3981423 100644 --- a/commands/auto-debug.md +++ b/commands/auto-debug.md @@ -1,14 +1,534 @@ --- description: テストエラーを解消するための自動デバッグプロセス。全テストケースの確認からエラー原因の調査、修正まで段階的に実行し、テストケースの成功率向上を目指します。 --- - テストエラーを解消して。 -最初に全テストケースの確認をタスク実行してテストケースのエラーをtodoにセットして -各対象毎に以下の作業を実施して +#ultrathink + +# step +1. 最初に全テストケースの確認をタスク実行してテストケースのエラーをtodoにセットして +2. 各対象毎に以下の作業を実施して 　 - タスクで詳細にテストのエラー原因を調る - 　- 新たなタスクで /tsumiki:tdd-green を使って修正する -最後に全体のテストの成功率を確認してレポートして -ゴールはテストケースの成功数を上げること + 　- をTask ツールで直接実行して修正する。パラメータとしてエラーの原因を渡す +3. ゴールはテストケースの成功数を上げること +4. テストエラー解消後に をTask ツールで直接実行してリファクタリングを実施する +5. 最後に全体のテストの成功率を確認してレポートして + +# rule NEVER: テストのスキップ -NEVER: 既存でテストケースの削除 -#ultrathink +NEVER: 既存テストケースの削除 + +# info + + +# エラーの解消（実装） + +エラー解消を実行します。 + +## 事前準備 + +開発コンテキストの準備を行います： + +1. **追加ルールの読み込み** + - `AGENTS.md` ファイルが存在する場合は読み込み + - `docs/rule` ディレクトリが存在する場合は読み込み + - `docs/rule/tdd` ディレクトリが存在する場合は読み込み + - `docs/rule/tdd/green` ディレクトリが存在する場合は読み込み + - 各ディレクトリ内のすべてのファイルを読み込み、追加ルールとして適用 + +2. **@agent-symbol-searcher で実装関連情報を検索し、見つかったファイルを読み込み** + - 既存の類似機能やユーティリティ関数を検索し、該当ファイルをReadツールで読み込み + - 実装パターンやアーキテクチャガイドラインを特定し、設計文書をReadツールで読み込み + - 依存関係やインポートパスを確認し、関連ファイルをReadツールで読み込み + + +読み込み完了後、準備されたコンテキスト情報を基にGreen task（実装）の作業を開始します。 + +**テスト実行時はTaskツールを利用する** + +## 信頼性レベル指示 + +実装コード作成時には、各実装内容について元の資料との照合状況を以下の信号でコメントしてください： + +- 🔵 **青信号**: 元の資料を参考にしてほぼ推測していない場合 +- 🟡 **黄信号**: 元の資料から妥当な推測の場合 +- 🔴 **赤信号**: 元の資料にない推測の場合 + +## 目標 + +- $ARGUMENTS を解消する **実装** を行ってください + + +## 実装の原則 + +- **テストが確実に通ること最優先** +- コードの美しさは二の次（Refactorで改善） +- 「とりあえず動く」レベルでOK +- 複雑なロジックは後回し、シンプルな実装を心がける +- テストがなかなか通らないときは、Taskツールを使用して失敗原因を調べてから修正の計画を立てて実装する +- 既存のテストがエラーになった場合は仕様を元に適切に修正する +- **モック使用の制限**: テストコード以外でモックを記述しない（実装コードは実際のロジックを書く） +- **ファイルサイズ管理**: 実装ファイルが800行を超えた時点でファイル分割を検討する +- NEVER: 必要なテストのスキップ禁止 +- NEVER: 必要なテストの削除禁止 +- NEVER: 実装コード内でのモック・スタブの記述禁止 +- NEVER: 実装コード内でDBに代わるインメモリーストレージの利用禁止 +- NEVER: 実装コード内でDB操作の省略禁止 + +## 実装時の日本語コメント要件 + +実装コードには以下の日本語コメントを必ず含めてください： + +### 関数・メソッドレベルのコメント + +```javascript +/** + * 【機能概要】: [この関数が何をするかを日本語で説明] + * 【実装方針】: [なぜこのような実装方法を選んだかを説明] + * 【テスト対応】: [どのテストケースを通すための実装かを明記] + * 🔵🟡🔴 信頼性レベル: [この実装が元資料のどの程度に基づいているか] + * @param {type} paramName - [パラメータの説明] + * @returns {type} - [戻り値の説明] + */ +function {{function_name}}(paramName) { + // 【実装内容】: [実装している処理の詳細説明] +} +``` + +### 処理ブロックレベルのコメント + +```javascript +function processData(input) { + // 【入力値検証】: [入力値の妥当性をチェックする理由と方法] 🔵🟡🔴 + if (!input) { + throw new Error('入力値が不正です'); // 【エラー処理】: [なぜこのエラーが必要かを説明] 🔵🟡🔴 + } + + // 【データ処理開始】: [メイン処理の開始を明示] 🔵🟡🔴 + // 【処理方針】: [この処理がテストを通すためにどう貢献するかを説明] 🔵🟡🔴 + const result = { + // 【結果構造】: [戻り値の構造とその理由を説明] + validData: [], + invalidData: [], + errors: [], + }; + + // 【結果返却】: [処理結果を返す理由と内容の説明] + return result; +} +``` + +### 変数・定数のコメント + +```javascript +// 【定数定義】: [この定数が必要な理由と使用目的] +const MAX_FILE_SIZE = 1024 * 1024; // 【制限値】: ファイルサイズの上限（1MB）を設定 + +// 【変数初期化】: [この変数がテスト通過のためになぜ必要かを説明] +let processedCount = 0; // 【カウンタ】: 処理済みファイル数を追跡するためのカウンタ +``` + +### エラーハンドリングのコメント + +```javascript +try { + // 【実処理実行】: [実際の処理を実行する部分の説明] + const data = processFile(filePath); +} catch (error) { + // 【エラー捕捉】: [エラーが発生した場合の対処方針] + // 【テスト要件対応】: [テストで期待されるエラーハンドリングを満たすための処理] + return { + success: false, + error: error.message, // 【エラー情報】: テストで検証されるエラーメッセージを適切に返却 + }; +} +``` + +## 実装例 + +```javascript +/** + * 【機能概要】: JSONファイルパスを検証し、有効/無効なパスを分類する + * 【実装方針】: テストケースを通すために最低限必要な機能のみを実装 + * 【テスト対応】: tdd-red フェーズで作成されたテストケースを通すための実装 + */ +function {{function_name}}(input) { + // 【入力値検証】: 不正な入力値を早期に検出してエラーを防ぐ + if (!input) { + // 【エラー処理】: テストで期待されるエラーケースに対応 + throw new Error('入力値が必要です'); + } + + // 【最小限実装】: テストを通すための最もシンプルな実装 + // 【ハードコーディング許可】: リファクタ段階で改善予定のため、現段階では固定値でOK + return {{simple_return_value}}; +} +``` + +## 段階的実装のガイドライン + +1. **まず1つのテストケースだけ通す** + - 【実装戦略】: 複数テストの同時対応は複雑化を招くため避ける + - 【品質確保】: 1つずつ確実に実装することで品質を担保 +2. **最も簡単な方法で実装** + - 【シンプル実装】: 複雑なアルゴリズムは後のリファクタで追加 + - 【可読性重視】: 現段階では理解しやすさを最優先 +3. **ファイルサイズを意識した実装** + - 【800行制限】: 実装ファイルが800行を超えた時点で分割を検討 + - 【モジュール設計】: 機能単位でファイルを適切に分離 + - 【関数分割】: 長大な関数は小さな単位に分割して実装 + - 【責任境界】: 各ファイルの責任範囲を明確にして実装 + - 【分割戦略】: 機能・レイヤー・ドメインでファイルを分離 +4. **コード品質基準の考慮** + - 【静的解析対応】: lintやtypecheckでエラーが出ない実装を心がける + - 【フォーマット統一】: プロジェクトの既存フォーマットに合わせた実装 + - 【命名規則遵守】: プロジェクトの命名規則に従った実装 +5. **他のテストケースは後回し** + - 【段階的開発】: TDDの原則に従い、1ステップずつ進める + - 【影響範囲限定】: 変更の影響を最小限に抑える +6. **エラーハンドリングも最小限** + - 【必要最小限】: テストで要求される部分のみ実装 + - 【将来拡張可能】: リファクタ段階で詳細なエラー処理を追加予定 +7. **モック使用の制限** + - 【実装コード制限】: 実装コード内でモック・スタブを使用しない + - 【テストコード限定】: モックはテストコード内でのみ使用 + - 【実際のロジック実装】: 実装コードは実際の処理を記述する + - 【依存関係注入】: 必要に応じて依存性注入パターンで実装 + +## 提供してください + +1. **実装コード**: テストを通すコード（必須の日本語コメント付き） +2. **テスト実行結果**: Taskツールを使用して実際にテストが通ることの確認 +3. **実装の説明**: どのような考えで実装したか（日本語コメントとの対応関係） +4. **課題の特定**: 現在の実装の問題点（リファクタ対象の明確化） +5. **ファイルサイズチェック**: 実装ファイルの行数確認（800行超過時の分割計画） +6. **モック使用確認**: 実装コードにモック・スタブが含まれていないことの確認 + +実装完了後、以下を実行してください： + +1. **手動確認**: 自動遷移条件を満たさない場合は以下を提供してください： + - 「Taskツールを使用してテストが通ったことを確認しました。」 + - 「現在の実装: [簡潔な説明]」 + - 「実装に含めた日本語コメント: [コメントの目的と内容]」 + - 「リファクタリングの候補: [改善すべき点]」 + - 「次のRefactorフェーズに進んでよろしいですか？」 + +## 品質判定基準 + +``` +✅ 高品質: +- テスト結果: Taskツールによる実行で全て成功 +- 実装品質: シンプルかつ動作する +- リファクタ箇所: 明確に特定可能 +- 機能的問題: なし +- コンパイルエラー: なし +- ファイルサイズ: 800行以下または分割計画が明確 +- モック使用: 実装コードにモック・スタブが含まれていない + +⚠️ 要改善: +- テストの一部が失敗（Taskツールで検出） +- 実装が複雑すぎる +- リファクタ方針が不明 +- 機能に懸念がある +- コンパイルエラーが存在 +- ファイルサイズが800行を超過し分割計画が不明 +- 実装コードにモック・スタブが含まれている +``` + + + + +--- +description: TDDのRefactorフェーズを実行します。テストを通す実装が完了した後、コード品質の改善とリファクタリングを行います。 +--- + +# TDD Refactorフェーズ（コード改善） + +TDDのRefactorフェーズを実行します。 + +## 事前準備 + +開発コンテキストの準備を行います： + +1. **追加ルールの読み込み** + - `AGENTS.md` ファイルが存在する場合は読み込み + - `docs/rule` ディレクトリが存在する場合は読み込み + - `docs/rule/tdd` ディレクトリが存在する場合は読み込み + - `docs/rule/tdd/refactor` ディレクトリが存在する場合は読み込み + - 各ディレクトリ内のすべてのファイルを読み込み、追加ルールとして適用 + +2. **@agent-symbol-searcher でリファクタリング関連情報を検索し、見つかったファイルを読み込み** + - 既存のコードスタイルやベストプラクティスを検索し、スタイルガイドをReadツールで読み込み + - プロジェクト全体のアーキテクチャパターンを特定し、設計文書をReadツールで読み込み + - 再利用可能なユーティリティ関数やコンポーネントを確認し、関連ファイルをReadツールで読み込み + +3. **関連ファイルを直接読み込み** + - 関連する設計文書やタスクファイルも必要に応じて読み込み + +読み込み完了後、準備されたコンテキスト情報を基にRefactorフェーズ（コード改善）の作業を開始します。 + +## 信頼性レベル指示 + +リファクタリング時には、各改善内容について元の資料との照合状況を以下の信号でコメントしてください： + +- 🔵 **青信号**: 元の資料を参考にしてほぼ推測していない場合 +- 🟡 **黄信号**: 元の資料から妥当な推測の場合 +- 🔴 **赤信号**: 元の資料にない推測の場合 + +## 目標 + +Greenフェーズで実装されたコードを以下の観点で改善してください。**テストは必ず通り続けること**が大前提です。 + +## 改善の観点 + +### 1. 可読性の向上 + +- 変数名・関数名の改善 +- 日本語コメントの充実 +- コードの構造を分かりやすく + +### 2. 重複コードの除去（DRY原則） + +- 同じような処理の共通化 +- 定数の抽出 +- ヘルパー関数の作成 + +### 3. 設計の改善 + +- 単一責任原則の適用 +- 依存関係の整理 +- モジュール化の検討 + +- NEVER: 実装コード内でのモック・スタブの記述 +- NEVER: 実装コード内でDBに代わるインメモリーストレージの利用 + +### 4. ファイルサイズの最適化 + +- ファイルサイズが500行未満になるよう分割・最適化 +- 長大なファイルの機能別分割 +- 適切なモジュール境界の設定 + +### 5. コード品質の確保 + +- lintエラーの解消 +- typecheckエラーの解消 +- フォーマットの統一 +- 静的解析ツールのチェッククリア + +### 6. セキュリティレビュー + +- 脆弱性に繋がる実装の検出と修正 +- 入力値検証の強化 +- SQLインジェクション対策の確認 +- XSS（Cross-Site Scripting）対策の確認 +- CSRF（Cross-Site Request Forgery）対策の確認 +- データ漏洩リスクの回避 +- 認証・認可の適切な実装 + +### 7. パフォーマンスレビュー + +- アルゴリズムの計算量解析 +- メモリ使用量の最適化 +- 不要な処理の削除 +- キャッシュ戦略の検討 +- データベースクエリの最適化 +- ループ処理の効率化 +- 非同期処理の適切な実装 + +### 8. エラーハンドリングの充実 + +- 入力値の検証 +- 適切なエラーメッセージ +- 例外処理の改善 + +## リファクタリング時の日本語コメント強化要件 + +リファクタリングでは既存の日本語コメントを改善し、新たなコメントを追加してください： + +### 改善された関数・メソッドのコメント + +```javascript +/** + * 【機能概要】: [リファクタ後の機能の詳細説明] + * 【改善内容】: [どのような改善を行ったかを説明] + * 【設計方針】: [なぜこの設計にしたかの理由] + * 【パフォーマンス】: [性能面での考慮事項] + * 【保守性】: [メンテナンスしやすくするための工夫] + * 🔵🟡🔴 信頼性レベル: [この改善が元資料のどの程度に基づいているか] + * @param {type} paramName - [パラメータの詳細説明と制約] + * @returns {type} - [戻り値の詳細説明と保証事項] + */ +function improvedFunction(paramName) { + // 【実装詳細】: [改善された実装の内容と理由] +} +``` + +### ヘルパー関数・ユーティリティのコメント + +```javascript +/** + * 【ヘルパー関数】: [この関数の役割と作成理由] + * 【再利用性】: [どのような場面で再利用できるか] + * 【単一責任】: [この関数が担当する責任の範囲] + */ +function helperFunction(input) { + // 【処理効率化】: [処理を効率化するための工夫] 🔵🟡🔴 + // 【可読性向上】: [コードの読みやすさを向上させる仕組み] 🔵🟡🔴 +} +``` + +### 定数・設定値のコメント + +```javascript +// 【設定定数】: [この定数の役割と設定理由] 🔵🟡🔴 +// 【調整可能性】: [将来的に調整が必要になる可能性と方法] 🔵🟡🔴 +const IMPROVED_CONSTANT = 100; // 【最適化済み】: パフォーマンステストに基づき最適化 🔵🟡🔴 + +// 【設定オブジェクト】: [設定をまとめた理由と管理方針] +const CONFIG = { + // 【各設定項目】: [それぞれの設定値の意味と影響範囲] + maxRetries: 3, // 【リトライ回数】: 実運用での経験に基づく適切な回数 + timeout: 5000, // 【タイムアウト】: ユーザビリティを考慮した時間設定 +}; +``` + +### エラーハンドリング改善のコメント + +```javascript +try { + // 【安全な処理実行】: [例外が発生する可能性と対策] + const result = riskyOperation(); +} catch (error) { + // 【詳細エラー処理】: [エラーの種類に応じた適切な処理] + // 【ユーザビリティ】: [ユーザーにとって分かりやすいエラー対応] + if (error.code === 'SPECIFIC_ERROR') { + // 【特定エラー対応】: [このエラーに特化した処理の理由] + return handleSpecificError(error); + } + // 【一般エラー対応】: [予期しないエラーへの安全な対処] + return handleGenericError(error); +} +``` + +## リファクタリングの手順 + +1. **現在のテストが全て通ることを確認** + - 【品質保証】: リファクタ前の動作確認 + - 【安全性確保】: 変更による機能破綻の防止 + - 【実行方法】: Taskツールを使用してテストを実行し、結果を詳細に分析 +2. **コード・テスト除外チェック** + - 【.gitignore確認】: 本来確認対象のコードファイルが除外されていないかチェック + - 【テスト除外確認】: `describe.skip`, `it.skip`, `test.skip`等でテストが無効化されていないかチェック + - 【jest設定確認】: `jest.config.js`や`package.json`の`testPathIgnorePatterns`等でテストファイルが除外されていないかチェック + - 【実行対象確認】: 実際に実行されるべきテストとコードが適切に対象に含まれているかチェック +3. **開発時生成ファイルのクリーンアップ** + - 【不要ファイル検出】: 開発中に作成された一時的なファイルを検出・削除 + - 【対象ファイルパターン】: 以下のパターンに該当するファイルを確認 + - `debug-*.js`, `debug-*.ts`: デバッグ用スクリプト + - `test-*.js`, `test-*.ts`, `temp-*.js`: 一時テストファイル + - `*.tmp`, `*.temp`, `*.bak`, `*.orig`: 一時・バックアップファイル + - `*~`, `.DS_Store`: エディタ・システム生成ファイル + - `test-output-*`, `*.test-output`: テスト出力ファイル + - 【安全確認】: 削除前に各ファイルの内容を確認し、重要なコードが含まれていないかチェック + - 【選択的削除】: 不要と判断されたファイルのみを削除し、必要なファイルは保持 + - 【削除ログ】: 削除したファイルと削除理由をログとして記録 + - 【実行手順】: + 1. `find . -name "debug-*" -o -name "test-*" -o -name "temp-*" -o -name "*.tmp" -o -name "*.temp" -o -name "*.bak" -o -name "*.orig" -o -name "*~" -o -name ".DS_Store" | grep -v node_modules` でファイル検出 + 2. 各ファイルの内容をReadツールで確認 + 3. 不要と判断されたファイルは削除し、削除理由を記録 +4. **セキュリティレビューの実施** + - 【脆弱性検査】: コード全体のセキュリティホールの特定 + - 【入力検証確認】: 不正な入力値に対する防御機能の確認 + - 【セキュリティガイドライン適用】: 業界標準のセキュリティベストプラクティスの適用 +5. **パフォーマンスレビューの実施** + - 【計算量解析】: アルゴリズムの時間計算量・空間計算量の評価 + - 【ボトルネック特定】: 処理速度やメモリ使用量の問題箇所の特定 + - 【最適化戦略】: 具体的なパフォーマンス改善施策の立案 +6. **小さな改善を1つずつ適用** + - 【段階的改善】: 影響範囲を限定した安全な変更 + - 【トレーサビリティ】: 変更内容の追跡可能性確保 +7. **各改善後にテストを実行** + - 【継続的検証】: 改善の度に動作確認 + - 【早期発見】: 問題の早期発見と修正 + - 【実行方法】: Taskツールを使用してテストを実行し、改善の影響を確認 +8. **テストが失敗したら即座に戻す** + - 【迅速復旧】: 問題発生時の素早い対応 + - 【安定性維持】: システムの安定した状態を保持 + +## 注意事項 + +- **機能的な変更は行わない**（新機能追加はNG） +- **テストが通らなくなったら即座に修正** +- **一度に大きな変更をしない** +- **日本語コメントの品質も向上させる** +- **品質確認のためのテスト実行時はTaskツールを利用する** + + +## 提供してください + +1. **セキュリティレビュー結果**: 脆弱性の有無と対応策 +2. **パフォーマンスレビュー結果**: 性能課題の分析と改善策 +3. **改善されたコード**: リファクタリング後のコード（強化された日本語コメント付き） +4. **改善ポイントの説明**: 何をどのように改善したか（セキュリティ・パフォーマンス観点を含む） +5. **テスト実行結果**: Taskツールを使用して全てのテストが引き続き通ることの確認 +6. **品質評価**: 現在のコードの品質レベル（セキュリティ・パフォーマンス評価を含む） +7. **コメント改善内容**: 日本語コメントをどのように強化したか + +## リファクタリング例 + +```javascript +// Before: ハードコーディング +function add(a, b) { + return 5; // とりあえず動く実装 +} + +// After: 適切な実装（改善された日本語コメント付き） +/** + * 【機能概要】: 2つの数値を加算し、結果を返す + * 【改善内容】: ハードコーディングを削除し、実際の加算処理を実装 + * 【設計方針】: 入力値検証と型安全性を重視した設計 + * 【エラー処理】: 不正な入力に対する適切な例外処理を実装 + */ +function add(firstNumber, secondNumber) { + // 【入力値検証】: 数値以外の入力を早期に検出してエラーを防ぐ + // 【型安全性】: TypeScriptの型チェックと併せて実行時検証を実施 + if (typeof firstNumber !== 'number' || typeof secondNumber !== 'number') { + // 【ユーザビリティ】: 開発者にとって分かりやすいエラーメッセージを提供 + throw new Error('引数は数値である必要があります'); + } + + // 【メイン処理】: シンプルで確実な加算処理 + // 【パフォーマンス】: 不要な処理を避けた効率的な実装 + return firstNumber + secondNumber; +} +``` + +リファクタリング完了後、以下を実行してください： + +1. **品質判定**: リファクタリング成果の品質を以下の基準で判定 + - テスト結果: 全てのテストが引き続き成功 + - セキュリティ: 重大な脆弱性が発見されていない + - パフォーマンス: 重大な性能課題が発見されていない + - リファクタ品質: 目標が達成されている + - コード品質: 適切なレベルに向上 + +## 品質判定基準 + +``` +✅ 高品質: +- テスト結果: Taskツールによる実行で全て継続成功 +- セキュリティ: 重大な脆弱性なし +- パフォーマンス: 重大な性能課題なし +- リファクタ品質: 目標達成 +- コード品質: 適切なレベル +- ドキュメント: 完成 + +⚠️ 要改善: +- テストの一部失敗（Taskツールで検出） +- セキュリティ脆弱性発見 +- パフォーマンス課題発見 +- リファクタ目標未達成 +- 品質改善不十分 +- ドキュメント不備 +``` + + diff --git a/commands/dcs/bug-analysis.md b/commands/dcs/bug-analysis.md new file mode 100644 index 0000000..da6bee2 --- /dev/null +++ b/commands/dcs/bug-analysis.md @@ -0,0 +1,1770 @@ +--- +description: バグの原因を特定するための詳細分析を実施する +allowed-tools: Read, Glob, Grep, Task, Bash, AskUserQuestion +argument-hint: [バグの概要（任意）] +--- +バグの発生経緯や症状から原因を特定し、修正方針を提示します。ソースコードを詳細に分析し、段階的に原因を絞り込みます。 + +# context + +出力ディレクトリ=".dcs" +カレントディレクトリ={{プロジェクトルート}} +分析ファイルリスト=[] +調査段階=1 + +# step + +- $1 がある場合、その内容を簡潔に説明する +- step1 を実行する + +## step1: 初期情報収集 + +- AskUserQuestion ツールを使って以下の質問を順番に実施し、context を更新する： + 1. バグの種類を確認 + 2. バグの発生状況を確認 + 3. エラー情報の有無を確認 + 4. 再現手順の有無を確認 +- 収集した context の内容をまとめてユーザに宣言する +- step2 を実行する + +## step2: 初期調査の実行 + +- 既存の出力ファイルを確認して、重複しないナンバリングを決定する + - {{出力ディレクトリ}}/{{timestamp}}_*/ を検索 + - バグの内容を簡単に英語化したもの（例: "order_total_bug", "cart_display_issue"）を作成 + - 同じ timestamp と内容で既存ディレクトリがある場合、末尾の連番を +1 する + - ベースディレクトリを "{{出力ディレクトリ}}/{{timestamp}}_{{内容の英語化}}" とする + - 例: ".dcs/20251025_143022_order_total_bug" +- 分析結果ファイルのリストを準備する + - インデックスファイル: "{{ベースディレクトリ}}/index.md" + - 初期調査ファイル: "{{ベースディレクトリ}}/initial_investigation.md" + - 処理フロー分析ファイル: "{{ベースディレクトリ}}/flow_analysis.md" + - 詳細原因分析ファイル: "{{ベースディレクトリ}}/root_cause_analysis.md" + - 最終レポートファイル: "{{ベースディレクトリ}}/final_report.md" +- すべてのファイル名を 分析ファイルリスト に追加する +- の内容を context の情報で埋めて、Task ツールで直接実行する + - subagent_type: "general-purpose" + - description: "バグ初期調査の実行" + - prompt: テンプレートの内容を context で埋めた完全なプロンプト +- Task の実行結果を受け取る +- step3 を実行する + +## step3: 処理フロー分析の実行 + +- 初期調査結果を Read で確認する +- 追加で確認すべき情報があるかユーザに確認する +- ユーザの承認を得てから続行する +- の内容を context と初期調査結果で埋めて、Task ツールで実行する + - subagent_type: "general-purpose" + - description: "バグ処理フロー分析の実行" + - prompt: テンプレートの内容を埋めた完全なプロンプト +- Task の実行結果を受け取る +- step4 を実行する + +## step4: 詳細原因分析の実行 + +- 処理フロー分析結果を Read で確認する +- の内容を context とこれまでの分析結果で埋めて、Task ツールで実行する + - subagent_type: "general-purpose" + - description: "バグ詳細原因分析の実行" + - prompt: テンプレートの内容を埋めた完全なプロンプト +- Task の実行結果を受け取る +- step5 を実行する + +## step5: 最終レポートの作成 + +- の内容を使って、Task ツールで最終レポートを作成する + - subagent_type: "general-purpose" + - description: "バグ分析 最終レポートの作成" + - prompt: テンプレートの内容を context で埋めた完全なプロンプト + - 最終レポートファイル名: "{{ベースディレクトリ}}/final_report.md" +- 全ての分析ファイルのパスを段階別に整理して表示する + - 初期調査ファイル + - 処理フロー分析ファイル + - 詳細原因分析ファイル + - 最終レポート +- 分析完了をユーザに報告する + +# rules + +## 確認ポイント + +AskUserQuestion ツールを使って、以下の質問を順番に実施する： + +### 質問1: バグの種類 +- **質問**: このバグはどのカテゴリに該当しますか？ +- **header**: "バグ種類" +- **multiSelect**: true +- **options**: + - "UI/表示バグ" - 画面表示、レイアウト、スタイルの問題 + - "ロジックバグ" - ビジネスロジック、計算処理、条件分岐の問題 + - "データバグ" - データベース、API、状態管理の問題 + - "統合バグ" - コンポーネント間連携、外部システム連携の問題 + - "パフォーマンスバグ" - 処理速度、メモリ使用量の問題 + +### 質問2: バグの発生状況 +- **質問**: バグはどのような状況で発生しますか？ +- **header**: "発生状況" +- **options**: + - "常に発生" - 特定の操作で必ず発生する + - "特定条件で発生" - 特定のデータや状態でのみ発生する + - "間欠的に発生" - 再現性が低く、たまに発生する + - "環境依存" - 特定の環境でのみ発生する + +### 質問3: エラー情報の有無 +- **質問**: エラーログやエラーメッセージはありますか？ +- **header**: "エラー情報" +- **options**: + - "あり（詳細）" - スタックトレースやエラーメッセージがある + - "あり（簡易）" - エラーメッセージのみある + - "なし" - エラー情報はないが動作がおかしい + +### 質問4: 再現手順の有無 +- **質問**: バグを再現する手順は明確ですか？ +- **header**: "再現手順" +- **options**: + - "明確" - 確実に再現できる手順がある + - "おおよそ" - 大まかな手順はわかるが確実ではない + - "不明" - 再現手順がわからない + +contextとして以下を保持する： +- バグの概要 +- バグの種類 +- 発生状況 +- エラー情報の有無 +- 再現手順の有無 +- その他のバグ詳細情報 + +## ファイル名のルール + +### timestamp の形式 +- yyyyMMddHHmmss 形式（例: 20251025143022） + +### 内容の英語化のルール +- バグの内容を簡潔な英語に変換する +- スネークケース（snake_case）を使用 +- 最大30文字程度に収める +- 例: + - "注文合計の計算バグ" → "order_total_bug" + - "カート表示の問題" → "cart_display_issue" + - "決済エラー" → "payment_error" + - "パフォーマンス問題" → "performance_issue" + +### セクション別ファイル名のルール +- 分析結果は段階ごとに分割し、各ファイル500行以内を目標とする +- ファイル一覧: + - `_index.md` - インデックス（全体概要とファイル一覧） + - `_initial_investigation.md` - 初期調査結果 + - `_flow_analysis.md` - 処理フロー分析 + - `_root_cause_analysis.md` - 詳細原因分析 + - `_final_report.md` - 最終レポート + +### 完全なファイル名の例 +- `.dcs/20251025143022_order_total_bug/index.md` +- `.dcs/20251025143022_order_total_bug/initial_investigation.md` +- `.dcs/20251025143022_order_total_bug/flow_analysis.md` +- `.dcs/20251025143022_order_total_bug/root_cause_analysis.md` +- `.dcs/20251025143022_order_total_bug/final_report.md` + +## ファイルパスの記載ルール + +- **カレントディレクトリを基準とした相対パスを使用する** +- フルパス（絶対パス）は記載しない +- 例: + - ❌ `/Users/makotan/projects/ensemble-si/src/utils/helper.ts` + - ✅ `src/utils/helper.ts` +- カレントディレクトリは分析開始時の作業ディレクトリ +- すべてのファイルパスは相対パスで統一する + +## バグの種類別分析アプローチ + +### UI/表示バグ +- コンポーネントの構造とプロパティ +- スタイル定義とCSS適用状況 +- データバインディングの確認 +- 条件付きレンダリングの検証 +- ブラウザ互換性の確認 + +### ロジックバグ +- 関数・メソッドの入出力 +- 条件分岐のロジック +- 計算処理の精度 +- エッジケースの処理 +- エラーハンドリング + +### データバグ +- データフローの追跡 +- API呼び出しとレスポンス +- 状態管理の整合性 +- データベースクエリ +- データ変換処理 + +###統合バグ +- コンポーネント間のデータ受け渡し +- イベント伝播 +- API連携のシーケンス +- 非同期処理のタイミング +- トランザクション境界 + +### パフォーマンスバグ +- N+1問題の検出 +- 重複処理の特定 +- 不要な再レンダリング +- メモリリークの可能性 +- 非効率なアルゴリズム + +## 原因特定のための観点 + +### コード解析の観点 +1. **制御フロー**: 条件分岐、ループ、例外処理 +2. **データフロー**: 変数の生成、変換、利用 +3. **依存関係**: モジュール間、関数間の依存 +4. **副作用**: 状態変更、外部システムへの影響 +5. **タイミング**: 非同期処理、イベント順序 + +### 検証すべきポイント +- 入力値の検証 +- 境界値の処理 +- nullチェック +- 型の整合性 +- エラーハンドリングの網羅性 + +### よくある原因パターン +- 未初期化変数の使用 +- nullポインタ参照 +- 配列の範囲外アクセス +- 型の不一致 +- 非同期処理の競合 +- メモリリーク +- 無限ループ +- 不適切なエラーハンドリング + +# info + + +あなたはバグ原因特定のエキスパートです。以下の情報に基づいて、バグの初期調査を実施し、関連するコード箇所を特定してください。 + +# バグの基本情報 + +バグの概要: {{バグの概要}} +バグの種類: {{バグの種類}} +発生状況: {{発生状況}} +エラー情報: {{エラー情報の有無と内容}} +再現手順: {{再現手順の有無と内容}} +その他の情報: {{その他のバグ詳細情報}} + +出力ファイル名: {{ベースディレクトリ}}/initial_investigation.md +カレントディレクトリ: {{カレントディレクトリ}} + +# 重要な注意事項 + +**すべてのファイルパスは、カレントディレクトリを基準とした相対パスで記載してください。** +**絶対パス（/Users/... や C:\\... など）は使用しないでください。** +**このファイルは500行以内を目標としてください。** + +# 初期調査の手順 + +## 1. バグの種類に応じた検索戦略の決定 + +バグの種類（{{バグの種類}}）に基づいて、適切な検索アプローチを決定する： + +### UI/表示バグの場合 +- コンポーネントファイルの特定（.tsx, .jsx, .vue など） +- スタイル定義の確認（CSS, styled-components など） +- データバインディングの確認 + +### ロジックバグの場合 +- 関連する関数・メソッドの特定 +- ビジネスロジックの所在確認 +- 計算処理のコード検索 + +### データバグの場合 +- API定義の確認 +- データモデルの特定 +- 状態管理コードの確認 + +### 統合バグの場合 +- コンポーネント間連携の確認 +- API呼び出しのシーケンス +- イベントハンドラの追跡 + +### パフォーマンスバグの場合 +- 重複処理の検出 +- N+1問題の確認 +- 不要な再レンダリングの特定 + +## 2. エラー情報からの手がかり抽出 + +{{エラー情報の有無と内容}}がある場合： +- エラーメッセージから関連するコード箇所を特定 +- スタックトレースから呼び出し経路を追跡 +- エラーコードから該当処理を検索 + +## 3. 関連機能・コンポーネントの特定 + +### 使用するツール +- Grep: キーワード検索でコード箇所を特定 +- Glob: ファイルパターンで関連ファイルを列挙 +- Read: 特定ファイルの内容確認 + +### 検索キーワードの選定 +- バグの概要から重要なキーワードを抽出 +- 関連する関数名、クラス名、コンポーネント名 +- エラーメッセージの一部 + +### 検索の実施 +1. 最も可能性の高いキーワードで Grep 検索 +2. 見つかったファイルを Read で確認 +3. 必要に応じて追加のキーワードで検索 +4. 関連ファイルを Glob で列挙 + +## 4. コードベースの構造理解 + +### プロジェクト構造の確認 +- frontend/ - フロントエンドアプリケーション +- admin/ - 管理画面 +- backend/ - バックエンドAPI +- prismatix-factory/ - リソース定義 + +### アーキテクチャパターンの理解 +- BFF（Backend for Frontend）パターン +- Next.js API ルート経由のバックエンド呼び出し +- Prismatix Factory によるコード生成 + +## 5. 初期調査結果のまとめ + +以下の形式で結果をファイルに出力してください。Write ツールを使用して保存してください。 + +```markdown +# バグ初期調査結果 + +**実施日時**: {{実施日時}} +**分析者**: Claude Code + +[← インデックスに戻る](./index.md) + +--- + +## バグの基本情報 + +### 概要 +{{バグの概要}} + +### バグの種類 +{{バグの種類}} + +### 発生状況 +{{発生状況}} + +### エラー情報 +{{エラー情報の詳細}} + +### 再現手順 +{{再現手順の詳細}} + +--- + +## 関連コンポーネント・ファイル + +### 主要な関連ファイル + +#### [相対パス](相対パス) +- **役割**: {{このファイルの役割}} +- **関連度**: 高/中/低 +- **理由**: {{なぜこのファイルが関連するのか}} +- **重要なコード箇所**: + - 行番号: {{行番号}} + - 内容: {{コードの概要}} + +#### [相対パス](相対パス) +（同様の形式で複数記載） + +### 補助的な関連ファイル + +#### [相対パス](相対パス) +- **役割**: {{このファイルの役割}} +- **関連度**: 中/低 +- **理由**: {{なぜこのファイルが関連するのか}} + +--- + +## 検索キーワードと結果 + +### 使用したキーワード +1. `{{キーワード1}}` - XX件ヒット +2. `{{キーワード2}}` - XX件ヒット +3. `{{キーワード3}}` - XX件ヒット + +### 検索結果のサマリー +{{検索結果の総括}} + +--- + +## コードベース構造の理解 + +### アーキテクチャ上の位置づけ +{{このバグに関連するコンポーネントがアーキテクチャ上どこに位置するか}} + +### データフローの概要 +{{データがどのように流れるか}} + +``` +{{データフロー図（テキスト形式）}} +例: +Frontend Component + ↓ (API呼び出し) +Next.js API Route (BFF) + ↓ (HTTP Request) +Backend API + ↓ (DLL呼び出し) +Prismatix Factory + ↓ (SQL) +PostgreSQL +``` + +--- + +## 初期仮説 + +### 可能性の高い原因候補 + +#### 候補1: {{原因の概要}} +- **確度**: 高/中/低 +- **理由**: {{なぜこの可能性が高いのか}} +- **該当箇所**: [相対パス:行番号](相対パス#L行番号) +- **検証方法**: {{どのように検証すべきか}} + +#### 候補2: {{原因の概要}} +（同様の形式で複数記載） + +### 可能性の低い候補 +{{可能性は低いが念のため記載する候補}} + +--- + +## 次段階の調査方針 + +### 処理フロー分析で確認すべき点 +1. {{確認ポイント1}} +2. {{確認ポイント2}} +3. {{確認ポイント3}} + +### 追加で確認すべき情報 +{{ユーザに確認したい情報があれば記載}} + +--- + +## 制限事項 + +### 検出できなかった可能性のある箇所 +- {{制限事項1}} +- {{制限事項2}} + +--- + +*この初期調査結果は自動生成されたものです。次段階の処理フロー分析でさらに詳細を確認します。* +``` + +# 調査の注意点 + +- 動的な呼び出し（リフレクション、eval など）は検出が困難 +- 文字列による間接的な参照は検出が困難 +- コメントアウトされたコードは除外する +- テストコードも関連性があれば含める +- **すべてのファイルパスは相対パスで記載する（絶対パスは使用しない）** +- **ファイルは500行以内を目標とする** + +最後に、インデックスファイル（{{ベースディレクトリ}}/index.md）も作成してください。インデックスファイルには以下の内容を含めてください： + +```markdown +# バグ原因分析 - インデックス + +**実施日時**: {{実施日時}} +**分析者**: Claude Code + +--- + +## バグ情報 + +### 概要 +{{バグの概要}} + +### 種類 +{{バグの種類}} + +--- + +## 分析結果ファイル一覧 + +### 調査段階 +- [初期調査](./initial_investigation.md) - 関連コンポーネントの特定 +- [処理フロー分析](./flow_analysis.md) - ※まだ実行されていません +- [詳細原因分析](./root_cause_analysis.md) - ※まだ実行されていません +- [最終レポート](./final_report.md) - ※まだ実行されていません + +--- + +## クイックサマリー + +### 初期仮説 +1. {{仮説1}} +2. {{仮説2}} +3. {{仮説3}} + +### 次のアクション +{{次に実施すべきこと}} + +--- + +*分析は段階的に実施されます。各段階の詳細は上記リンクから参照してください。* +``` + + + +あなたはバグ原因特定のエキスパートです。初期調査結果に基づいて、バグが発生するまでの処理フローを詳細に分析してください。 + +# 分析対象の情報 + +バグの概要: {{バグの概要}} +バグの種類: {{バグの種類}} +初期調査結果ファイル: {{ベースディレクトリ}}/initial_investigation.md +出力ファイル名: {{ベースディレクトリ}}/flow_analysis.md +カレントディレクトリ: {{カレントディレクトリ}} + +# 重要な注意事項 + +**すべてのファイルパスは、カレントディレクトリを基準とした相対パスで記載してください。** +**絶対パス（/Users/... や C:\\... など）は使用しないでください。** +**このファイルは500行以内を目標としてください。500行を超える場合は複数ファイルに分割してください。** + +# 処理フロー分析の手順 + +## 1. 初期調査結果の確認 + +- {{ベースディレクトリ}}/initial_investigation.md を Read で読み込む +- 特定された関連ファイルと初期仮説を把握する +- 分析の焦点を明確にする + +## 2. エントリーポイントの特定 + +### UI/表示バグの場合 +- ユーザーが操作する画面コンポーネント +- イベントハンドラ +- useEffect などのライフサイクルフック + +### ロジックバグの場合 +- APIエンドポイント +- サービス層の関数 +- ビジネスロジックの開始点 + +### データバグの場合 +- データ取得のAPI呼び出し +- 状態管理の初期化 +- データベースクエリの発行箇所 + +### 統合バグの場合 +- コンポーネント間のインターフェース +- API呼び出しの開始点 +- イベント発火の起点 + +### パフォーマンスバグの場合 +- パフォーマンスボトルネックが発生する処理 +- ループ処理 +- 繰り返し呼ばれる関数 + +## 3. 処理フローの追跡 + +### ステップバイステップ分析 +各処理ステップについて以下を記録する： +1. **ステップ番号**: 処理の順序 +2. **ファイルと行番号**: [相対パス:行番号](相対パス#L行番号) +3. **処理内容**: 何をしているか +4. **入力**: どのようなデータを受け取るか +5. **出力**: どのようなデータを返すか +6. **副作用**: 状態変更、API呼び出しなど +7. **注目点**: バグに関連する可能性のあるポイント + +### データの変換追跡 +- データがどのように変換されるか +- 型の変更 +- 値の計算 +- フィルタリング、マッピングなどの操作 + +### 状態の変化追跡 +- どの時点でどの状態が変わるか +- 状態変更のトリガー +- 状態の依存関係 + +### 条件分岐の分析 +- 条件式の評価 +- 各分岐での処理内容 +- バグが発生する条件での分岐 + +## 4. 異常系の処理確認 + +### エラーハンドリング +- try-catch ブロックの配置 +- エラーの伝播経路 +- エラーメッセージの生成 + +### バリデーション +- 入力値の検証 +- 境界値のチェック +- null/undefined チェック + +### ガード条件 +- early return +- デフォルト値の設定 +- フォールバック処理 + +## 5. 非同期処理の分析 + +### Promise/async-await +- 非同期処理の順序 +- awaitの有無 +- Promise.allなどの並行処理 + +### タイミングの問題 +- レースコンディション +- 状態の更新タイミング +- イベントの発火順序 + +## 6. 処理フロー分析結果のまとめ + +以下の形式で結果をファイルに出力してください。Write ツールを使用して保存してください。 + +```markdown +# バグ処理フロー分析 + +**実施日時**: {{実施日時}} +**分析者**: Claude Code + +[← インデックスに戻る](./index.md) | [初期調査](./initial_investigation.md) + +--- + +## 分析対象 + +### バグの概要 +{{バグの概要}} + +### 分析の焦点 +{{初期調査で特定された主要な関連箇所}} + +--- + +## エントリーポイント + +### [相対パス:行番号](相対パス#L行番号) + +**役割**: {{エントリーポイントの役割}} + +**コードスニペット**: +```{{language}} +{{関連するコードの抜粋（10行程度）}} +``` + +**トリガー**: {{このエントリーポイントが呼ばれる条件}} + +--- + +## 処理フローの詳細 + +### ステップ1: {{ステップの名前}} + +**ファイル**: [相対パス:行番号](相対パス#L行番号) + +**処理内容**: +{{この処理で何が行われるか}} + +**入力**: +- `{{変数名}}`: {{型}} - {{説明}} +- `{{変数名}}`: {{型}} - {{説明}} + +**出力**: +- `{{変数名}}`: {{型}} - {{説明}} + +**副作用**: +- {{状態変更、API呼び出しなど}} + +**コードスニペット**: +```{{language}} +{{関連するコードの抜粋}} +``` + +**注目点**: +{{バグに関連する可能性のあるポイント}} + +--- + +### ステップ2: {{ステップの名前}} + +（同様の形式で各ステップを記載） + +--- + +### ステップN: {{ステップの名前}} + +（処理フローの最終ステップ） + +--- + +## データフローの詳細 + +### データ変換の追跡 + +``` +{{データの変換フロー（テキスト形式）}} +例: +初期データ: { orderId: "123", items: [...] } + ↓ (ステップ1: データ取得) +APIレスポンス: { order: {...}, total: 1000 } + ↓ (ステップ2: データ整形) +整形済みデータ: { id: "123", amount: 1000, ... } + ↓ (ステップ3: 状態更新) +最終状態: OrderState = { ... } +``` + +### 重要なデータ変換ポイント + +#### 変換1: {{変換の名前}} +- **位置**: [相対パス:行番号](相対パス#L行番号) +- **変換前**: {{変換前のデータ構造}} +- **変換後**: {{変換後のデータ構造}} +- **変換ロジック**: {{どのように変換されるか}} +- **注目点**: {{バグに関連する可能性}} + +--- + +## 状態変化の追跡 + +### 状態の変更履歴 + +| ステップ | 状態変数 | 変更前の値 | 変更後の値 | 変更箇所 | +|---------|---------|-----------|-----------|---------| +| ステップ1 | `{{変数名}}` | `{{値}}` | `{{値}}` | [相対パス:行番号](相対パス#L行番号) | +| ステップ2 | `{{変数名}}` | `{{値}}` | `{{値}}` | [相対パス:行番号](相対パス#L行番号) | + +### 重要な状態変更 + +#### 状態変更1: {{変更の概要}} +- **タイミング**: {{いつ変更されるか}} +- **トリガー**: {{何が変更を引き起こすか}} +- **影響範囲**: {{どのコンポーネントに影響するか}} +- **注目点**: {{バグに関連する可能性}} + +--- + +## 条件分岐の分析 + +### 重要な条件分岐 + +#### 分岐1: {{分岐の概要}} + +**位置**: [相対パス:行番号](相対パス#L行番号) + +**条件式**: +```{{language}} +{{条件式のコード}} +``` + +**分岐パターン**: +- **条件A（真の場合）**: {{処理内容}} → ステップ{{N}}へ +- **条件B（偽の場合）**: {{処理内容}} → ステップ{{M}}へ + +**バグ発生時の条件**: +{{バグが発生する場合の条件式の評価結果}} + +**注目点**: +{{バグに関連する可能性}} + +--- + +## 異常系の処理 + +### エラーハンドリングの実装状況 + +#### エラーハンドリング1: {{エラーの種類}} + +**位置**: [相対パス:行番号](相対パス#L行番号) + +**対象エラー**: {{どのようなエラーを捕捉するか}} + +**処理内容**: +```{{language}} +{{エラーハンドリングのコード}} +``` + +**問題点**: +{{不十分な点、改善すべき点}} + +### バリデーションの実装状況 + +#### バリデーション1: {{検証内容}} + +**位置**: [相対パス:行番号](相対パス#L行番号) + +**検証項目**: {{何を検証しているか}} + +**実装の有無**: ✅ 実装済み / ❌ 未実装 + +**問題点**: +{{不十分な点、改善すべき点}} + +--- + +## 非同期処理の分析 + +### 非同期処理の順序 + +``` +{{非同期処理のシーケンス（テキスト形式）}} +例: +1. ユーザー操作 + ↓ +2. API呼び出し開始（非同期） + ↓ (await) +3. APIレスポンス受信 + ↓ +4. 状態更新（同期） + ↓ +5. 再レンダリング +``` + +### タイミング問題の可能性 + +#### タイミング問題1: {{問題の概要}} + +**位置**: [相対パス:行番号](相対パス#L行番号) + +**問題の詳細**: +{{レースコンディション、順序の問題など}} + +**発生条件**: +{{どのような条件で問題が発生するか}} + +**影響**: +{{バグへの影響}} + +--- + +## フロー分析からの所見 + +### 発見された問題点 + +#### 問題点1: {{問題の概要}} +- **深刻度**: 高/中/低 +- **位置**: [相対パス:行番号](相対パス#L行番号) +- **詳細**: {{問題の詳細説明}} +- **バグとの関連**: {{このバグにどう関連するか}} + +#### 問題点2: {{問題の概要}} +（同様の形式で複数記載） + +### 次段階で詳しく調べるべき箇所 + +1. **{{調査ポイント1}}** + - 理由: {{なぜ詳しく調べる必要があるか}} + - 着目点: {{何に着目すべきか}} + +2. **{{調査ポイント2}}** + （同様の形式で記載） + +--- + +*この処理フロー分析結果に基づいて、次段階で詳細な原因分析を実施します。* +``` + +# 分析の注意点 + +- 処理フローは時系列順に記載する +- 各ステップのコードスニペットは簡潔に（10行程度） +- データと状態の変化を明確に追跡する +- バグに関連する可能性のあるポイントを強調する +- **すべてのファイルパスは相対パスで記載する（絶対パスは使用しない）** +- **ファイルは500行以内を目標とする。超える場合は分割する** + +分析が完了したら、インデックスファイル（{{ベースディレクトリ}}/index.md）を更新して、処理フロー分析へのリンクを有効化してください。 + + + +あなたはバグ原因特定のエキスパートです。これまでの分析結果に基づいて、バグの根本原因を特定し、詳細な検証を実施してください。 + +# 分析対象の情報 + +バグの概要: {{バグの概要}} +バグの種類: {{バグの種類}} +初期調査結果ファイル: {{ベースディレクトリ}}/initial_investigation.md +処理フロー分析ファイル: {{ベースディレクトリ}}/flow_analysis.md +出力ファイル名: {{ベースディレクトリ}}/root_cause_analysis.md +カレントディレクトリ: {{カレントディレクトリ}} + +# 重要な注意事項 + +**すべてのファイルパスは、カレントディレクトリを基準とした相対パスで記載してください。** +**絶対パス（/Users/... や C:\\... など）は使用しないでください。** +**このファイルは500行以内を目標としてください。500行を超える場合は複数ファイルに分割してください。** + +# 詳細原因分析の手順 + +## 1. これまでの分析結果の統合 + +- {{ベースディレクトリ}}/initial_investigation.md を Read で読み込む +- {{ベースディレクトリ}}/flow_analysis.md を Read で読み込む +- 初期仮説と処理フロー分析から得られた所見を統合する +- 最も可能性の高い原因候補を特定する + +## 2. 原因候補の絞り込み + +### よくある原因パターンとの照合 + +#### 未初期化変数 +- 変数が使用される前に初期化されているか +- デフォルト値が適切か +- 条件付き初期化の漏れはないか + +#### nullポインタ/undefined参照 +- null/undefinedチェックが適切か +- オプショナルチェイニングの使用 +- デフォルト値の設定 + +#### 配列の範囲外アクセス +- インデックスの範囲チェック +- 空配列の処理 +- 境界値での動作 + +#### 型の不一致 +- 型変換の適切性 +- TypeScript/型定義の整合性 +- 暗黙の型変換による問題 + +#### 非同期処理の問題 +- awaitの漏れ +- Promise.allの適切な使用 +- レースコンディション +- 状態更新のタイミング + +#### ロジックの誤り +- 条件式の誤り +- 計算式の誤り +- ループの終了条件 +- エッジケースの処理漏れ + +#### メモリ関連 +- メモリリークの可能性 +- 循環参照 +- イベントリスナーの解除漏れ + +#### エラーハンドリングの不備 +- try-catchの範囲 +- エラーの伝播 +- エラーメッセージの不適切さ + +### バグの種類別のチェックポイント + +#### UI/表示バグ +- データバインディングの誤り +- 条件付きレンダリングのロジック +- スタイルの優先順位 +- useEffectの依存配列 +- 再レンダリングのタイミング + +#### ロジックバグ +- ビジネスルールの実装誤り +- 計算ロジックの誤り +- 条件分岐の不備 +- エッジケースの考慮漏れ + +#### データバグ +- データ変換の誤り +- API契約の不一致 +- 状態の整合性 +- キャッシュの問題 + +#### 統合バグ +- インターフェースの不一致 +- データの受け渡しミス +- イベントの伝播問題 +- トランザクション境界 + +#### パフォーマンスバグ +- N+1問題 +- 不要な再計算 +- 大量データの非効率な処理 +- メモ化の不足 + +## 3. 詳細コード検証 + +### 該当箇所の徹底調査 +- コードの詳細な読解 +- 変数のスコープ確認 +- 関数の入出力検証 +- 副作用の特定 + +### 境界値での動作確認 +- 最小値での動作 +- 最大値での動作 +- 空データでの動作 +- null/undefinedでの動作 + +### エッジケースの検証 +- 想定外の入力 +- 極端なデータサイズ +- 並行実行 +- エラー発生時の動作 + +## 4. 関連コードの確認 + +### 呼び出し元の確認 +- どのような引数で呼ばれるか +- 呼び出しタイミング +- 複数回呼び出される可能性 + +### 呼び出し先の確認 +- 依存する関数の動作 +- 外部APIの仕様 +- ライブラリの使用方法 + +### テストコードの確認 +- 既存のテストケース +- テストでカバーされていない範囲 +- テストが失敗していないか + +## 5. 根本原因の特定 + +### 根本原因の定義 +- 技術的な原因 +- ビジネスロジックの問題 +- 設計上の問題 +- 実装の誤り + +### 原因の検証 +- コードから明らかな問題 +- ドキュメントとの照合 +- 仕様との整合性 + +## 6. 詳細原因分析結果のまとめ + +以下の形式で結果をファイルに出力してください。Write ツールを使用して保存してください。 + +```markdown +# バグ詳細原因分析 + +**実施日時**: {{実施日時}} +**分析者**: Claude Code + +[← インデックスに戻る](./index.md) | [初期調査](./initial_investigation.md) | [処理フロー](./flow_analysis.md) + +--- + +## 分析サマリー + +### バグの概要 +{{バグの概要}} + +### これまでの分析経緯 +{{初期調査と処理フロー分析で判明したこと}} + +--- + +## 原因候補の評価 + +### 候補1: {{原因の概要}} + +**確度**: ⭐⭐⭐⭐⭐ (5段階評価) + +**位置**: [相対パス:行番号](相対パス#L行番号) + +**問題の詳細**: +{{技術的な問題の詳細説明}} + +**該当コード**: +```{{language}} +{{問題のあるコードスニペット（20行程度）}} +``` + +**問題点の指摘**: +```{{language}} +// ❌ 問題のあるコード +{{問題のある部分を抽出}} + +// ✅ 期待される動作 +{{本来どうあるべきか}} +``` + +**なぜこれが問題か**: +{{この問題がバグを引き起こす理由を詳しく説明}} + +**バグとの関連性**: +{{報告されているバグ症状とどう結びつくか}} + +**検証内容**: +1. {{検証した内容1}} +2. {{検証した内容2}} +3. {{検証した内容3}} + +**検証結果**: +{{検証から得られた確証}} + +--- + +### 候補2: {{原因の概要}} + +（候補1と同様の形式で記載） + +--- + +### 候補3: {{原因の概要}} + +（確度が低い場合も含めて記載） + +--- + +## 根本原因の特定 + +### 最も可能性の高い根本原因 + +**結論**: {{根本原因の結論}} + +**原因の分類**: +- [ ] 未初期化変数 +- [ ] null/undefined参照 +- [ ] 配列の範囲外アクセス +- [ ] 型の不一致 +- [ ] 非同期処理の問題 +- [ ] ロジックの誤り +- [ ] メモリ関連 +- [ ] エラーハンドリングの不備 +- [x] {{該当する分類}} + +**技術的な説明**: +{{技術的な観点からの原因説明}} + +**発生メカニズム**: +``` +{{バグが発生するまでのステップバイステップの説明}} +例: +1. ユーザーが特定の操作を実行 + ↓ +2. {{ファイル名}}の{{関数名}}が呼ばれる + ↓ +3. 変数{{変数名}}が未初期化のまま参照される + ↓ +4. undefinedに対して{{操作}}を実行 + ↓ +5. エラーが発生またはバグが顕在化 +``` + +**なぜ今まで発見されなかったか**: +{{このバグが今まで見逃されていた理由}} + +--- + +## 詳細コード検証 + +### 問題箇所の詳細分析 + +#### [相対パス:行番号](相対パス#L行番号) + +**コード全体**: +```{{language}} +{{問題のある関数・メソッド全体（必要に応じて40行程度）}} +``` + +**問題のある部分**: +```{{language}} +{{特に問題のある5-10行を抽出}} +``` + +**詳細な説明**: +{{行ごとの詳細な分析}} + +**変数の状態**: +| 変数名 | この時点での値 | 期待される値 | 問題 | +|-------|-------------|-------------|------| +| `{{変数名}}` | `{{実際の値}}` | `{{期待値}}` | {{問題点}} | + +**実行フロー**: +``` +{{この箇所での実行フローの詳細}} +``` + +**エッジケースでの動作**: +- **正常系**: {{正常時の動作}} +- **異常系**: {{異常時の動作}} ← バグ発生 +- **境界値**: {{境界値での動作}} + +--- + +## 影響範囲の確認 + +### このバグが影響する範囲 + +#### 直接的な影響 +1. **{{影響1}}** + - 影響箇所: [相対パス:行番号](相対パス#L行番号) + - 影響内容: {{どのような影響があるか}} + +2. **{{影響2}}** + （同様の形式で記載） + +#### 間接的な影響 +1. **{{影響1}}** + - 影響経路: {{どのような経路で影響するか}} + - 影響内容: {{どのような影響があるか}} + +--- + +## 関連する問題点 + +### 類似のバグの可能性 + +#### 類似箇所1: [相対パス:行番号](相対パス#L行番号) +- **類似度**: 高/中/低 +- **問題の内容**: {{同じパターンの問題がある可能性}} +- **確認の必要性**: {{確認すべきかどうか}} + +### 設計上の問題 + +{{根本原因が設計に起因する場合}} +- **問題点**: {{設計上の問題}} +- **影響範囲**: {{どの程度広範囲に影響するか}} +- **抜本的な対策**: {{どのような対策が必要か}} + +--- + +## テストケースの検証 + +### 既存テストの確認 + +#### テストファイル: [相対パス](相対パス) + +**カバレッジ状況**: +- ✅ カバーされている: {{カバーされている内容}} +- ❌ カバーされていない: {{カバーされていない内容}} + +**このバグを検出できなかった理由**: +{{なぜ既存テストで検出できなかったか}} + +### 必要なテストケース + +#### テストケース1: {{テスト名}} +```{{language}} +// テストの疑似コード +test('{{テスト名}}', () => { + // Given: {{前提条件}} + // When: {{実行内容}} + // Then: {{期待結果}} +}) +``` + +**目的**: {{このテストで何を検証するか}} + +--- + +## 修正の方向性 + +### 推奨される修正方法 + +#### 修正案1: {{修正方法の概要}}（推奨） + +**変更箇所**: [相対パス:行番号](相対パス#L行番号) + +**修正前**: +```{{language}} +{{現在のコード}} +``` + +**修正後**: +```{{language}} +{{修正後のコード案}} +``` + +**修正の説明**: +{{なぜこの修正が適切か}} + +**メリット**: +- {{メリット1}} +- {{メリット2}} + +**デメリット**: +- {{デメリット1}}（あれば） + +**影響範囲**: +{{この修正による影響}} + +**テスト方針**: +{{どのようにテストすべきか}} + +--- + +#### 修正案2: {{修正方法の概要}}（代替案） + +（修正案1と同様の形式で記載） + +--- + +### 応急処置と恒久対策 + +#### 応急処置（短期） +{{すぐに実施できる対策}} + +#### 恒久対策（長期） +{{根本的な解決策}} + +--- + +## 再発防止策 + +### コードレベルの対策 +1. {{対策1}} +2. {{対策2}} +3. {{対策3}} + +### プロセスレベルの対策 +1. {{対策1}}（例: レビュープロセスの改善） +2. {{対策2}}（例: テストカバレッジの向上） +3. {{対策3}}（例: リント設定の追加） + +### 設計レベルの対策 +{{設計の見直しが必要な場合}} + +--- + +## 参考情報 + +### 関連ドキュメント +- {{関連するドキュメントや仕様}} + +### 外部参考資料 +- {{参考になる記事やドキュメントのURL}} + +--- + +*この詳細原因分析の結果は、最終レポートで総括されます。* +``` + +# 分析の注意点 + +- 根本原因の特定には確実な根拠が必要 +- 推測と確実な事実を明確に区別する +- 複数の原因候補がある場合は確度を評価する +- 修正案は具体的なコード例を示す +- **すべてのファイルパスは相対パスで記載する（絶対パスは使用しない）** +- **ファイルは500行以内を目標とする。超える場合は分割する** + +分析が完了したら、インデックスファイル（{{ベースディレクトリ}}/index.md）を更新して、詳細原因分析へのリンクを有効化してください。 + + + +あなたはバグ原因特定のエキスパートです。これまでのすべての分析結果を統合し、包括的な最終レポートを作成してください。 + +# レポート作成対象の情報 + +バグの概要: {{バグの概要}} +分析ファイルリスト: {{分析ファイルリスト}} +最終レポートファイル名: {{ベースディレクトリ}}/final_report.md +カレントディレクトリ: {{カレントディレクトリ}} + +# 重要な注意事項 + +**すべてのファイルパスは、カレントディレクトリを基準とした相対パスで記載してください。** +**絶対パス（/Users/... や C:\\... など）は使用しないでください。** +**このファイルは500行以内を目標としてください。** + +# 最終レポート作成手順 + +## 1. 全分析結果の読み込み + +- {{ベースディレクトリ}}/initial_investigation.md を Read で読み込む +- {{ベースディレクトリ}}/flow_analysis.md を Read で読み込む +- {{ベースディレクトリ}}/root_cause_analysis.md を Read で読み込む +- 各ファイルの内容を把握し、重要なポイントを抽出する + +## 2. 情報の統合とサマリー作成 + +- バグの根本原因を明確にする +- 分析プロセスで得られた重要な発見をまとめる +- 修正方針と優先順位を決定する +- テスト戦略を策定する + +## 3. エグゼクティブサマリーの作成 + +- 非技術者にも理解できる概要 +- 技術的な詳細は別セクションで説明 +- 結論を先に、詳細は後で + +## 4. 最終レポートの出力 + +以下の形式で結果をファイルに出力してください。Write ツールを使用して保存してください。 + +```markdown +# バグ原因分析 - 最終レポート + +**実施日時**: {{実施日時}} +**分析者**: Claude Code + +--- + +## ナビゲーション + +- [インデックス](./{filename}_index.md) +- [初期調査](./initial_investigation.md) +- [処理フロー分析](./flow_analysis.md) +- [詳細原因分析](./root_cause_analysis.md) + +--- + +## エグゼクティブサマリー + +### バグの概要 +{{バグの簡潔な説明}} + +### 根本原因 +{{根本原因を1-2文で簡潔に}} + +### 影響度 +**深刻度**: 🔴 高 / 🟡 中 / 🟢 低 + +**影響範囲**: {{どの機能に影響するか}} + +### 推奨される対応 +**優先度**: 🔴 即座に対応 / 🟡 早急に対応 / 🟢 計画的に対応 + +**修正工数**: {{概算時間}} + +**リリースへの影響**: {{リリースを遅らせるべきか}} + +--- + +## バグの詳細情報 + +### 発生条件 +{{どのような条件でバグが発生するか}} + +### 症状 +{{ユーザーから見えるバグの症状}} + +### エラー情報 +{{エラーメッセージやスタックトレース（ある場合）}} + +### 再現手順 +1. {{ステップ1}} +2. {{ステップ2}} +3. {{ステップ3}} +4. {{バグが発生}} + +--- + +## 分析結果のサマリー + +### 分析プロセス +1. **初期調査**: {{何を調査したか}} +2. **処理フロー分析**: {{何を分析したか}} +3. **詳細原因分析**: {{何を特定したか}} + +### 主要な発見事項 + +#### 発見1: {{発見内容}} +- **重要度**: 高/中/低 +- **詳細**: {{詳しい説明}} +- **参照**: [詳細](./{filename}_{{section}}.md) + +#### 発見2: {{発見内容}} +（同様の形式で記載） + +--- + +## 根本原因の詳細 + +### 技術的な原因 + +**分類**: {{原因のカテゴリ}}（例: null/undefined参照、ロジックの誤り、非同期処理の問題など） + +**問題箇所**: [相対パス:行番号](相対パス#L行番号) + +**問題のコード**: +```{{language}} +{{問題のあるコードスニペット（10-20行）}} +``` + +**何が問題か**: +{{技術的な観点からの詳細な説明}} + +**なぜバグが発生するか**: +``` +{{バグ発生のメカニズムをステップバイステップで説明}} +1. {{ステップ1}} + ↓ +2. {{ステップ2}} + ↓ +3. {{バグ発生}} +``` + +### ビジネスロジック上の問題 +{{ビジネスロジックに関連する問題がある場合}} + +### 設計上の問題 +{{設計レベルの問題がある場合}} + +--- + +## 修正方針 + +### 推奨される修正方法 + +**概要**: {{修正の概要を1-2文で}} + +**変更箇所**: [相対パス:行番号](相対パス#L行番号) + +**修正前**: +```{{language}} +{{現在のコード}} +``` + +**修正後**: +```{{language}} +{{修正後のコード}} +``` + +**修正の説明**: +{{なぜこの修正が適切か}} + +**変更の影響範囲**: +- {{影響1}} +- {{影響2}} +- {{影響3}} + +**破壊的変更**: ✅ あり / ❌ なし + +--- + +### 代替案 +{{他の修正方法がある場合}} + +--- + +## 修正作業の詳細 + +### 実装ステップ + +1. **{{ステップ1}}** + - ファイル: [相対パス](相対パス) + - 作業内容: {{具体的な作業}} + - 所要時間: {{概算}} + +2. **{{ステップ2}}** + （同様の形式で記載） + +### 注意点 +- {{注意点1}} +- {{注意点2}} +- {{注意点3}} + +--- + +## テスト戦略 + +### 修正の検証方法 + +#### 手動テスト +1. **{{テストケース1}}** + - 手順: {{テスト手順}} + - 期待結果: {{期待される結果}} + +2. **{{テストケース2}}** + （同様の形式で記載） + +#### 自動テスト + +**追加すべきユニットテスト**: +```{{language}} +// テストの疑似コード +test('{{テスト名}}', () => { + // Given: {{前提条件}} + // When: {{実行内容}} + // Then: {{期待結果}} +}) +``` + +**追加すべき統合テスト**: +{{統合テストの内容}} + +**E2Eテスト**: +{{E2Eテストの内容}} + +### 回帰テスト +{{既存機能への影響を確認するテスト}} + +### テストカバレッジ目標 +- **変更箇所のカバレッジ**: {{目標値}}% +- **関連箇所のカバレッジ**: {{目標値}}% + +--- + +## 影響範囲と関連修正 + +### 直接的な影響 + +#### [相対パス:行番号](相対パス#L行番号) +- **影響内容**: {{どのような影響があるか}} +- **必要な修正**: {{修正が必要か}} + +### 間接的な影響 + +#### [相対パス:行番号](相対パス#L行番号) +- **影響内容**: {{どのような影響があるか}} +- **確認事項**: {{確認すべきこと}} + +### 類似のバグの可能性 + +#### [相対パス:行番号](相対パス#L行番号) +- **類似度**: 高/中/低 +- **確認の必要性**: {{確認すべきか}} +- **対応方針**: {{どう対応するか}} + +--- + +## 再発防止策 + +### 即座に実施すべき対策 + +1. **{{対策1}}** + - 内容: {{具体的な対策内容}} + - 実施者: {{担当者}} + - 期限: {{期限}} + +2. **{{対策2}}** + （同様の形式で記載） + +### コードレベルの改善 + +#### リント設定の追加 +```{{language}} +// ESLint/TSConfig などの設定例 +{{設定の追加内容}} +``` + +#### 型定義の強化 +{{TypeScriptの型定義を厳格にするなど}} + +#### テストカバレッジの向上 +{{カバレッジ目標と計画}} + +### プロセスの改善 + +#### コードレビュー +- {{改善ポイント1}} +- {{改善ポイント2}} + +#### テストプロセス +- {{改善ポイント1}} +- {{改善ポイント2}} + +#### ドキュメント +- {{改善ポイント1}} +- {{改善ポイント2}} + +### 設計の見直し +{{設計レベルの改善が必要な場合}} + +--- + +## タイムライン + +### 修正作業のスケジュール + +| フェーズ | 作業内容 | 担当 | 期間 | 状態 | +|---------|---------|------|------|------| +| 1 | {{作業1}} | {{担当者}} | {{期間}} | ⏳ 未着手 | +| 2 | {{作業2}} | {{担当者}} | {{期間}} | ⏳ 未着手 | +| 3 | {{作業3}} | {{担当者}} | {{期間}} | ⏳ 未着手 | +| 4 | {{作業4}} | {{担当者}} | {{期間}} | ⏳ 未着手 | + +**総所要時間**: {{合計時間}} + +--- + +## リスクと課題 + +### 既知のリスク + +#### リスク1: {{リスクの内容}} +- **発生確率**: 高/中/低 +- **影響度**: 高/中/低 +- **対策**: {{リスク軽減策}} + +#### リスク2: {{リスクの内容}} +（同様の形式で記載） + +### 未解決の課題 + +1. **{{課題1}}** + - 詳細: {{課題の詳細}} + - 対応方針: {{どう対応するか}} + +2. **{{課題2}}** + （同様の形式で記載） + +--- + +## 関係者への推奨事項 + +### 開発チームへ +- {{推奨事項1}} +- {{推奨事項2}} +- {{推奨事項3}} + +### QAチームへ +- {{推奨事項1}} +- {{推奨事項2}} + +### プロダクトオーナーへ +- {{推奨事項1}} +- {{推奨事項2}} + +--- + +## 付録 + +### 用語集 +- **{{用語1}}**: {{説明}} +- **{{用語2}}**: {{説明}} + +### 参考資料 +- [{{資料1}}]({{URL}}) +- [{{資料2}}]({{URL}}) + +### 分析ファイル一覧 +1. [初期調査](./initial_investigation.md) +2. [処理フロー分析](./flow_analysis.md) +3. [詳細原因分析](./root_cause_analysis.md) + +--- + +## 結論 + +{{分析全体の結論を2-3段落でまとめる}} + +--- + +**分析完了日**: {{日付}} +**分析者**: Claude Code +**レビュー状況**: ⏳ レビュー待ち + +--- + +*このレポートは自動生成されたものです。内容についてはチームでレビューしてください。* +``` + +# レポート作成の注意点 + +- エグゼクティブサマリーは簡潔に（1ページ以内） +- 技術的な詳細は適切なセクションに配置 +- 具体的で実行可能な推奨事項を提示 +- タイムラインは現実的な見積もりを +- **すべてのファイルパスは相対パスで記載する（絶対パスは使用しない）** +- **ファイルは500行以内を目標とする** + +レポート作成が完了したら、インデックスファイル（{{ベースディレクトリ}}/index.md）を最終更新して、すべての分析へのリンクを有効化し、クイックサマリーを更新してください。 + diff --git a/commands/dcs/feature-rubber-duck.md b/commands/dcs/feature-rubber-duck.md new file mode 100644 index 0000000..e9ae5d4 --- /dev/null +++ b/commands/dcs/feature-rubber-duck.md @@ -0,0 +1,816 @@ +--- +description: アイデアを整理して実現可能なPRDを作成する +allowed-tools: Read, Glob, Grep, Task, Bash, WebSearch, WebFetch, AskUserQuestion +argument-hint: [機能やアイデアの概要（任意）] +--- +曖昧なアイデアや要望を対話を通じて整理し、実現可能なPRD（Product Requirements Document）を作成します。コードベースの調査、技術検証、要件の具体化を段階的に進めます。 + +# context + +出力ディレクトリ=".dcs" +カレントディレクトリ={{プロジェクトルート}} +セッションファイルリスト=[] +イテレーション回数=0 +最大イテレーション=10 + +# step + +- $1 がある場合、初期アイデアとして記録する +- $1 がない場合、ユーザーに「どのような機能やアイデアについて相談したいですか？」と尋ねる +- AskUserQuestion ツールを使って初期ヒアリングを実施し、context を更新する +- 収集した context の内容をユーザーに宣言する +- step2 を実行する + +## step2: セッション初期化 + +- 既存の出力ファイルを確認して、重複しないナンバリングを決定する + - {{出力ディレクトリ}}/{{timestamp}}_* を検索 + - 今回の内容を簡単に英語化したもの（例: "order_export", "payment_integration"）を作成 + - 同じ timestamp と内容で既存ディレクトリがある場合、末尾の連番を +1 する + - ベースディレクトリを "{{出力ディレクトリ}}/{{timestamp}}_{{内容の英語化}}" とする + - 例: ".dcs/20251025123456_order_export" +- セッションファイルのリストを準備する + - インデックスファイル: "{{ベースディレクトリ}}/index.md" + - 会話履歴ファイル: "{{ベースディレクトリ}}/conversation.md" + - コンテキストファイル: "{{ベースディレクトリ}}/context.md" + - 調査結果ファイル: "{{ベースディレクトリ}}/research.md" + - PRDファイル: "{{ベースディレクトリ}}/prd.md" +- すべてのファイル名を セッションファイルリスト に追加する +- インデックスファイルを作成し、セッション情報を記録する +- step3 を実行する + +## step3: 対話セッション + +- イテレーション回数を +1 する +- 現在の理解状況をユーザーに確認する + - これまでの整理内容を簡潔にまとめる + - 不明点や確認したい点をリストアップする +- ユーザーからの追加情報や質問への回答を受け取る +- 必要に応じて以下を実施する： + - **コードベース調査**: Task ツールで関連コードを検索・分析 + - **技術調査**: WebSearch/WebFetch で技術情報を収集 + - **既存機能確認**: Read/Grep で既存実装を確認 +- 新しい情報を context に統合し、整理する +- 会話履歴ファイルとコンテキストファイルを更新する +- 調査を実施した場合は調査結果ファイルを更新する +- 次のアクションを判断する ルール に基づいて判断し、該当するステップに進む + +## step4: PRD作成 + +- の内容を使って、Task ツールで PRD ファイルを作成する + - subagent_type: "general-purpose" + - description: "PRD（Product Requirements Document）の作成" + - prompt: PRD テンプレートの内容を context で埋めた完全なプロンプト + - PRD ファイル名: "{{ベースディレクトリ}}/prd.md" +- インデックスファイルを最終更新する +- 全てのセッションファイルのパスを整理して表示する + - インデックスファイル + - 会話履歴ファイル + - コンテキストファイル + - 調査結果ファイル（該当する場合） + - PRDファイル +- セッション完了をユーザーに報告する +- ユーザーに次のアクションを提案する + - PRDの内容を実装に進めるか + - さらに詳細化が必要か + - 影響範囲分析を実施するか + +# rules + +## 初期ヒアリングの質問 + +AskUserQuestion ツールを使って、以下の質問を実施する： + +### 質問1: アイデアのカテゴリ +- **質問**: このアイデアはどのカテゴリに該当しますか？ +- **header**: "カテゴリ" +- **multiSelect**: false +- **options**: + - "新機能の追加" - 全く新しい機能を追加したい + - "既存機能の改善" - 既存の機能を改善・拡張したい + - "技術的な改善" - パフォーマンス、アーキテクチャなどの技術的改善 + - "バグ修正・問題解決" - 既知の問題を解決したい + +### 質問2: 優先度と緊急度 +- **質問**: この機能の優先度はどの程度ですか？ +- **header**: "優先度" +- **multiSelect**: false +- **options**: + - "高 - すぐに必要" - ビジネスクリティカル、早急に必要 + - "中 - 近い将来必要" - 重要だが少し時間的余裕がある + - "低 - あると良い" - Nice to have、時間があれば実装したい + - "調査中 - まだ決まっていない" - 優先度を判断するために相談したい + +### 質問3: 現状の理解度 +- **質問**: この機能に関連する技術やコードベースについて、どの程度理解していますか？ +- **header**: "理解度" +- **multiSelect**: false +- **options**: + - "詳しく理解している" - 技術スタックやコードベースを把握している + - "ある程度理解している" - 概要は理解しているが詳細は不明 + - "あまり理解していない" - 技術的な詳細はよくわからない + - "全く理解していない" - 一から教えてほしい + +contextとして以下を保持する： +- アイデアの概要 +- カテゴリ +- 優先度 +- 理解度 +- 関連する既存機能（判明している場合） +- 技術的制約（判明している場合） + +## 次のアクションを判断するルール + +各イテレーションの終わりに、以下の基準で次のアクションを判断する： + +### step3 を継続する条件（以下のいずれかに該当） +- ユーザーのアイデアがまだ曖昧で具体化が必要 +- 追加の技術調査や検証が必要 +- 既存コードベースとの統合方法が不明確 +- ユーザーからの追加情報待ち +- イテレーション回数が最大イテレーション未満 + +### step4 に進む条件（以下のすべてに該当） +- アイデアが十分に具体化されている +- 技術的な実現可能性が確認されている +- 要件が明確に定義されている +- ユーザーが PRD 作成に合意している + +### セッション終了条件 +- イテレーション回数が最大イテレーションに達した +- ユーザーが明示的にセッション終了を希望した + +## ファイル名のルール + +### timestamp の形式 +- yyyyMMddHHmmss 形式（例: 20251025123456） + +### 内容の英語化のルール +- アイデアを簡潔な英語に変換する +- スネークケース（snake_case）を使用 +- 最大30文字程度に収める +- 例: + - "注文履歴のエクスポート機能" → "order_export" + - "決済方法の追加" → "payment_integration" + - "パフォーマンス改善" → "performance_improvement" + - "CSVインポート" → "csv_import" + +### セッションファイル名のルール +- `index.md` - セッション全体のインデックス +- `conversation.md` - 会話履歴の記録 +- `context.md` - 整理されたコンテキスト情報 +- `research.md` - 技術調査・コード調査の結果 +- `prd.md` - 最終的なPRD + +### 完全なファイル名の例 +- `.dcs/20251025123456_order_export/index.md` +- `.dcs/20251025123456_order_export/conversation.md` +- `.dcs/20251025123456_order_export/context.md` +- `.dcs/20251025123456_order_export/research.md` +- `.dcs/20251025123456_order_export/prd.md` + +## ファイルパスの記載ルール + +- **カレントディレクトリを基準とした相対パスを使用する** +- フルパス（絶対パス）は記載しない +- 例: + - ❌ `/Users/makotan/projects/ensemble-si/backend/src/main/kotlin/si/ensemble/api/` + - ✅ `backend/src/main/kotlin/si/ensemble/api/` + +## 対話のガイドライン + +### 質問の仕方 +- オープンエンドな質問から始める +- 具体的な選択肢を提示して絞り込む +- 技術的な詳細は段階的に深掘りする +- ユーザーの理解度に合わせた説明をする + +### 整理の方法 +- 5W1H（Who, What, When, Where, Why, How）を意識する +- ユーザーストーリー形式で要件を整理する +- 技術的な実現方法と要件を分けて考える +- 優先順位をつけて整理する + +### 調査のタイミング +- コードベースの既存機能を確認する必要がある時 +- 技術的な実現可能性を検証する必要がある時 +- 類似機能の実装例を探す時 +- 外部ライブラリやAPIの情報が必要な時 + +### Task 利用のガイドライン +- 複雑なコードベース調査は Task で実施する +- 会話が長くなりコンテキストが複雑になってきたら Task を使う +- 調査結果は必ずファイルに保存する + +## イテレーション管理 + +- 各イテレーションで以下を実施する： + 1. 現状の理解を整理して提示 + 2. 不明点や確認事項を質問 + 3. 必要な調査を実施 + 4. 新しい情報を統合 + 5. ファイルを更新 + 6. 次のアクションを判断 + +- イテレーション情報を会話履歴ファイルに記録する +- 最大イテレーション（10回）に達したら、現状をまとめて PRD 作成を提案する + +# info + +## インデックスファイルのフォーマット + +```markdown +# ラバーダックセッション - インデックス + +**開始日時**: {{開始日時}} +**最終更新**: {{最終更新日時}} +**ファシリテーター**: Claude Code + +--- + +## セッション概要 + +### アイデア +{{アイデアの概要}} + +### カテゴリ +{{カテゴリ}} + +### 優先度 +{{優先度}} + +### 現在のステータス +- **イテレーション**: {{現在のイテレーション}}/{{最大イテレーション}} +- **フェーズ**: 対話中 / PRD作成完了 +- **進捗**: {{進捗状況の簡単な説明}} + +--- + +## セッションファイル一覧 + +- [会話履歴](./conversation.md) - 全ての対話記録 +- [整理されたコンテキスト](./context.md) - 要件と技術情報の整理 +- [調査結果](./research.md) - 技術調査・コード調査の結果 +- [PRD](./prd.md) - 最終的なProduct Requirements Document + +--- + +## クイックサマリー + +### 主要な要件 +1. {{要件1}} +2. {{要件2}} +3. {{要件3}} + +### 技術的な考慮事項 +- {{考慮事項1}} +- {{考慮事項2}} + +### 次のステップ +- {{次にやるべきこと}} + +--- + +*セッションの詳細は各ファイルを参照してください。* +``` + +## 会話履歴ファイルのフォーマット + +```markdown +# ラバーダックセッション - 会話履歴 + +**開始日時**: {{開始日時}} +**最終更新**: {{最終更新日時}} + +[← インデックスに戻る](./index.md) + +--- + +## イテレーション 1 + +**日時**: {{日時}} + +### ユーザー +{{ユーザーの発言}} + +### Claude +{{Claudeの応答}} + +### アクション +- {{実施したアクション1}} +- {{実施したアクション2}} + +--- + +## イテレーション 2 + +（同様の形式で記録） + +--- + +*会話は時系列順に記録されています。* +``` + +## コンテキストファイルのフォーマット + +```markdown +# ラバーダックセッション - コンテキスト + +**最終更新**: {{最終更新日時}} + +[← インデックスに戻る](./index.md) + +--- + +## アイデアの概要 + +{{アイデアの詳細な説明}} + +--- + +## ユーザーストーリー + +### As a {{ユーザー種別}} +I want to {{やりたいこと}} +So that {{目的・理由}} + +--- + +## 要件定義 + +### 機能要件 +1. **{{要件1のタイトル}}** + - 説明: {{詳細説明}} + - 優先度: 高/中/低 + - 実現方法: {{技術的なアプローチ}} + +2. **{{要件2のタイトル}}** + （同様の形式） + +### 非機能要件 +- **パフォーマンス**: {{パフォーマンス要件}} +- **セキュリティ**: {{セキュリティ要件}} +- **可用性**: {{可用性要件}} +- **保守性**: {{保守性要件}} + +--- + +## 技術的考慮事項 + +### 既存システムとの統合 +- {{統合ポイント1}} +- {{統合ポイント2}} + +### 技術スタック +- **Frontend**: {{使用する技術}} +- **Backend**: {{使用する技術}} +- **Database**: {{使用する技術}} +- **その他**: {{その他の技術}} + +### 制約条件 +- {{制約1}} +- {{制約2}} + +--- + +## ユーザーインターフェース + +### 画面・機能一覧 +1. {{画面名1}} - {{説明}} +2. {{画面名2}} - {{説明}} + +### データフロー +{{データの流れを説明}} + +--- + +## 疑問点・未解決事項 + +- [ ] {{疑問点1}} +- [ ] {{疑問点2}} +- [x] {{解決済みの疑問点}} + +--- + +*このコンテキストは対話を通じて継続的に更新されています。* +``` + +## 調査結果ファイルのフォーマット + +```markdown +# ラバーダックセッション - 調査結果 + +**最終更新**: {{最終更新日時}} + +[← インデックスに戻る](./index.md) + +--- + +## 調査1: {{調査のタイトル}} + +**実施日時**: {{日時}} +**目的**: {{調査の目的}} + +### 調査方法 +- {{使用したツールや方法}} + +### 調査結果 +{{調査で分かったこと}} + +### 関連ファイル +- [{{ファイルパス1}}]({{相対パス1}}) +- [{{ファイルパス2}}]({{相対パス2}}) + +### 結論 +{{調査から得られた結論}} + +--- + +## 調査2: {{調査のタイトル}} + +（同様の形式） + +--- + +## 技術検証サマリー + +### 実現可能性 +- **評価**: 高/中/低 +- **理由**: {{評価の理由}} + +### リスク +1. {{リスク1}} - 対策: {{対策}} +2. {{リスク2}} - 対策: {{対策}} + +### 推奨アプローチ +{{推奨する技術的アプローチ}} + +--- + +*調査結果は時系列順に記録されています。* +``` + + +あなたは製品要件定義のエキスパートです。以下の情報に基づいて、実現可能なPRD（Product Requirements Document）を作成してください。 + +# PRD作成に必要な情報 + +アイデアの概要: {{アイデアの概要}} +カテゴリ: {{カテゴリ}} +優先度: {{優先度}} +セッションファイルリスト: {{セッションファイルリスト}} +ベースディレクトリ: {{ベースディレクトリ}} +カレントディレクトリ: {{カレントディレクトリ}} + +# 重要な注意事項 + +**すべてのファイルパスは、カレントディレクトリを基準とした相対パスで記載してください。** +**絶対パス（/Users/... や C:\\... など）は使用しないでください。** +**PRDは読みやすく、実装者が理解しやすい形式で記述してください。** + +# PRD作成手順 + +## 1. セッションファイルの読み込み + +- {{セッションファイルリスト}} に含まれるすべてのファイルを Read で読み込む +- 会話履歴、コンテキスト、調査結果を把握する + +## 2. 要件の整理と優先順位付け + +- 機能要件を整理し、優先順位をつける +- 非機能要件を明確化する +- MVP（Minimum Viable Product）の範囲を定義する + +## 3. 技術的実現方法の明確化 + +- 調査結果に基づいて技術的アプローチを決定する +- 既存システムとの統合方法を明記する +- 必要な変更箇所をリストアップする + +## 4. タスク分解 + +- 実装タスクを具体的に分解する +- 各タスクの見積もりと優先順位を設定する +- タスク間の依存関係を明確化する + +## 5. リスクと対策 + +- 技術的リスクを特定する +- ビジネスリスクを評価する +- それぞれの対策を定義する + +## 6. PRDファイルの出力 + +以下の出力形式で {{ベースディレクトリ}}/prd.md に結果を保存してください。 + +# PRD出力形式 + +```markdown +# PRD: {{機能名}} + +**作成日**: {{作成日}} +**最終更新**: {{最終更新日}} +**ステータス**: Draft / Review / Approved +**優先度**: {{優先度}} + +[← インデックスに戻る](./index.md) + +--- + +## 1. エグゼクティブサマリー + +### 概要 +{{機能の概要を3-5行で簡潔に}} + +### 背景と目的 +{{なぜこの機能が必要なのか}} + +### 期待される成果 +- {{成果1}} +- {{成果2}} +- {{成果3}} + +--- + +## 2. ユーザーストーリー + +### プライマリーユーザーストーリー +``` +As a {{ユーザー種別}} +I want to {{やりたいこと}} +So that {{目的・理由}} +``` + +### セカンダリーユーザーストーリー +（必要に応じて追加） + +--- + +## 3. 機能要件 + +### 3.1 MVP（Minimum Viable Product）範囲 + +#### 必須機能 +1. **{{機能1のタイトル}}** + - **説明**: {{詳細説明}} + - **受け入れ基準**: + - [ ] {{基準1}} + - [ ] {{基準2}} + - **優先度**: 高 + - **見積もり**: {{工数}} + +2. **{{機能2のタイトル}}** + （同様の形式） + +#### 除外する機能（将来的に実装予定） +- {{除外機能1}} - 理由: {{理由}} +- {{除外機能2}} - 理由: {{理由}} + +### 3.2 フェーズ2以降の機能 +（MVP後に実装予定の機能） + +--- + +## 4. 非機能要件 + +### 4.1 パフォーマンス +- **応答時間**: {{要件}} +- **スループット**: {{要件}} +- **リソース使用量**: {{要件}} + +### 4.2 セキュリティ +- **認証・認可**: {{要件}} +- **データ保護**: {{要件}} +- **監査ログ**: {{要件}} + +### 4.3 可用性・信頼性 +- **稼働率**: {{目標値}} +- **エラーハンドリング**: {{要件}} +- **データバックアップ**: {{要件}} + +### 4.4 保守性・拡張性 +- **コード品質**: {{基準}} +- **テストカバレッジ**: {{目標値}} +- **ドキュメント**: {{要件}} + +--- + +## 5. 技術仕様 + +### 5.1 アーキテクチャ + +#### システム構成 +{{システム構成図や説明}} + +#### コンポーネント +- **Frontend**: {{使用技術とアプローチ}} +- **Backend**: {{使用技術とアプローチ}} +- **Database**: {{使用技術とアプローチ}} + +### 5.2 データモデル + +#### 新規テーブル・リソース +1. **{{テーブル名1}}** + - 目的: {{目的}} + - 主要フィールド: + - `{{フィールド1}}`: {{型}} - {{説明}} + - `{{フィールド2}}`: {{型}} - {{説明}} + +#### 既存テーブル・リソースの変更 +1. **{{テーブル名}}** + - 変更内容: {{変更の説明}} + - 影響: {{影響範囲}} + +### 5.3 API設計 + +#### 新規エンドポイント +1. **POST /api/{{エンドポイント}}** + - 目的: {{目的}} + - リクエスト: {{リクエスト形式}} + - レスポンス: {{レスポンス形式}} + +#### 既存エンドポイントの変更 +1. **GET /api/{{エンドポイント}}** + - 変更内容: {{変更の説明}} + - 後方互換性: {{互換性の保証方法}} + +### 5.4 UI/UX設計 + +#### 画面一覧 +1. **{{画面名1}}** + - 目的: {{目的}} + - 主要要素: {{要素のリスト}} + - ワイヤーフレーム: {{リンクまたは説明}} + +#### ユーザーフロー +{{ユーザーの操作フローを説明}} + +--- + +## 6. 実装計画 + +### 6.1 タスク分解 + +#### フェーズ1: 基盤実装（見積もり: {{工数}}） +1. **{{タスク1}}** + - 内容: {{詳細}} + - 担当: {{担当者またはチーム}} + - 見積もり: {{工数}} + - 依存: なし + +2. **{{タスク2}}** + - 内容: {{詳細}} + - 担当: {{担当者またはチーム}} + - 見積もり: {{工数}} + - 依存: {{タスク1}} + +#### フェーズ2: 機能実装（見積もり: {{工数}}） +（同様の形式） + +#### フェーズ3: テスト・統合（見積もり: {{工数}}） +（同様の形式） + +### 6.2 マイルストーン + +| マイルストーン | 完了条件 | 期日 | +|--------------|---------|------| +| {{マイルストーン1}} | {{完了条件}} | {{期日}} | +| {{マイルストーン2}} | {{完了条件}} | {{期日}} | + +--- + +## 7. テスト戦略 + +### 7.1 単体テスト +- **対象**: {{テスト対象}} +- **カバレッジ目標**: {{目標値}} +- **重点項目**: {{重点的にテストすべき項目}} + +### 7.2 統合テスト +- **対象**: {{テスト対象}} +- **シナリオ**: {{主要なテストシナリオ}} + +### 7.3 E2Eテスト +- **対象**: {{テスト対象}} +- **ユーザーシナリオ**: {{主要なユーザーシナリオ}} + +### 7.4 パフォーマンステスト +- **対象**: {{テスト対象}} +- **負荷条件**: {{負荷条件}} +- **合格基準**: {{合格基準}} + +--- + +## 8. リスクと対策 + +### 8.1 技術的リスク + +| リスク | 影響度 | 発生確率 | 対策 | +|--------|--------|---------|------| +| {{リスク1}} | 高/中/低 | 高/中/低 | {{対策}} | +| {{リスク2}} | 高/中/低 | 高/中/低 | {{対策}} | + +### 8.2 ビジネスリスク + +| リスク | 影響度 | 発生確率 | 対策 | +|--------|--------|---------|------| +| {{リスク1}} | 高/中/低 | 高/中/低 | {{対策}} | + +--- + +## 9. 依存関係と前提条件 + +### 9.1 技術的依存 +- {{依存1}} - {{状態}} +- {{依存2}} - {{状態}} + +### 9.2 ビジネス的依存 +- {{依存1}} - {{状態}} +- {{依存2}} - {{状態}} + +### 9.3 前提条件 +- {{前提1}} +- {{前提2}} + +--- + +## 10. 成功の指標（KPI） + +### 定量的指標 +- **{{指標1}}**: 目標値 {{値}}、測定方法 {{方法}} +- **{{指標2}}**: 目標値 {{値}}、測定方法 {{方法}} + +### 定性的指標 +- {{指標1}} +- {{指標2}} + +--- + +## 11. リリース計画 + +### 11.1 リリース戦略 +- **リリース方法**: {{方法}}（例: カナリアリリース、段階的ロールアウト） +- **ロールバック計画**: {{ロールバック方法}} + +### 11.2 移行計画 +（既存機能からの移行が必要な場合） +- {{移行ステップ1}} +- {{移行ステップ2}} + +### 11.3 トレーニング・ドキュメント +- **ユーザードキュメント**: {{必要なドキュメント}} +- **開発者ドキュメント**: {{必要なドキュメント}} +- **トレーニング**: {{必要なトレーニング}} + +--- + +## 12. 関連ドキュメント + +- [会話履歴](./conversation.md) - セッションの全対話記録 +- [コンテキスト](./context.md) - 整理された要件情報 +- [調査結果](./research.md) - 技術調査の詳細 + +--- + +## 13. 承認 + +| 役割 | 名前 | 承認日 | ステータス | +|------|------|--------|-----------| +| プロダクトオーナー | {{名前}} | {{日付}} | Pending/Approved | +| テックリード | {{名前}} | {{日付}} | Pending/Approved | +| アーキテクト | {{名前}} | {{日付}} | Pending/Approved | + +--- + +## 変更履歴 + +| 日付 | バージョン | 変更内容 | 変更者 | +|------|----------|---------|--------| +| {{日付}} | 1.0 | 初版作成 | Claude Code | + +--- + +*このPRDは対話セッションを通じて作成されました。実装前に関係者のレビューと承認を得てください。* +``` + +# PRD作成の注意点 + +- 実装者が理解しやすい具体的な内容にする +- 技術的な実現方法を明確に記述する +- タスクは実装可能な粒度に分解する +- リスクと対策を現実的に評価する +- **すべてのファイルパスは相対パスで記載する（絶対パスは使用しない）** +- 既存のコードベースや技術スタックに基づいた現実的な内容にする + +必ず Write ツールを使用して、{{ベースディレクトリ}}/prd.md に結果を保存してください。 + + +# 注意事項 + +- ユーザーの理解度に合わせた説明を心がける +- 技術的な詳細は段階的に深掘りする +- 定期的に理解状況を確認し、必要に応じて軌道修正する +- 実現可能性を常に念頭に置き、現実的な提案をする +- 会話が長くなったら適切に Task を利用してコンテキストを整理する +- すべてのファイルパスは相対パスで記載する +- セッション内容は継続的にファイルに保存する diff --git a/commands/dcs/impact-analysis.md b/commands/dcs/impact-analysis.md new file mode 100644 index 0000000..98612af --- /dev/null +++ b/commands/dcs/impact-analysis.md @@ -0,0 +1,1076 @@ +--- +description: 影響範囲分析を実施する +allowed-tools: Read, Glob, Grep, Task, Bash +argument-hint: [変更対象（ファイルパス/関数名/クラス名/自然言語）] +--- +変更対象の影響範囲を分析し、修正が必要なファイルとリスク評価を提供します。一時ファイルを作成せず直接 Task で実行し、必要に応じて追加調査を繰り返し、最後に全体サマリーを作成します。 + +# context + +出力ディレクトリ=".dcs" +カレントディレクトリ={{プロジェクトルート}} +分析ファイルリスト=[] + +# step + +- $1 がない場合、「引数に変更対象を指定してください（例: ファイルパス、関数名、クラス名、または自然言語）」と言って終了する +- $1 の内容を簡潔に説明する +- AskUserQuestion ツールを使って以下の質問を順番に実施し、context を更新する： + 1. 変更対象の種類を確認 + 2. 変更内容の種類を確認 + 3. 分析の目的を確認 + 4. 除外条件の有無を確認 +- 収集した context の内容をまとめてユーザに宣言する +- step2 を実行する + +## step2 + +- 既存の出力ファイルを確認して、重複しないナンバリングを決定する + - {{出力ディレクトリ}}/{{timestamp}}_* を検索 + - 今回の内容を簡単に英語化したもの（例: "calculate_function", "user_model"）を作成 + - 同じ timestamp と内容で既存ディレクトリがある場合、末尾の連番を +1 する + - ベースディレクトリを "{{出力ディレクトリ}}/{{timestamp}}_{{内容の英語化}}" とする + - 例: ".dcs/20251008_123456_calculate_function" + - 例: ".dcs/20251008_123456_user_model" +- 分析結果ファイルのリストを準備する（セクション別分割ファイル） + - インデックスファイル: "{{ベースディレクトリ}}/index.md" + - サマリーファイル: "{{ベースディレクトリ}}/summary.md" + - 各層別ファイル: "core.md", "api.md", "service.md", "data.md", "ui.md", "test.md", "config.md", "other.md" + - その他: "external.md", "recommendations.md", "details.md" +- すべてのファイル名を 分析ファイルリスト に追加する +- の内容を context の情報で埋めて、Task ツールで直接実行する + - subagent_type: "general-purpose" + - description: "影響範囲分析の実行" + - prompt: テンプレートの内容を context で埋めた完全なプロンプト +- Task の実行結果を受け取る +- step3 を実行する + +## step3 + +- 出力されたファイルを Read で確認する +- 深掘り内容のルール に基づいて、追加調査が必要かを判断する +- 追加調査が必要な場合： + - 追加調査の内容をリストとしてユーザに提示する + - ユーザの承認を得る + - 追加調査項目が複数ある場合、各項目に対して個別に Task ツールで追加調査を実行する + - 各項目ごとに新しい連番で追加ファイルとして保存する（例: "2_core.md", "3_api.md", "4_service.md"） + - 各ファイル名を 分析ファイルリスト に追加する + - 再度 step3 を実行する（追加調査が不要になるまで繰り返す、最大5回） +- 追加調査が不要な場合： + - step4 を実行する + +## step4 + +- の内容を使って、Task ツールで最終サマリーファイルを作成する + - subagent_type: "general-purpose" + - description: "影響範囲分析 最終サマリーの作成" + - prompt: サマリーテンプレートの内容を context で埋めた完全なプロンプト + - 最終サマリーファイル名: "{{ベースディレクトリ}}/final_summary.md" +- 全ての分析ファイルのパスを分析回数別に整理して表示する + - 初回分析ファイル一覧（インデックス、サマリー、層別ファイルなど） + - 追加調査ファイル一覧（該当する場合） + - 最終サマリー +- 分析完了をユーザに報告する + +# rules + +## 確認ポイント + +AskUserQuestion ツールを使って、以下の質問を順番に実施する： + +### 質問1: 変更対象の種類 +- **質問**: 変更対象はどの種類ですか？ +- **header**: "対象種類" +- **options**: + - "ファイルパス" - 特定のファイル全体またはファイル内の特定箇所 + - "関数/メソッド" - 特定の関数やメソッド + - "クラス/型" - クラスや型定義 + - "自然言語" - 機能や概念の説明（具体的なコード要素は未特定） + +### 質問2: 変更内容の種類 +- **質問**: どのような変更を予定していますか？ +- **header**: "変更種類" +- **multiSelect**: true +- **options**: + - "削除" - コードやファイルを削除する + - "変更" - 既存のコードを修正する + - "追加" - 新しいコードや機能を追加する + - "リファクタリング" - 動作を変えずに内部実装を改善する + +### 質問3: 分析の目的 +- **質問**: この影響範囲分析の主な目的は何ですか？ +- **header**: "分析目的" +- **options**: + - "リリース前の影響確認" - 本番リリース前のリスク評価 + - "リファクタリング計画" - コード改善の影響範囲把握 + - "バグ修正の影響確認" - バグ修正による副作用の確認 + - "機能追加の影響確認" - 新機能追加による既存機能への影響確認 + +### 質問4: 除外条件 +- **質問**: 分析から除外したい対象はありますか？ +- **header**: "除外条件" +- **multiSelect**: true +- **options**: + - "テストコード" - テストファイルを除外 + - "ドキュメント" - ドキュメントファイルを除外 + - "特定ディレクトリ" - 特定のディレクトリを除外（追記で指定） + - "除外なし" - すべて分析対象にする + +contextとして以下を保持する +- 変更対象（具体的なファイルパスまたはコード要素） +- 変更対象の種類 +- 変更内容の種類 +- 分析の目的 +- 除外条件 + +## ファイル名のルール + +### timestamp の形式 +- yyyyMMddHHmmss 形式（例: 20251008123456） + +### 内容の英語化のルール +- 変更対象を簡潔な英語に変換する +- スネークケース（snake_case）を使用 +- 最大30文字程度に収める +- 例: + - "calculateTotal 関数" → "calculate_total" + - "ユーザーモデル" → "user_model" + - "src/utils/helper.ts" → "utils_helper" + - "APIエンドポイント" → "api_endpoint" + +### セクション別ファイル名のルール +- 分析結果は論理的なセクション単位で分割し、各セクション500行以内を目標とする +- 各セクションはベースディレクトリ内に個別ファイルとして配置 +- セクション一覧: + - `index.md` - インデックス（全体概要とファイル一覧） + - `summary.md` - 分析対象とサマリー + - `core.md` - コアロジック層の影響 + - `api.md` - API層の影響 + - `service.md` - サービス層の影響 + - `data.md` - データアクセス層の影響 + - `ui.md` - UI層の影響 + - `test.md` - テストの影響 + - `config.md` - 設定の影響 + - `other.md` - その他の影響 + - `external.md` - 外部依存関係 + - `recommendations.md` - 推奨アクション + - `details.md` - 分析詳細 + +### 追加調査ファイル名のルール +- 追加調査が必要な場合、追加調査ごとに新しいセクション別ファイルを作成 +- 追加調査には連番プレフィックスを付与: `2_`, `3_`, `4_` など +- 例: `2_core.md`, `2_api.md`, `3_service.md` など（ベースディレクトリ内に配置） + +### 完全なファイル名の例 +**初回分析**: +- `.dcs/20251008123456_calculate_total/index.md` (インデックス) +- `.dcs/20251008123456_calculate_total/summary.md` (サマリー) +- `.dcs/20251008123456_calculate_total/core.md` (コアロジック層) +- `.dcs/20251008123456_calculate_total/api.md` (API層) +- ... (その他のセクション) + +**追加調査1回目**: +- `.dcs/20251008123456_calculate_total/2_core.md` (追加調査のコアロジック層) +- `.dcs/20251008123456_calculate_total/2_api.md` (追加調査のAPI層) +- ... (その他のセクション) + +**最終サマリー**: +- `.dcs/20251008123456_calculate_total/final_summary.md` (全体サマリー) + +## ファイルパスの記載ルール + +- **カレントディレクトリを基準とした相対パスを使用する** +- フルパス（絶対パス）は記載しない +- 例: + - ❌ `/Users/makotan/projects/esample/src/utils/helper.ts` + - ✅ `src/utils/helper.ts` +- カレントディレクトリは分析開始時の作業ディレクトリ +- すべてのファイルパスは相対パスで統一する + +## リスク評価基準 + +総合的に以下の観点でリスクを評価する： + +### 影響の深さ +- 直接参照: 高リスク +- 1階層の間接参照: 中リスク +- 2階層以上の間接参照: 低リスク + +### 影響の範囲 +- 影響を受けるファイル数が多い: リスク増加 +- 影響が限定的: リスク低下 + +### コードの重要度 +- コアロジック、データ処理: 高リスク +- API層、ビジネスロジック: 中リスク +- UI層、表示ロジック: 低リスク +- テストコード: 参考情報 + +### 変更の種類 +- 削除、破壊的変更: 高リスク +- 型変更、インターフェース変更: 中リスク +- 追加、内部実装のみの変更: 低リスク + +## ファイル種別の分類基準 + +以下の基準でファイルを分類する： + +- **コアロジック**: ビジネスロジック、データモデル、ユーティリティ +- **API層**: エンドポイント、コントローラー、ルーティング +- **サービス層**: サービスクラス、ビジネスサービス +- **データアクセス層**: リポジトリ、DAO、クエリ +- **UI層**: コンポーネント、ビュー、テンプレート +- **テスト**: テストコード全般 +- **設定**: 設定ファイル、環境変数 +- **その他**: 上記に該当しないファイル + +## 影響の種類 + +- **直接参照**: import/require による直接的な依存 +- **関数呼び出し**: 関数・メソッドの直接呼び出し +- **継承**: クラスの継承関係 +- **実装**: インターフェースの実装 +- **型依存**: 型定義への依存 +- **間接参照**: 中間ファイルを経由した依存 + +## 追加調査が必要な条件 + +以下の条件のいずれかに該当する場合、追加調査を提案する： + +- リスク評価が「高」のファイルが5件以上ある +- 影響が大きいが詳細が不明なファイルがある +- 複雑な依存関係があるファイルがある（循環参照、多階層依存など） +- 外部APIとの連携部分に影響がある +- データベーススキーマとの関連がある +- 設定ファイルへの影響がある +- パフォーマンスへの影響が懸念される +- 分析結果に不明確な点や曖昧な箇所がある + +## 深掘り内容のルール + +調査した内容を元に、以下の観点で追加調査が必要な箇所をリストアップする： + +- 影響が大きいが詳細が不明なファイル +- 複雑な依存関係があるファイル +- 外部APIとの連携部分 +- データベーススキーマとの関連 +- 設定ファイルへの影響 +- パフォーマンスへの影響 + +具体的な調査内容を提示し、originRule を参考に深掘りする。 + +## step3 の繰り返しルール + +- 追加調査が必要な項目がある場合、step3 を繰り返す +- 最大5回まで繰り返す（無限ループ防止） +- 追加調査項目が複数ある場合は、各項目ごとに個別に Task を実行する +- 各繰り返しで新しい連番のファイルを作成する +- ユーザーの承認を得てから次の調査を実行する +- 追加調査が不要になったら step4 に進む + +# info + + +あなたは影響範囲分析のエキスパートです。以下の情報に基づいて、変更対象の影響範囲を分析し、セクション別に分割してファイル出力してください。 + +# 分析対象の情報 + +変更対象: {{変更対象の具体的な情報}} +変更内容: {{変更内容の種類}} +分析目的: {{分析の目的}} +除外条件: {{除外条件（なければ「なし」）}} +ベースディレクトリ: {{ベースディレクトリ}}（例: ".dcs/20251008123456_calculate_total"） +カレントディレクトリ: {{カレントディレクトリ}} + +# 重要な注意事項 + +**すべてのファイルパスは、カレントディレクトリを基準とした相対パスで記載してください。** +**絶対パス（/Users/... や C:\... など）は使用しないでください。** +**各セクションファイルは500行以内を目標としてください。** + +例: +- ❌ `/Users/makotan/projects/esample/src/utils/helper.ts` +- ✅ `src/utils/helper.ts` + +# 出力ファイル構成 + +分析結果は以下のセクション別ファイルに分割して出力してください： + +1. **インデックスファイル**: `{{ベースディレクトリ}}/index.md` + - 全体概要と全セクションファイルへのリンク + +2. **サマリーファイル**: `{{ベースディレクトリ}}/summary.md` + - 分析対象、サマリー、リスク評価 + +3. **層別影響ファイル**（影響があるもののみ作成）: + - `{{ベースディレクトリ}}/core.md` - コアロジック層 + - `{{ベースディレクトリ}}/api.md` - API層 + - `{{ベースディレクトリ}}/service.md` - サービス層 + - `{{ベースディレクトリ}}/data.md` - データアクセス層 + - `{{ベースディレクトリ}}/ui.md` - UI層 + - `{{ベースディレクトリ}}/test.md` - テスト + - `{{ベースディレクトリ}}/config.md` - 設定 + - `{{ベースディレクトリ}}/other.md` - その他 + +4. **その他のファイル**: + - `{{ベースディレクトリ}}/external.md` - 外部依存関係 + - `{{ベースディレクトリ}}/recommendations.md` - 推奨アクション + - `{{ベースディレクトリ}}/details.md` - 分析詳細 + +# 分析手順 + +## 1. 変更対象の特定 + +- 変更対象が自然言語の場合、Grep/Globで具体的なファイル・関数・クラスを特定する +- 変更対象がファイルパスの場合、そのファイルの内容を Read で確認する +- 変更対象が関数/クラス名の場合、Grep で定義箇所を特定する +- 特定結果を記録する（相対パス、行番号、コード要素の種類） + +## 2. 直接的な影響の分析 + +- Grep を使用して、変更対象を直接参照している箇所をすべて検索する + - import/require 文 + - 関数・メソッド呼び出し + - 継承・実装関係 + - 型定義の使用 +- 各参照について以下を記録する + - 相対パス:行番号 + - 影響の種類（直接参照、関数呼び出し、継承など） + - コードのコンテキスト + +## 3. 間接的な影響の分析 + +- 直接影響を受けるファイルそれぞれについて、さらにそれを参照しているファイルを検索する +- 最大3階層まで追跡する（必要に応じて調整） +- 各間接参照について記録する + - 相対パス:行番号 + - 影響の種類 + - 影響の深さ（何階層目か） + - 依存経路 + +## 4. ファイル種別の分類 + +- 以下の基準で、影響を受ける各ファイルを分類する + - **コアロジック**: ビジネスロジック、データモデル、ユーティリティ + - **API層**: エンドポイント、コントローラー、ルーティング + - **サービス層**: サービスクラス、ビジネスサービス + - **データアクセス層**: リポジトリ、DAO、クエリ + - **UI層**: コンポーネント、ビュー、テンプレート + - **テスト**: テストコード全般 + - **設定**: 設定ファイル、環境変数 + - **その他**: 上記に該当しないファイル +- ファイルパスやディレクトリ構造から推測する +- 必要に応じてファイル内容を Read で確認する + +## 5. リスク評価 + +以下の基準に基づいて、各ファイルの影響度を総合的に評価する： + +### 影響の深さ +- 直接参照: 高リスク +- 1階層の間接参照: 中リスク +- 2階層以上の間接参照: 低リスク + +### 影響の範囲 +- 影響を受けるファイル数が多い: リスク増加 +- 影響が限定的: リスク低下 + +### コードの重要度 +- コアロジック、データ処理: 高リスク +- API層、ビジネスロジック: 中リスク +- UI層、表示ロジック: 低リスク +- テストコード: 参考情報 + +### 変更の種類 +- 削除、破壊的変更: 高リスク +- 型変更、インターフェース変更: 中リスク +- 追加、内部実装のみの変更: 低リスク + +総合的なリスクレベル（高/中/低）を判定し、リスク評価の根拠を記録する。 + +## 6. 外部依存関係の確認 + +- package.json、go.mod、requirements.txt などの依存関係ファイルを確認する +- 変更対象が外部パッケージに影響する可能性を調査する +- 外部依存の参考情報として記録する + +## 7. 推奨アクションの生成 + +- リスク評価に基づいて、優先的に確認すべきファイルをリストアップする +- テスト推奨範囲を提示する +- その他の注意事項を記述する + +## 8. セクション別ファイル出力 + +以下の順序で各セクションファイルを作成してください。**各ファイルは Write ツールを使って個別に保存してください。** + +### 8.1 インデックスファイルの作成 + +最初に `{{ベースディレクトリ}}/index.md` を作成してください。 + +### 8.2 サマリーファイルの作成 + +次に `{{ベースディレクトリ}}/summary.md` を作成してください。 + +### 8.3 層別影響ファイルの作成 + +影響があるファイル種別について、それぞれ個別ファイルを作成してください： +- `{{ベースディレクトリ}}/core.md` - コアロジック層（影響がある場合のみ） +- `{{ベースディレクトリ}}/api.md` - API層（影響がある場合のみ） +- `{{ベースディレクトリ}}/service.md` - サービス層（影響がある場合のみ） +- `{{ベースディレクトリ}}/data.md` - データアクセス層（影響がある場合のみ） +- `{{ベースディレクトリ}}/ui.md` - UI層（影響がある場合のみ） +- `{{ベースディレクトリ}}/test.md` - テスト（影響がある場合のみ） +- `{{ベースディレクトリ}}/config.md` - 設定（影響がある場合のみ） +- `{{ベースディレクトリ}}/other.md` - その他（影響がある場合のみ） + +### 8.4 その他のファイルの作成 + +以下のファイルを作成してください： +- `{{ベースディレクトリ}}/external.md` - 外部依存関係 +- `{{ベースディレクトリ}}/recommendations.md` - 推奨アクション +- `{{ベースディレクトリ}}/details.md` - 分析詳細 + +# 各セクションファイルの出力形式 + +## インデックスファイル (`index.md`) + +```markdown +# 影響範囲分析 - インデックス + +**実施日時**: {{実施日時}} +**分析者**: Claude Code + +--- + +## 分析概要 + +### 変更対象 +- **対象**: {{変更対象の詳細}} +- **変更内容**: {{変更内容の種類}} +- **分析目的**: {{分析の目的}} + +### サマリー + +| 項目 | 内容 | +|------|------| +| 影響を受けるファイル数 | XX件 | +| 総合リスク評価 | **高/中/低** | +| 最大影響深度 | X階層 | + +--- + +## 分析結果ファイル一覧 + +### 基本情報 +- [サマリー](./summary.md) - 分析対象とリスク評価 + +### 影響を受けるファイル（層別） +- [コアロジック層](./core.md) - XX件の影響 +- [API層](./api.md) - XX件の影響 +- [サービス層](./service.md) - XX件の影響 +- [データアクセス層](./data.md) - XX件の影響 +- [UI層](./ui.md) - XX件の影響 +- [テスト](./test.md) - XX件の影響 +- [設定](./config.md) - XX件の影響 +- [その他](./other.md) - XX件の影響 + +### その他の情報 +- [外部依存関係](./external.md) +- [推奨アクション](./recommendations.md) +- [分析詳細](./details.md) + +--- + +## クイックナビゲーション + +### 高リスク項目 +1. {{高リスク項目1}} - [詳細](./{{section}}.md) +2. {{高リスク項目2}} - [詳細](./{{section}}.md) + +### 即座に対応が必要な項目 +1. {{対応項目1}} - [詳細](./recommendations.md) +2. {{対応項目2}} - [詳細](./recommendations.md) + +--- + +*各ファイルの詳細は上記リンクから参照してください。* +``` + +## サマリーファイル (`summary.md`) + +```markdown +# 影響範囲分析 - サマリー + +**実施日時**: {{実施日時}} +**分析者**: Claude Code + +[← インデックスに戻る](./index.md) + +--- + +## 分析対象 + +### 変更対象 +- **対象**: {{変更対象の詳細（相対パス:行番号、関数名など）}} +- **変更内容**: {{変更内容の種類}} +- **分析目的**: {{分析の目的}} +- **除外条件**: {{除外条件}} + +--- + +## サマリー + +| 項目 | 内容 | +|------|------| +| 影響を受けるファイル数 | XX件 | +| 総合リスク評価 | **高/中/低** | +| 最大影響深度 | X階層 | +| 推奨対応優先度 | 高/中/低 | + +### リスク評価の根拠 +{{総合的なリスク評価の理由を簡潔に記述}} + +--- + +## ファイル種別ごとの影響統計 + +| ファイル種別 | 影響ファイル数 | リスクレベル | 詳細 | +|-------------|--------------|------------|------| +| コアロジック | XX件 | 高/中/低 | [詳細](./core.md) | +| API層 | XX件 | 高/中/低 | [詳細](./api.md) | +| サービス層 | XX件 | 高/中/低 | [詳細](./service.md) | +| データアクセス層 | XX件 | 高/中/低 | [詳細](./data.md) | +| UI層 | XX件 | 高/中/低 | [詳細](./ui.md) | +| テスト | XX件 | 低 | [詳細](./test.md) | +| 設定 | XX件 | 高/中/低 | [詳細](./config.md) | +| その他 | XX件 | 高/中/低 | [詳細](./other.md) | + +--- + +## 追加調査が必要な項目 + +以下の項目について、追加調査が推奨されます： + +1. {{追加調査項目1}} +2. {{追加調査項目2}} +3. {{追加調査項目3}} + +（追加調査が不要な場合は「なし」と記載） + +--- + +*詳細な影響内容は各層別ファイルを参照してください。* +``` + +## 層別影響ファイル (`core.md`, `api.md`, `service.md`, `data.md`, `ui.md`, `test.md`, `config.md`, `other.md`) + +各層のファイルは以下の形式で記述してください： + +```markdown +# 影響範囲分析 - {{層名}}層 + +**実施日時**: {{実施日時}} +**分析者**: Claude Code + +[← インデックスに戻る](./index.md) | [サマリー](./summary.md) + +--- + +## {{層名}}層の影響概要 + +| 項目 | 内容 | +|------|------| +| 影響ファイル数 | XX件 | +| リスクレベル | **高/中/低** | +| 直接影響 | XX件 | +| 間接影響 | XX件 | + +--- + +## 直接的な影響 + +### [相対パス:行番号](相対パス#L行番号) + +- **影響の種類**: 直接参照/関数呼び出し/継承/実装/型依存 +- **影響度**: 高/中/低 +- **理由**: {{なぜこの影響度なのか、どのような修正が必要か}} +- **コードコンテキスト**: {{関連するコードの説明}} +- **推奨対応**: {{対応方法}} + +### [相対パス:行番号](相対パス#L行番号) + +（同様の形式で記述） + +--- + +## 間接的な影響（2階層） + +### [相対パス:行番号](相対パス#L行番号) + +- **影響の種類**: 間接参照 +- **依存経路**: 変更対象 → 中間ファイルA → このファイル +- **影響度**: 中/低 +- **理由**: {{影響の説明}} +- **推奨対応**: {{対応方法}} + +--- + +## 間接的な影響（3階層以上） + +### [相対パス:行番号](相対パス#L行番号) + +（同様の形式で記述） + +--- + +*このファイルには{{層名}}層に関する影響のみを記載しています。他の層の影響は対応するファイルを参照してください。* +``` + +## 外部依存関係ファイル (`external.md`) + +```markdown +# 影響範囲分析 - 外部依存関係 + +**実施日時**: {{実施日時}} +**分析者**: Claude Code + +[← インデックスに戻る](./index.md) + +--- + +## 影響を受ける可能性のある外部パッケージ + +### パッケージ名@バージョン + +- **使用箇所**: {{どこで使用されているか（相対パス）}} +- **影響の可能性**: {{どのような影響が考えられるか}} +- **リスクレベル**: 高/中/低 +- **推奨対応**: {{必要な対応があれば}} + +--- + +## パッケージ依存関係の注意事項 + +- {{注意事項1}} +- {{注意事項2}} + +--- + +*外部パッケージへの影響は間接的である可能性があります。実際の影響は詳細な検証が必要です。* +``` + +## 推奨アクションファイル (`recommendations.md`) + +```markdown +# 影響範囲分析 - 推奨アクション + +**実施日時**: {{実施日時}} +**分析者**: Claude Code + +[← インデックスに戻る](./index.md) + +--- + +## 優先度: 高（即座に対応が必要） + +### 1. [相対パス:行番号](相対パス#L行番号) + +- **理由**: {{なぜ即座に対応が必要か}} +- **影響範囲**: {{影響範囲}} +- **推奨対応**: {{具体的な対応方法}} +- **所要時間**: {{概算}} + +### 2. [相対パス:行番号](相対パス#L行番号) + +（同様の形式で記述） + +--- + +## 優先度: 中（レビューと検証が必要） + +### 1. [相対パス:行番号](相対パス#L行番号) + +- **理由**: {{なぜレビューが必要か}} +- **影響範囲**: {{影響範囲}} +- **推奨対応**: {{具体的な対応方法}} + +--- + +## 優先度: 低（念のため確認推奨） + +### 1. [相対パス:行番号](相対パス#L行番号) + +- **理由**: {{確認が推奨される理由}} + +--- + +## テスト推奨範囲 + +### ユニットテスト +- {{テストすべき関数・クラス1}} +- {{テストすべき関数・クラス2}} + +### 統合テスト +- {{テストすべきモジュール間連携1}} +- {{テストすべきモジュール間連携2}} + +### E2Eテスト +- {{テストすべきユーザーシナリオ1}} +- {{テストすべきユーザーシナリオ2}} + +--- + +## その他の注意事項 + +- {{注意すべき点1}} +- {{注意すべき点2}} +- {{注意すべき点3}} + +--- + +*推奨アクションは分析結果に基づいて生成されています。実際の対応は状況に応じて調整してください。* +``` + +## 分析詳細ファイル (`details.md`) + +```markdown +# 影響範囲分析 - 分析詳細 + +**実施日時**: {{実施日時}} +**分析者**: Claude Code + +[← インデックスに戻る](./index.md) + +--- + +## 検索キーワード + +### 使用した検索パターン +- `{{パターン1}}` +- `{{パターン2}}` +- `{{パターン3}}` + +--- + +## 分析範囲 + +### 対象ディレクトリ +- {{分析したディレクトリ（相対パス）}} + +### 除外条件 +- {{除外条件1}} +- {{除外条件2}} + +### 分析深度 +- 最大追跡階層: {{何階層まで追跡したか}} +- 分析したファイル総数: {{総数}} + +--- + +## 分析手法 + +### 使用したツール +- {{使用したツール1}} +- {{使用したツール2}} + +### 分析アプローチ +{{分析アプローチの説明}} + +--- + +## 制限事項 + +- {{分析の制限や注意点1}} +- {{分析の制限や注意点2}} +- {{分析の制限や注意点3}} + +--- + +## 追加情報 + +### 検出できなかった可能性のある影響 +- 動的な呼び出し（リフレクション、eval など） +- 文字列による間接的な参照 +- ランタイムでの動的ロード + +--- + +*この分析結果は自動生成されたものです。実際の影響範囲は、コードレビューやテストを通じて確認してください。* +``` + +# 分析の注意点 + +- 動的な呼び出し（リフレクション、eval など）は検出できない可能性がある +- 文字列による間接的な参照は検出が困難 +- コメントアウトされたコードは除外する +- テストコードは参考情報として含めるが、リスク評価は低めに設定する +- 循環参照がある場合は無限ループに注意し、訪問済みファイルを記録する +- すべての影響を受けるファイルを修正対象として提示する +- **すべてのファイルパスは相対パスで記載する（絶対パスは使用しない）** +- **各セクションファイルは500行以内を目標とする。500行を超える場合は、さらに細かく分割する** + +# 出力手順 + +**重要**: 必ず以下の順序でファイルを作成してください： + +1. **インデックスファイルを最初に作成** (`{{ベースディレクトリ}}/index.md`) + - Write ツールで保存 + - 全セクションファイルへのリンクを含める + +2. **サマリーファイルを作成** (`{{ベースディレクトリ}}/summary.md`) + - Write ツールで保存 + +3. **影響がある層別ファイルを作成**（影響があるものだけ） + - 各ファイルを個別に Write ツールで保存 + - 例: `{{ベースディレクトリ}}/core.md`, `{{ベースディレクトリ}}/api.md`, ... + +4. **その他のファイルを作成** + - `{{ベースディレクトリ}}/external.md` + - `{{ベースディレクトリ}}/recommendations.md` + - `{{ベースディレクトリ}}/details.md` + - 各ファイルを個別に Write ツールで保存 + +**各ファイルは Write ツールを使って個別に保存してください。一つのファイルにまとめないでください。** + + + +あなたは影響範囲分析のサマリー作成エキスパートです。以下の情報に基づいて、全体サマリーを作成してください。 + +# サマリー作成対象の情報 + +変更対象: {{変更対象の具体的な情報}} +分析ファイルリスト: {{分析ファイルリスト}}（インデックスファイル、サマリーファイル、層別ファイルなど） +最終サマリーファイル名: {{サマリーファイル名}}（例: ".dcs/20251008123456_calculate_total/final_summary.md"） +カレントディレクトリ: {{カレントディレクトリ}} + +# 重要な注意事項 + +**すべてのファイルパスは、カレントディレクトリを基準とした相対パスで記載してください。** +**絶対パス（/Users/... や C:\... など）は使用しないでください。** +**このファイルは500行以内に収まるように簡潔に記述してください。** + +例: +- ❌ `/Users/makotan/projects/esample/src/utils/helper.ts` +- ✅ `src/utils/helper.ts` + +# サマリー作成手順 + +## 1. 全分析ファイルの読み込み + +- {{分析ファイルリスト}} に含まれるすべてのファイルを Read で読み込む +- 各ファイルの内容を把握する + +## 2. 情報の統合 + +- すべての分析結果から以下の情報を統合する + - 影響を受けるファイルの総数 + - 総合リスク評価（最も高いリスクレベル） + - 最大影響深度 + - ファイル種別ごとの影響数 + - 優先度別の推奨アクション数 + +## 3. ハイライトの抽出 + +- 最も重要な発見をハイライトする +- 特に注意が必要な箇所を強調する +- 追加調査で判明した重要事項を記載する + +## 4. 統合推奨アクションの作成 + +- 全分析結果から優先度の高いアクションを抽出する +- 重複を排除し、優先順位を付ける +- 全体的な対応方針を提示する + +## 5. サマリーファイルの出力 + +以下の出力形式で {{サマリーファイル名}} に結果を保存してください。 + +# 出力形式 + +```markdown +# 影響範囲分析 - 最終サマリー + +**実施日時**: {{実施日時}} +**分析者**: Claude Code + +--- + +## ナビゲーション + +- [初回分析インデックス](./index.md) +- [初回分析サマリー](./summary.md) + +（追加調査がある場合は追加） +- [追加調査2（コアロジック層）](./2_core.md) +- [追加調査3（API層）](./3_api.md) + +--- + +## 分析概要 + +### 変更対象 +- **対象**: {{変更対象の詳細}} +- **変更内容**: {{変更内容の種類}} +- **分析目的**: {{分析の目的}} + +### 分析実施状況 +- **実施した分析回数**: {{分析回数}}回（初回 + 追加調査{{N}}回） +- **作成されたファイル数**: {{ファイル数}}件 + +--- + +## 総合サマリー + +| 項目 | 内容 | +|------|------| +| 影響を受けるファイル総数 | XX件 | +| 総合リスク評価 | **高/中/低** | +| 最大影響深度 | X階層 | +| 推奨対応優先度 | 高/中/低 | + +### 総合リスク評価の根拠 +{{全体を通じたリスク評価の理由を記述}} + +--- + +## 主要な発見事項 + +### 重要なハイライト + +1. **{{ハイライト1のタイトル}}** + - {{詳細説明}} + - 影響: {{影響の概要}} + - リスク: 高/中/低 + +2. **{{ハイライト2のタイトル}}** + - {{詳細説明}} + - 影響: {{影響の概要}} + - リスク: 高/中/低 + +3. **{{ハイライト3のタイトル}}** + - {{詳細説明}} + - 影響: {{影響の概要}} + - リスク: 高/中/低 + +--- + +## ファイル種別ごとの影響統計 + +| ファイル種別 | 影響ファイル数 | リスクレベル | 備考 | +|-------------|--------------|------------|------| +| コアロジック | XX件 | 高/中/低 | {{備考}} | +| API層 | XX件 | 高/中/低 | {{備考}} | +| サービス層 | XX件 | 高/中/低 | {{備考}} | +| データアクセス層 | XX件 | 高/中/低 | {{備考}} | +| UI層 | XX件 | 高/中/低 | {{備考}} | +| テスト | XX件 | 低 | {{備考}} | +| 設定 | XX件 | 高/中/低 | {{備考}} | +| その他 | XX件 | 高/中/低 | {{備考}} | + +--- + +## 統合推奨アクション + +### 優先度: 高（即座に対応が必要） + +1. [相対パス:行番号](相対パス#L行番号) - {{理由}} +2. [相対パス:行番号](相対パス#L行番号) - {{理由}} +3. [相対パス:行番号](相対パス#L行番号) - {{理由}} + +### 優先度: 中（レビューと検証が必要） + +1. [相対パス:行番号](相対パス#L行番号) - {{理由}} +2. [相対パス:行番号](相対パス#L行番号) - {{理由}} +3. [相対パス:行番号](相対パス#L行番号) - {{理由}} + +### 優先度: 低（念のため確認推奨） + +1. [相対パス:行番号](相対パス#L行番号) - {{理由}} +2. [相対パス:行番号](相対パス#L行番号) - {{理由}} + +--- + +## 全体的な対応方針 + +### 推奨アプローチ + +1. **{{アプローチ1}}** + - {{詳細説明}} + +2. **{{アプローチ2}}** + - {{詳細説明}} + +3. **{{アプローチ3}}** + - {{詳細説明}} + +### テスト戦略 + +- **ユニットテスト**: {{テスト対象と範囲}} +- **統合テスト**: {{テスト対象と範囲}} +- **E2Eテスト**: {{テスト対象と範囲}} +- **リグレッションテスト**: {{特に注意すべき領域}} + +### リスク軽減策 + +1. {{リスク軽減策1}} +2. {{リスク軽減策2}} +3. {{リスク軽減策3}} + +--- + +## 外部依存関係の統合情報 + +### 影響を受ける外部パッケージ + +- **パッケージ名**: パッケージ名@バージョン + - **影響の可能性**: {{統合された影響情報}} + - **推奨対応**: {{推奨される対応}} + +--- + +## 追加で考慮すべき事項 + +1. **{{考慮事項1}}** + - {{詳細}} + +2. **{{考慮事項2}}** + - {{詳細}} + +3. **{{考慮事項3}}** + - {{詳細}} + +--- + +## 詳細分析ファイル一覧 + +以下のファイルに詳細な分析結果が記録されています： + +1. [{{ファイル名1}}]({{相対パス1}}) - 初回分析 +2. [{{ファイル名2}}]({{相対パス2}}) - 追加調査1 +3. [{{ファイル名3}}]({{相対パス3}}) - 追加調査2 +... + +--- + +## 分析の制限事項と注意点 + +- {{制限事項1}} +- {{制限事項2}} +- {{制限事項3}} + +--- + +*このサマリーは複数の分析結果を統合して自動生成されたものです。詳細は個別の分析ファイルを参照してください。* +``` + +# サマリー作成の注意点 + +- すべての分析ファイルの内容を網羅的に把握する +- 重複する情報を排除し、簡潔にまとめる +- 最も重要な情報を優先的に記載する +- 全体の傾向やパターンを識別する +- **すべてのファイルパスは相対パスで記載する（絶対パスは使用しない）** + +必ず Write ツールを使用して、{{サマリーファイル名}} に結果を保存してください。 + diff --git a/commands/dcs/incremental-dev.md b/commands/dcs/incremental-dev.md new file mode 100644 index 0000000..ca12332 --- /dev/null +++ b/commands/dcs/incremental-dev.md @@ -0,0 +1,1723 @@ +--- +description: 増分開発の計画を立案する +allowed-tools: Read, Glob, Grep, Task, Bash, AskUserQuestion, Write +argument-hint: [開発対象（機能名/改善内容/自然言語）] +--- +増分開発の対象を分析し、初期調査から追加調査を経て、実装方法毎のPRD（Product Requirements Document）を作成します。すべてのファイルは500行以内に分割して出力します。 + +# context + +出力ディレクトリ=".dcs" +カレントディレクトリ={{プロジェクトルート}} +分析ファイルリスト=[] +追加調査リスト=[] +実装アプローチリスト=[] + +# step + +- $1 がない場合、「引数に開発対象を指定してください（例: 機能名、改善内容、または自然言語での説明）」と言って終了する +- $1 の内容を簡潔に説明する +- AskUserQuestion ツールを使って以下の質問を順番に実施し、context を更新する： + 1. 開発の種類を確認 + 2. 実装の優先事項を確認 + 3. 調査の深さを確認 + 4. 除外条件の有無を確認 +- 収集した context の内容をまとめてユーザに宣言する +- step2 を実行する + +## step2: 初期調査の実施 + +- 既存の出力ファイルを確認して、重複しないナンバリングを決定する + - {{出力ディレクトリ}}/{{timestamp}}_* を検索 + - 今回の内容を簡単に英語化したもの（例: "user_auth", "payment_feature"）を作成 + - 同じ timestamp と内容で既存ディレクトリがある場合、末尾の連番を +1 する + - ベースディレクトリを "{{出力ディレクトリ}}/{{timestamp}}_{{内容の英語化}}" とする + - 例: ".dcs/20251025_143000_user_auth" + - 例: ".dcs/20251025_143000_payment_feature" +- 初期調査用ファイルのリストを準備する + - インデックスファイル: "{{ベースディレクトリ}}/index.md" + - 初期調査サマリー: "{{ベースディレクトリ}}/survey_summary.md" + - 既存実装調査: "{{ベースディレクトリ}}/existing_impl.md" + - 技術スタック: "{{ベースディレクトリ}}/tech_stack.md" + - 依存関係分析: "{{ベースディレクトリ}}/dependencies.md" + - 複雑度評価: "{{ベースディレクトリ}}/complexity.md" + - 課題と制約: "{{ベースディレクトリ}}/constraints.md" +- すべてのファイル名を 分析ファイルリスト に追加する +- の内容を context の情報で埋めて、Task ツールで直接実行する + - subagent_type: "general-purpose" + - description: "増分開発 初期調査の実行" + - prompt: テンプレートの内容を context で埋めた完全なプロンプト +- Task の実行結果を受け取る +- step3 を実行する + +## step3: 追加調査内容の決定とヒアリング + +- 出力されたファイルを Read で確認する +- 初期調査サマリーから追加調査が必要な項目を抽出する +- 追加調査の観点に基づいて、調査項目をリストアップする（3〜5項目程度） +- 追加調査項目をユーザに提示し、AskUserQuestion で以下を確認する： + - どの追加調査を実施するか（multiSelect: true） + - 実装アプローチの候補（複数選択可能） +- ユーザの選択に基づいて 追加調査リスト と 実装アプローチリスト を更新する +- step4 を実行する + +## step4: 追加調査の実施 + +- 追加調査リスト が空の場合、step5 にスキップする +- 追加調査リスト の各項目に対して、以下を実行する： + - 追加調査用のファイル名を決定する + - "{{ベースディレクトリ}}/detail_{{調査項目の英語化}}_{{連番}}.md" + - 例: ".dcs/20251025_143000_user_auth/detail_security_2.md" + - ファイル名を 分析ファイルリスト に追加する + - の内容を使って、Task ツールで追加調査を実行する + - subagent_type: "general-purpose" + - description: "追加調査: {{調査項目名}}" + - prompt: テンプレートの内容を context で埋めた完全なプロンプト + - Task の実行結果を受け取る +- すべての追加調査が完了したら、step5 を実行する + +## step5: PRDの作成 + +- 実装アプローチリスト が空の場合、デフォルトのアプローチを1つ設定する +- 実装アプローチリスト の各アプローチに対して、以下を実行する： + - PRD用のファイル名を決定する + - インデックス: "{{ベースディレクトリ}}/prd_{{アプローチの英語化}}_index.md" + - 要件定義: "{{ベースディレクトリ}}/prd_{{アプローチの英語化}}_requirements.md" + - 技術設計: "{{ベースディレクトリ}}/prd_{{アプローチの英語化}}_design.md" + - 実装計画: "{{ベースディレクトリ}}/prd_{{アプローチの英語化}}_plan.md" + - テスト戦略: "{{ベースディレクトリ}}/prd_{{アプローチの英語化}}_tests.md" + - リスクと対策: "{{ベースディレクトリ}}/prd_{{アプローチの英語化}}_risks.md" + - すべてのPRDファイル名を 分析ファイルリスト に追加する + - の内容を使って、Task ツールでPRDを作成する + - subagent_type: "general-purpose" + - description: "PRD作成: {{アプローチ名}}" + - prompt: テンプレートの内容を context で埋めた完全なプロンプト + - Task の実行結果を受け取る +- すべてのPRDが完了したら、step6 を実行する + +## step6: 最終サマリーの作成 + +- の内容を使って、Task ツールで最終サマリーファイルを作成する + - subagent_type: "general-purpose" + - description: "増分開発 最終サマリーの作成" + - prompt: サマリーテンプレートの内容を context で埋めた完全なプロンプト + - 最終サマリーファイル名: "{{ベースディレクトリ}}/final_summary.md" +- 全ての分析ファイルのパスをフェーズ別に整理して表示する + - 初期調査ファイル一覧 + - 追加調査ファイル一覧（該当する場合） + - PRDファイル一覧（アプローチ毎） + - 最終サマリー +- 開発計画完了をユーザに報告する + +# rules + +## 確認ポイント + +AskUserQuestion ツールを使って、以下の質問を順番に実施する： + +### 質問1: 開発の種類 +- **質問**: どのような開発を行いますか？ +- **header**: "開発種類" +- **options**: + - "新機能追加" - 新しい機能を追加する + - "既存機能改善" - 既存機能の拡張や改良 + - "リファクタリング" - コード品質向上のための再構成 + - "バグ修正" - バグの修正とその影響範囲の調査 + +### 質問2: 実装の優先事項 +- **質問**: 実装において最も優先したい事項は何ですか？ +- **header**: "優先事項" +- **multiSelect**: true +- **options**: + - "品質" - コード品質とテストカバレッジを重視 + - "速度" - 実装速度と早期リリースを重視 + - "保守性" - 将来の保守やメンテナンス性を重視 + - "パフォーマンス" - 実行速度や効率を重視 + +### 質問3: 調査の深さ +- **質問**: どの程度の深さで調査を行いますか？ +- **header**: "調査深度" +- **options**: + - "簡易" - 基本的な影響範囲の確認のみ + - "標準" - 通常レベルの詳細調査 + - "詳細" - 深い分析と複数の追加調査 + - "徹底" - 最も詳細な調査と複数の実装案検討 + +### 質問4: 除外条件 +- **質問**: 調査から除外したい対象はありますか？ +- **header**: "除外条件" +- **multiSelect**: true +- **options**: + - "テストコード" - テストファイルを除外 + - "ドキュメント" - ドキュメントファイルを除外 + - "特定ディレクトリ" - 特定のディレクトリを除外（追記で指定） + - "除外なし" - すべて分析対象にする + +contextとして以下を保持する +- 開発対象（具体的な機能名や改善内容） +- 開発の種類 +- 実装の優先事項 +- 調査の深さ +- 除外条件 + +## ファイル名のルール + +### timestamp の形式 +- yyyyMMddHHmmss 形式（例: 20251025143000） + +### 内容の英語化のルール +- 開発対象を簡潔な英語に変換する +- スネークケース（snake_case）を使用 +- 最大30文字程度に収める +- 例: + - "ユーザー認証機能" → "user_auth" + - "決済機能の改善" → "payment_improve" + - "データベースリファクタリング" → "db_refactor" + - "APIエンドポイント追加" → "api_endpoint" + +### セクション別ファイル名のルール +- 各セクションは500行以内を目標とする +- 各セクションには専用のサフィックスを付与 + +**初期調査**: +- `index.md` - インデックス（全体概要とファイル一覧） +- `survey_summary.md` - 初期調査サマリー +- `existing_impl.md` - 既存実装調査 +- `tech_stack.md` - 技術スタック +- `dependencies.md` - 依存関係分析 +- `complexity.md` - 複雑度評価 +- `constraints.md` - 課題と制約 + +**追加調査**（必要に応じて）: +- `detail_{topic}_{n}.md` - 追加調査の詳細（topic=調査項目、n=連番） + +**PRD**（アプローチ毎）: +- `prd_{approach}_index.md` - PRDインデックス +- `prd_{approach}_requirements.md` - 要件定義 +- `prd_{approach}_design.md` - 技術設計 +- `prd_{approach}_plan.md` - 実装計画 +- `prd_{approach}_tests.md` - テスト戦略 +- `prd_{approach}_risks.md` - リスクと対策 + +**最終サマリー**: +- `final_summary.md` - 全体サマリー + +### 完全なファイル名の例 + +**初期調査**: +- `.dcs/20251025143000_user_auth/index.md` +- `.dcs/20251025143000_user_auth/survey_summary.md` +- `.dcs/20251025143000_user_auth/existing_impl.md` +- `.dcs/20251025143000_user_auth/tech_stack.md` +- ... + +**追加調査**: +- `.dcs/20251025143000_user_auth/detail_security_2.md` +- `.dcs/20251025143000_user_auth/detail_performance_3.md` + +**PRD**（アプローチA）: +- `.dcs/20251025143000_user_auth/prd_jwt_index.md` +- `.dcs/20251025143000_user_auth/prd_jwt_requirements.md` +- `.dcs/20251025143000_user_auth/prd_jwt_design.md` +- ... + +**PRD**（アプローチB）: +- `.dcs/20251025143000_user_auth/prd_session_index.md` +- `.dcs/20251025143000_user_auth/prd_session_requirements.md` +- ... + +**最終サマリー**: +- `.dcs/20251025143000_user_auth/final_summary.md` + +## ファイルパスの記載ルール + +- **カレントディレクトリを基準とした相対パスを使用する** +- フルパス（絶対パス）は記載しない +- 例: + - ❌ `/Users/makotan/projects/example/src/auth/login.ts` + - ✅ `src/auth/login.ts` +- カレントディレクトリは分析開始時の作業ディレクトリ +- すべてのファイルパスは相対パスで統一する + +## 調査の観点 + +### 初期調査で確認すべき項目 + +1. **既存実装の調査** + - 類似機能の実装パターン + - 既存のアーキテクチャ + - コーディング規約やベストプラクティス + - 再利用可能なコンポーネント + +2. **技術スタック** + - 使用言語とバージョン + - フレームワークとライブラリ + - データベースとORM + - 開発ツールとビルドシステム + +3. **依存関係** + - 関連するモジュールやパッケージ + - 外部APIとの連携 + - 他機能との依存関係 + +4. **複雑度評価** + - 実装の複雑さ + - 必要な工数の概算 + - 技術的な難易度 + +5. **課題と制約** + - 既存システムの制約 + - 技術的な課題 + - パフォーマンス上の考慮事項 + +### 追加調査の観点 + +初期調査の結果に基づいて、以下の観点で追加調査を提案する： + +- **セキュリティ**: 認証、認可、データ保護 +- **パフォーマンス**: 負荷、応答時間、最適化 +- **スケーラビリティ**: 拡張性、将来の成長 +- **データ整合性**: トランザクション、一貫性 +- **UI/UX**: ユーザー体験、アクセシビリティ +- **統合**: 外部システムとの連携 +- **移行**: データ移行、互換性 +- **運用**: 監視、ログ、デプロイ + +## PRDに含める内容 + +### 要件定義 +- 機能要件 +- 非機能要件 +- 受け入れ基準 +- ユーザーストーリー +- 成功指標 + +### 技術設計 +- システムアーキテクチャ +- データモデル +- API設計 +- セキュリティ設計 +- パフォーマンス設計 + +### 実装計画 +- タスク分割 +- 優先順位 +- 依存関係 +- 工数見積もり +- マイルストーン + +### テスト戦略 +- ユニットテスト +- 統合テスト +- E2Eテスト +- パフォーマンステスト +- セキュリティテスト + +### リスクと対策 +- 技術的リスク +- スケジュールリスク +- リソースリスク +- リスク軽減策 + +# info + + +あなたは増分開発の初期調査エキスパートです。以下の情報に基づいて、開発対象の初期調査を実施し、セクション別に分割してファイル出力してください。 + +# 調査対象の情報 + +開発対象: {{開発対象の具体的な情報}} +開発種類: {{開発の種類}} +優先事項: {{実装の優先事項}} +調査深度: {{調査の深さ}} +除外条件: {{除外条件（なければ「なし」）}} +ベースディレクトリ: {{ベースディレクトリ}}（例: ".dcs/20251025143000_user_auth"） +カレントディレクトリ: {{カレントディレクトリ}} + +# 重要な注意事項 + +**すべてのファイルパスは、カレントディレクトリを基準とした相対パスで記載してください。** +**絶対パス（/Users/... や C:\... など）は使用しないでください。** +**各セクションファイルは500行以内を目標としてください。500行を超える場合は、さらに細かく分割してください。** + +例: +- ❌ `/Users/makotan/projects/example/src/auth/login.ts` +- ✅ `src/auth/login.ts` + +# 出力ファイル構成 + +初期調査結果は以下のセクション別ファイルに分割して出力してください： + +1. **インデックスファイル**: `{{ベースディレクトリ}}/index.md` + - 全体概要と全セクションファイルへのリンク + +2. **初期調査サマリーファイル**: `{{ベースディレクトリ}}/survey_summary.md` + - 調査対象、サマリー、追加調査提案 + +3. **調査詳細ファイル**: + - `{{ベースディレクトリ}}/existing_impl.md` - 既存実装調査 + - `{{ベースディレクトリ}}/tech_stack.md` - 技術スタック + - `{{ベースディレクトリ}}/dependencies.md` - 依存関係分析 + - `{{ベースディレクトリ}}/complexity.md` - 複雑度評価 + - `{{ベースディレクトリ}}/constraints.md` - 課題と制約 + +# 調査手順 + +## 1. 開発対象の特定と理解 + +- 開発対象が自然言語の場合、Grep/Globで具体的なファイル・関数・クラスを特定する +- 類似機能や関連コードを検索する +- 既存の実装パターンを把握する + +## 2. 既存実装の調査 + +- 類似機能の実装を検索する + - Grep で関連するキーワードを検索 + - Glob でファイルパターンを探す +- 以下を記録する + - 類似実装のファイルパス（相対パス） + - 実装パターンとアプローチ + - 再利用可能なコンポーネント + - コーディング規約の確認 + +## 3. 技術スタックの確認 + +- package.json, go.mod, requirements.txt などを確認 +- プロジェクトの README や設定ファイルを読む +- 以下を記録する + - 使用言語とバージョン + - フレームワークとライブラリ + - データベースとORM + - ビルドツールと開発環境 + +## 4. 依存関係の分析 + +- 関連するモジュールやファイルを特定する +- import/require 文を調査する +- 以下を記録する + - 内部モジュール依存 + - 外部パッケージ依存 + - API連携の有無 + - データベーススキーマとの関連 + +## 5. 複雑度の評価 + +- コードの複雑さを分析する +- 実装に必要な工数を概算する +- 以下を評価する + - 技術的難易度（高/中/低） + - 実装の複雑さ（高/中/低） + - 概算工数（日数または時間） + - 主な複雑性の要因 + +## 6. 課題と制約の特定 + +- 既存システムの制約を確認する +- 技術的な課題を洗い出す +- 以下を記録する + - 既存システムの制約 + - 技術的な課題 + - パフォーマンス上の考慮事項 + - セキュリティ上の考慮事項 + +## 7. 追加調査項目の提案 + +- 初期調査の結果から、さらに深掘りが必要な項目を3〜5個提案する +- 以下の観点から提案する + - セキュリティ + - パフォーマンス + - スケーラビリティ + - データ整合性 + - UI/UX + - 統合 + - 移行 + - 運用 + +## 8. セクション別ファイル出力 + +以下の順序で各セクションファイルを作成してください。**各ファイルは Write ツールを使って個別に保存してください。** + +### 8.1 インデックスファイルの作成 + +最初に `{{ベースディレクトリ}}/index.md` を作成してください。 + +形式: +```markdown +# 増分開発 初期調査 - インデックス + +**実施日時**: {{実施日時}} +**分析者**: Claude Code + +--- + +## 調査概要 + +### 開発対象 +- **対象**: {{開発対象の詳細}} +- **開発種類**: {{開発の種類}} +- **優先事項**: {{実装の優先事項}} + +### サマリー + +| 項目 | 内容 | +|------|------| +| 技術的難易度 | 高/中/低 | +| 概算工数 | XX日 | +| 主な課題 | {{課題の概要}} | + +--- + +## 調査結果ファイル一覧 + +### 基本情報 +- [初期調査サマリー](./survey_summary.md) + +### 調査詳細 +- [既存実装調査](./existing_impl.md) +- [技術スタック](./tech_stack.md) +- [依存関係分析](./dependencies.md) +- [複雑度評価](./complexity.md) +- [課題と制約](./constraints.md) + +--- + +## クイックナビゲーション + +### 重要な発見 +1. {{発見1}} - [詳細](./{{section}}.md) +2. {{発見2}} - [詳細](./{{section}}.md) + +### 推奨される追加調査 +1. {{追加調査1}} - {{理由}} +2. {{追加調査2}} - {{理由}} + +--- + +*各ファイルの詳細は上記リンクから参照してください。* +``` + +### 8.2 初期調査サマリーファイルの作成 + +次に `{{ベースディレクトリ}}/survey_summary.md` を作成してください。 + +形式: +```markdown +# 増分開発 初期調査 - サマリー + +**実施日時**: {{実施日時}} +**分析者**: Claude Code + +[← インデックスに戻る](./index.md) + +--- + +## 調査対象 + +### 開発対象 +- **対象**: {{開発対象の詳細}} +- **開発種類**: {{開発の種類}} +- **優先事項**: {{実装の優先事項}} +- **調査深度**: {{調査の深さ}} +- **除外条件**: {{除外条件}} + +--- + +## 調査サマリー + +| 項目 | 内容 | +|------|------| +| 類似実装の有無 | あり/なし | +| 技術的難易度 | 高/中/低 | +| 実装の複雑さ | 高/中/低 | +| 概算工数 | XX日〜XX日 | +| 主な技術スタック | {{技術スタックの要約}} | + +### 総合評価 + +{{調査全体を通じた総合的な評価を記述}} + +--- + +## 主要な発見事項 + +### 1. {{発見事項1のタイトル}} +- **詳細**: {{説明}} +- **影響**: {{開発への影響}} +- **推奨**: {{推奨アクション}} + +### 2. {{発見事項2のタイトル}} +- **詳細**: {{説明}} +- **影響**: {{開発への影響}} +- **推奨**: {{推奨アクション}} + +### 3. {{発見事項3のタイトル}} +- **詳細**: {{説明}} +- **影響**: {{開発への影響}} +- **推奨**: {{推奨アクション}} + +--- + +## 推奨される追加調査項目 + +以下の項目について、追加調査を推奨します： + +### 1. {{追加調査項目1}} +- **理由**: {{なぜこの調査が必要か}} +- **調査内容**: {{具体的に何を調査するか}} +- **優先度**: 高/中/低 + +### 2. {{追加調査項目2}} +- **理由**: {{なぜこの調査が必要か}} +- **調査内容**: {{具体的に何を調査するか}} +- **優先度**: 高/中/低 + +### 3. {{追加調査項目3}} +- **理由**: {{なぜこの調査が必要か}} +- **調査内容**: {{具体的に何を調査するか}} +- **優先度**: 高/中/低 + +--- + +## 実装アプローチの候補 + +以下の実装アプローチが考えられます： + +### アプローチA: {{アプローチ名}} +- **概要**: {{アプローチの説明}} +- **メリット**: {{メリット}} +- **デメリット**: {{デメリット}} +- **難易度**: 高/中/低 +- **工数**: {{概算}} + +### アプローチB: {{アプローチ名}} +- **概要**: {{アプローチの説明}} +- **メリット**: {{メリット}} +- **デメリット**: {{デメリット}} +- **難易度**: 高/中/低 +- **工数**: {{概算}} + +--- + +*詳細な調査内容は各セクションファイルを参照してください。* +``` + +### 8.3 既存実装調査ファイルの作成 + +`{{ベースディレクトリ}}/existing_impl.md` を作成してください。 + +形式: +```markdown +# 増分開発 初期調査 - 既存実装調査 + +**実施日時**: {{実施日時}} +**分析者**: Claude Code + +[← インデックスに戻る](./index.md) | [サマリー](./survey_summary.md) + +--- + +## 類似実装の調査 + +### 類似実装1: [相対パス](相対パス) + +- **ファイル**: {{相対パス}} +- **実装パターン**: {{パターンの説明}} +- **主要な機能**: {{機能の説明}} +- **再利用可能な部分**: {{再利用可能なコードやロジック}} +- **参考になる点**: {{参考ポイント}} + +### 類似実装2: [相対パス](相対パス) + +（同様の形式で記述） + +--- + +## 既存のアーキテクチャ + +### 全体構成 +{{プロジェクトの全体的なアーキテクチャを説明}} + +### レイヤー構成 +- **UI層**: {{説明}} +- **API層**: {{説明}} +- **サービス層**: {{説明}} +- **データアクセス層**: {{説明}} + +### 主要なデザインパターン +- {{パターン1}}: {{使用箇所と説明}} +- {{パターン2}}: {{使用箇所と説明}} + +--- + +## コーディング規約 + +### ファイル構成 +{{ファイル構成の規約}} + +### 命名規則 +{{命名規則の説明}} + +### コードスタイル +{{コードスタイルの特徴}} + +--- + +## 再利用可能なコンポーネント + +### コンポーネント1: {{名前}} +- **場所**: {{相対パス}} +- **機能**: {{機能説明}} +- **使用方法**: {{使用方法}} +- **今回の開発での活用方法**: {{活用案}} + +### コンポーネント2: {{名前}} +（同様の形式で記述） + +--- + +*このファイルには既存実装の調査結果を記載しています。* +``` + +### 8.4 その他の調査詳細ファイルの作成 + +以下のファイルを同様の形式で作成してください： +- `{{ベースディレクトリ}}/tech_stack.md` - 技術スタック +- `{{ベースディレクトリ}}/dependencies.md` - 依存関係分析 +- `{{ベースディレクトリ}}/complexity.md` - 複雑度評価 +- `{{ベースディレクトリ}}/constraints.md` - 課題と制約 + +各ファイルは以下の基本構造を持ちます： +```markdown +# 増分開発 初期調査 - {{セクション名}} + +**実施日時**: {{実施日時}} +**分析者**: Claude Code + +[← インデックスに戻る](./index.md) | [サマリー](./survey_summary.md) + +--- + +## {{セクションの内容}} + +（セクション固有の内容） + +--- + +*このファイルには{{セクション名}}の調査結果を記載しています。* +``` + +# 調査の注意点 + +- すべての調査は実際のコードベースを確認して行う +- 推測ではなく、具体的な証拠に基づいて記述する +- ファイルパスは必ず相対パスで記載する +- 各セクションファイルは500行以内に収める +- コードサンプルは必要最小限に抑える（重要な部分のみ） + +# 出力手順 + +**重要**: 必ず以下の順序でファイルを作成してください： + +1. **インデックスファイルを最初に作成** (`{{ベースディレクトリ}}/index.md`) + - Write ツールで保存 + +2. **サマリーファイルを作成** (`{{ベースディレクトリ}}/survey_summary.md`) + - Write ツールで保存 + +3. **調査詳細ファイルを作成** + - 各ファイルを個別に Write ツールで保存 + - `existing_impl.md`, `tech_stack.md`, `dependencies.md`, `complexity.md`, `constraints.md` + +**各ファイルは Write ツールを使って個別に保存してください。一つのファイルにまとめないでください。** + + + +あなたは増分開発の追加調査エキスパートです。以下の情報に基づいて、指定された項目について追加調査を実施し、ファイル出力してください。 + +# 追加調査の情報 + +開発対象: {{開発対象の具体的な情報}} +調査項目: {{追加調査項目名}} +調査理由: {{なぜこの調査が必要か}} +初期調査ファイル: {{初期調査ファイルのリスト}} +出力ファイル名: {{追加調査ファイル名}}（例: ".dcs/20251025143000_user_auth/detail_security_2.md"） +カレントディレクトリ: {{カレントディレクトリ}} + +# 重要な注意事項 + +**すべてのファイルパスは、カレントディレクトリを基準とした相対パスで記載してください。** +**絶対パス（/Users/... や C:\... など）は使用しないでください。** +**ファイルは500行以内を目標としてください。500行を超える場合は、複数ファイルに分割してください。** + +# 調査手順 + +## 1. 初期調査結果の確認 + +- {{初期調査ファイルのリスト}} に含まれるファイルを Read で読み込む +- 初期調査で判明した内容を把握する +- 追加調査が必要になった背景を理解する + +## 2. 詳細調査の実施 + +調査項目に応じて、以下の観点で詳細調査を行う： + +### セキュリティ調査の場合 +- 認証・認可の仕組み +- データ保護の方法 +- セキュリティベストプラクティスとの照合 +- 既存のセキュリティ実装パターン + +### パフォーマンス調査の場合 +- 既存のパフォーマンス特性 +- ボトルネックの可能性 +- 最適化の余地 +- パフォーマンステストの有無 + +### スケーラビリティ調査の場合 +- 現在の拡張性 +- 将来の成長への対応 +- スケールアウト/スケールアップの可能性 + +### データ整合性調査の場合 +- トランザクション管理 +- データ一貫性の保証方法 +- 並行制御の仕組み + +### UI/UX調査の場合 +- 既存のUI/UXパターン +- ユーザビリティの考慮事項 +- アクセシビリティ対応 + +### 統合調査の場合 +- 外部システムとの連携方法 +- API仕様 +- データフォーマット + +### 移行調査の場合 +- データ移行の必要性 +- 後方互換性の確保 +- 移行戦略 + +### 運用調査の場合 +- 監視とログ +- デプロイ方法 +- 運用上の考慮事項 + +## 3. 調査結果のファイル出力 + +以下の形式で {{出力ファイル名}} に結果を保存してください。 + +形式: +```markdown +# 増分開発 追加調査 - {{調査項目名}} + +**実施日時**: {{実施日時}} +**分析者**: Claude Code +**調査番号**: {{連番}} + +--- + +## 調査概要 + +### 調査項目 +{{調査項目名}} + +### 調査理由 +{{なぜこの調査が必要になったか}} + +### 調査方法 +{{どのような方法で調査を行ったか}} + +--- + +## 調査結果 + +### 主要な発見 + +#### 発見1: {{発見のタイトル}} +- **詳細**: {{詳細説明}} +- **影響**: {{開発への影響}} +- **関連ファイル**: [{{相対パス}}]({{相対パス}}) +- **推奨**: {{推奨アクション}} + +#### 発見2: {{発見のタイトル}} +（同様の形式で記述） + +--- + +## 詳細分析 + +### {{分析観点1}} +{{詳細な分析内容}} + +### {{分析観点2}} +{{詳細な分析内容}} + +--- + +## 実装への影響 + +### 設計への影響 +{{設計にどのような影響があるか}} + +### 実装への影響 +{{実装にどのような影響があるか}} + +### テストへの影響 +{{テストにどのような影響があるか}} + +--- + +## 推奨事項 + +### 推奨1: {{推奨のタイトル}} +- **理由**: {{理由}} +- **内容**: {{具体的な推奨内容}} +- **優先度**: 高/中/低 + +### 推奨2: {{推奨のタイトル}} +（同様の形式で記述） + +--- + +## 参考情報 + +### 参考ファイル +- [{{相対パス}}]({{相対パス}}) - {{説明}} + +### 参考ドキュメント +- {{ドキュメント名}} - {{説明}} + +--- + +*この調査結果は初期調査を補完するものです。初期調査結果と合わせて参照してください。* +``` + +# 出力手順 + +**重要**: Write ツールを使用して、{{出力ファイル名}} に結果を保存してください。 + +調査結果は具体的な証拠に基づいて記述し、推測は最小限に抑えてください。 + + + +あなたは増分開発のPRD作成エキスパートです。以下の情報に基づいて、指定された実装アプローチのPRDを作成してください。 + +# PRD作成の情報 + +開発対象: {{開発対象の具体的な情報}} +実装アプローチ: {{実装アプローチ名}} +調査ファイル: {{全調査ファイルのリスト}} +PRDベースディレクトリ: {{PRDベースディレクトリ}}（例: ".dcs/20251025143000_user_auth"） +PRDファイルプレフィックス: {{PRDファイルプレフィックス}}（例: "prd_jwt"） +カレントディレクトリ: {{カレントディレクトリ}} + +# 重要な注意事項 + +**すべてのファイルパスは、カレントディレクトリを基準とした相対パスで記載してください。** +**絶対パス（/Users/... や C:\... など）は使用しないでください。** +**各セクションファイルは500行以内を目標としてください。** + +# 出力ファイル構成 + +PRDは以下のセクション別ファイルに分割して出力してください： + +1. **PRDインデックス**: `{{PRDベースディレクトリ}}/{{PRDファイルプレフィックス}}_index.md` +2. **要件定義**: `{{PRDベースディレクトリ}}/{{PRDファイルプレフィックス}}_requirements.md` +3. **技術設計**: `{{PRDベースディレクトリ}}/{{PRDファイルプレフィックス}}_design.md` +4. **実装計画**: `{{PRDベースディレクトリ}}/{{PRDファイルプレフィックス}}_plan.md` +5. **テスト戦略**: `{{PRDベースディレクトリ}}/{{PRDファイルプレフィックス}}_tests.md` +6. **リスクと対策**: `{{PRDベースディレクトリ}}/{{PRDファイルプレフィックス}}_risks.md` + +# PRD作成手順 + +## 1. 全調査結果の確認 + +- {{全調査ファイルのリスト}} に含まれるすべてのファイルを Read で読み込む +- 初期調査と追加調査の内容を統合して理解する +- 実装アプローチの詳細を把握する + +## 2. 各セクションファイルの作成 + +### 2.1 PRDインデックスファイルの作成 + +`{{PRDベースディレクトリ}}/{{PRDファイルプレフィックス}}_index.md` を作成してください。 + +形式: +```markdown +# PRD - {{実装アプローチ名}} - インデックス + +**作成日時**: {{作成日時}} +**作成者**: Claude Code +**対象**: {{開発対象}} + +--- + +## PRD概要 + +### 実装アプローチ +{{実装アプローチ名}} + +### アプローチの概要 +{{実装アプローチの説明}} + +### 主要な特徴 +- {{特徴1}} +- {{特徴2}} +- {{特徴3}} + +--- + +## PRDドキュメント一覧 + +1. [要件定義](./{{PRDファイルプレフィックス}}_requirements.md) - 機能要件、非機能要件、受け入れ基準 +2. [技術設計](./{{PRDファイルプレフィックス}}_design.md) - アーキテクチャ、データモデル、API設計 +3. [実装計画](./{{PRDファイルプレフィックス}}_plan.md) - タスク分割、スケジュール、工数 +4. [テスト戦略](./{{PRDファイルプレフィックス}}_tests.md) - テストケース、テスト範囲 +5. [リスクと対策](./{{PRDファイルプレフィックス}}_risks.md) - リスク分析、軽減策 + +--- + +## クイックサマリー + +| 項目 | 内容 | +|------|------| +| 技術的難易度 | 高/中/低 | +| 概算工数 | XX日 | +| 主要リスク | {{リスクの概要}} | +| 推奨優先度 | 高/中/低 | + +--- + +*各ドキュメントの詳細は上記リンクから参照してください。* +``` + +### 2.2 要件定義ファイルの作成 + +`{{PRDベースディレクトリ}}/{{PRDファイルプレフィックス}}_requirements.md` を作成してください。 + +形式: +```markdown +# PRD - {{実装アプローチ名}} - 要件定義 + +**作成日時**: {{作成日時}} +**作成者**: Claude Code + +[← PRDインデックスに戻る](./{{PRDファイルプレフィックス}}_index.md) + +--- + +## 機能要件 + +### FR-001: {{機能要件1}} +- **説明**: {{機能の説明}} +- **優先度**: 必須/推奨/オプション +- **実装詳細**: {{詳細}} + +### FR-002: {{機能要件2}} +（同様の形式で記述） + +--- + +## 非機能要件 + +### NFR-001: パフォーマンス +- **要件**: {{パフォーマンス要件}} +- **測定方法**: {{測定方法}} +- **目標値**: {{目標値}} + +### NFR-002: セキュリティ +- **要件**: {{セキュリティ要件}} +- **対応方法**: {{対応方法}} + +### NFR-003: 拡張性 +- **要件**: {{拡張性要件}} +- **対応方法**: {{対応方法}} + +--- + +## 受け入れ基準 + +### 機能的受け入れ基準 +1. {{基準1}} +2. {{基準2}} +3. {{基準3}} + +### 非機能的受け入れ基準 +1. {{基準1}} +2. {{基準2}} + +--- + +## ユーザーストーリー + +### US-001: {{ユーザーストーリー1}} +- **As a** {{ユーザー}} +- **I want to** {{やりたいこと}} +- **So that** {{理由}} +- **受け入れ基準**: + - {{基準1}} + - {{基準2}} + +### US-002: {{ユーザーストーリー2}} +（同様の形式で記述） + +--- + +## 成功指標 + +### 主要指標 +- **{{指標1}}**: {{目標値と測定方法}} +- **{{指標2}}**: {{目標値と測定方法}} + +### 副次的指標 +- **{{指標3}}**: {{目標値と測定方法}} + +--- + +*この要件定義は調査結果に基づいて作成されています。* +``` + +### 2.3 技術設計ファイルの作成 + +`{{PRDベースディレクトリ}}/{{PRDファイルプレフィックス}}_design.md` を作成してください。 + +形式: +```markdown +# PRD - {{実装アプローチ名}} - 技術設計 + +**作成日時**: {{作成日時}} +**作成者**: Claude Code + +[← PRDインデックスに戻る](./{{PRDファイルプレフィックス}}_index.md) + +--- + +## システムアーキテクチャ + +### 全体構成 +{{アーキテクチャの説明}} + +### コンポーネント構成 +- **{{コンポーネント1}}**: {{説明}} +- **{{コンポーネント2}}**: {{説明}} + +### データフロー +{{データの流れの説明}} + +--- + +## データモデル + +### エンティティ1: {{エンティティ名}} + +```typescript +interface {{エンティティ名}} { + // フィールド定義 +} +``` + +- **説明**: {{エンティティの説明}} +- **関連**: {{他のエンティティとの関連}} + +### エンティティ2: {{エンティティ名}} +（同様の形式で記述） + +--- + +## API設計 + +### エンドポイント1: {{メソッド}} {{パス}} + +- **説明**: {{エンドポイントの説明}} +- **リクエスト**: + ```json + { + // リクエストボディ + } + ``` +- **レスポンス**: + ```json + { + // レスポンスボディ + } + ``` +- **エラー**: {{エラーケース}} + +### エンドポイント2: {{メソッド}} {{パス}} +（同様の形式で記述） + +--- + +## セキュリティ設計 + +### 認証 +{{認証方法の説明}} + +### 認可 +{{認可方法の説明}} + +### データ保護 +{{データ保護方法の説明}} + +--- + +## パフォーマンス設計 + +### 最適化戦略 +{{最適化の方針}} + +### キャッシング +{{キャッシング戦略}} + +### データベースインデックス +{{インデックス設計}} + +--- + +*この技術設計は要件定義と調査結果に基づいて作成されています。* +``` + +### 2.4 実装計画ファイルの作成 + +`{{PRDベースディレクトリ}}/{{PRDファイルプレフィックス}}_plan.md` を作成してください。 + +形式: +```markdown +# PRD - {{実装アプローチ名}} - 実装計画 + +**作成日時**: {{作成日時}} +**作成者**: Claude Code + +[← PRDインデックスに戻る](./{{PRDファイルプレフィックス}}_index.md) + +--- + +## タスク分割 + +### フェーズ1: {{フェーズ名}}（XX日） + +#### タスク1.1: {{タスク名}} +- **説明**: {{タスクの説明}} +- **工数**: {{概算工数}} +- **優先度**: 高/中/低 +- **依存**: {{依存するタスク}} +- **成果物**: {{成果物}} + +#### タスク1.2: {{タスク名}} +（同様の形式で記述） + +### フェーズ2: {{フェーズ名}}（XX日） +（同様の形式で記述） + +--- + +## 依存関係 + +```mermaid +graph TD + A[タスク1] --> B[タスク2] + A --> C[タスク3] + B --> D[タスク4] + C --> D +``` + +--- + +## 工数見積もり + +| フェーズ | タスク数 | 工数（日） | 備考 | +|---------|---------|-----------|------| +| フェーズ1 | XX | XX | {{備考}} | +| フェーズ2 | XX | XX | {{備考}} | +| 合計 | XX | XX | - | + +--- + +## マイルストーン + +### M1: {{マイルストーン1}}（{{日付}}） +- {{達成基準}} + +### M2: {{マイルストーン2}}（{{日付}}） +- {{達成基準}} + +--- + +## リソース計画 + +### 必要なスキル +- {{スキル1}} +- {{スキル2}} + +### 必要なツール/環境 +- {{ツール1}} +- {{ツール2}} + +--- + +*この実装計画は技術設計に基づいて作成されています。* +``` + +### 2.5 テスト戦略ファイルの作成 + +`{{PRDベースディレクトリ}}/{{PRDファイルプレフィックス}}_tests.md` を作成してください。 + +形式: +```markdown +# PRD - {{実装アプローチ名}} - テスト戦略 + +**作成日時**: {{作成日時}} +**作成者**: Claude Code + +[← PRDインデックスに戻る](./{{PRDファイルプレフィックス}}_index.md) + +--- + +## テスト方針 + +### テストレベル +- **ユニットテスト**: {{方針}} +- **統合テスト**: {{方針}} +- **E2Eテスト**: {{方針}} + +### カバレッジ目標 +- **コードカバレッジ**: XX% +- **機能カバレッジ**: XX% + +--- + +## ユニットテスト + +### テストケース1: {{テストケース名}} +- **対象**: {{テスト対象の関数/クラス}} +- **テスト内容**: {{テスト内容}} +- **期待結果**: {{期待結果}} + +### テストケース2: {{テストケース名}} +（同様の形式で記述） + +--- + +## 統合テスト + +### テストシナリオ1: {{シナリオ名}} +- **対象**: {{テスト対象のモジュール連携}} +- **前提条件**: {{前提条件}} +- **テスト手順**: + 1. {{手順1}} + 2. {{手順2}} +- **期待結果**: {{期待結果}} + +### テストシナリオ2: {{シナリオ名}} +（同様の形式で記述） + +--- + +## E2Eテスト + +### ユーザーシナリオ1: {{シナリオ名}} +- **ユーザー**: {{ユーザータイプ}} +- **目的**: {{目的}} +- **手順**: + 1. {{手順1}} + 2. {{手順2}} +- **期待結果**: {{期待結果}} + +### ユーザーシナリオ2: {{シナリオ名}} +（同様の形式で記述） + +--- + +## パフォーマンステスト + +### 負荷テスト +- **テスト内容**: {{テスト内容}} +- **目標値**: {{目標値}} +- **測定項目**: {{測定項目}} + +### ストレステスト +- **テスト内容**: {{テスト内容}} +- **目標値**: {{目標値}} + +--- + +## セキュリティテスト + +### テスト項目 +1. {{セキュリティテスト項目1}} +2. {{セキュリティテスト項目2}} + +--- + +*このテスト戦略は要件定義と技術設計に基づいて作成されています。* +``` + +### 2.6 リスクと対策ファイルの作成 + +`{{PRDベースディレクトリ}}/{{PRDファイルプレフィックス}}_risks.md` を作成してください。 + +形式: +```markdown +# PRD - {{実装アプローチ名}} - リスクと対策 + +**作成日時**: {{作成日時}} +**作成者**: Claude Code + +[← PRDインデックスに戻る](./{{PRDファイルプレフィックス}}_index.md) + +--- + +## リスク評価サマリー + +| リスクレベル | 件数 | +|------------|------| +| 高 | XX件 | +| 中 | XX件 | +| 低 | XX件 | + +--- + +## 技術的リスク + +### リスク1: {{リスク名}} +- **レベル**: 高/中/低 +- **説明**: {{リスクの説明}} +- **影響**: {{発生時の影響}} +- **発生確率**: 高/中/低 +- **軽減策**: {{リスク軽減のための対策}} +- **緊急時対応**: {{発生時の対応}} + +### リスク2: {{リスク名}} +（同様の形式で記述） + +--- + +## スケジュールリスク + +### リスク1: {{リスク名}} +- **レベル**: 高/中/低 +- **説明**: {{リスクの説明}} +- **影響**: {{発生時の影響}} +- **発生確率**: 高/中/低 +- **軽減策**: {{リスク軽減のための対策}} + +--- + +## リソースリスク + +### リスク1: {{リスク名}} +- **レベル**: 高/中/低 +- **説明**: {{リスクの説明}} +- **影響**: {{発生時の影響}} +- **発生確率**: 高/中/低 +- **軽減策**: {{リスク軽減のための対策}} + +--- + +## 外部依存リスク + +### リスク1: {{リスク名}} +- **レベル**: 高/中/低 +- **説明**: {{リスクの説明}} +- **影響**: {{発生時の影響}} +- **発生確率**: 高/中/低 +- **軽減策**: {{リスク軽減のための対策}} + +--- + +## リスク管理計画 + +### モニタリング方法 +{{リスクをどのように監視するか}} + +### エスカレーション基準 +{{いつエスカレーションするか}} + +### 定期レビュー +{{リスクの定期的な見直し方法}} + +--- + +*このリスク分析は調査結果と実装計画に基づいて作成されています。* +``` + +# 出力手順 + +**重要**: 必ず以下の順序でファイルを作成してください： + +1. **PRDインデックスファイルを作成** (`{{PRDベースディレクトリ}}/{{PRDファイルプレフィックス}}_index.md`) + - Write ツールで保存 + +2. **要件定義ファイルを作成** (`{{PRDベースディレクトリ}}/{{PRDファイルプレフィックス}}_requirements.md`) + - Write ツールで保存 + +3. **技術設計ファイルを作成** (`{{PRDベースディレクトリ}}/{{PRDファイルプレフィックス}}_design.md`) + - Write ツールで保存 + +4. **実装計画ファイルを作成** (`{{PRDベースディレクトリ}}/{{PRDファイルプレフィックス}}_plan.md`) + - Write ツールで保存 + +5. **テスト戦略ファイルを作成** (`{{PRDベースディレクトリ}}/{{PRDファイルプレフィックス}}_tests.md`) + - Write ツールで保存 + +6. **リスクと対策ファイルを作成** (`{{PRDベースディレクトリ}}/{{PRDファイルプレフィックス}}_risks.md`) + - Write ツールで保存 + +**各ファイルは Write ツールを使って個別に保存してください。** + +# PRD作成の注意点 + +- 調査結果に基づいて具体的に記述する +- 推測や仮定は明示する +- 実装可能性を考慮した現実的な計画を立てる +- 各セクションは500行以内に収める +- ファイルパスは必ず相対パスで記載する + + + +あなたは増分開発の最終サマリー作成エキスパートです。以下の情報に基づいて、全体サマリーを作成してください。 + +# サマリー作成対象の情報 + +開発対象: {{開発対象の具体的な情報}} +分析ファイルリスト: {{分析ファイルリスト}}（初期調査、追加調査、PRDなど） +最終サマリーファイル名: {{サマリーファイル名}}（例: ".dcs/20251025143000_user_auth/final_summary.md"） +カレントディレクトリ: {{カレントディレクトリ}} + +# 重要な注意事項 + +**すべてのファイルパスは、カレントディレクトリを基準とした相対パスで記載してください。** +**絶対パス（/Users/... や C:\... など）は使用しないでください。** +**このファイルは500行以内に収まるように簡潔に記述してください。** + +# サマリー作成手順 + +## 1. 全ファイルの読み込み + +- {{分析ファイルリスト}} に含まれるすべてのファイルを Read で読み込む +- 各ファイルの内容を把握する + +## 2. 情報の統合 + +- すべての分析結果とPRDから以下の情報を統合する + - 主要な発見事項 + - 技術的難易度と工数 + - 実装アプローチの比較 + - 推奨されるアプローチ + - 主要なリスク + +## 3. サマリーファイルの出力 + +以下の形式で {{サマリーファイル名}} に結果を保存してください。 + +形式: +```markdown +# 増分開発 - 最終サマリー + +**作成日時**: {{作成日時}} +**作成者**: Claude Code + +--- + +## ナビゲーション + +### 初期調査 +- [初期調査インデックス](./index.md) +- [初期調査サマリー](./survey_summary.md) + +### 追加調査（実施した場合） +- [追加調査1](./detail_{{topic}}_2.md) +- [追加調査2](./detail_{{topic}}_3.md) + +### PRD +- [PRD（アプローチA）インデックス](./prd_{{approach_a}}_index.md) +- [PRD（アプローチB）インデックス](./prd_{{approach_b}}_index.md) + +--- + +## 開発概要 + +### 開発対象 +- **対象**: {{開発対象の詳細}} +- **開発種類**: {{開発の種類}} +- **優先事項**: {{実装の優先事項}} + +### 実施した分析 +- **初期調査**: {{実施日}} +- **追加調査**: {{実施した追加調査の数}}件 +- **作成したPRD**: {{作成したPRDの数}}件 + +--- + +## 主要な発見事項 + +### 発見1: {{発見事項1のタイトル}} +- **詳細**: {{説明}} +- **影響**: {{開発への影響}} +- **重要度**: 高/中/低 + +### 発見2: {{発見事項2のタイトル}} +- **詳細**: {{説明}} +- **影響**: {{開発への影響}} +- **重要度**: 高/中/低 + +### 発見3: {{発見事項3のタイトル}} +- **詳細**: {{説明}} +- **影響**: {{開発への影響}} +- **重要度**: 高/中/低 + +--- + +## 実装アプローチの比較 + +### アプローチA: {{アプローチ名}} + +| 項目 | 評価 | +|------|------| +| 技術的難易度 | 高/中/低 | +| 概算工数 | XX日 | +| 主要なメリット | {{メリット}} | +| 主要なデメリット | {{デメリット}} | +| リスクレベル | 高/中/低 | + +### アプローチB: {{アプローチ名}} + +（同様の形式で記述） + +--- + +## 推奨される実装アプローチ + +### 推奨: {{推奨アプローチ名}} + +**推奨理由**: +1. {{理由1}} +2. {{理由2}} +3. {{理由3}} + +**主要なメリット**: +- {{メリット1}} +- {{メリット2}} + +**注意点**: +- {{注意点1}} +- {{注意点2}} + +--- + +## 技術的サマリー + +### 主要な技術スタック +- {{技術1}} +- {{技術2}} +- {{技術3}} + +### 再利用可能なコンポーネント +- [{{コンポーネント1}}]({{相対パス}}) +- [{{コンポーネント2}}]({{相対パス}}) + +### 新規に必要な実装 +- {{実装1}} +- {{実装2}} + +--- + +## 工数とスケジュール + +### 推奨アプローチの工数 + +| フェーズ | 工数（日） | 主要タスク | +|---------|-----------|----------| +| フェーズ1 | XX | {{タスク概要}} | +| フェーズ2 | XX | {{タスク概要}} | +| フェーズ3 | XX | {{タスク概要}} | +| 合計 | XX | - | + +### マイルストーン +1. **M1** ({{日付}}): {{達成基準}} +2. **M2** ({{日付}}): {{達成基準}} +3. **M3** ({{日付}}): {{達成基準}} + +--- + +## 主要なリスクと対策 + +### リスク1: {{リスク名}}（レベル: 高/中/低） +- **影響**: {{影響}} +- **軽減策**: {{対策}} + +### リスク2: {{リスク名}}（レベル: 高/中/低） +- **影響**: {{影響}} +- **軽減策**: {{対策}} + +### リスク3: {{リスク名}}（レベル: 高/中/低） +- **影響**: {{影響}} +- **軽減策**: {{対策}} + +--- + +## テスト戦略サマリー + +### テストレベル別のカバレッジ +- **ユニットテスト**: {{カバレッジ目標}}、{{主要なテスト対象}} +- **統合テスト**: {{カバレッジ目標}}、{{主要なテスト対象}} +- **E2Eテスト**: {{主要なシナリオ数}}シナリオ + +### 重点的にテストすべき領域 +1. {{領域1}} +2. {{領域2}} +3. {{領域3}} + +--- + +## 次のステップ + +### 即座に実施すべきこと +1. {{ステップ1}} +2. {{ステップ2}} + +### 実装開始前に確認すべきこと +1. {{確認事項1}} +2. {{確認事項2}} + +### 実装中に注意すべきこと +1. {{注意事項1}} +2. {{注意事項2}} + +--- + +## 作成されたドキュメント一覧 + +### 初期調査 +1. [{{ファイル名}}]({{相対パス}}) - {{説明}} +2. [{{ファイル名}}]({{相対パス}}) - {{説明}} +... + +### 追加調査 +1. [{{ファイル名}}]({{相対パス}}) - {{説明}} +... + +### PRD +1. [{{ファイル名}}]({{相対パス}}) - {{説明}} +... + +--- + +## 分析の制限事項 + +- {{制限事項1}} +- {{制限事項2}} +- {{制限事項3}} + +--- + +*このサマリーは複数の分析結果とPRDを統合して自動生成されたものです。詳細は個別のドキュメントを参照してください。* +``` + +# 出力手順 + +**重要**: Write ツールを使用して、{{サマリーファイル名}} に結果を保存してください。 + +サマリーは全体を俯瞰できるように、重要な情報を簡潔にまとめてください。 + diff --git a/commands/dcs/performance-analysis.md b/commands/dcs/performance-analysis.md new file mode 100644 index 0000000..f466cc8 --- /dev/null +++ b/commands/dcs/performance-analysis.md @@ -0,0 +1,1024 @@ +--- +description: 性能問題の原因を調査する +allowed-tools: Read, Glob, Grep, Task, Bash, AskUserQuestion, TodoWrite +argument-hint: [調査対象（機能名/エンドポイント/画面/自然言語）] +--- +性能問題の原因を特定するための包括的な調査を実施します。初期調査、詳細な原因分析、最終サマリーを段階的に作成し、性能問題の根本原因を明らかにします。 + +# context + +出力ディレクトリ=".dcs" +カレントディレクトリ={{プロジェクトルート}} +分析ファイルリスト=[] +調査回数=0 + +# step + +- $1 がない場合、「引数に調査対象を指定してください（例: エンドポイント名、画面名、機能名、または自然言語）」と言って終了する +- $1 の内容を簡潔に説明する +- TodoWrite ツールで以下のタスクリストを作成する： + 1. 性能問題の詳細情報を収集 + 2. 初期調査の実施 + 3. 原因候補の特定と詳細調査 + 4. 最終サマリーの作成 +- タスク1を in_progress にする +- AskUserQuestion ツールを使って以下の質問を順番に実施し、context を更新する： + 1. 性能劣化の症状を確認 + 2. 発生タイミングを確認 + 3. 影響範囲を確認 + 4. 環境情報を確認 +- 収集した context の内容をまとめてユーザに宣言する +- タスク1を completed にして、タスク2を in_progress にする +- step2 を実行する + +## step2 + +- 既存の出力ファイルを確認して、重複しないナンバリングを決定する + - {{出力ディレクトリ}}/{{timestamp}}_* を検索 + - 今回の内容を簡単に英語化したもの（例: "order_api", "cart_screen"）を作成 + - 同じ timestamp と内容で既存ディレクトリがある場合、末尾の連番を +1 する + - ベースディレクトリを "{{出力ディレクトリ}}/{{timestamp}}_{{内容の英語化}}" とする + - 例: ".dcs/20251025_123456_order_api" + - 例: ".dcs/20251025_123456_cart_screen" +- 分析結果ファイルのリストを準備する + - インデックスファイル: "{{ベースディレクトリ}}/index.md" + - 初期調査ファイル: "{{ベースディレクトリ}}/initial.md" + - 原因分析ファイル: "{{ベースディレクトリ}}/causes.md" + - 推奨対応ファイル: "{{ベースディレクトリ}}/recommendations.md" +- すべてのファイル名を 分析ファイルリスト に追加する +- の内容を context の情報で埋めて、Task ツールで直接実行する + - subagent_type: "general-purpose" + - description: "性能劣化 初期調査の実行" + - prompt: テンプレートの内容を context で埋めた完全なプロンプト +- Task の実行結果を受け取る +- 調査回数を 1 にする +- タスク2を completed にして、タスク3を in_progress にする +- step3 を実行する + +## step3 + +- 出力されたファイルを Read で確認する +- causes ファイルから原因候補をリストアップする +- 各原因候補について詳細調査が必要かを判断する +- 詳細調査が必要な場合： + - 調査する原因候補をリストとしてユーザに提示する + - ユーザの承認を得る + - 各原因候補に対して個別に Task ツールで詳細調査を実行する + - 各調査ごとに新しい連番で追加ファイルとして保存する（例: "detail_2.md", "detail_3.md"） + - 各ファイル名を 分析ファイルリスト に追加する + - 調査回数を +1 する + - 再度 step3 を実行する（詳細調査が不要になるまで繰り返す、最大5回） +- 詳細調査が不要な場合： + - タスク3を completed にして、タスク4を in_progress にする + - step4 を実行する + +## step4 + +- の内容を使って、Task ツールで最終サマリーファイルを作成する + - subagent_type: "general-purpose" + - description: "性能劣化調査 最終サマリーの作成" + - prompt: サマリーテンプレートの内容を context で埋めた完全なプロンプト + - 最終サマリーファイル名: "{{ベースディレクトリ}}/final_summary.md" +- 全ての分析ファイルのパスを調査回数別に整理して表示する + - 初期調査ファイル一覧 + - 詳細調査ファイル一覧（該当する場合） + - 最終サマリー +- タスク4を completed にする +- 調査完了をユーザに報告する + +# rules + +## 確認ポイント + +AskUserQuestion ツールを使って、以下の質問を順番に実施する： + +### 質問1: 性能問題の症状 +- **質問**: どのような性能問題が発生していますか？ +- **header**: "症状" +- **multiSelect**: true +- **options**: + - "レスポンスが遅い" - API応答やページ表示が遅い + - "タイムアウトが発生する" - 処理が完了せずタイムアウトする + - "メモリ使用量が多い" - メモリリークやメモリ圧迫 + - "CPU使用率が高い" - CPUリソースを過剰に消費 + - "データベースが遅い" - DBクエリの実行が遅い + - "その他" - 上記以外の症状（追記で詳細を指定） + +### 質問2: 発生タイミング +- **質問**: 性能問題はいつから発生していますか？ +- **header**: "発生時期" +- **options**: + - "最近のリリース後" - 特定のリリース後に発生 + - "データ量増加後" - データベースのデータが増えてから + - "アクセス数増加後" - ユーザー数やトラフィックが増えてから + - "特定の時間帯のみ" - ピーク時や特定時刻のみ + - "常に発生" - システム起動時から常に遅い + +### 質問3: 影響範囲 +- **質問**: 性能問題の影響範囲はどの程度ですか？ +- **header**: "影響範囲" +- **options**: + - "特定の機能のみ" - 一部の機能やページのみ + - "特定のユーザーのみ" - 特定の条件下のユーザーのみ + - "システム全体" - システム全体に影響 + - "不明" - 影響範囲が明確でない + +### 質問4: 環境情報 +- **質問**: どの環境で発生していますか？ +- **header**: "環境" +- **multiSelect**: true +- **options**: + - "本番環境" - 本番環境で発生 + - "ステージング環境" - ステージング環境で発生 + - "開発環境" - 開発環境で発生 + - "ローカル環境" - ローカル開発環境で発生 + +contextとして以下を保持する： +- 調査対象（具体的な機能名やエンドポイント） +- 性能劣化の症状 +- 発生タイミング +- 影響範囲 +- 環境情報 + +## ファイル名のルール + +### timestamp の形式 +- yyyyMMddHHmmss 形式（例: 20251025123456） + +### 内容の英語化のルール +- 調査対象を簡潔な英語に変換する +- スネークケース（snake_case）を使用 +- 最大30文字程度に収める +- 例: + - "注文API" → "order_api" + - "カート画面" → "cart_screen" + - "商品検索" → "goods_search" + +### ファイル構成 +- `index.md` - インデックス（全体概要とファイル一覧） +- `initial.md` - 初期調査結果 +- `causes.md` - 原因候補の分析 +- `recommendations.md` - 推奨対応 +- `detail_N.md` - 詳細調査結果（Nは連番） +- `final_summary.md` - 最終サマリー + +### 完全なファイル名の例 +**初期調査**: +- `.dcs/20251025123456_order_api/index.md` +- `.dcs/20251025123456_order_api/initial.md` +- `.dcs/20251025123456_order_api/causes.md` +- `.dcs/20251025123456_order_api/recommendations.md` + +**詳細調査**: +- `.dcs/20251025123456_order_api/detail_2.md` +- `.dcs/20251025123456_order_api/detail_3.md` + +**最終サマリー**: +- `.dcs/20251025123456_order_api/final_summary.md` + +## ファイルパスの記載ルール + +- **カレントディレクトリを基準とした相対パスを使用する** +- フルパス（絶対パス）は記載しない +- 例: + - ❌ `/Users/makotan/projects/ensemble-si/backend/src/main/kotlin/...` + - ✅ `backend/src/main/kotlin/...` + +## 原因候補の分類 + +性能問題の原因候補を以下のカテゴリで分類する： + +### 1. データベース関連 +- N+1クエリ問題 +- インデックスの欠如 +- 非効率なクエリ +- トランザクションの長時間ロック +- データ量の増加 + +### 2. アプリケーション層 +- メモリリーク +- 不適切なキャッシュ戦略 +- 同期処理のボトルネック +- 大量のオブジェクト生成 +- 非効率なアルゴリズム +- 同一処理の重複実行 + +### 3. ネットワーク・通信 +- 外部API呼び出しの遅延 +- 不要な通信の繰り返し +- 大容量データの転送 +- タイムアウト設定の不備 + +### 4. インフラ・環境 +- リソース不足（CPU、メモリ、ディスク） +- ネットワーク帯域の問題 +- 環境設定の不備 +- ログ出力の過多 + +### 5. アーキテクチャ +- 責務の集中 +- モジュール間の密結合 +- スケーラビリティの欠如 + +## 詳細調査が必要な条件 + +以下の条件のいずれかに該当する場合、詳細調査を提案する： + +- 原因候補が複数あり、特定に至っていない +- データベースクエリの詳細な分析が必要 +- コードの実装詳細の確認が必要 +- 外部サービスとの連携部分の調査が必要 +- 環境設定やインフラの確認が必要 +- パフォーマンステストの結果分析が必要 + +## step3 の繰り返しルール + +- 詳細調査が必要な項目がある場合、step3 を繰り返す +- 最大5回まで繰り返す（無限ループ防止） +- 詳細調査項目が複数ある場合は、各項目ごとに個別に Task を実行する +- 各繰り返しで新しい連番のファイルを作成する +- ユーザーの承認を得てから次の調査を実行する +- 詳細調査が不要になったら step4 に進む + +# info + + +あなたは性能問題の調査エキスパートです。以下の情報に基づいて、性能問題の原因を調査し、ファイル出力してください。 + +# 調査対象の情報 + +調査対象: {{調査対象の具体的な情報}} +症状: {{性能劣化の症状}} +発生タイミング: {{発生タイミング}} +影響範囲: {{影響範囲}} +環境: {{環境情報}} +ベースディレクトリ: {{ベースディレクトリ}}（例: ".dcs/20251025123456_order_api"） +カレントディレクトリ: {{カレントディレクトリ}} + +# 重要な注意事項 + +**すべてのファイルパスは、カレントディレクトリを基準とした相対パスで記載してください。** +**絶対パス（/Users/... や C:\\... など）は使用しないでください。** + +例: +- ❌ `/Users/makotan/projects/ensemble-si/backend/src/main/kotlin/...` +- ✅ `backend/src/main/kotlin/...` + +# 出力ファイル構成 + +調査結果は以下のファイルに分割して出力してください： + +1. **インデックスファイル**: `{{ベースディレクトリ}}/index.md` + - 全体概要と全ファイルへのリンク + +2. **初期調査ファイル**: `{{ベースディレクトリ}}/initial.md` + - プロジェクト概要と調査対象の詳細分析 + +3. **原因分析ファイル**: `{{ベースディレクトリ}}/causes.md` + - 考えられる原因候補のリストと分析 + +4. **推奨対応ファイル**: `{{ベースディレクトリ}}/recommendations.md` + - 具体的な改善提案と対応方針 + +# 調査手順 + +## 1. 調査対象の特定 + +- 調査対象が自然言語の場合、Grep/Globで具体的なファイル・関数・クラスを特定する +- 調査対象がエンドポイントの場合、対応するコントローラーやサービスを特定する +- 調査対象が画面の場合、対応するコンポーネントとAPI通信を特定する +- 特定結果を記録する（相対パス、行番号、コード要素の種類） + +## 2. プロジェクト概要の把握 + +- アーキテクチャの理解（BFF、Prismatix Factory、データフローなど） +- 使用技術スタックの確認 +- 関連するコンポーネントの特定 +- データベーススキーマの確認（prismatix-factory/resources/*.yaml） + +## 3. 調査対象の詳細分析 + +### コード実装の確認 +- 主要な処理フローを追跡する +- データベースアクセス部分を特定する +- 外部API呼び出しを特定する +- ループや再帰処理を確認する + +### データベースクエリの分析 +- SQLクエリを抽出する +- クエリの実行回数を推定する +- インデックスの有無を確認する +- JOINの複雑さを評価する + +### 依存関係の確認 +- 関連するファイルとその役割 +- サービス間の呼び出し関係 +- データの流れ + +## 4. 原因候補の特定 + +以下の観点から原因候補を分析する： + +### データベース関連 +- **N+1問題の有無**: ループ内でのクエリ実行 +- **インデックス**: 必要なインデックスが存在するか +- **クエリ最適化**: JOIN、WHERE句、SELECT句の効率性 +- **トランザクション**: 長時間ロックの可能性 +- **データ量**: テーブルのレコード数とパフォーマンスの関係 + +調査方法： +```bash +# Prismatix Factoryのリソース定義を確認 +# インデックス定義を確認 +# クエリの複雑さを分析 +``` + +### アプリケーション層 +- **メモリ使用**: オブジェクト生成やキャッシュ戦略 +- **同期処理**: ブロッキング処理の有無 +- **アルゴリズム**: 計算量の評価（O(n), O(n²)など） +- **並列処理**: 非同期処理の活用度 +- **重複処理**: フロー内での同一機能の重複処理 + +調査方法： +- コードレビュー +- ループのネスト構造確認 +- メモリ使用パターンの分析 + +### ネットワーク・通信 +- **API呼び出し**: 外部API呼び出しの回数と応答時間 +- **BFF層**: BFFとバックエンド間の通信効率 +- **データサイズ**: 転送データ量 +- **タイムアウト**: 適切なタイムアウト設定 + +調査方法： +- API呼び出し箇所の特定 +- データペイロードサイズの確認 +- 通信回数の推定 + +### インフラ・環境 +- **リソース**: CPU、メモリ、ディスク使用率 +- **設定**: JVMオプション、接続プール設定 +- **ログ**: 過剰なログ出力 +- **環境差異**: 本番と開発環境の差異 + +調査方法： +- 設定ファイルの確認（application.yml、環境変数） +- リソース設定の確認 +- ログレベルの確認 + +## 5. 各原因候補の評価 + +各原因候補について以下を評価する： + +### 可能性レベル +- **高**: 明確な証拠がある、または非常に可能性が高い +- **中**: 可能性はあるが、さらなる調査が必要 +- **低**: 可能性は低いが、念のため確認推奨 + +### 影響度 +- **高**: 修正により大幅な性能改善が期待できる +- **中**: 一定の改善が期待できる +- **低**: 限定的な改善 + +### 調査難易度 +- **低**: すぐに確認・検証可能 +- **中**: 追加の調査やテストが必要 +- **高**: 大規模な調査や環境構築が必要 + +## 6. 推奨対応の作成 + +### 即座に実施可能な対応 +- コード修正が少なく、影響範囲が限定的 +- リスクが低い +- 効果が見込める + +### 検証が必要な対応 +- 影響範囲が広い +- 追加のテストが必要 +- パフォーマンステストで効果を確認すべき + +### 長期的な対応 +- アーキテクチャの変更を伴う +- 大規模なリファクタリングが必要 +- インフラの増強が必要 + +## 7. ファイル出力 + +以下の順序で各ファイルを作成してください。**各ファイルは Write ツールを使って個別に保存してください。** + +### 7.1 インデックスファイルの作成 +`{{ベースディレクトリ}}/index.md` を作成 + +### 7.2 初期調査ファイルの作成 +`{{ベースディレクトリ}}/initial.md` を作成 + +### 7.3 原因分析ファイルの作成 +`{{ベースディレクトリ}}/causes.md` を作成 + +### 7.4 推奨対応ファイルの作成 +`{{ベースディレクトリ}}/recommendations.md` を作成 + +# 各ファイルの出力形式 + +## インデックスファイル (`index.md`) + +```markdown +# 性能劣化調査 - インデックス + +**実施日時**: {{実施日時}} +**調査者**: Claude Code + +--- + +## 調査概要 + +### 調査対象 +- **対象**: {{調査対象の詳細}} +- **症状**: {{性能劣化の症状}} +- **発生タイミング**: {{発生タイミング}} +- **影響範囲**: {{影響範囲}} +- **環境**: {{環境情報}} + +### サマリー + +| 項目 | 内容 | +|------|------| +| 原因候補数 | XX件 | +| 高可能性の原因 | XX件 | +| 推奨対応数 | XX件 | + +--- + +## 調査結果ファイル一覧 + +### 基本情報 +- [初期調査](./initial.md) - プロジェクト概要と調査対象の分析 +- [原因分析](./causes.md) - 原因候補のリストと評価 +- [推奨対応](./recommendations.md) - 具体的な改善提案 + +--- + +## クイックナビゲーション + +### 高可能性の原因 +1. {{原因1}} - [詳細](./causes.md#原因1) +2. {{原因2}} - [詳細](./causes.md#原因2) + +### 優先対応項目 +1. {{対応1}} - [詳細](./recommendations.md#対応1) +2. {{対応2}} - [詳細](./recommendations.md#対応2) + +--- + +*各ファイルの詳細は上記リンクから参照してください。* +``` + +## 初期調査ファイル (`initial.md`) + +```markdown +# 性能劣化調査 - 初期調査 + +**実施日時**: {{実施日時}} +**調査者**: Claude Code + +[← インデックスに戻る](./index.md) + +--- + +## プロジェクト概要 + +### アーキテクチャ +{{システム構成の概要}} + +### 技術スタック +- **Frontend**: {{フロントエンド技術}} +- **Backend**: {{バックエンド技術}} +- **Database**: {{データベース}} +- **その他**: {{その他の主要技術}} + +--- + +## 調査対象の詳細 + +### 対象コンポーネント +- **ファイルパス**: [{{相対パス}}]({{相対パス}}) +- **種類**: {{コンポーネントの種類（Controller, Service, Component等）}} +- **役割**: {{コンポーネントの役割}} + +### 処理フロー +{{主要な処理フローの説明}} + +### 関連ファイル +{{調査対象に関連する主要ファイルのリスト}} + +--- + +## データベーススキーマ + +### 関連テーブル +{{調査対象が使用するテーブルの情報}} + +### インデックス定義 +{{現在のインデックス定義の状況}} + +--- + +## コード分析 + +### 主要な処理 +{{コードの主要な処理内容}} + +### データベースアクセス +{{SQLクエリやORM使用状況}} + +### 外部API呼び出し +{{外部サービスとの連携状況}} + +### ループ・再帰処理 +{{ループや再帰処理の有無と内容}} + +--- + +## 観測された問題点 + +{{初期調査で見つかった気になる点}} + +--- + +*詳細な原因分析は [原因分析ファイル](./causes.md) を参照してください。* +``` + +## 原因分析ファイル (`causes.md`) + +```markdown +# 性能劣化調査 - 原因分析 + +**実施日時**: {{実施日時}} +**調査者**: Claude Code + +[← インデックスに戻る](./index.md) | [初期調査](./initial.md) + +--- + +## 原因候補サマリー + +| カテゴリ | 原因候補数 | 高可能性 | 中可能性 | 低可能性 | +|---------|----------|---------|---------|---------| +| データベース | XX件 | XX件 | XX件 | XX件 | +| アプリケーション | XX件 | XX件 | XX件 | XX件 | +| ネットワーク | XX件 | XX件 | XX件 | XX件 | +| インフラ | XX件 | XX件 | XX件 | XX件 | + +--- + +## データベース関連の原因候補 + +### 原因1: {{原因名}} + +- **可能性レベル**: 高/中/低 +- **影響度**: 高/中/低 +- **調査難易度**: 高/中/低 + +#### 詳細説明 +{{原因の詳細な説明}} + +#### 証拠・根拠 +- [{{ファイルパス}}:{{行番号}}]({{相対パス}}#L{{行番号}}) + - {{該当コードの説明}} +- {{その他の証拠}} + +#### 推定される影響 +{{この原因による性能への影響}} + +#### 検証方法 +{{この原因を確認するための方法}} + +--- + +## アプリケーション層の原因候補 + +（同様の形式で記述） + +--- + +## ネットワーク・通信の原因候補 + +（同様の形式で記述） + +--- + +## インフラ・環境の原因候補 + +（同様の形式で記述） + +--- + +## 追加調査が必要な項目 + +以下の項目について、詳細調査が推奨されます： + +1. {{追加調査項目1}} + - 理由: {{なぜ追加調査が必要か}} + - 調査内容: {{具体的に何を調査するか}} + +2. {{追加調査項目2}} + - 理由: {{なぜ追加調査が必要か}} + - 調査内容: {{具体的に何を調査するか}} + +（追加調査が不要な場合は「なし」と記載） + +--- + +*推奨される対応は [推奨対応ファイル](./recommendations.md) を参照してください。* +``` + +## 推奨対応ファイル (`recommendations.md`) + +```markdown +# 性能劣化調査 - 推奨対応 + +**実施日時**: {{実施日時}} +**調査者**: Claude Code + +[← インデックスに戻る](./index.md) | [原因分析](./causes.md) + +--- + +## 優先度: 高（即座に実施推奨） + +### 1. {{対応項目1}} + +- **対応する原因**: [{{原因名}}](./causes.md#原因名) +- **期待される効果**: {{改善効果の説明}} +- **実装難易度**: 低/中/高 +- **リスク**: 低/中/高 + +#### 具体的な対応内容 +{{対応の詳細}} + +#### 実装例 +```言語 +// 修正前 +{{修正前のコード例}} + +// 修正後 +{{修正後のコード例}} +``` + +#### 影響範囲 +{{この対応による影響範囲}} + +#### 検証方法 +{{対応後の検証方法}} + +--- + +## 優先度: 中（検証後に実施推奨） + +### 1. {{対応項目2}} + +（同様の形式で記述） + +--- + +## 優先度: 低（長期的な改善） + +### 1. {{対応項目3}} + +（同様の形式で記述） + +--- + +## パフォーマンステスト推奨項目 + +### 負荷テスト +- **対象**: {{テスト対象}} +- **シナリオ**: {{テストシナリオ}} +- **計測指標**: {{何を計測するか}} + +### ベンチマークテスト +- **対象**: {{テスト対象}} +- **比較項目**: {{何と何を比較するか}} + +--- + +## モニタリング推奨項目 + +### 追加すべきメトリクス +1. {{メトリクス1}} - {{理由}} +2. {{メトリクス2}} - {{理由}} + +### ログ出力の追加 +1. {{ログ箇所1}} - {{目的}} +2. {{ログ箇所2}} - {{目的}} + +--- + +## その他の注意事項 + +- {{注意点1}} +- {{注意点2}} +- {{注意点3}} + +--- + +*この推奨対応は調査結果に基づいています。実際の実装前に十分な検証を行ってください。* +``` + +# 調査の注意点 + +- 推測だけでなく、コードやデータに基づいた分析を行う +- 複数の原因が複合的に作用している可能性を考慮する +- パフォーマンスの計測方法も提案する +- すべてのファイルパスは相対パスで記載する +- 原因候補は必ず優先度と影響度を評価する + +# 出力手順 + +**重要**: 必ず以下の順序でファイルを作成してください： + +1. **インデックスファイルを最初に作成** (`{{ベースディレクトリ}}/index.md`) + - Write ツールで保存 + +2. **初期調査ファイルを作成** (`{{ベースディレクトリ}}/initial.md`) + - Write ツールで保存 + +3. **原因分析ファイルを作成** (`{{ベースディレクトリ}}/causes.md`) + - Write ツールで保存 + +4. **推奨対応ファイルを作成** (`{{ベースディレクトリ}}/recommendations.md`) + - Write ツールで保存 + +**各ファイルは Write ツールを使って個別に保存してください。一つのファイルにまとめないでください。** + + + +あなたは性能劣化調査のサマリー作成エキスパートです。以下の情報に基づいて、最終サマリーを作成してください。 + +# サマリー作成対象の情報 + +調査対象: {{調査対象の具体的な情報}} +分析ファイルリスト: {{分析ファイルリスト}} +最終サマリーファイル名: {{サマリーファイル名}} +カレントディレクトリ: {{カレントディレクトリ}} + +# 重要な注意事項 + +**すべてのファイルパスは、カレントディレクトリを基準とした相対パスで記載してください。** +**絶対パス（/Users/... や C:\\... など）は使用しないでください。** + +例: +- ❌ `/Users/makotan/projects/ensemble-si/backend/src/main/kotlin/...` +- ✅ `backend/src/main/kotlin/...` + +# サマリー作成手順 + +## 1. 全分析ファイルの読み込み + +- {{分析ファイルリスト}} に含まれるすべてのファイルを Read で読み込む +- 各ファイルの内容を把握する + +## 2. 情報の統合 + +- すべての調査結果から以下の情報を統合する + - 特定された原因の総数 + - 最も可能性の高い原因 + - 推奨対応の優先順位 + - 詳細調査で判明した新事実 + +## 3. 結論の導出 + +- 最も可能性が高い原因を特定する +- 複数の原因が複合している場合はその関係性を説明する +- 最優先で対応すべき項目を明確にする + +## 4. アクションプランの作成 + +- 短期的な対応（即座に実施可能） +- 中期的な対応（検証後に実施） +- 長期的な対応（アーキテクチャ改善） + +## 5. サマリーファイルの出力 + +以下の出力形式で {{サマリーファイル名}} に結果を保存してください。 + +# 出力形式 + +```markdown +# 性能劣化調査 - 最終サマリー + +**実施日時**: {{実施日時}} +**調査者**: Claude Code + +--- + +## ナビゲーション + +- [初期調査インデックス](./index.md) +- [初期調査](./initial.md) +- [原因分析](./causes.md) +- [推奨対応](./recommendations.md) + +（詳細調査がある場合は追加） +- [詳細調査2](./detail_2.md) +- [詳細調査3](./detail_3.md) + +--- + +## 調査概要 + +### 調査対象 +- **対象**: {{調査対象の詳細}} +- **症状**: {{性能劣化の症状}} +- **発生タイミング**: {{発生タイミング}} +- **影響範囲**: {{影響範囲}} +- **環境**: {{環境情報}} + +### 調査実施状況 +- **調査回数**: {{調査回数}}回（初期調査 + 詳細調査{{N}}回） +- **作成されたファイル数**: {{ファイル数}}件 +- **特定された原因候補数**: {{原因候補数}}件 + +--- + +## 結論 + +### 最も可能性が高い原因 + +#### 1. {{原因名1}}（可能性: 高） + +- **カテゴリ**: データベース/アプリケーション/ネットワーク/インフラ +- **影響度**: 高/中/低 +- **詳細**: {{原因の詳細説明}} +- **証拠**: [{{ファイルパス}}:{{行番号}}]({{相対パス}}#L{{行番号}}) + - {{証拠の説明}} + +#### 2. {{原因名2}}（可能性: 高） + +（同様の形式で記述） + +### その他の原因候補 + +- {{原因3}}（可能性: 中） - {{簡潔な説明}} +- {{原因4}}（可能性: 中） - {{簡潔な説明}} + +--- + +## 総合分析 + +### 性能劣化のメカニズム + +{{複数の原因がどのように絡み合って性能劣化を引き起こしているか}} + +### 根本原因 + +{{根本的な原因は何か}} + +--- + +## 推奨アクションプラン + +### フェーズ1: 即座に実施（優先度: 高） + +#### 1. {{対応項目1}} + +- **対応する原因**: {{原因名}} +- **期待される効果**: {{効果の説明}} +- **実装難易度**: 低/中/高 +- **所要時間**: {{概算}} +- **リスク**: 低/中/高 + +**具体的な対応**: +{{対応の詳細}} + +#### 2. {{対応項目2}} + +（同様の形式で記述） + +--- + +### フェーズ2: 検証後に実施（優先度: 中） + +#### 1. {{対応項目3}} + +（同様の形式で記述） + +--- + +### フェーズ3: 長期的な改善（優先度: 低） + +#### 1. {{対応項目4}} + +（同様の形式で記述） + +--- + +## パフォーマンステスト戦略 + +### 現状の計測 + +#### 計測すべき指標 +1. {{指標1}} - {{目的}} +2. {{指標2}} - {{目的}} + +#### 計測方法 +{{具体的な計測方法}} + +### 改善後の検証 + +#### ベンチマークシナリオ +1. {{シナリオ1}} +2. {{シナリオ2}} + +#### 成功基準 +{{どの程度の改善を目標とするか}} + +--- + +## モニタリング・継続的改善 + +### 追加すべきモニタリング + +#### メトリクス +1. {{メトリクス1}} - {{理由}} +2. {{メトリクス2}} - {{理由}} + +#### アラート設定 +1. {{アラート条件1}} +2. {{アラート条件2}} + +### 定期的な見直し項目 +- {{見直し項目1}} +- {{見直し項目2}} + +--- + +## 予想される改善効果 + +| 対応項目 | 改善見込み | 根拠 | +|---------|----------|------| +| {{対応1}} | {{XX%改善}} | {{根拠}} | +| {{対応2}} | {{XX%改善}} | {{根拠}} | +| {{対応3}} | {{XX%改善}} | {{根拠}} | + +--- + +## リスクと注意事項 + +### 実装時のリスク +1. {{リスク1}} + - **影響**: {{影響の説明}} + - **対策**: {{リスク軽減策}} + +2. {{リスク2}} + - **影響**: {{影響の説明}} + - **対策**: {{リスク軽減策}} + +### 注意事項 +- {{注意点1}} +- {{注意点2}} + +--- + +## 詳細調査ファイル一覧 + +以下のファイルに詳細な調査結果が記録されています： + +1. [{{ファイル名1}}]({{相対パス1}}) - 初期調査 +2. [{{ファイル名2}}]({{相対パス2}}) - 詳細調査1 +3. [{{ファイル名3}}]({{相対パス3}}) - 詳細調査2 +... + +--- + +## 調査の制限事項 + +- {{制限事項1}} +- {{制限事項2}} +- {{制限事項3}} + +--- + +## 次のステップ + +1. **即座に実施**: {{対応項目}} +2. **パフォーマンステスト**: {{テスト内容}} +3. **効果検証**: {{検証方法}} +4. **継続的モニタリング**: {{モニタリング項目}} + +--- + +*このサマリーは複数の調査結果を統合して自動生成されたものです。実装前に十分な検証を行ってください。* +``` + +# サマリー作成の注意点 + +- すべての調査結果を網羅的に把握する +- 最も重要な発見を明確に強調する +- 実行可能なアクションプランを提示する +- リスクと注意事項を明記する +- すべてのファイルパスは相対パスで記載する + +必ず Write ツールを使用して、{{サマリーファイル名}} に結果を保存してください。 + diff --git a/commands/dcs/sequence-diagram-analysis.md b/commands/dcs/sequence-diagram-analysis.md new file mode 100644 index 0000000..a29862c --- /dev/null +++ b/commands/dcs/sequence-diagram-analysis.md @@ -0,0 +1,999 @@ +--- +description: 機能のシーケンス図を作成する +allowed-tools: Read, Glob, Grep, Task, Bash, AskUserQuestion, Write +argument-hint: [機能名または対象(ファイルパス/関数名/クラス名/自然言語)] +--- +指定された機能のシーケンス図をmermaid形式で作成します。調査結果を一時ファイルに保存し、Task で参照することでコンテキスト削減を実現します。 + +# context + +出力ディレクトリ=".dcs" +カレントディレクトリ={{プロジェクトルート}} +分析ファイルリスト=[] +機能特定済み=false +対象機能=[] +ベースディレクトリ="" +tmpディレクトリ="" + +# step + +- $1 がない場合、「引数に機能名または対象を指定してください（例: 注文確定処理、OrderController.confirmOrder、src/api/order など）」と言って終了する +- $1 の内容を簡潔に説明する +- step2 を実行する + +## step2 + +- $1 が具体的な機能を指していない場合（自然言語の一般的な記述、ディレクトリパスなど）: + - Grep/Glob を使って、$1 に関連する機能を調査する + - 調査結果から具体的な機能候補をリストアップする + - AskUserQuestion ツールを使って、ユーザに対象機能を選択してもらう + - **質問**: どの機能のシーケンス図を作成しますか? + - **header**: "対象機能の選択" + - **multiSelect**: true + - **options**: {{調査結果から抽出した機能リスト}}（最大10件程度） + - 選択された機能を 対象機能 に設定し、機能特定済み=true とする +- $1 が具体的な機能を指している場合（関数名、クラス名、特定のエンドポイントなど）: + - その機能を 対象機能 に設定し、機能特定済み=true とする +- 対象機能をユーザに宣言し、確認を得る +- AskUserQuestion ツールを使って以下の質問を順番に実施し、context を更新する： + 1. 図に含めるシナリオを確認 + 2. 詳細レベルを確認 + 3. 除外条件の有無を確認 +- 収集した context の内容をまとめてユーザに宣言する +- step2.5 を実行する + +## step2.5 (初期調査と一時ファイル作成) + +- 既存の出力ファイルを確認して、重複しないナンバリングを決定する + - {{出力ディレクトリ}}/{{timestamp}}_* を検索 + - 今回の内容を簡単に英語化したもの（例: "order_confirmation", "cart_update"）を作成 + - 同じ timestamp と内容で既存ディレクトリがある場合、末尾の連番を +1 する + - ベースディレクトリを "{{出力ディレクトリ}}/{{timestamp}}_{{内容の英語化}}" とする + - 例: ".dcs/20251027_123456_order_confirmation" + - tmpディレクトリを "{{ベースディレクトリ}}/tmp" とする +- tmpディレクトリを作成する（Bash で mkdir -p） +- 対象機能に関する初期調査を Task ツールで実施し、以下の一時ファイルに結果を保存する： + +### 調査ファイル構造 +1. **コンポーネント分析**: `{{tmpディレクトリ}}/component_analysis.md` + - 関連するコンポーネント（Frontend, BFF, Backend, Database, External API）の情報 + - 各コンポーネントの役割、技術スタック、主要ファイルパス（相対パス） + +2. **処理フロー分析**: `{{tmpディレクトリ}}/flow_analysis.md` + - エントリーポイント情報（ファイルパス、関数名、行番号） + - 主要な処理ステップと呼び出し順序 + - 処理の分岐条件 + - データベースアクセスや外部API呼び出しの概要 + +3. **エラーハンドリング分析**: `{{tmpディレクトリ}}/error_handling.md` + - バリデーションエラーのパターン + - ビジネスロジックエラーのパターン + - システムエラー、外部API障害のハンドリング + - 認証/認可エラーのハンドリング + +4. **重要ファイル抜粋**: `{{tmpディレクトリ}}/file_contents/` + - 各重要ファイルの関連部分を抜粋して保存 + - ファイル名: `controller.md`, `service.md`, `repository.md` など + - 各ファイルには以下を含める: + - 元のファイルパス（相対パス） + - 関連する関数/メソッドの抜粋（最大200行程度） + - 重要なコメントやアノテーション + +### 調査実施手順 +1. Grep/Glob で対象機能に関連するファイルを特定 +2. Read で主要ファイルの内容を確認（必要な部分のみ） +3. コンポーネント分析結果を `component_analysis.md` に Write +4. 処理フロー分析結果を `flow_analysis.md` に Write +5. エラーハンドリング分析結果を `error_handling.md` に Write +6. 重要ファイルの抜粋を `file_contents/*.md` に Write（各ファイル個別に） +7. 作成した調査ファイルのパスをユーザに報告 + +- step3 を実行する + +## step3 + +- 分析結果ファイルのリストを準備する + - インデックスファイル: "{{ベースディレクトリ}}/index.md" + - サマリーファイル: "{{ベースディレクトリ}}/summary.md" + - シーケンス図ファイル: "{{ベースディレクトリ}}/sequence_success.md" (成功パターン) + - シーケンス図ファイル: "{{ベースディレクトリ}}/sequence_error.md" (エラーパターン) + - シーケンス図ファイル: "{{ベースディレクトリ}}/sequence_exception.md" (例外パターン) + - 分析詳細ファイル: "{{ベースディレクトリ}}/details.md" +- すべてのファイル名を 分析ファイルリスト に追加する +- の内容を context の情報で埋めて、Task ツールで実行する + - subagent_type: "general-purpose" + - description: "シーケンス図の作成" + - prompt: テンプレートの内容を context で埋めた完全なプロンプト + - **重要**: 調査結果ファイルのパスを渡し、Task内でReadして使用する +- Task の実行結果を受け取る +- step4 を実行する + +## step4 + +- 出力されたファイルを Read で確認する +- 深掘り内容のルール に基づいて、追加調査が必要かを判断する +- 追加調査が必要な場合： + - 追加調査の内容をリストとしてユーザに提示する + - ユーザの承認を得る + - 追加調査項目が複数ある場合、各項目に対して個別に処理する: + 1. 追加調査用の一時ファイルを作成（`{{tmpディレクトリ}}/additional_N_*.md`） + 2. Task ツールで追加調査を実行（調査結果ファイルのパスを渡す） + 3. 各項目ごとに新しい連番で追加ファイルとして保存する（例: "2_sequence_success.md", "3_sequence_error.md"） + 4. 各ファイル名を 分析ファイルリスト に追加する + - 再度 step4 を実行する（追加調査が不要になるまで繰り返す、最大5回） +- 追加調査が不要な場合： + - step5 を実行する + +## step5 + +- の内容を使って、Task ツールで最終サマリーファイルを作成する + - subagent_type: "general-purpose" + - description: "シーケンス図作成 最終サマリーの作成" + - prompt: サマリーテンプレートの内容を context で埋めた完全なプロンプト + - **重要**: 分析ファイルリストを渡し、Task内でReadして使用する + - 最終サマリーファイル名: "{{ベースディレクトリ}}/final_summary.md" +- 全ての分析ファイルのパスを分析回数別に整理して表示する + - 初回分析ファイル一覧（インデックス、サマリー、シーケンス図など） + - 追加調査ファイル一覧（該当する場合） + - 最終サマリー +- 一時ファイル（tmpディレクトリ）について説明する + - 調査結果は `{{tmpディレクトリ}}` に保存されている + - 必要に応じて参照可能 +- 分析完了をユーザに報告する + +# rules + +## 確認ポイント + +AskUserQuestion ツールを使って、以下の質問を順番に実施する： + +### 質問1: 図に含めるシナリオ +- **質問**: どのシナリオのシーケンス図を作成しますか？ +- **header**: "シナリオ選択" +- **multiSelect**: true +- **options**: + - "成功パターン" - 正常な処理フロー + - "バリデーションエラー" - 入力値検証エラーのパターン + - "ビジネスロジックエラー" - ビジネスルール違反のパターン + - "例外パターン" - システムエラー、外部API障害など + - "認証/認可エラー" - 認証・認可失敗のパターン + - "すべて" - すべてのパターンを含める + +### 質問2: 詳細レベル +- **質問**: シーケンス図の詳細レベルはどの程度にしますか？ +- **header**: "詳細レベル" +- **options**: + - "概要レベル" - 主要なコンポーネント間の処理フローのみ + - "標準レベル" - コンポーネント間の主要な処理とデータフロー + - "詳細レベル" - 内部処理やメソッド呼び出し、データ変換も含める + +### 質問3: 除外条件 +- **質問**: シーケンス図から除外したい対象はありますか？ +- **header**: "除外条件" +- **multiSelect**: true +- **options**: + - "ログ出力処理" - ログ出力の記述を除外 + - "バリデーション詳細" - バリデーションの詳細を簡略化 + - "データ変換処理" - データ変換の詳細を簡略化 + - "キャッシュ処理" - キャッシュアクセスを除外 + - "除外なし" - すべて含める + +contextとして以下を保持する +- 対象機能（具体的な機能名、エンドポイント、関数名など） +- 図に含めるシナリオ +- 詳細レベル +- 除外条件 +- ベースディレクトリ +- tmpディレクトリ + +## ファイル名のルール + +### timestamp の形式 +- yyyyMMddHHmmss 形式（例: 20251027123456） + +### 内容の英語化のルール +- 対象機能を簡潔な英語に変換する +- スネークケース（snake_case）を使用 +- 最大30文字程度に収める +- 例: + - "注文確定処理" → "order_confirmation" + - "カート更新" → "cart_update" + - "OrderController.confirmOrder" → "order_confirm" + - "商品在庫確認" → "inventory_check" + +### シーケンス図ファイル名のルール +- シーケンス図はシナリオごとに個別ファイルとして配置 +- シナリオ別ファイル名: + - `sequence_success.md` - 成功パターン + - `sequence_error.md` - エラーパターン（バリデーション、ビジネスロジック） + - `sequence_exception.md` - 例外パターン（システムエラー、外部API障害） + - `sequence_auth_error.md` - 認証/認可エラーパターン + +### 追加調査ファイル名のルール +- 追加調査が必要な場合、追加調査ごとに新しいファイルを作成 +- 追加調査には連番プレフィックスを付与: `2_`, `3_`, `4_` など +- 例: `2_sequence_success.md`, `3_sequence_error.md` など（ベースディレクトリ内に配置） + +### 一時ファイルのルール +- すべての調査結果は `{{ベースディレクトリ}}/tmp/` に保存 +- コンポーネント分析: `tmp/component_analysis.md` +- 処理フロー分析: `tmp/flow_analysis.md` +- エラーハンドリング分析: `tmp/error_handling.md` +- 重要ファイル抜粋: `tmp/file_contents/*.md` +- 追加調査結果: `tmp/additional_N_*.md` + +### 完全なファイル名の例 +**初回分析**: +- `.dcs/20251027123456_order_confirmation/index.md` (インデックス) +- `.dcs/20251027123456_order_confirmation/summary.md` (サマリー) +- `.dcs/20251027123456_order_confirmation/sequence_success.md` (成功パターン) +- `.dcs/20251027123456_order_confirmation/sequence_error.md` (エラーパターン) +- `.dcs/20251027123456_order_confirmation/sequence_exception.md` (例外パターン) +- `.dcs/20251027123456_order_confirmation/details.md` (分析詳細) + +**調査結果（一時ファイル）**: +- `.dcs/20251027123456_order_confirmation/tmp/component_analysis.md` +- `.dcs/20251027123456_order_confirmation/tmp/flow_analysis.md` +- `.dcs/20251027123456_order_confirmation/tmp/error_handling.md` +- `.dcs/20251027123456_order_confirmation/tmp/file_contents/controller.md` + +**追加調査1回目**: +- `.dcs/20251027123456_order_confirmation/tmp/additional_2_flow.md` +- `.dcs/20251027123456_order_confirmation/2_sequence_success.md` (追加調査) +- `.dcs/20251027123456_order_confirmation/2_sequence_error.md` (追加調査) + +**最終サマリー**: +- `.dcs/20251027123456_order_confirmation/final_summary.md` (全体サマリー) + +## ファイルパスの記載ルール + +- **カレントディレクトリを基準とした相対パスを使用する** +- フルパス（絶対パス）は記載しない +- 例: + - ❌ `/Users/makotan/projects/esample/src/api/order.ts` + - ✅ `src/api/order.ts` +- カレントディレクトリは分析開始時の作業ディレクトリ +- すべてのファイルパスは相対パスで統一する + +## 追加調査が必要な条件 + +以下の条件のいずれかに該当する場合、追加調査を提案する： + +- 処理フローが複雑で、詳細な分岐パターンが不明確 +- 外部API連携の詳細が不明（リトライ処理、タイムアウト処理など） +- トランザクション境界が不明確 +- エラーハンドリングの詳細が不明 +- データ変換処理の詳細が不明 +- 非同期処理やイベント駆動の詳細が不明 +- キャッシュやキューなどの中間層の動作が不明 +- セキュリティ関連の処理（認証、認可、暗号化）の詳細が不明 + +## 深掘り内容のルール + +調査した内容を元に、以下の観点で追加調査が必要な箇所をリストアップする： + +- 処理フローの分岐条件の詳細 +- 外部API連携の詳細（エラーハンドリング、リトライなど） +- トランザクション管理の詳細 +- エラーハンドリングの詳細 +- データ変換処理の詳細 +- 非同期処理の詳細 +- 中間層（キャッシュ、キュー）の動作 + +具体的な調査内容を提示し、originRule を参考に深掘りする。 + +## step4 の繰り返しルール + +- 追加調査が必要な項目がある場合、step4 を繰り返す +- 最大5回まで繰り返す（無限ループ防止） +- 追加調査項目が複数ある場合は、各項目ごとに個別に Task を実行する +- 各繰り返しで新しい連番のファイルを作成する +- ユーザーの承認を得てから次の調査を実行する +- 追加調査が不要になったら step5 に進む + +## 一時ファイルの扱い + +- すべての調査結果は `{{tmpディレクトリ}}` に保存される +- Task実行時は一時ファイルのパスのみを渡す +- Task内で Read ツールを使って必要な情報を取得する +- 一時ファイルは分析完了後も保持され、必要に応じて参照可能 + +# info + + +あなたはシーケンス図作成のエキスパートです。以下の情報に基づいて、対象機能のシーケンス図をmermaid形式で作成し、ファイル出力してください。 + +# 分析対象の情報 + +対象機能: {{対象機能の具体的な情報}} +図に含めるシナリオ: {{シナリオリスト}} +詳細レベル: {{詳細レベル}} +除外条件: {{除外条件（なければ「なし」）}} +ベースディレクトリ: {{ベースディレクトリ}}（例: ".dcs/20251027123456_order_confirmation"） +カレントディレクトリ: {{カレントディレクトリ}} + +# 調査結果ファイルのパス + +**重要**: 以下のファイルに調査結果が保存されています。これらのファイルを Read で読み込んで参照してください。 + +- コンポーネント分析: {{tmpディレクトリ}}/component_analysis.md +- 処理フロー分析: {{tmpディレクトリ}}/flow_analysis.md +- エラーハンドリング分析: {{tmpディレクトリ}}/error_handling.md +- 重要ファイル抜粋: {{tmpディレクトリ}}/file_contents/*.md + +# 重要な注意事項 + +**すべてのファイルパスは、カレントディレクトリを基準とした相対パスで記載してください。** +**絶対パス（/Users/... や C:\\... など）は使用しないでください。** +**各ファイルは500行以内を目標としてください。** +**調査結果ファイルは必ず Read で読み込んでから使用してください。** + +例: +- ❌ `/Users/makotan/projects/esample/src/api/order.ts` +- ✅ `src/api/order.ts` + +# 出力ファイル構成 + +シーケンス図は以下のファイルに分割して出力してください： + +1. **インデックスファイル**: `{{ベースディレクトリ}}/index.md` + - 全体概要とファイルへのリンク + +2. **サマリーファイル**: `{{ベースディレクトリ}}/summary.md` + - 対象機能、シナリオ、詳細レベルのサマリー + +3. **シーケンス図ファイル**（シナリオごとに作成）: + - `{{ベースディレクトリ}}/sequence_success.md` - 成功パターン + - `{{ベースディレクトリ}}/sequence_error.md` - エラーパターン + - `{{ベースディレクトリ}}/sequence_exception.md` - 例外パターン + - `{{ベースディレクトリ}}/sequence_auth_error.md` - 認証/認可エラーパターン + +4. **分析詳細ファイル**: + - `{{ベースディレクトリ}}/details.md` - 分析詳細とコンポーネント情報 + +# 分析手順 + +## 1. 調査結果の読み込み + +**最初に必ず以下のファイルを Read で読み込んでください：** + +1. コンポーネント分析ファイル (`{{tmpディレクトリ}}/component_analysis.md`) +2. 処理フロー分析ファイル (`{{tmpディレクトリ}}/flow_analysis.md`) +3. エラーハンドリング分析ファイル (`{{tmpディレクトリ}}/error_handling.md`) +4. 重要ファイル抜粋 (`{{tmpディレクトリ}}/file_contents/*.md`) - 必要に応じて + +## 2. シナリオ別のフロー作成 + +読み込んだ調査結果を基に、以下のシナリオについてシーケンス図を作成する： + +### 成功パターン (sequence_success.md) +- 正常な処理フロー +- すべてのステップが成功する場合 +- 返却される成功レスポンス + +### エラーパターン (sequence_error.md) +- バリデーションエラー +- ビジネスロジックエラー +- 返却されるエラーレスポンス + +### 例外パターン (sequence_exception.md) +- システムエラー（データベース接続失敗、タイムアウトなど） +- 外部API障害 +- リトライ処理 +- フォールバック処理 +- 返却される例外レスポンス + +### 認証/認可エラーパターン (sequence_auth_error.md) +- 認証失敗 +- 認可失敗（権限不足） +- セッション期限切れ +- 返却されるエラーレスポンス + +## 3. mermaid 記法での記述 + +各シーケンス図は以下のmermaid記法で記述する： + +```mermaid +sequenceDiagram + participant Frontend + participant BFF + participant Backend + participant Database + participant ExternalAPI + + Frontend->>BFF: POST /api/orders + Note over Frontend,BFF: リクエストボディ:
{orderId, items, ...} + + BFF->>Backend: POST /orders/confirm + Note over BFF,Backend: Authorization Header
Pzx-Clan-Code Header + + Backend->>Database: SELECT * FROM orders WHERE id = ? + Database-->>Backend: Order データ + + alt 在庫が十分な場合 + Backend->>Database: UPDATE inventory SET quantity = quantity - ? + Database-->>Backend: Success + + Backend->>ExternalAPI: POST /payment/charge + ExternalAPI-->>Backend: Payment Success + + Backend->>Database: UPDATE orders SET status = 'CONFIRMED' + Database-->>Backend: Success + + Backend-->>BFF: 200 OK {orderId, status: 'CONFIRMED'} + BFF-->>Frontend: 200 OK {orderId, status: 'CONFIRMED'} + else 在庫が不足の場合 + Backend-->>BFF: 400 Bad Request {error: 'INSUFFICIENT_INVENTORY'} + BFF-->>Frontend: 400 Bad Request {error: 'INSUFFICIENT_INVENTORY'} + end +``` + +### mermaid 記法のルール +- `sequenceDiagram` で開始する +- `participant` でコンポーネントを定義する +- `->>`（実線矢印）で同期呼び出しを表現する +- `-->>` (破線矢印）でレスポンスを表現する +- `Note over A,B:` で注釈を追加する +- `alt` / `else` / `end` で条件分岐を表現する +- `loop` / `end` でループを表現する +- `par` / `and` / `end` で並列処理を表現する +- `opt` / `end` でオプショナル処理を表現する + +## 4. ファイル出力 + +以下の順序で各ファイルを作成してください。**各ファイルは Write ツールを使って個別に保存してください。** + +### 4.1 インデックスファイルの作成 + +最初に `{{ベースディレクトリ}}/index.md` を作成してください。 + +### 4.2 サマリーファイルの作成 + +次に `{{ベースディレクトリ}}/summary.md` を作成してください。 + +### 4.3 シーケンス図ファイルの作成 + +シナリオごとに個別ファイルを作成してください： +- `{{ベースディレクトリ}}/sequence_success.md` +- `{{ベースディレクトリ}}/sequence_error.md` +- `{{ベースディレクトリ}}/sequence_exception.md` +- `{{ベースディレクトリ}}/sequence_auth_error.md` (必要な場合) + +### 4.4 分析詳細ファイルの作成 + +`{{ベースディレクトリ}}/details.md` を作成してください。 + +# 各ファイルの出力形式 + +## インデックスファイル (`index.md`) + +```markdown +# シーケンス図 - インデックス + +**作成日時**: {{実施日時}} +**作成者**: Claude Code + +--- + +## 対象機能 + +- **機能**: {{対象機能の詳細}} +- **シナリオ**: {{シナリオリスト}} +- **詳細レベル**: {{詳細レベル}} + +--- + +## シーケンス図ファイル一覧 + +### 基本情報 +- [サマリー](./summary.md) - 対象機能とシナリオの概要 + +### シーケンス図 +- [成功パターン](./sequence_success.md) - 正常な処理フロー +- [エラーパターン](./sequence_error.md) - バリデーション・ビジネスロジックエラー +- [例外パターン](./sequence_exception.md) - システムエラー・外部API障害 +- [認証/認可エラー](./sequence_auth_error.md) - 認証・認可失敗 + +### その他の情報 +- [分析詳細](./details.md) - コンポーネント情報と分析手法 + +--- + +*各ファイルの詳細は上記リンクから参照してください。* +``` + +## サマリーファイル (`summary.md`) + +```markdown +# シーケンス図 - サマリー + +**作成日時**: {{実施日時}} +**作成者**: Claude Code + +[← インデックスに戻る](./index.md) + +--- + +## 対象機能 + +### 機能概要 +- **機能名**: {{対象機能の詳細}} +- **エントリーポイント**: {{エントリーポイント（相対パス:行番号）}} +- **機能説明**: {{機能の説明}} + +--- + +## シナリオ一覧 + +| シナリオ | ファイル | 説明 | +|---------|---------|------| +| 成功パターン | [sequence_success.md](./sequence_success.md) | 正常な処理フロー | +| エラーパターン | [sequence_error.md](./sequence_error.md) | バリデーション・ビジネスロジックエラー | +| 例外パターン | [sequence_exception.md](./sequence_exception.md) | システムエラー・外部API障害 | +| 認証/認可エラー | [sequence_auth_error.md](./sequence_auth_error.md) | 認証・認可失敗 | + +--- + +## コンポーネント一覧 + +| コンポーネント | 役割 | 関連ファイル | +|--------------|------|-------------| +| Frontend | {{役割}} | {{相対パス}} | +| BFF | {{役割}} | {{相対パス}} | +| Backend | {{役割}} | {{相対パス}} | +| Database | {{役割}} | - | +| External API | {{役割}} | - | + +--- + +## 主要な処理フロー + +1. {{ステップ1の説明}} +2. {{ステップ2の説明}} +3. {{ステップ3の説明}} +... + +--- + +## 追加調査が必要な項目 + +以下の項目について、追加調査が推奨されます： + +1. {{追加調査項目1}} +2. {{追加調査項目2}} +3. {{追加調査項目3}} + +（追加調査が不要な場合は「なし」と記載） + +--- + +*詳細なシーケンス図は各シナリオファイルを参照してください。* +``` + +## シーケンス図ファイル (`sequence_success.md`, `sequence_error.md`, `sequence_exception.md`, `sequence_auth_error.md`) + +各シナリオのファイルは以下の形式で記述してください： + +```markdown +# シーケンス図 - {{シナリオ名}} + +**作成日時**: {{実施日時}} +**作成者**: Claude Code + +[← インデックスに戻る](./index.md) | [サマリー](./summary.md) + +--- + +## シナリオ概要 + +- **シナリオ**: {{シナリオ名}} +- **説明**: {{シナリオの説明}} +- **前提条件**: {{前提条件}} +- **期待結果**: {{期待結果}} + +--- + +## シーケンス図 + +```mermaid +sequenceDiagram + {{mermaid記法で記述したシーケンス図}} +``` + +--- + +## 処理ステップの詳細 + +### ステップ1: {{ステップ名}} +- **コンポーネント**: {{コンポーネント名}} +- **処理内容**: {{処理の説明}} +- **関連ファイル**: [相対パス:行番号](相対パス#L行番号) +- **データ**: {{送受信されるデータ}} + +### ステップ2: {{ステップ名}} +（同様の形式で記述） + +--- + +## エラーハンドリング（エラー・例外パターンの場合） + +### エラー種別: {{エラー種別}} +- **原因**: {{エラーの原因}} +- **エラーコード**: {{エラーコード}} +- **エラーメッセージ**: {{エラーメッセージ}} +- **ハンドリング方法**: {{ハンドリング方法}} +- **関連ファイル**: [相対パス:行番号](相対パス#L行番号) + +--- + +## 関連するテストケース + +- {{テストケース1}} +- {{テストケース2}} + +--- + +*このファイルには{{シナリオ名}}のシーケンス図のみを記載しています。他のシナリオは対応するファイルを参照してください。* +``` + +## 分析詳細ファイル (`details.md`) + +```markdown +# シーケンス図 - 分析詳細 + +**作成日時**: {{実施日時}} +**作成者**: Claude Code + +[← インデックスに戻る](./index.md) + +--- + +## 分析対象の詳細 + +### エントリーポイント +- **ファイル**: {{相対パス}} +- **関数/メソッド**: {{関数名}} +- **行番号**: {{行番号}} + +### 関連ファイル一覧 +- {{相対パス1}} - {{役割}} +- {{相対パス2}} - {{役割}} +- {{相対パス3}} - {{役割}} + +--- + +## コンポーネント詳細 + +### Frontend +- **技術スタック**: {{技術スタック}} +- **主要ファイル**: {{相対パス}} +- **役割**: {{役割の説明}} + +### BFF (Backend for Frontend) +- **技術スタック**: {{技術スタック}} +- **主要ファイル**: {{相対パス}} +- **役割**: {{役割の説明}} + +### Backend +- **技術スタック**: {{技術スタック}} +- **主要ファイル**: {{相対パス}} +- **役割**: {{役割の説明}} + +### Database +- **データベース**: {{データベース種類}} +- **関連テーブル**: {{テーブル一覧}} +- **役割**: {{役割の説明}} + +### External API +- **API名**: {{API名}} +- **エンドポイント**: {{エンドポイント}} +- **役割**: {{役割の説明}} + +--- + +## 分析手法 + +### 使用した調査結果 +- コンポーネント分析: `{{tmpディレクトリ}}/component_analysis.md` +- 処理フロー分析: `{{tmpディレクトリ}}/flow_analysis.md` +- エラーハンドリング分析: `{{tmpディレクトリ}}/error_handling.md` + +### 分析アプローチ +調査結果ファイルから情報を抽出し、シーケンス図として可視化しました。 + +--- + +## 制限事項 + +- 動的な呼び出し（リフレクション、eval など）は検出できない可能性がある +- 非同期処理のタイミングは概算で表現している +- キャッシュやキューなどの中間層は、状態に応じて処理が変わる可能性がある +- 外部APIの詳細な動作は推測に基づいている + +--- + +*この分析結果は調査結果ファイルを基に自動生成されたものです。実際の処理フローは、コードレビューやテストを通じて確認してください。* +``` + +# 分析の注意点 + +- 調査結果ファイルは必ず Read で読み込んでから使用する +- すべてのファイルパスは相対パスで記載する（絶対パスは使用しない） +- 各ファイルは500行以内を目標とする。500行を超える場合は、さらに細かく分割する +- 追加の詳細情報が必要な場合は、summary.md の「追加調査が必要な項目」に記載する + +# 出力手順 + +**重要**: 必ず以下の順序でファイルを作成してください： + +1. **調査結果ファイルを Read で読み込む** + - `{{tmpディレクトリ}}/component_analysis.md` + - `{{tmpディレクトリ}}/flow_analysis.md` + - `{{tmpディレクトリ}}/error_handling.md` + +2. **インデックスファイルを最初に作成** (`{{ベースディレクトリ}}/index.md`) + - Write ツールで保存 + - 全ファイルへのリンクを含める + +3. **サマリーファイルを作成** (`{{ベースディレクトリ}}/summary.md`) + - Write ツールで保存 + +4. **シーケンス図ファイルを作成**（シナリオごとに） + - 各ファイルを個別に Write ツールで保存 + - 例: `{{ベースディレクトリ}}/sequence_success.md`, `{{ベースディレクトリ}}/sequence_error.md`, ... + +5. **分析詳細ファイルを作成** + - `{{ベースディレクトリ}}/details.md` + - Write ツールで保存 + +**各ファイルは Write ツールを使って個別に保存してください。一つのファイルにまとめないでください。** + + + +あなたはシーケンス図作成のサマリー作成エキスパートです。以下の情報に基づいて、全体サマリーを作成してください。 + +# サマリー作成対象の情報 + +対象機能: {{対象機能の具体的な情報}} +分析ファイルリスト: {{分析ファイルリスト}}（インデックスファイル、サマリーファイル、シーケンス図ファイルなど） +最終サマリーファイル名: {{サマリーファイル名}}（例: ".dcs/20251027123456_order_confirmation/final_summary.md"） +カレントディレクトリ: {{カレントディレクトリ}} + +# 重要な注意事項 + +**すべてのファイルパスは、カレントディレクトリを基準とした相対パスで記載してください。** +**絶対パス（/Users/... や C:\\... など）は使用しないでください。** +**このファイルは500行以内に収まるように簡潔に記述してください。** +**分析ファイルリストのファイルは必ず Read で読み込んでから使用してください。** + +例: +- ❌ `/Users/makotan/projects/esample/src/api/order.ts` +- ✅ `src/api/order.ts` + +# サマリー作成手順 + +## 1. 全分析ファイルの読み込み + +- {{分析ファイルリスト}} に含まれるすべてのファイルを Read で読み込む +- 各ファイルの内容を把握する + +## 2. 情報の統合 + +- すべての分析結果から以下の情報を統合する + - 対象機能の概要 + - シナリオ一覧 + - コンポーネント一覧 + - 主要な処理フロー + - エラーハンドリングのパターン + +## 3. ハイライトの抽出 + +- 最も重要な処理フローをハイライトする +- 複雑な処理や注意が必要な箇所を強調する +- 追加調査で判明した重要事項を記載する + +## 4. 統合ガイドの作成 + +- 全シナリオを通じた理解のポイントを提示する +- テストすべき重要なパスを提示する +- ドキュメント化の推奨事項を提示する + +## 5. サマリーファイルの出力 + +以下の出力形式で {{サマリーファイル名}} に結果を保存してください。 + +# 出力形式 + +```markdown +# シーケンス図 - 最終サマリー + +**作成日時**: {{実施日時}} +**作成者**: Claude Code + +--- + +## ナビゲーション + +- [初回分析インデックス](./index.md) +- [初回分析サマリー](./summary.md) + +（追加調査がある場合は追加） +- [追加調査2（成功パターン）](./2_sequence_success.md) +- [追加調査3（エラーパターン）](./3_sequence_error.md) + +--- + +## 対象機能の概要 + +### 機能 +- **機能名**: {{対象機能の詳細}} +- **エントリーポイント**: {{エントリーポイント}} +- **機能説明**: {{機能の説明}} + +### 分析実施状況 +- **実施した分析回数**: {{分析回数}}回（初回 + 追加調査{{N}}回） +- **作成されたファイル数**: {{ファイル数}}件 + +--- + +## 総合サマリー + +| 項目 | 内容 | +|------|------| +| シナリオ数 | XX件 | +| コンポーネント数 | XX個 | +| 処理ステップ数 | XX個 | +| エラーパターン数 | XX個 | + +--- + +## 主要な処理フロー + +### 全体フロー +1. {{ステップ1の説明}} +2. {{ステップ2の説明}} +3. {{ステップ3の説明}} +... + +### 重要なハイライト + +1. **{{ハイライト1のタイトル}}** + - {{詳細説明}} + - 関連ファイル: [相対パス:行番号](相対パス#L行番号) + +2. **{{ハイライト2のタイトル}}** + - {{詳細説明}} + - 関連ファイル: [相対パス:行番号](相対パス#L行番号) + +3. **{{ハイライト3のタイトル}}** + - {{詳細説明}} + - 関連ファイル: [相対パス:行番号](相対パス#L行番号) + +--- + +## シナリオ別サマリー + +### 成功パターン +- **説明**: {{説明}} +- **主要コンポーネント**: {{コンポーネント}} +- **詳細**: [sequence_success.md](./sequence_success.md) + +### エラーパターン +- **説明**: {{説明}} +- **エラー種別**: {{エラー種別}} +- **詳細**: [sequence_error.md](./sequence_error.md) + +### 例外パターン +- **説明**: {{説明}} +- **例外種別**: {{例外種別}} +- **詳細**: [sequence_exception.md](./sequence_exception.md) + +### 認証/認可エラー +- **説明**: {{説明}} +- **エラー種別**: {{エラー種別}} +- **詳細**: [sequence_auth_error.md](./sequence_auth_error.md) + +--- + +## コンポーネント間の相互作用 + +### 主要なメッセージフロー +1. Frontend → BFF: {{メッセージ内容}} +2. BFF → Backend: {{メッセージ内容}} +3. Backend → Database: {{メッセージ内容}} +4. Backend → External API: {{メッセージ内容}} + +### データフロー +- {{データの流れの説明}} + +--- + +## エラーハンドリングのパターン + +### パターン1: {{パターン名}} +- **エラー種別**: {{エラー種別}} +- **ハンドリング方法**: {{ハンドリング方法}} +- **関連ファイル**: [相対パス:行番号](相対パス#L行番号) + +### パターン2: {{パターン名}} +（同様の形式で記述） + +--- + +## テスト推奨事項 + +### 重要なテストパス +1. {{テストパス1の説明}} +2. {{テストパス2の説明}} +3. {{テストパス3の説明}} + +### テストすべきエッジケース +- {{エッジケース1}} +- {{エッジケース2}} +- {{エッジケース3}} + +--- + +## ドキュメント化の推奨事項 + +### 追加すべきドキュメント +1. **{{ドキュメント1のタイトル}}** + - {{内容の説明}} + +2. **{{ドキュメント2のタイトル}}** + - {{内容の説明}} + +### API仕様の明確化 +- {{明確化が必要な項目1}} +- {{明確化が必要な項目2}} + +--- + +## 改善提案 + +### パフォーマンス最適化 +- {{提案1}} +- {{提案2}} + +### エラーハンドリングの改善 +- {{提案1}} +- {{提案2}} + +### コードの可読性向上 +- {{提案1}} +- {{提案2}} + +--- + +## 詳細分析ファイル一覧 + +以下のファイルに詳細な分析結果が記録されています： + +1. [{{ファイル名1}}]({{相対パス1}}) - 初回分析 +2. [{{ファイル名2}}]({{相対パス2}}) - 追加調査1 +3. [{{ファイル名3}}]({{相対パス3}}) - 追加調査2 +... + +--- + +## 制限事項と注意点 + +- {{制限事項1}} +- {{制限事項2}} +- {{制限事項3}} + +--- + +*このサマリーは複数の分析結果を統合して自動生成されたものです。詳細は個別の分析ファイルを参照してください。* +``` + +# サマリー作成の注意点 + +- すべての分析ファイルの内容を網羅的に把握する +- 重複する情報を排除し、簡潔にまとめる +- 最も重要な情報を優先的に記載する +- 全体の傾向やパターンを識別する +- **すべてのファイルパスは相対パスで記載する（絶対パスは使用しない）** + +必ず Write ツールを使用して、{{サマリーファイル名}} に結果を保存してください。 + diff --git a/commands/dcs/state-transition-analysis.md b/commands/dcs/state-transition-analysis.md new file mode 100644 index 0000000..37d3532 --- /dev/null +++ b/commands/dcs/state-transition-analysis.md @@ -0,0 +1,1738 @@ +--- +description: データの状態遷移フローを包括的に分析する +allowed-tools: Read, Glob, Grep, Task, Bash, Write +argument-hint: [対象データ名（リソース名/エンティティ名/モデル名）] +--- +対象データの状態遷移に関わる全ての機能を特定し、状態遷移フロー、関連データとの依存関係、リスク評価を提供します。 + +# context + +出力ディレクトリ=".dcs" +カレントディレクトリ={{プロジェクトルート}} +分析ファイルリスト=[] +対象データ名="" +状態フィールド名="" +検出された状態値リスト=[] + +# step + +- $1 がない場合、「引数に対象データ名を指定してください（例: Order, Cart, Inventory）」と言って終了する +- $1 の内容を簡潔に説明する +- AskUserQuestion ツールを使って以下の質問を順番に実施し、context を更新する： + 1. 対象データの種類を確認 + 2. 状態フィールド名を確認（自動検出も試みる） + 3. 分析範囲を確認 + 4. 出力形式の希望を確認 +- 収集した context の内容をまとめてユーザに宣言する +- step2 を実行する + +## step2 + +- 既存の出力ファイルを確認して、重複しないナンバリングを決定する + - {{出力ディレクトリ}}/{{timestamp}}_*.md を検索 + - 今回の対象データ名を英語化したもの（例: "order_state", "cart_status"）を作成 + - 同じ timestamp と内容で既存ファイルがある場合、末尾の連番を +1 する + - ベースディレクトリを "{{出力ディレクトリ}}/{{timestamp}}_{{データ名の英語化}}" とする + - 例: ".dcs/20251026_143000_order_state" +- 分析結果ファイルのリストを準備する（セクション別分割ファイル） + - インデックスファイル: "{{ベースディレクトリ}}/index.md" + - サマリーファイル: "{{ベースディレクトリ}}/summary.md" + - 状態遷移図ファイル: "{{ベースディレクトリ}}/diagram.md" + - 遷移表ファイル: "{{ベースディレクトリ}}/transitions.md" + - 機能別分析: "{{ベースディレクトリ}}/functions.md" + - データ依存関係: "{{ベースディレクトリ}}/dependencies.md" + - リスク評価: "{{ベースディレクトリ}}/risks.md" + - 推奨事項: "{{ベースディレクトリ}}/recommendations.md" +- すべてのファイル名を 分析ファイルリスト に追加する +- の内容を context の情報で埋めて、Task ツールで直接実行する + - subagent_type: "general-purpose" + - description: "状態遷移分析の実行" + - prompt: テンプレートの内容を context で埋めた完全なプロンプト +- Task の実行結果を受け取る +- step3 を実行する + +## step3 + +- 出力されたファイルを Read で確認する +- 深掘り内容のルール に基づいて、追加調査が必要かを判断する +- 追加調査が必要な場合： + - 追加調査の内容をリストとしてユーザに提示する + - ユーザの承認を得る + - 追加調査項目が複数ある場合、各項目に対して個別に Task ツールで追加調査を実行する + - 各項目ごとに新しい連番で追加ファイルとして保存する（例: "_2.md", "_3.md", "_4.md"） + - 各ファイル名を 分析ファイルリスト に追加する + - 再度 step3 を実行する（追加調査が不要になるまで繰り返す、最大5回） +- 追加調査が不要な場合： + - step4 を実行する + +## step4 + +- の内容を使って、Task ツールで最終サマリーファイルを作成する + - subagent_type: "general-purpose" + - description: "状態遷移分析 最終サマリーの作成" + - prompt: サマリーテンプレートの内容を context で埋めた完全なプロンプト + - 最終サマリーファイル名: "{{ベースディレクトリ}}/final_summary.md" +- 全ての分析ファイルのパスを分析回数別に整理して表示する + - 初回分析ファイル一覧（インデックス、サマリー、遷移図など） + - 追加調査ファイル一覧（該当する場合） + - 最終サマリー +- 分析完了をユーザに報告する + +# rules + +## 確認ポイント + +AskUserQuestion ツールを使って、以下の質問を順番に実施する： + +### 質問1: 対象データの種類 +- **質問**: 対象データはどの種類ですか？ +- **header**: "データ種類" +- **options**: + - "Prismatix リソース" - YAMLで定義されたリソース（prismatix-factory/resources/） + - "Kotlinエンティティ" - バックエンドのエンティティクラス + - "TypeScript型" - フロントエンドの型定義 + - "自然言語" - 概念的なデータ（具体的な実装は未特定） + +### 質問2: 状態フィールド名 +- **質問**: 状態を表すフィールド名は何ですか？（わからない場合は「自動検出」を選択） +- **header**: "状態フィールド" +- **options**: + - "status" - 一般的な status フィールド + - "state" - state フィールド + - "orderStatus" - 注文ステータス + - "自動検出" - コードから自動的に検出を試みる + +### 質問3: 分析範囲 +- **質問**: どの範囲まで分析しますか？ +- **header**: "分析範囲" +- **multiSelect**: true +- **options**: + - "バックエンド" - Kotlin Spring Bootのコード + - "フロントエンド" - React/Next.jsのコード + - "BFF" - Next.js API routes + - "インターセプター" - Prismatix Factoryのインターセプター + +### 質問4: 出力形式 +- **質問**: どの出力形式を希望しますか？ +- **header**: "出力形式" +- **multiSelect**: true +- **options**: + - "Mermaid図" - 状態遷移図をMermaid形式で出力 + - "遷移表" - 状態遷移をテーブル形式で出力 + - "フロー詳細" - 各遷移の詳細な説明 + - "リスク評価" - 状態遷移に伴うリスク評価 + +contextとして以下を保持する +- 対象データ名 +- データの種類 +- 状態フィールド名 +- 分析範囲 +- 出力形式 + +## ファイル名のルール + +### timestamp の形式 +- yyyyMMddHHmmss 形式（例: 20251026143000） + +### データ名の英語化のルール +- 対象データ名を簡潔な英語に変換し、状態を示すサフィックスを追加 +- スネークケース（snake_case）を使用 +- 最大30文字程度に収める +- 例: + - "Order" → "order_state" + - "Cart" → "cart_status" + - "在庫" → "inventory_state" + - "決済" → "payment_status" + +### セクション別ファイル名のルール +- 分析結果は論理的なセクション単位で分割し、各セクション500行以内を目標とする +- セクション一覧: + - `index.md` - インデックス（全体概要とファイル一覧） + - `summary.md` - 分析対象とサマリー + - `diagram.md` - 状態遷移図（Mermaid形式） + - `transitions.md` - 状態遷移表 + - `functions.md` - 機能別の状態遷移分析 + - `dependencies.md` - 他のデータとの依存関係 + - `risks.md` - リスク評価 + - `recommendations.md` - 推奨事項 + +## ファイルパスの記載ルール + +- **カレントディレクトリを基準とした相対パスを使用する** +- フルパス（絶対パス）は記載しない +- 例: + - ❌ `/Users/makotan/projects/ensemble-si/backend/src/main/kotlin/...` + - ✅ `backend/src/main/kotlin/...` + +## 状態遷移分析の観点 + +### 1. 状態値の特定 +- 可能な状態値をすべて列挙する +- enum定義、定数定義、YAMLでの定義を確認 +- コード内で文字列リテラルで使用されている状態値も検出 + +### 2. 遷移パターンの分類 +- **正常遷移**: ビジネスフローに沿った通常の遷移 +- **異常遷移**: エラーやキャンセル等の例外的な遷移 +- **補正遷移**: 管理者による手動修正など +- **自動遷移**: バッチ処理やスケジューラーによる遷移 + +### 3. 遷移トリガーの特定 +- APIエンドポイント呼び出し +- インターセプターの自動実行 +- バッチ処理 +- 外部システムからの通知 +- タイムアウト等の時間ベース + +### 4. 遷移条件の分析 +- 状態遷移の前提条件（どの状態からどの状態へ遷移可能か） +- ビジネスルールによる制約 +- 関連データの状態依存 +- 権限チェック + +### 5. 副作用の特定 +- 状態遷移に伴う他のデータの変更 +- 通知の送信（メール、プッシュ通知等） +- 外部システムへの連携 +- ログ記録 + +## リスク評価基準 + +以下の観点でリスクを評価する： + +### 状態の複雑度 +- 状態数が多い: リスク増加 +- 遷移パターンが複雑: リスク増加 +- 循環遷移がある: 要注意 + +### データ整合性 +- 複数データの状態が連動: 高リスク +- トランザクション境界が不明確: 高リスク +- ロールバック処理が未実装: 高リスク + +### エラーハンドリング +- 異常系の遷移が未定義: 高リスク +- リトライ処理が不適切: 中リスク +- エラー通知が不足: 中リスク + +### テスタビリティ +- 状態遷移のテストが不足: 中リスク +- エッジケースのテストがない: 高リスク + +## 追加調査が必要な条件 + +以下の条件のいずれかに該当する場合、追加調査を提案する： + +- 状態数が10個以上ある +- 循環遷移パターンが検出された +- 複数のデータの状態が密接に連動している +- 外部システムとの連携がある +- トランザクション境界が不明確 +- エラーハンドリングが不十分 +- テストカバレッジが低い +- ドキュメントと実装が乖離している可能性 + +## 深掘り内容のルール + +調査した内容を元に、以下の観点で追加調査が必要な箇所をリストアップする： + +- 複雑な遷移パターンの詳細分析 +- データ整合性の検証方法 +- エラーハンドリングの改善点 +- テストケースの不足箇所 +- パフォーマンスへの影響 +- セキュリティ上の懸念点 + +# info + + +あなたは状態遷移分析のエキスパートです。以下の情報に基づいて、対象データの状態遷移を包括的に分析し、セクション別に分割してファイル出力してください。 + +# 分析対象の情報 + +対象データ名: {{対象データ名}} +データの種類: {{データの種類}} +状態フィールド名: {{状態フィールド名}} +分析範囲: {{分析範囲}} +出力形式: {{出力形式}} +ベースディレクトリ: {{ベースディレクトリ}}（例: ".dcs/20251026143000_order_state"） +カレントディレクトリ: {{カレントディレクトリ}} + +# 重要な注意事項 + +**すべてのファイルパスは、カレントディレクトリを基準とした相対パスで記載してください。** +**絶対パス（/Users/... など）は使用しないでください。** +**各セクションファイルは500行以内を目標としてください。** + +# 出力ファイル構成 + +分析結果は以下のセクション別ファイルに分割して出力してください： + +1. **インデックスファイル**: `{{ベースディレクトリ}}/index.md` + - 全体概要と全セクションファイルへのリンク + +2. **サマリーファイル**: `{{ベースディレクトリ}}/summary.md` + - 分析対象、サマリー、リスク評価 + +3. **状態遷移図ファイル**: `{{ベースディレクトリ}}/diagram.md` + - Mermaid形式の状態遷移図 + +4. **遷移表ファイル**: `{{ベースディレクトリ}}/transitions.md` + - 状態遷移の詳細な表 + +5. **機能別分析ファイル**: `{{ベースディレクトリ}}/functions.md` + - 各機能が行う状態遷移の詳細 + +6. **データ依存関係ファイル**: `{{ベースディレクトリ}}/dependencies.md` + - 他のデータとの状態依存関係 + +7. **リスク評価ファイル**: `{{ベースディレクトリ}}/risks.md` + - 状態遷移に関するリスク評価 + +8. **推奨事項ファイル**: `{{ベースディレクトリ}}/recommendations.md` + - 改善提案と推奨アクション + +# 分析手順 + +## 1. 対象データの特定と状態フィールドの確認 + +### 1.1 データ定義の特定 +- データの種類に応じて定義箇所を検索 + - Prismatixリソース: `prismatix-factory/resources/{{対象データ名}}.yaml` + - Kotlinエンティティ: `backend/src/main/kotlin/**/entity/**/*{{対象データ名}}*.kt` + - TypeScript型: `frontend/src/**/*{{対象データ名}}*.ts` または `admin/src/**/*{{対象データ名}}*.ts` +- Read ツールで定義ファイルを読み込む + +### 1.2 状態フィールドの確認 +- 指定された状態フィールド名を確認 +- 「自動検出」の場合、以下のパターンで検索: + - `status`, `state`, `{{データ名}}Status`, `{{データ名}}State` + - enum定義を検索: `enum.*Status`, `enum.*State` +- 状態フィールドの型を特定（enum, string, number等） + +### 1.3 状態値の列挙 +- enum定義から状態値を抽出 +- YAML定義から可能な値を抽出 +- コード内で使用されている状態値を Grep で検索 + - 文字列リテラル: `"PENDING"`, `"COMPLETED"` 等 + - 定数参照: `OrderStatus.PENDING` 等 +- 検出された全ての状態値をリスト化 + +## 2. 状態遷移を行う機能の検索 + +### 2.1 バックエンドの検索（分析範囲に含まれる場合） +- **コントローラー**: 状態を更新するAPIエンドポイント + - Grep: `@PutMapping.*{{対象データ名}}`, `@PostMapping.*{{対象データ名}}` + - 状態フィールドへの代入を検索: `\.{{状態フィールド名}}\s*=` +- **サービスクラス**: ビジネスロジック内の状態更新 + - Grep: `class.*Service`, `fun.*update`, `fun.*change` +- **インターセプター**: 自動的な状態更新 + - Grep: `Interceptor`, `@Component.*Interceptor` + - 特に `Before`, `After`, `Around` 系のインターセプター +- **バッチ処理**: スケジューラーによる状態更新 + - Grep: `@Scheduled`, `@EnableScheduling` + +### 2.2 フロントエンドの検索（分析範囲に含まれる場合） +- **API呼び出し**: 状態を変更するAPI呼び出し + - Grep: `api.*{{対象データ名}}`, `fetch.*{{対象データ名}}` + - `PUT`, `POST`, `PATCH` メソッドを特定 +- **状態管理**: クライアント側の状態管理 + - Grep: `useState`, `useReducer`, `{{対象データ名}}Context` + +### 2.3 BFFの検索（分析範囲に含まれる場合） +- **API Routes**: Next.js API routesでの状態更新 + - Glob: `frontend/src/pages/api/**/*.ts`, `admin/src/pages/api/**/*.ts` + - Grep: `{{対象データ名}}`, 状態フィールド名 + +## 3. 各機能の状態遷移パターンの分析 + +各検出された機能について、以下を分析： + +### 3.1 遷移元・遷移先の特定 +- 状態を変更するコードを Read で詳細確認 +- どの状態からどの状態へ遷移するかを特定 + - 条件分岐（if, when, switch）を確認 + - 状態チェックのロジックを抽出 +- 遷移が可能な状態の組み合わせを記録 + +### 3.2 遷移条件の抽出 +- 状態遷移の前提条件を特定 + - 現在の状態のチェック + - ビジネスルールの検証 + - 関連データの状態確認 + - 権限チェック +- 条件式や検証ロジックを記録 + +### 3.3 遷移トリガーの分類 +- APIエンドポイント呼び出し → エンドポイントURLとHTTPメソッド +- インターセプター → トリガーとなるイベント（Before/After/Around） +- バッチ処理 → 実行スケジュール（cron式等） +- 外部連携 → 外部システム名と連携方法 + +### 3.4 副作用の特定 +- 状態遷移時に実行される処理を抽出 + - 他のデータの更新 + - 通知の送信（メール、プッシュ通知等） + - ログ記録 + - イベント発行 + - 外部システムへの連携 + +## 4. データ依存関係の分析 + +### 4.1 関連データの特定 +- 外部キーで関連するデータを特定 + - YAML定義の relations セクション + - Kotlinエンティティの `@ManyToOne`, `@OneToMany` 等 +- Grep で関連データへの参照を検索 + +### 4.2 状態の連動パターン +- 対象データの状態変更が他のデータに与える影響を分析 +- 他のデータの状態変更が対象データに与える影響を分析 +- 例: + - Order.status が "COMPLETED" になると OrderItem.status も連動 + - Payment.status が "PAID" になると Order.status が更新される + +### 4.3 トランザクション境界の確認 +- 状態更新がトランザクション内で行われるか確認 +- `@Transactional` アノテーションの有無 +- 複数データの状態更新が同一トランザクションか確認 + +## 5. リスク評価 + +以下の基準でリスクを評価： + +### 5.1 状態の複雑度 +- 状態数: 多いほどリスク増加（10個以上: 高リスク） +- 遷移パターン数: 複雑なほどリスク増加 +- 循環遷移: 存在する場合は要注意 + +### 5.2 データ整合性リスク +- 複数データの状態連動: 連動が多いほど高リスク +- トランザクション境界: 不明確な場合は高リスク +- ロールバック処理: 未実装の場合は高リスク + +### 5.3 エラーハンドリング +- 異常系の遷移定義: 不足している場合は高リスク +- エラー時のリトライ: 不適切な場合は中リスク +- エラー通知: 不足している場合は中リスク + +### 5.4 テスタビリティ +- 状態遷移のテストケース: 不足している場合は中〜高リスク +- エッジケースのカバレッジ: 低い場合は高リスク + +## 6. セクション別ファイル出力 + +以下の順序で各セクションファイルを作成してください。**各ファイルは Write ツールを使って個別に保存してください。** + +### 6.1 インデックスファイルの作成 +`{{ベースディレクトリ}}/index.md` + +```markdown +# 状態遷移分析 - インデックス + +**実施日時**: {{実施日時}} +**分析者**: Claude Code + +--- + +## 分析概要 + +### 対象データ +- **データ名**: {{対象データ名}} +- **状態フィールド**: {{状態フィールド名}} +- **状態数**: XX個 +- **遷移パターン数**: XX個 + +### サマリー + +| 項目 | 内容 | +|------|------| +| 総合リスク評価 | **高/中/低** | +| 検出された機能数 | XX個 | +| データ依存関係 | XX個 | + +--- + +## 分析結果ファイル一覧 + +### 基本情報 +- [サマリー](./summary.md) - 分析結果の概要 + +### 状態遷移の詳細 +- [状態遷移図](./diagram.md) - Mermaid形式の視覚化 +- [遷移表](./transitions.md) - 詳細な遷移表 + +### 機能とデータ +- [機能別分析](./functions.md) - 各機能の状態遷移 +- [データ依存関係](./dependencies.md) - 関連データとの依存 + +### 評価と推奨 +- [リスク評価](./risks.md) - リスク評価の詳細 +- [推奨事項](./recommendations.md) - 改善提案 + +--- + +## クイックナビゲーション + +### 高リスク項目 +1. {{高リスク項目1}} - [詳細](./risks.md) +2. {{高リスク項目2}} - [詳細](./risks.md) + +### 複雑な遷移パターン +1. {{複雑なパターン1}} - [詳細](./transitions.md) +2. {{複雑なパターン2}} - [詳細](./transitions.md) + +--- + +*各ファイルの詳細は上記リンクから参照してください。* +``` + +### 6.2 サマリーファイルの作成 +`{{ベースディレクトリ}}/summary.md` + +```markdown +# 状態遷移分析 - サマリー + +**実施日時**: {{実施日時}} +**分析者**: Claude Code + +[← インデックスに戻る](./index.md) + +--- + +## 分析対象 + +### 対象データ +- **データ名**: {{対象データ名}} +- **データ種類**: {{データの種類}} +- **状態フィールド**: {{状態フィールド名}} +- **状態フィールドの型**: {{型情報}} + +### 分析範囲 +- {{分析範囲1}} +- {{分析範囲2}} + +--- + +## 状態値の一覧 + +検出された状態値（XX個）: + +| 状態値 | 説明 | 定義箇所 | +|-------|------|----------| +| {{状態1}} | {{説明}} | {{相対パス:行番号}} | +| {{状態2}} | {{説明}} | {{相対パス:行番号}} | +| ... | ... | ... | + +--- + +## 分析結果サマリー + +| 項目 | 内容 | +|------|------| +| 検出された状態数 | XX個 | +| 遷移パターン数 | XX個 | +| 状態遷移を行う機能数 | XX個 | +| データ依存関係数 | XX個 | +| 総合リスク評価 | **高/中/低** | + +### リスク評価の根拠 +{{総合的なリスク評価の理由を簡潔に記述}} + +--- + +## 遷移パターンの分類 + +| 分類 | 件数 | 備考 | +|------|------|------| +| 正常遷移 | XX件 | ビジネスフローに沿った遷移 | +| 異常遷移 | XX件 | エラーやキャンセル | +| 補正遷移 | XX件 | 管理者による手動修正 | +| 自動遷移 | XX件 | バッチ処理等 | + +--- + +## 機能の分類 + +| 機能種別 | 件数 | 主なファイル | +|---------|------|-------------| +| コントローラー | XX件 | [詳細](./functions.md) | +| サービス | XX件 | [詳細](./functions.md) | +| インターセプター | XX件 | [詳細](./functions.md) | +| バッチ処理 | XX件 | [詳細](./functions.md) | + +--- + +## 主要な発見事項 + +1. **{{発見事項1}}** + - {{詳細}} + - リスク: 高/中/低 + +2. **{{発見事項2}}** + - {{詳細}} + - リスク: 高/中/低 + +3. **{{発見事項3}}** + - {{詳細}} + - リスク: 高/中/低 + +--- + +## 追加調査が必要な項目 + +以下の項目について、追加調査が推奨されます： + +1. {{追加調査項目1}} +2. {{追加調査項目2}} +3. {{追加調査項目3}} + +（追加調査が不要な場合は「なし」と記載） + +--- + +*詳細な分析結果は各セクションファイルを参照してください。* +``` + +### 6.3 状態遷移図ファイルの作成 +`{{ベースディレクトリ}}/diagram.md` + +```markdown +# 状態遷移分析 - 状態遷移図 + +**実施日時**: {{実施日時}} +**分析者**: Claude Code + +[← インデックスに戻る](./index.md) | [サマリー](./summary.md) + +--- + +## 状態遷移図（Mermaid） + +### 全体の状態遷移 + +\```mermaid +stateDiagram-v2 + [*] --> {{初期状態}} + + {{初期状態}} --> {{状態A}} : {{遷移条件A}} + {{状態A}} --> {{状態B}} : {{遷移条件B}} + {{状態B}} --> {{状態C}} : {{遷移条件C}} + {{状態C}} --> [*] + + {{状態A}} --> {{エラー状態}} : エラー発生 + {{状態B}} --> {{エラー状態}} : エラー発生 + + note right of {{状態A}} + {{状態Aの説明}} + end note +\``` + +### 正常フローの遷移 + +\```mermaid +stateDiagram-v2 + {{正常フローの状態遷移図}} +\``` + +### 異常フローの遷移 + +\```mermaid +stateDiagram-v2 + {{異常フローの状態遷移図}} +\``` + +--- + +## 遷移パターンの凡例 + +| パターン | 説明 | トリガー例 | +|---------|------|-----------| +| A → B | {{パターン説明}} | {{トリガー}} | +| B → C | {{パターン説明}} | {{トリガー}} | +| X → エラー | {{パターン説明}} | {{トリガー}} | + +--- + +## 循環遷移の注意点 + +（循環遷移が存在する場合） + +以下の循環遷移パターンが検出されました： + +1. **{{循環パターン1}}**: A → B → C → A + - リスク: {{リスクレベル}} + - 注意事項: {{注意事項}} + +--- + +*遷移の詳細は遷移表ファイルを参照してください。* +``` + +### 6.4 遷移表ファイルの作成 +`{{ベースディレクトリ}}/transitions.md` + +```markdown +# 状態遷移分析 - 遷移表 + +**実施日時**: {{実施日時}} +**分析者**: Claude Code + +[← インデックスに戻る](./index.md) | [サマリー](./summary.md) + +--- + +## 状態遷移表（全体） + +| 遷移ID | 遷移元 | 遷移先 | 遷移条件 | トリガー | 機能 | リスク | +|-------|--------|--------|---------|---------|------|-------| +| T001 | {{状態A}} | {{状態B}} | {{条件}} | {{トリガー}} | [詳細](./functions.md#func1) | 低 | +| T002 | {{状態B}} | {{状態C}} | {{条件}} | {{トリガー}} | [詳細](./functions.md#func2) | 中 | +| ... | ... | ... | ... | ... | ... | ... | + +--- + +## 状態別の遷移詳細 + +### {{状態A}} からの遷移 + +#### {{状態A}} → {{状態B}} +- **遷移ID**: T001 +- **遷移条件**: + - {{条件1}} + - {{条件2}} +- **トリガー**: {{トリガーの詳細}} +- **実装箇所**: [{{相対パス}}]({{相対パス}}#L{{行番号}}) +- **副作用**: + - {{副作用1}} + - {{副作用2}} +- **関連データの状態変更**: + - {{データX}}.{{状態フィールド}} を {{新しい状態}} に変更 +- **リスク**: 低/中/高 +- **リスクの理由**: {{理由}} + +#### {{状態A}} → {{エラー状態}} +（同様の形式で記述） + +--- + +### {{状態B}} からの遷移 + +（同様の形式で各状態からの遷移を記述） + +--- + +## 遷移パターン別の詳細 + +### 正常遷移パターン + +（正常フローの遷移を詳細に記述） + +### 異常遷移パターン + +（異常フローの遷移を詳細に記述） + +### 補正遷移パターン + +（管理者による手動修正等の遷移を記述） + +--- + +## 遷移不可能なパターン + +以下の遷移は実装上不可能です： + +| 遷移元 | 遷移先 | 理由 | +|-------|--------|------| +| {{状態X}} | {{状態Y}} | {{不可能な理由}} | + +--- + +*各機能の詳細は機能別分析ファイルを参照してください。* +``` + +### 6.5 機能別分析ファイルの作成 +`{{ベースディレクトリ}}/functions.md` + +```markdown +# 状態遷移分析 - 機能別分析 + +**実施日時**: {{実施日時}} +**分析者**: Claude Code + +[← インデックスに戻る](./index.md) | [サマリー](./summary.md) + +--- + +## コントローラー層 + +### [相対パス:行番号](相対パス#L行番号) + +- **機能名**: {{機能名}} +- **エンドポイント**: `{{HTTPメソッド}} {{URL}}` +- **実行する状態遷移**: + - {{状態A}} → {{状態B}} + - {{状態B}} → {{状態C}} +- **遷移条件**: + - {{条件1}} + - {{条件2}} +- **副作用**: + - {{副作用1}} + - {{副作用2}} +- **トランザクション**: あり/なし +- **エラーハンドリング**: {{エラー処理の説明}} +- **テストケース**: {{テストの有無と場所}} +- **リスク**: 低/中/高 +- **備考**: {{その他の注意事項}} + +--- + +## サービス層 + +### [相対パス:行番号](相対パス#L行番号) + +（同様の形式で記述） + +--- + +## インターセプター + +### [相対パス:行番号](相対パス#L行番号) + +- **インターセプター名**: {{名前}} +- **トリガー**: Before/After/Around {{イベント名}} +- **実行する状態遷移**: + - {{状態X}} → {{状態Y}} +- **遷移条件**: + - {{条件}} +- **自動実行**: はい/いいえ +- **副作用**: + - {{副作用}} +- **エラーハンドリング**: {{エラー処理}} +- **リスク**: 低/中/高 +- **備考**: {{注意事項}} + +--- + +## バッチ処理 + +### [相対パス:行番号](相対パス#L行番号) + +- **バッチ名**: {{名前}} +- **実行スケジュール**: {{cron式}} +- **実行する状態遷移**: + - {{状態P}} → {{状態Q}} +- **対象データの抽出条件**: + - {{条件}} +- **副作用**: + - {{副作用}} +- **エラーハンドリング**: {{エラー処理}} +- **リトライ処理**: あり/なし +- **リスク**: 低/中/高 +- **備考**: {{注意事項}} + +--- + +## BFF（Backend for Frontend） + +### [相対パス:行番号](相対パス#L行番号) + +- **API Route**: `{{HTTPメソッド}} {{パス}}` +- **呼び出す Backend API**: {{バックエンドAPI}} +- **実行する状態遷移**: + - {{状態M}} → {{状態N}} +- **フロントエンドでの表示**: {{UI上の変化}} +- **エラーハンドリング**: {{エラー処理}} +- **リスク**: 低/中/高 + +--- + +*各機能が行う遷移の詳細は遷移表ファイルを参照してください。* +``` + +### 6.6 データ依存関係ファイルの作成 +`{{ベースディレクトリ}}/dependencies.md` + +```markdown +# 状態遷移分析 - データ依存関係 + +**実施日時**: {{実施日時}} +**分析者**: Claude Code + +[← インデックスに戻る](./index.md) | [サマリー](./summary.md) + +--- + +## 関連データの一覧 + +| データ名 | 関係種別 | 状態フィールド | 依存方向 | +|---------|---------|--------------|---------| +| {{データA}} | 1:N | {{statusField}} | 双方向 | +| {{データB}} | N:1 | {{stateField}} | 単方向 | +| ... | ... | ... | ... | + +--- + +## 状態連動パターン + +### {{対象データ}} → {{データA}} への影響 + +#### {{対象データ}}.{{状態}} が {{状態値}} になると + +- **{{データA}}への影響**: + - {{データA}}.{{状態フィールド}} が {{新しい状態}} に変更される + - 実装箇所: [{{相対パス}}]({{相対パス}}#L{{行番号}}) + - トランザクション境界: {{同一トランザクション/別トランザクション}} +- **ビジネスルール**: + - {{ルール説明}} +- **エラーケース**: + - {{エラー時の動作}} +- **リスク**: 低/中/高 +- **リスクの理由**: {{理由}} + +### {{データB}} → {{対象データ}} への影響 + +#### {{データB}}.{{状態}} が {{状態値}} になると + +（同様の形式で記述） + +--- + +## 複合的な状態依存 + +### パターン1: {{複合パターン名}} + +- **関係するデータ**: + - {{対象データ}} + - {{データA}} + - {{データB}} +- **状態連動のフロー**: + 1. {{データB}}.{{状態}} が {{状態1}} になる + 2. {{対象データ}}.{{状態}} が {{状態2}} に変更される + 3. {{データA}}.{{状態}} が {{状態3}} に変更される +- **実装箇所**: + - [{{相対パス1}}]({{相対パス1}}#L{{行番号}}) + - [{{相対パス2}}]({{相対パス2}}#L{{行番号}}) +- **トランザクション境界**: {{説明}} +- **整合性リスク**: 低/中/高 +- **リスクの理由**: {{理由}} + +--- + +## トランザクション境界の分析 + +### 同一トランザクション内の状態更新 + +以下のデータは同一トランザクション内で状態が更新されます： + +1. **{{トランザクション1}}**: + - 更新されるデータ: {{対象データ}}, {{データA}} + - 実装箇所: [{{相対パス}}]({{相対パス}}#L{{行番号}}) + - `@Transactional` の有無: あり/なし + - リスク: 低/中/高 + +### 異なるトランザクションでの状態更新 + +以下のデータは異なるトランザクションで状態が更新されます： + +1. **{{データ組み合わせ}}**: + - データ1: {{対象データ}} (トランザクション A) + - データ2: {{データB}} (トランザクション B) + - 整合性リスク: 高 + - リスクの理由: {{理由}} + - 推奨対応: {{対応方法}} + +--- + +## 外部システムとの連携 + +### {{外部システム名}} + +- **連携タイミング**: {{対象データ}}.{{状態}} が {{状態値}} になったとき +- **連携内容**: {{内容}} +- **実装箇所**: [{{相対パス}}]({{相対パス}}#L{{行番号}}) +- **エラーハンドリング**: {{エラー時の動作}} +- **リトライ処理**: あり/なし +- **リスク**: 低/中/高 + +--- + +## データ整合性リスク + +### 高リスク項目 + +1. **{{リスク項目1}}**: + - リスクの内容: {{説明}} + - 影響範囲: {{影響}} + - 推奨対応: {{対応方法}} + +2. **{{リスク項目2}}**: + （同様の形式で記述） + +--- + +*依存関係に関連するリスク評価はリスク評価ファイルを参照してください。* +``` + +### 6.7 リスク評価ファイルの作成 +`{{ベースディレクトリ}}/risks.md` + +```markdown +# 状態遷移分析 - リスク評価 + +**実施日時**: {{実施日時}} +**分析者**: Claude Code + +[← インデックスに戻る](./index.md) | [サマリー](./summary.md) + +--- + +## 総合リスク評価 + +| 項目 | 評価 | 理由 | +|------|------|------| +| 状態の複雑度 | 高/中/低 | {{理由}} | +| データ整合性 | 高/中/低 | {{理由}} | +| エラーハンドリング | 高/中/低 | {{理由}} | +| テスタビリティ | 高/中/低 | {{理由}} | +| **総合評価** | **高/中/低** | {{総合的な理由}} | + +--- + +## 状態の複雑度リスク + +### 状態数 +- **検出された状態数**: XX個 +- **評価**: 高/中/低 +- **理由**: {{評価の理由}} + +### 遷移パターン数 +- **検出された遷移パターン数**: XX個 +- **評価**: 高/中/低 +- **理由**: {{評価の理由}} + +### 循環遷移 +- **循環遷移の有無**: あり/なし +- **循環パターン**: {{パターンの説明}} +- **評価**: 高/中/低 +- **理由**: {{評価の理由}} + +--- + +## データ整合性リスク + +### 複数データの状態連動 + +| 連動パターン | 関連データ数 | トランザクション | リスク | +|-------------|------------|----------------|-------| +| {{パターン1}} | X個 | 同一/別 | 高/中/低 | +| {{パターン2}} | X個 | 同一/別 | 高/中/低 | + +#### 高リスク項目の詳細 + +1. **{{連動パターン名}}**: + - リスクの内容: {{説明}} + - 影響範囲: {{影響}} + - 発生条件: {{条件}} + - 推奨対応: {{対応方法}} + +### トランザクション境界の問題 + +- **不明確なトランザクション境界**: XX箇所 +- **評価**: 高/中/低 +- **具体例**: + - [{{相対パス}}]({{相対パス}}#L{{行番号}}) + - 問題点: {{問題の説明}} + +### ロールバック処理 + +- **ロールバック処理の実装**: あり/なし/一部 +- **評価**: 高/中/低 +- **未実装箇所**: + - [{{相対パス}}]({{相対パス}}#L{{行番号}}) + +--- + +## エラーハンドリングリスク + +### 異常系の遷移定義 + +- **定義済み異常遷移**: XX個 +- **未定義の可能性がある異常遷移**: XX個 +- **評価**: 高/中/低 + +#### 未定義の異常遷移 + +1. **{{状態A}} でエラーが発生した場合**: + - 現状: {{現状の動作}} + - 問題点: {{問題}} + - 推奨対応: {{対応方法}} + +### リトライ処理 + +- **リトライ処理の実装**: あり/なし/一部 +- **評価**: 高/中/低 +- **問題箇所**: + - [{{相対パス}}]({{相対パス}}#L{{行番号}}) + - 問題点: {{問題の説明}} + +### エラー通知 + +- **エラー通知の実装**: あり/なし/一部 +- **評価**: 高/中/低 +- **不足箇所**: + - {{箇所の説明}} + +--- + +## テスタビリティリスク + +### 状態遷移のテストカバレッジ + +- **テスト済み遷移パターン**: XX / YY 個 (XX%) +- **評価**: 高/中/低 + +#### 未テストの遷移 + +| 遷移元 | 遷移先 | 機能 | リスク | +|-------|--------|------|-------| +| {{状態A}} | {{状態B}} | [詳細](./functions.md#func1) | 高/中/低 | + +### エッジケースのテスト + +- **エッジケースのテスト**: あり/なし/一部 +- **評価**: 高/中/低 +- **未テストのエッジケース**: + 1. {{エッジケース1}} + 2. {{エッジケース2}} + +--- + +## セキュリティリスク + +### 権限チェック + +- **権限チェックの実装**: あり/なし/一部 +- **評価**: 高/中/低 +- **不足箇所**: + - [{{相対パス}}]({{相対パス}}#L{{行番号}}) + - 問題点: {{問題の説明}} + +### 状態遷移の不正操作 + +- **不正操作の防止**: あり/なし/一部 +- **評価**: 高/中/低 +- **脆弱性の可能性**: + - {{脆弱性の説明}} + +--- + +## パフォーマンスリスク + +### 高頻度で実行される遷移 + +| 遷移 | 実行頻度 | パフォーマンス影響 | リスク | +|------|---------|------------------|-------| +| {{遷移1}} | 高 | {{影響}} | 高/中/低 | + +### データベースロック + +- **ロックの発生可能性**: あり/なし +- **評価**: 高/中/低 +- **リスク箇所**: + - [{{相対パス}}]({{相対パス}}#L{{行番号}}) + +--- + +## リスクの優先順位 + +### 即座に対応が必要（高リスク） + +1. **{{リスク項目1}}**: + - リスクレベル: 高 + - 影響範囲: {{影響}} + - 推奨対応: {{対応方法}} + - 所要時間: {{概算}} + +2. **{{リスク項目2}}**: + （同様の形式で記述） + +### レビューと検証が必要（中リスク） + +1. **{{リスク項目}}**: + - リスクレベル: 中 + - 影響範囲: {{影響}} + - 推奨対応: {{対応方法}} + +### 念のため確認推奨（低リスク） + +1. **{{リスク項目}}**: + - リスクレベル: 低 + - 推奨対応: {{対応方法}} + +--- + +*リスクへの対応方法は推奨事項ファイルを参照してください。* +``` + +### 6.8 推奨事項ファイルの作成 +`{{ベースディレクトリ}}/recommendations.md` + +```markdown +# 状態遷移分析 - 推奨事項 + +**実施日時**: {{実施日時}} +**分析者**: Claude Code + +[← インデックスに戻る](./index.md) | [サマリー](./summary.md) + +--- + +## 優先度: 高（即座に対応が必要） + +### 1. {{推奨事項1}} + +- **対象箇所**: [{{相対パス}}]({{相対パス}}#L{{行番号}}) +- **現状の問題**: {{問題の説明}} +- **推奨対応**: + 1. {{対応ステップ1}} + 2. {{対応ステップ2}} + 3. {{対応ステップ3}} +- **期待される効果**: {{効果}} +- **所要時間**: {{概算}} +- **関連リスク**: [{{リスク名}}](./risks.md) + +### 2. {{推奨事項2}} + +（同様の形式で記述） + +--- + +## 優先度: 中（レビューと検証が必要） + +### 1. {{推奨事項}} + +- **対象箇所**: [{{相対パス}}]({{相対パス}}#L{{行番号}}) +- **現状の問題**: {{問題の説明}} +- **推奨対応**: {{対応方法}} +- **期待される効果**: {{効果}} +- **関連リスク**: [{{リスク名}}](./risks.md) + +--- + +## 優先度: 低（念のため確認推奨） + +### 1. {{推奨事項}} + +- **対象箇所**: [{{相対パス}}]({{相対パス}}#L{{行番号}}) +- **推奨対応**: {{対応方法}} + +--- + +## テスト強化の推奨 + +### ユニットテスト + +**追加すべきテストケース**: + +1. **{{テストケース1}}**: + - テスト内容: {{内容}} + - 対象機能: [{{機能名}}](./functions.md#func1) + - 優先度: 高/中/低 + +2. **{{テストケース2}}**: + （同様の形式で記述） + +### 統合テスト + +**追加すべきテストシナリオ**: + +1. **{{シナリオ1}}**: + - シナリオ: {{説明}} + - 検証する遷移: {{遷移パターン}} + - 優先度: 高/中/低 + +### E2Eテスト + +**追加すべきユーザーシナリオ**: + +1. **{{シナリオ1}}**: + - ユーザーストーリー: {{説明}} + - 検証する状態遷移: {{遷移フロー}} + - 優先度: 高/中/低 + +--- + +## ドキュメント整備の推奨 + +### 状態遷移仕様書 + +- **現状**: {{現状のドキュメント状況}} +- **推奨内容**: + - 状態遷移図の作成（本分析結果を参照） + - 各遷移の条件とビジネスルールの明文化 + - エラーケースの定義 +- **利用者**: 開発者、QAエンジニア、プロダクトオーナー + +### API仕様書 + +- **現状**: {{現状の仕様書}} +- **推奨内容**: + - 状態遷移を行うAPIエンドポイントの明記 + - 遷移可能な状態の組み合わせの記載 + - エラーレスポンスの詳細化 + +--- + +## コード改善の推奨 + +### リファクタリング + +1. **{{リファクタリング項目1}}**: + - 対象: [{{相対パス}}]({{相対パス}}#L{{行番号}}) + - 問題点: {{問題}} + - 推奨改善: {{改善方法}} + - メリット: {{メリット}} + +### デザインパターンの適用 + +1. **State パターンの適用**: + - 対象: {{対象箇所}} + - 理由: {{適用する理由}} + - 期待される効果: {{効果}} + +--- + +## モニタリングとアラートの推奨 + +### 状態遷移のモニタリング + +- **推奨メトリクス**: + 1. 各状態の滞在時間 + 2. 遷移の成功率/失敗率 + 3. 異常遷移の発生頻度 +- **実装方法**: {{実装の提案}} + +### アラート設定 + +- **推奨アラート**: + 1. {{アラート1}}: {{条件と通知先}} + 2. {{アラート2}}: {{条件と通知先}} + +--- + +## エラーハンドリング改善の推奨 + +### リトライ処理の追加 + +- **対象箇所**: [{{相対パス}}]({{相対パス}}#L{{行番号}}) +- **推奨リトライ戦略**: + - 最大リトライ回数: {{回数}} + - リトライ間隔: {{間隔}} + - リトライ対象エラー: {{エラー種別}} + +### エラー通知の改善 + +- **対象箇所**: {{箇所}} +- **推奨通知方法**: {{方法}} +- **通知内容**: {{内容}} + +--- + +## セキュリティ強化の推奨 + +### 権限チェックの追加 + +- **対象箇所**: [{{相対パス}}]({{相対パス}}#L{{行番号}}) +- **推奨チェック内容**: + - {{チェック項目1}} + - {{チェック項目2}} + +### 監査ログの追加 + +- **対象遷移**: {{遷移}} +- **記録すべき情報**: + - {{情報1}} + - {{情報2}} + +--- + +## データ整合性改善の推奨 + +### トランザクション境界の明確化 + +- **対象箇所**: [{{相対パス}}]({{相対パス}}#L{{行番号}}) +- **推奨対応**: {{対応方法}} + +### 整合性チェックの追加 + +- **対象データ**: {{データ名}} +- **推奨チェック内容**: + - {{チェック項目1}} + - {{チェック項目2}} + +--- + +## その他の推奨事項 + +1. **{{その他の推奨1}}**: + - 内容: {{説明}} + - 期待される効果: {{効果}} + +2. **{{その他の推奨2}}**: + （同様の形式で記述） + +--- + +*各推奨事項の詳細なリスク評価はリスク評価ファイルを参照してください。* +``` + +## 7. 分析の注意点 + +- 動的な状態変更（リフレクション等）は検出できない可能性がある +- 文字列による間接的な状態更新は検出が困難 +- コメントアウトされたコードは除外する +- テストコードは参考情報として含める +- **すべてのファイルパスは相対パスで記載する（絶対パスは使用しない）** +- **各セクションファイルは500行以内を目標とする** + +## 8. 出力手順 + +**重要**: 必ず以下の順序でファイルを作成してください： + +1. **インデックスファイルを最初に作成** (`{{ベースディレクトリ}}/index.md`) +2. **サマリーファイルを作成** (`{{ベースディレクトリ}}/summary.md`) +3. **状態遷移図ファイルを作成** (`{{ベースディレクトリ}}/diagram.md`) +4. **遷移表ファイルを作成** (`{{ベースディレクトリ}}/transitions.md`) +5. **機能別分析ファイルを作成** (`{{ベースディレクトリ}}/functions.md`) +6. **データ依存関係ファイルを作成** (`{{ベースディレクトリ}}/dependencies.md`) +7. **リスク評価ファイルを作成** (`{{ベースディレクトリ}}/risks.md`) +8. **推奨事項ファイルを作成** (`{{ベースディレクトリ}}/recommendations.md`) + +**各ファイルは Write ツールを使って個別に保存してください。一つのファイルにまとめないでください。** + + + +あなたは状態遷移分析のサマリー作成エキスパートです。以下の情報に基づいて、最終サマリーを作成してください。 + +# サマリー作成対象の情報 + +対象データ名: {{対象データ名}} +分析ファイルリスト: {{分析ファイルリスト}} +最終サマリーファイル名: {{サマリーファイル名}}（例: ".dcs/20251026143000_order_state/final_summary.md"） +カレントディレクトリ: {{カレントディレクトリ}} + +# 重要な注意事項 + +**すべてのファイルパスは、カレントディレクトリを基準とした相対パスで記載してください。** +**絶対パス（/Users/... など）は使用しないでください。** +**このファイルは500行以内に収まるように簡潔に記述してください。** + +# サマリー作成手順 + +## 1. 全分析ファイルの読み込み + +- {{分析ファイルリスト}} に含まれるすべてのファイルを Read で読み込む +- 各ファイルの内容を把握する + +## 2. 情報の統合 + +- すべての分析結果から以下の情報を統合する + - 検出された状態値の総数 + - 遷移パターンの総数 + - 機能数の総数 + - データ依存関係の総数 + - 総合リスク評価（最も高いリスクレベル） + +## 3. ハイライトの抽出 + +- 最も重要な発見をハイライトする +- 特に注意が必要な箇所を強調する +- 追加調査で判明した重要事項を記載する + +## 4. 統合推奨アクションの作成 + +- 全分析結果から優先度の高いアクションを抽出する +- 重複を排除し、優先順位を付ける +- 全体的な改善方針を提示する + +## 5. サマリーファイルの出力 + +以下の出力形式で {{サマリーファイル名}} に結果を保存してください。 + +# 出力形式 + +```markdown +# 状態遷移分析 - 最終サマリー + +**実施日時**: {{実施日時}} +**分析者**: Claude Code + +--- + +## ナビゲーション + +- [初回分析インデックス](./index.md) +- [初回分析サマリー](./summary.md) + +（追加調査がある場合は追加） +- [追加調査2インデックス](./{base_filename}_2/index.md) +- [追加調査3インデックス](./{base_filename}_3/index.md) + +--- + +## 分析概要 + +### 対象データ +- **データ名**: {{対象データ名}} +- **状態フィールド**: {{状態フィールド名}} +- **データの種類**: {{データの種類}} + +### 分析実施状況 +- **実施した分析回数**: {{分析回数}}回（初回 + 追加調査{{N}}回） +- **作成されたファイル数**: {{ファイル数}}件 + +--- + +## 総合サマリー + +| 項目 | 内容 | +|------|------| +| 検出された状態数 | XX個 | +| 遷移パターン数 | XX個 | +| 機能数 | XX個 | +| データ依存関係数 | XX個 | +| 総合リスク評価 | **高/中/低** | + +### 総合リスク評価の根拠 +{{全体を通じたリスク評価の理由を記述}} + +--- + +## 状態遷移の全体像 + +### 状態値の一覧 + +| 状態値 | 説明 | 遷移元となる回数 | 遷移先となる回数 | +|-------|------|----------------|----------------| +| {{状態1}} | {{説明}} | XX回 | XX回 | +| {{状態2}} | {{説明}} | XX回 | XX回 | +| ... | ... | ... | ... | + +### 遷移パターンの統計 + +| 分類 | 件数 | 備考 | +|------|------|------| +| 正常遷移 | XX件 | {{備考}} | +| 異常遷移 | XX件 | {{備考}} | +| 補正遷移 | XX件 | {{備考}} | +| 自動遷移 | XX件 | {{備考}} | + +--- + +## 主要な発見事項 + +### 重要なハイライト + +1. **{{ハイライト1のタイトル}}** + - {{詳細説明}} + - 影響: {{影響の概要}} + - リスク: 高/中/低 + +2. **{{ハイライト2のタイトル}}** + - {{詳細説明}} + - 影響: {{影響の概要}} + - リスク: 高/中/低 + +3. **{{ハイライト3のタイトル}}** + - {{詳細説明}} + - 影響: {{影響の概要}} + - リスク: 高/中/低 + +--- + +## 複雑な遷移パターン + +### パターン1: {{パターン名}} + +- **遷移フロー**: {{状態A}} → {{状態B}} → {{状態C}} +- **トリガー**: {{トリガー}} +- **複雑度の理由**: {{理由}} +- **関連データ**: {{データ名}} +- **リスク**: 高/中/低 + +--- + +## データ依存関係の統合情報 + +### 関連データの一覧 + +| データ名 | 関係種別 | 状態連動 | リスク | +|---------|---------|---------|-------| +| {{データA}} | 1:N | あり | 高/中/低 | +| {{データB}} | N:1 | あり | 高/中/低 | +| ... | ... | ... | ... | + +### 複合的な状態依存 + +- **パターン**: {{パターン名}} +- **関係するデータ**: {{データ名リスト}} +- **整合性リスク**: 高/中/低 + +--- + +## 統合リスク評価 + +| リスク分類 | 評価 | 主な問題点 | +|-----------|------|-----------| +| 状態の複雑度 | 高/中/低 | {{問題点}} | +| データ整合性 | 高/中/低 | {{問題点}} | +| エラーハンドリング | 高/中/低 | {{問題点}} | +| テスタビリティ | 高/中/低 | {{問題点}} | +| セキュリティ | 高/中/低 | {{問題点}} | +| パフォーマンス | 高/中/低 | {{問題点}} | + +--- + +## 統合推奨アクション + +### 優先度: 高（即座に対応が必要） + +1. [{{相対パス}}]({{相対パス}}#L{{行番号}}) - {{推奨事項}} +2. [{{相対パス}}]({{相対パス}}#L{{行番号}}) - {{推奨事項}} +3. [{{相対パス}}]({{相対パス}}#L{{行番号}}) - {{推奨事項}} + +### 優先度: 中（レビューと検証が必要） + +1. {{推奨事項}} +2. {{推奨事項}} +3. {{推奨事項}} + +### 優先度: 低（念のため確認推奨） + +1. {{推奨事項}} +2. {{推奨事項}} + +--- + +## 全体的な改善方針 + +### 短期的な改善（1-2週間） + +1. **{{改善項目1}}** + - 内容: {{説明}} + - 期待される効果: {{効果}} + +2. **{{改善項目2}}** + （同様の形式で記述） + +### 中期的な改善（1-2ヶ月） + +1. **{{改善項目}}** + - 内容: {{説明}} + - 期待される効果: {{効果}} + +### 長期的な改善（3ヶ月以上） + +1. **{{改善項目}}** + - 内容: {{説明}} + - 期待される効果: {{効果}} + +--- + +## テスト戦略 + +### ユニットテスト強化 + +- **追加すべきテストケース数**: XX個 +- **重点テスト対象**: + 1. {{対象1}} + 2. {{対象2}} + +### 統合テスト強化 + +- **追加すべきシナリオ数**: XX個 +- **重点シナリオ**: + 1. {{シナリオ1}} + 2. {{シナリオ2}} + +### E2Eテスト強化 + +- **追加すべきユーザーストーリー数**: XX個 +- **重点ストーリー**: + 1. {{ストーリー1}} + 2. {{ストーリー2}} + +--- + +## ドキュメント整備計画 + +1. **状態遷移仕様書の作成** + - 本分析結果を基にした正式仕様書 + - 対象読者: 開発者、QA、PO + +2. **API仕様書の更新** + - 状態遷移に関する情報の追加 + - エラーケースの明文化 + +3. **運用ドキュメントの作成** + - モニタリング方法 + - トラブルシューティング + +--- + +## 追加で考慮すべき事項 + +1. **{{考慮事項1}}** + - {{詳細}} + +2. **{{考慮事項2}}** + - {{詳細}} + +3. **{{考慮事項3}}** + - {{詳細}} + +--- + +## 詳細分析ファイル一覧 + +以下のファイルに詳細な分析結果が記録されています： + +### 初回分析 +1. [インデックス](./index.md) +2. [サマリー](./summary.md) +3. [状態遷移図](./diagram.md) +4. [遷移表](./transitions.md) +5. [機能別分析](./functions.md) +6. [データ依存関係](./dependencies.md) +7. [リスク評価](./risks.md) +8. [推奨事項](./recommendations.md) + +（追加調査がある場合は追加） +### 追加調査 +... + +--- + +## 分析の制限事項と注意点 + +- {{制限事項1}} +- {{制限事項2}} +- {{制限事項3}} + +--- + +*このサマリーは複数の分析結果を統合して自動生成されたものです。詳細は個別の分析ファイルを参照してください。* +``` + +# サマリー作成の注意点 + +- すべての分析ファイルの内容を網羅的に把握する +- 重複する情報を排除し、簡潔にまとめる +- 最も重要な情報を優先的に記載する +- 全体の傾向やパターンを識別する +- **すべてのファイルパスは相対パスで記載する（絶対パスは使用しない）** +- **500行以内に収める** + +必ず Write ツールを使用して、{{サマリーファイル名}} に結果を保存してください。 + diff --git a/commands/direct-setup.md b/commands/direct-setup.md index e9c9f88..cc305eb 100644 --- a/commands/direct-setup.md +++ b/commands/direct-setup.md @@ -1,5 +1,7 @@ --- description: DIRECTタスクの設定作業を実行します。設計文書に基づいて環境構築、設定ファイル作成、依存関係のインストールなどを行います。 +allowed-tools: Read, Glob, Grep, Task, Write, Edit, TodoWrite +argument-hint: [要件名] [TASK-ID] --- # direct-setup @@ -53,9 +55,62 @@ DIRECTタスクの設定作業を実行します。設計文書に基づいて 作業記録は `docs/implements/{要件名}/{TASK-ID}/` ディレクトリに以下のファイルとして作成されます： - `setup-report.md`: 設定作業実行記録 +## README.mdへの記録 + +開発環境の構築や運用に関する重要な情報は、**必ずREADME.mdにも記録**してください： + +### 記録すべき内容 +- 新しい環境変数の設定方法 +- 追加した依存関係とそのインストール方法 +- データベースの初期化手順 +- 新しいサービスの起動方法 +- 設定ファイルの場所と説明 +- トラブルシューティング情報（エラーと解決方法） + +### 記録方法 +1. 既存のセクションに追記する場合は、適切な箇所を見つけて追記 +2. 新しいセクションが必要な場合は、適切な位置に新規セクションを作成 +3. コマンド例は必ずコードブロックで記載 +4. 重要な注意事項は明確に記載 + +### 記録例 + +#### セットアップセクションへの追加 +```markdown +### 6. {新しいサービス名}のセットアップ +\`\`\`bash +cd {ディレクトリ} +{インストールコマンド} +{起動コマンド} +\`\`\` +``` + +#### 開発コマンドセクションへの追加 +```markdown +### {サービス名} +\`\`\`bash +# {コマンドの説明} +{コマンド} +\`\`\` +``` + +#### トラブルシューティングセクションへの追加 +```markdown +### {問題の概要} + +\`\`\`bash +# 問題の確認方法 +{確認コマンド} + +# 解決方法 +{解決コマンド} +\`\`\` +``` + ## 出力フォーマット例 -````markdown + +```markdown # {TASK-ID} 設定作業実行 ## 作業概要 @@ -79,7 +134,6 @@ DIRECTタスクの設定作業を実行します。設計文書に基づいて export NODE_ENV=development export DATABASE_URL=postgresql://localhost:5432/mydb ``` -```` **設定内容**: @@ -127,11 +181,11 @@ psql -d mydb -f database-schema.sql ## 作業結果 -- [ ] 環境変数の設定完了 -- [ ] 設定ファイルの作成完了 -- [ ] 依存関係のインストール完了 -- [ ] データベースの初期化完了 -- [ ] サービスの起動設定完了 +- [x] 環境変数の設定完了 +- [x] 設定ファイルの作成完了 +- [x] 依存関係のインストール完了 +- [x] データベースの初期化完了 +- [x] サービスの起動設定完了 ## 遭遇した問題と解決方法 @@ -145,6 +199,8 @@ psql -d mydb -f database-schema.sql - `/tsumiki:direct-verify` を実行して設定を確認 - 必要に応じて設定の調整を実施 +``` + ## 実行後の確認 - `docs/implements/{要件名}/{TASK-ID}/setup-report.md` ファイルが作成されていることを確認 diff --git a/commands/direct-verify.md b/commands/direct-verify.md index edb9267..5f1f26e 100644 --- a/commands/direct-verify.md +++ b/commands/direct-verify.md @@ -1,5 +1,7 @@ --- description: DIRECTタスクで実行した設定作業の動作確認とテストを行います。設定が正しく適用され、システムが期待通りに動作することを確認します。 +allowed-tools: Read, Glob, Grep, Task, Write, Edit, TodoWrite +argument-hint: [要件名] [TASK-ID] --- # direct-verify @@ -18,52 +20,236 @@ DIRECTタスクで実行した設定作業の動作確認とテストを行い **【重要】**: direct-setupで作成されたファイルについて、コンパイルエラーや構文エラーが見つかった場合は自動的に解決を試行します。 -1. **追加ルールの読み込み** - - `docs/rule` ディレクトリが存在する場合は読み込み - - `docs/rule/direct` ディレクトリが存在する場合は読み込み - - `docs/rule/direct/verify` ディレクトリが存在する場合は読み込み - - 各ディレクトリ内のすべてのファイルを読み込み、追加ルールとして適用 - -2. **技術スタック定義の読み込み** - - `docs/tech-stack.md` が存在する場合は読み込み - - 存在しない場合は `CLAUDE.md` から技術スタックセクションを読み込み - - どちらも存在しない場合は `.claude/commands/tech-stack.md` のデフォルト定義を使用 - -3. **設定の確認** - - 読み込んだ技術スタック定義に基づいて検証項目を特定 - - @agent-symbol-searcher で関連設定や検証パターンを検索し、見つかったファイルをReadツールで読み込み - - `docs/implements/{要件名}/{TASK-ID}/setup-report.md` をReadツールで読み込み、設定作業の結果を確認 - - 環境変数の確認 - - 設定ファイルの内容確認 - - 依存関係のインストール状況確認 - - サービスの起動状況確認 - -3. **コンパイル・構文確認** - - TypeScript/JavaScript構文エラーチェック（該当する場合） - - 設定ファイルの構文確認（JSON, YAML等） - - SQL構文確認（該当する場合） - - 最低限のコンパイルエラー解消 - -4. **動作テストの実行** - - @agent-symbol-searcher で既存のテストケースや検証スクリプトを検索し、見つかったファイルをReadツールで読み込み - - 基本的な動作確認 - - 接続テスト - - 権限の確認 - - エラーケースの確認 - -5. **品質チェック** - - セキュリティ設定の確認 - - パフォーマンス基準の確認 - - ログの確認 +### 1. 追加ルールの読み込み +- `docs/rule` ディレクトリが存在する場合は読み込み +- `docs/rule/direct` ディレクトリが存在する場合は読み込み +- `docs/rule/direct/verify` ディレクトリが存在する場合は読み込み +- 各ディレクトリ内のすべてのファイルを読み込み、追加ルールとして適用 + +### 2. 技術スタック定義の読み込み +- `docs/tech-stack.md` が存在する場合は読み込み +- 存在しない場合は `CLAUDE.md` から技術スタックセクションを読み込み +- どちらも存在しない場合は `.claude/commands/tech-stack.md` のデフォルト定義を使用 + +### 3. 設定の確認 +- 読み込んだ技術スタック定義に基づいて検証項目を特定 +- @agent-symbol-searcher で関連設定や検証パターンを検索し、見つかったファイルをReadツールで読み込み +- `docs/implements/{要件名}/{TASK-ID}/setup-report.md` をReadツールで読み込み、設定作業の結果を確認 +- 環境変数の確認 +- 設定ファイルの内容確認 +- 依存関係のインストール状況確認 +- サービスの起動状況確認 + +### 4. コンパイル・構文確認 +- TypeScript/JavaScript構文エラーチェック（該当する場合） +- 設定ファイルの構文確認（JSON, YAML等） +- SQL構文確認（該当する場合） +- 最低限のコンパイルエラー解消 +- **エラーが見つかった場合は自動的に修正を試行** + +### 5. 動作テストの実行 +- @agent-symbol-searcher で既存のテストケースや検証スクリプトを検索し、見つかったファイルをReadツールで読み込み +- 基本的な動作確認 +- 接続テスト +- 権限の確認 +- エラーケースの確認 + +### 6. 品質チェック +- セキュリティ設定の確認 +- パフォーマンス基準の確認 +- ログの確認 + +### 7. CLAUDE.mdへの記録 +- サブプロジェクトの存在確認（`package.json`, `Cargo.toml`, `pyproject.toml`, `go.mod`等） +- 各サブプロジェクトまたはルートの `CLAUDE.md` の存在確認 +- CLAUDE.mdに以下の情報が**最小限**記載されているか確認： + - テスト実行コマンド + - アプリケーション起動コマンド + - ビルドコマンド（該当する場合） + - データベース操作コマンド（該当する場合） +- 情報が不足している場合は「## 開発コマンド」セクションを追加/更新 +- 既存の情報が古い場合は更新。ファイルがなければ必要に応じて新規作成 + +### 8. 検証レポートの作成 +- `docs/implements/{要件名}/{TASK-ID}/verify-report.md` を作成 +- 全ての確認結果を記録 +- 発見された問題と解決内容を記載 +- CLAUDE.mdへの記録内容を記載 +- 推奨事項と次のステップを記載 + +### 9. タスクの完了マーキング +完了条件を全て満たす場合は、**自動的に**以下のファイルを更新： + +#### 完了条件 +- 全ての設定確認項目がクリア +- コンパイル・構文チェックが成功（エラーがすべて解決済み） +- 全ての動作テストが成功 +- 品質チェック項目が基準を満たしている +- 発見された問題が適切に対処されている +- セキュリティ設定が適切 +- パフォーマンス基準を満たしている + +#### 更新対象ファイル +1. **Overview ファイル**: `docs/tasks/{要件名}/overview.md` または `docs/tasks/{要件名}-overview.md` + - 該当タスクの進捗状況を「完了」に更新 + - 完了日を記録 + +2. **タスク詳細ファイル**: `docs/tasks/{要件名}/TASK-{task_id}.md` または `docs/tasks/{要件名}-tasks.md` + - ステータスを「✅ 完了」に更新 + - 完了日を記録 + - 完了条件のチェックボックスを全て `[x]` に変更 ## 出力先 確認記録は `docs/implements/{要件名}/{TASK-ID}/` ディレクトリに以下のファイルとして作成されます： - `verify-report.md`: 設定確認・動作テスト記録 +## CLAUDE.mdへの記録 + +動作確認で必要となった最小限の実行方法は、**必ずCLAUDE.mdに記録**してください： + +### 記録すべき内容（最小限） +- **テストケースの実行方法** + - テストコマンド（例: `npm test`, `pytest`, `cargo test`） + - 特定のテストファイル/ディレクトリの実行方法 + - テスト環境のセットアップ方法（必要な場合のみ） + +- **アプリケーションの実行方法** + - 開発サーバーの起動コマンド（例: `npm run dev`, `python manage.py runserver`） + - ビルドコマンド（例: `npm run build`, `cargo build --release`） + - 本番環境での起動方法（該当する場合） + +- **データベース関連**（該当する場合のみ） + - マイグレーション実行方法 + - シードデータの投入方法 + +### 記録場所の判定ロジック + +1. **サブプロジェクトの特定** + - `package.json`, `Cargo.toml`, `pyproject.toml`, `go.mod` などの存在で判定 + - サブプロジェクトごとに独立したCLAUDE.mdを作成 + +2. **CLAUDE.mdの配置ルール** + - **サブプロジェクトが存在する場合**: 各サブプロジェクトのルートに `CLAUDE.md` を作成 + - 例: `frontend/CLAUDE.md`, `backend/CLAUDE.md` + - **モノリポ構造の場合**: ルートの `CLAUDE.md` に全体像を記載し、各サブプロジェクトに詳細を記載 + - **単一プロジェクトの場合**: ルートの `CLAUDE.md` にのみ記載 + +3. **既存のCLAUDE.mdが存在する場合** + - 既に必要な情報が記載されているかチェック + - 不足している情報のみ追記 + - 情報が古い場合は更新 + +### 記録方法 + +各CLAUDE.mdに以下のセクションを追加または更新： + +```markdown +## 開発コマンド + +### テスト実行 +\`\`\`bash +# すべてのテストを実行 +{テストコマンド} + +# 特定のテストを実行 +{特定テスト実行コマンド} +\`\`\` + +### アプリケーション実行 +\`\`\`bash +# 開発サーバー起動 +{開発サーバー起動コマンド} + +# ビルド +{ビルドコマンド} +\`\`\` + +### データベース操作（該当する場合） +\`\`\`bash +# マイグレーション実行 +{マイグレーションコマンド} + +# シードデータ投入 +{シードコマンド} +\`\`\` +``` + +### 記録の優先順位 + +1. **必須**: テスト実行方法、アプリケーション起動方法 +2. **推奨**: ビルド方法、データベース操作（該当する場合） +3. **任意**: 詳細なトラブルシューティング（README.mdに記載） + +## README.mdへの記録 + +動作確認結果や運用に関する重要な情報は、**必ずREADME.mdにも記録**してください： + +### 記録すべき内容 +- 動作確認の手順とコマンド +- 各コンポーネントの正常動作の確認方法 +- パフォーマンス基準値（起動時間、メモリ使用量等） +- 発見された問題と解決方法（トラブルシューティング） +- 推奨される運用設定 +- セキュリティ関連の注意事項 + +### 記録方法 +1. **動作確認セクション**に確認手順を追記 + - 既存の「動作確認」セクションがあれば、そこに追記 + - なければ新規作成 + +2. **トラブルシューティングセクション**に問題と解決方法を追記 + - 発見された問題は必ず記録 + - 解決コマンドは実行可能な形で記載 + +3. **プロジェクトステータスセクション**にタスク完了情報を更新 + - タスク完了時は自動的に更新される + +### 記録例 + +#### 動作確認セクションへの追加 +```markdown +### {サービス名}の検証 + +\`\`\`bash +# {確認項目の説明} +{確認コマンド} +\`\`\` + +**期待される結果**: {期待される出力や状態} +``` + +#### パフォーマンス基準の記録 +```markdown +### パフォーマンス基準 + +- 起動時間: {時間}秒以内 +- メモリ使用量: {サイズ}MB以内 +- レスポンスタイム: {時間}ms以内 +``` + +#### トラブルシューティングセクションへの追加 +```markdown +### {問題の概要} + +**症状**: {問題の詳細な説明} + +\`\`\`bash +# 問題の確認 +{確認コマンド} + +# 解決方法 +{解決コマンド} +\`\`\` + +**原因**: {問題の原因} +**解決**: {解決の説明} +``` + ## 出力フォーマット例 -````markdown + +```markdown # {TASK-ID} 設定確認・動作テスト ## 確認概要 @@ -82,7 +268,7 @@ DIRECTタスクで実行した設定作業の動作確認とテストを行い echo $NODE_ENV echo $DATABASE_URL ``` -```` +``` **確認結果**: @@ -297,131 +483,68 @@ jq '.port = 3000' config.json > temp.json && mv temp.json config.json - 関連するタスクの開始準備 - 必要に応じて設定の微調整 -```` - -## 実行後の確認 -- `docs/implements/{要件名}/{TASK-ID}/verify-report.md` ファイルが作成されていることを確認 -- 全ての確認項目が完了していることを確認 -- 問題が発見された場合は適切に対処されていることを確認 -- タスクの完了条件を満たしていることを確認 -- 次のタスクに進む準備が整っていることを確認 - -## ディレクトリ確認 - -`docs/implements/{要件名}/{TASK-ID}/` ディレクトリが存在することを確認してください（direct-setupで作成済みのはず） +## CLAUDE.mdへの記録内容 -## タスクの完了マーキング -品質チェックが十分で、全ての確認項目がクリアされた場合は、**自動的に**tasksディレクトリの該当するタスクファイルに完了マークを付けてください。 - -### 完了条件 -以下の条件を全て満たす場合にタスクを完了とマークします： -- [ ] 全ての設定確認項目がクリア -- [ ] コンパイル・構文チェックが成功（エラーがすべて解決済み） -- [ ] 全ての動作テストが成功 -- [ ] 品質チェック項目が基準を満たしている -- [ ] 発見された問題が適切に対処されている -- [ ] セキュリティ設定が適切 -- [ ] パフォーマンス基準を満たしている - -### 完了マークの付け方 -1. `docs/implements/{要件名}/{TASK-ID}/verify-report.md` で完了条件を確認 -2. 該当するタスクファイル（taskman-phase*.md）を特定 -3. タスクの完了状況を以下のように更新： - - `- [ ] **タスク完了**` → `- [x] **タスク完了** ✅ 完了 (YYYY-MM-DD)` - - 完了条件のチェックボックスも `[x]` に変更 -4. 必要に応じて進捗概要（taskman-overview.md）も更新 - -## README.mdの更新 -タスクが完了した場合、プロジェクトのルートディレクトリの `README.md` を作成または更新してください。 - -### 更新内容 -1. **現在のREADME.mdの確認**: 既存のREADME.mdがある場合は内容を確認 -2. **完了したタスクの情報を追加**: - - 実装した機能の概要 - - 設定手順 - - 動作確認方法 - - 使用方法 -3. **プロジェクト全体の情報を更新**: - - セットアップ手順 - - 依存関係 - - 環境要件 - - 開発・運用手順 - -### README.md更新フォーマット例 +### 更新対象 +- {サブプロジェクトのパス}/CLAUDE.md（サブプロジェクトがある場合） +- ./CLAUDE.md（単一プロジェクトの場合） +### 追加した情報 ```markdown -# プロジェクト名 - -## 概要 -{プロジェクトの概要} - -## 完了した機能 -### {TASK-ID}: {タスク名} -- **実装日**: {実装日} -- **概要**: {機能の概要} -- **設定内容**: {設定した内容} -- **動作確認**: {動作確認の結果} +## 開発コマンド -## セットアップ手順 -### 前提条件 -- {必要な環境・ツール} +### テスト実行 +\`\`\`bash +# すべてのテストを実行 +{実際に使用したテストコマンド} -### インストール -```bash -# 依存関係のインストール -{インストールコマンド} - -# 環境変数の設定 -{環境変数設定} -```` +# 特定のテストを実行 +{実際に使用した特定テスト実行コマンド} +\`\`\` -### 起動方法 +### アプリケーション実行 +\`\`\`bash +# 開発サーバー起動 +{実際に使用した起動コマンド} -```bash -# 開発サーバーの起動 -{起動コマンド} +# ビルド +{実際に使用したビルドコマンド} +\`\`\` ``` -## 設定 - -### 環境変数 +### 更新理由 +- {CLAUDE.mdに該当情報が存在しなかった/情報が古かった} +- 動作確認で必要となった最小限の実行方法を記録 -- `{環境変数名}`: {説明} - -### 設定ファイル - -- `{設定ファイルパス}`: {説明} - -## 使用方法 - -{使用方法の説明} - -## 開発 - -### 開発環境の準備 - -{開発環境の準備手順} - -### テスト - -{テストの実行方法} - -## トラブルシューティング - -### よくある問題 +``` + -- **問題**: {問題の内容} -- **解決方法**: {解決方法} +## 更新ファイルのフォーマット -## 更新履歴 +### Overview ファイルの更新フォーマット + +```markdown +# 進捗サマリー +## フェーズ1: {フェーズ名} +- [x] TASK-0001: {タスク名} ✅ 完了 (2025-11-03) +- [ ] TASK-0002: {タスク名} +``` + -- {日付}: {TASK-ID} {変更内容} +### タスク詳細ファイルの更新フォーマット + +```markdown +## TASK-0001: {タスク名} -``` +### ステータス +- **状態**: ✅ 完了 +- **完了日**: 2025-11-03 +- **実装者**: Claude -### 実行手順 -1. 現在のREADME.mdを確認（存在しない場合は新規作成） -2. 完了したタスクの情報を追加 -3. 必要に応じて他のセクションも更新 -4. 変更内容をコミット +### 完了条件 +- [x] 全ての設定確認項目がクリア +- [x] コンパイル・構文チェックが成功 +- [x] 全ての動作テストが成功 +- [x] 品質チェック項目が基準を満たしている ``` + diff --git a/commands/init-tech-stack.md b/commands/init-tech-stack.md index e810a0e..a3fda81 100644 --- a/commands/init-tech-stack.md +++ b/commands/init-tech-stack.md @@ -13,421 +13,442 @@ description: プロジェクトの初期設定として技術スタックの選 - プロジェクトルートディレクトリで実行 - `docs/` ディレクトリが存在する（なければ作成） -## 実行内容 +## 実行フロー -段階的なヒアリングを通じて技術選択を行い、最終的に `docs/tech-stack.md` を生成します。 +このコマンドは、**AskUserQuestionツール**を使用して段階的にヒアリングを行います。 -## ヒアリングフロー +### Phase 1: プロジェクト基本情報の収集 -### Phase 1: プロジェクト基本情報 +まず、以下の3つの質問をAskUserQuestionツールで同時に提示してください： -まず、プロジェクトの基本情報をお聞かせください。 - -#### 質問1: プロジェクトタイプ -以下から最も近いものを選択してください： - -1. **Webアプリケーション** - ブラウザで動作するアプリケーション -2. **モバイルアプリ** - スマートフォン/タブレット向けアプリ -3. **API/バックエンドサービス** - API提供がメインのサービス -4. **デスクトップアプリケーション** - PC向けネイティブアプリ -5. **ライブラリ/SDK** - 他の開発者向けのツール -6. **フルスタック（Web + API）** - フロントエンドとバックエンドの両方 -7. **その他** - 上記以外 - -**あなたの選択**: [ユーザー入力を待つ] - ---- - -#### 質問2: プロジェクト規模 -開発チームの規模を教えてください： - -1. **個人開発** - 1人で開発 -2. **小規模チーム** - 2-5人 -3. **中規模チーム** - 6-15人 -4. **大規模チーム** - 16人以上 - -**あなたの選択**: [ユーザー入力を待つ] - ---- - -#### 質問3: 開発期間 -予定している開発期間はどの程度ですか？ - -1. **プロトタイプ/MVP** - 1-2ヶ月 -2. **短期プロジェクト** - 3-6ヶ月 -3. **中期プロジェクト** - 6ヶ月-1年 -4. **長期プロジェクト** - 1年以上 - -**あなたの選択**: [ユーザー入力を待つ] - ---- - -### Phase 2: 技術制約・要件 - -#### 質問4: 既存システム連携 -既存のシステムやデータベースとの連携はありますか？ - -1. **新規構築** - 全て新しく作成 -2. **既存DB連携あり** - 既存データベースを使用 -3. **既存API連携あり** - 既存のAPIと連携 -4. **レガシーシステム移行** - 既存システムからの移行 -5. **その他連携要件あり** - 具体的に教えてください - -**あなたの選択**: [ユーザー入力を待つ] - -**既存技術がある場合は具体的に**: [ユーザー入力を待つ] - ---- - -#### 質問5: パフォーマンス要件 -想定される負荷や性能要件を教えてください： - -1. **軽負荷** - 同時利用者数10人以下、レスポンス時間3秒以内 -2. **中負荷** - 同時利用者数100人程度、レスポンス時間1秒以内 -3. **高負荷** - 同時利用者数1000人以上、レスポンス時間0.5秒以内 -4. **未定/不明** - まだ詳細は決まっていない - -**あなたの選択**: [ユーザー入力を待つ] - ---- - -#### 質問6: セキュリティ要件 -セキュリティの重要度を教えてください： - -1. **基本的なセキュリティ** - 一般的なWebセキュリティ対策 -2. **高度なセキュリティ** - 個人情報取り扱い、金融系など -3. **エンタープライズレベル** - 企業向け、コンプライアンス要件あり -4. **未定/不明** - まだ詳細は決まっていない - -**あなたの選択**: [ユーザー入力を待つ] - ---- - -### Phase 3: チーム・スキル状況 - -#### 質問7: チームの技術スキル -チームメンバーの技術経験を教えてください（複数選択可）： - -1. **JavaScript/TypeScript** - 経験豊富 -2. **Python** - 経験豊富 -3. **Java/Kotlin** - 経験豊富 -4. **C#/.NET** - 経験豊富 -5. **PHP** - 経験豊富 -6. **Go/Rust** - 経験豊富 -7. **React/Vue/Angular** - 経験豊富 -8. **データベース設計** - 経験豊富 -9. **クラウド（AWS/Azure/GCP）** - 経験豊富 -10. **Docker/Kubernetes** - 経験豊富 -11. **技術スキルは限定的** - 学習しながら進めたい - -**あなたの選択（複数可）**: [ユーザー入力を待つ] - ---- - -#### 質問8: 学習コスト許容度 -新しい技術の習得についてどう考えますか？ - -1. **積極的に新技術を導入したい** - 最新技術でチャレンジしたい -2. **バランス重視** - 新技術と安定技術のバランスを取りたい -3. **安定技術優先** - 枯れた技術で確実に開発したい -4. **既存スキル活用** - チームが知っている技術を最大限活用したい - -**あなたの選択**: [ユーザー入力を待つ] - ---- +``` +AskUserQuestion({ + questions: [ + { + question: "プロジェクトのタイプを教えてください", + header: "プロジェクト", + multiSelect: false, + options: [ + { label: "Webアプリケーション", description: "ブラウザで動作するアプリケーション" }, + { label: "モバイルアプリ", description: "スマートフォン/タブレット向けアプリ" }, + { label: "API/バックエンド", description: "API提供がメインのサービス" }, + { label: "デスクトップアプリ", description: "PC向けネイティブアプリ" }, + { label: "ライブラリ/SDK", description: "他の開発者向けのツール" }, + { label: "フルスタック", description: "フロントエンドとバックエンドの両方" } + ] + }, + { + question: "開発チームの規模を教えてください", + header: "チーム規模", + multiSelect: false, + options: [ + { label: "個人開発", description: "1人で開発" }, + { label: "小規模チーム", description: "2-5人" }, + { label: "中規模チーム", description: "6-15人" }, + { label: "大規模チーム", description: "16人以上" } + ] + }, + { + question: "予定している開発期間はどの程度ですか？", + header: "開発期間", + multiSelect: false, + options: [ + { label: "プロトタイプ/MVP", description: "1-2ヶ月" }, + { label: "短期プロジェクト", description: "3-6ヶ月" }, + { label: "中期プロジェクト", description: "6ヶ月-1年" }, + { label: "長期プロジェクト", description: "1年以上" } + ] + } + ] +}) +``` -### Phase 4: 運用・インフラ要件 +### Phase 2: 技術制約・要件の収集 -#### 質問9: デプロイ・ホスティング -アプリケーションをどこで動かす予定ですか？ +次に、以下の3つの質問をAskUserQuestionツールで同時に提示してください： -1. **クラウド（AWS/Azure/GCP）** - パブリッククラウド -2. **PaaS（Vercel/Netlify/Heroku）** - 簡単デプロイ重視 -3. **VPS/専用サーバー** - 自前サーバー -4. **オンプレミス** - 社内サーバー -5. **未定** - まだ決まっていない +``` +AskUserQuestion({ + questions: [ + { + question: "既存のシステムやデータベースとの連携はありますか？", + header: "既存連携", + multiSelect: false, + options: [ + { label: "新規構築", description: "全て新しく作成" }, + { label: "既存DB連携", description: "既存データベースを使用" }, + { label: "既存API連携", description: "既存のAPIと連携" }, + { label: "レガシー移行", description: "既存システムからの移行" } + ] + }, + { + question: "想定される負荷や性能要件を教えてください", + header: "パフォーマンス", + multiSelect: false, + options: [ + { label: "軽負荷", description: "同時利用者数10人以下、レスポンス3秒以内" }, + { label: "中負荷", description: "同時利用者数100人程度、レスポンス1秒以内" }, + { label: "高負荷", description: "同時利用者数1000人以上、レスポンス0.5秒以内" }, + { label: "未定/不明", description: "まだ詳細は決まっていない" } + ] + }, + { + question: "セキュリティの重要度を教えてください", + header: "セキュリティ", + multiSelect: false, + options: [ + { label: "基本レベル", description: "一般的なWebセキュリティ対策" }, + { label: "高度", description: "個人情報取り扱い、金融系など" }, + { label: "エンタープライズ", description: "企業向け、コンプライアンス要件あり" }, + { label: "未定/不明", description: "まだ詳細は決まっていない" } + ] + } + ] +}) +``` -**あなたの選択**: [ユーザー入力を待つ] +### Phase 3: チーム・スキル状況の収集 ---- +次に、以下の2つの質問をAskUserQuestionツールで同時に提示してください： -#### 質問10: 予算制約 -開発・運用コストについて教えてください： +``` +AskUserQuestion({ + questions: [ + { + question: "チームメンバーの技術経験を教えてください（複数選択可）", + header: "技術スキル", + multiSelect: true, + options: [ + { label: "JavaScript/TypeScript", description: "経験豊富" }, + { label: "Python", description: "経験豊富" }, + { label: "Java/Kotlin", description: "経験豊富" }, + { label: "C#/.NET", description: "経験豊富" }, + { label: "Go/Rust", description: "経験豊富" }, + { label: "React/Vue/Angular", description: "経験豊富" }, + { label: "データベース設計", description: "経験豊富" }, + { label: "クラウド(AWS/Azure/GCP)", description: "経験豊富" }, + { label: "Docker/Kubernetes", description: "経験豊富" }, + { label: "技術スキル限定的", description: "学習しながら進めたい" } + ] + }, + { + question: "新しい技術の習得についてどう考えますか？", + header: "学習コスト", + multiSelect: false, + options: [ + { label: "積極的に新技術", description: "最新技術でチャレンジしたい" }, + { label: "バランス重視", description: "新技術と安定技術のバランス" }, + { label: "安定技術優先", description: "枯れた技術で確実に開発" }, + { label: "既存スキル活用", description: "チームの知識を最大限活用" } + ] + } + ] +}) +``` -1. **コスト最小化** - 無料・低コストツール優先 -2. **バランス重視** - 適度なコストは許容 -3. **品質重視** - コストより品質・効率を優先 -4. **予算潤沢** - 最適なツールを選択可能 +### Phase 4: 運用・インフラ要件の収集 -**あなたの選択**: [ユーザー入力を待つ] +最後に、以下の2つの質問をAskUserQuestionツールで同時に提示してください： ---- +``` +AskUserQuestion({ + questions: [ + { + question: "アプリケーションをどこで動かす予定ですか？", + header: "ホスティング", + multiSelect: false, + options: [ + { label: "クラウド", description: "AWS/Azure/GCP" }, + { label: "PaaS", description: "Vercel/Netlify/Heroku" }, + { label: "VPS/専用サーバー", description: "自前サーバー" }, + { label: "オンプレミス", description: "社内サーバー" }, + { label: "未定", description: "まだ決まっていない" } + ] + }, + { + question: "開発・運用コストについて教えてください", + header: "予算制約", + multiSelect: false, + options: [ + { label: "コスト最小化", description: "無料・低コストツール優先" }, + { label: "バランス重視", description: "適度なコストは許容" }, + { label: "品質重視", description: "コストより品質・効率を優先" }, + { label: "予算潤沢", description: "最適なツールを選択可能" } + ] + } + ] +}) +``` ## 技術スタック推奨ロジック -### 推奨アルゴリズム +全ての回答を収集した後、以下のロジックで技術を推奨してください： -ユーザーの回答に基づいて以下のロジックで技術を推奨： +### フロントエンド選択ロジック -#### フロントエンド選択 ``` IF プロジェクトタイプ == "Webアプリケーション" OR "フルスタック" IF チーム経験に "React/Vue/Angular" あり - IF 学習コスト許容度 == "積極的" - 推奨: React 18 + TypeScript (最新技術) + IF 学習コスト許容度 == "積極的に新技術" + 推奨: React 19 + TypeScript 5.7+ + Vite 6 (最新技術) ELSE - 推奨: React 18 + JavaScript (安定性重視) - ELSE IF JavaScript経験あり - 推奨: Vue 3 + TypeScript (学習コスト低) + 推奨: React 18.3 + TypeScript 5.7+ + Vite 6 (安定性重視) + ELSE IF "JavaScript/TypeScript" 経験あり + 推奨: Vue 3.5+ + TypeScript 5.7+ + Vite 6 (学習コスト低) ELSE - 推奨: Next.js (フルスタック簡単) + 推奨: Next.js 15 + TypeScript 5.7+ (フルスタック簡単) ``` -#### バックエンド選択 +### バックエンド選択ロジック + ``` -IF JavaScript経験豊富 - 推奨: Node.js + Express/Fastify -ELSE IF Python経験豊富 - 推奨: FastAPI/Django -ELSE IF 他言語経験豊富 - その言語のフレームワーク推奨 +IF "JavaScript/TypeScript" 経験豊富 + IF 学習コスト許容度 == "積極的に新技術" + 推奨: Node.js 22 LTS + Fastify 5 + TypeScript 5.7+ (高速) + ELSE + 推奨: Node.js 22 LTS + Express 5 + TypeScript 5.7+ (安定) +ELSE IF "Python" 経験豊富 + IF パフォーマンス要件 == "高負荷" + 推奨: FastAPI 0.115+ (Python 3.12+) (高速API) + ELSE + 推奨: Django 5.1+ (Python 3.12+) (フルフィーチャー) +ELSE IF "Java/Kotlin" 経験豊富 + 推奨: Spring Boot 3.4+ (Kotlin 2.1+, Java 21+) +ELSE IF "C#/.NET" 経験豊富 + 推奨: ASP.NET Core 9 (.NET 9) +ELSE IF "Go/Rust" 経験豊富 + 推奨: Go 1.23+ (Gin 1.10+ / Fiber 3) または Rust 1.83+ (Actix-web 4) ELSE - 推奨: Node.js (フロントエンドとの統一) + 推奨: Node.js 22 LTS + Express 5 (フロントエンドとの統一) ``` -#### データベース選択 +### データベース選択ロジック + ``` IF パフォーマンス要件 == "高負荷" - 推奨: PostgreSQL + Redis -ELSE IF セキュリティ要件 == "高度" - 推奨: PostgreSQL -ELSE IF プロジェクト規模 == "個人" OR "小規模" - 推奨: SQLite → PostgreSQL (段階移行) + 推奨: PostgreSQL 17+ + Redis 7.4+ (スケーラビリティ) +ELSE IF セキュリティ要件 == "高度" OR "エンタープライズ" + 推奨: PostgreSQL 17+ (ACID準拠、堅牢) +ELSE IF プロジェクト規模 == "個人開発" AND 開発期間 == "プロトタイプ/MVP" + 推奨: SQLite 3.47+ → PostgreSQL 17+ (段階移行) ELSE - 推奨: PostgreSQL + 推奨: PostgreSQL 17+ (汎用的) ``` -### 推奨結果表示 +### 開発環境・ツール選択ロジック -各フェーズの回答後、ライブラリの最新バージョンやLTS版を検索して、以下の形式で推奨結果を表示： +``` +コンテナ: + 推奨: Docker 27+ + Docker Compose v2 (全プロジェクト共通) + +パッケージマネージャー: +IF 言語 == "Python" + 推奨: uv (最速・モダン) +ELSE IF 言語 == "Node.js/TypeScript" + 推奨: pnpm 9+ (高速・ディスク効率) +ELSE IF 言語 == "Java/Kotlin" + 推奨: Gradle 8.12+ (Kotlin DSL) + +テストツール: +IF フロントエンド == React系 AND ビルドツール == Vite + 推奨: Vitest 2+ + Testing Library (高速統合) +ELSE IF フロントエンド == Vue系 + 推奨: Vitest 2+ + Vue Test Utils +ELSE IF バックエンド == Python + 推奨: pytest 8+ + pytest-asyncio +ELSE IF バックエンド == Java/Kotlin + 推奨: JUnit 5 + Kotest + +E2Eテスト: + 推奨: Playwright 1.49+ (全言語対応・高速・信頼性高) + +リンター・フォーマッター: +IF 言語 == "Python" + 推奨: Ruff 0.8+ (最速オールインワン) +ELSE IF 言語 == "TypeScript/JavaScript" + 推奨: Biome 1.9+ (最速) または ESLint 9+ + Prettier 3+ +ELSE IF 言語 == "Kotlin" + 推奨: ktlint 1.5+ + detekt 1.23+ +``` + +## 推奨結果の表示 + +全ての回答に基づいて、以下の形式で推奨結果をマークダウンで表示してください： ```markdown # あなたの回答に基づく技術スタック推奨 ## 📋 回答サマリー -- プロジェクトタイプ: Webアプリケーション -- 規模: 小規模チーム（3人） -- 期間: 中期プロジェクト（8ヶ月） -- 技術スキル: JavaScript/TypeScript経験豊富 -- 学習コスト許容度: バランス重視 +- プロジェクトタイプ: [回答] +- チーム規模: [回答] +- 開発期間: [回答] +- 既存連携: [回答] +- パフォーマンス: [回答] +- セキュリティ: [回答] +- 技術スキル: [回答（複数の場合はカンマ区切り）] +- 学習コスト許容度: [回答] +- ホスティング: [回答] +- 予算: [回答] ## 🚀 推奨技術スタック ### フロントエンド -✅ **React 18 + TypeScript** - - 理由: チームのReact経験を活かせます - - メリット: 豊富なエコシステム、求人市場での優位性 - - 学習コスト: 中（既存経験あり） +✅ **[推奨技術]** + - 理由: [選択理由] + - メリット: [メリット] + - 学習コスト: [低/中/高] -⚠️ **Vue 3 + TypeScript** （代替案） - - 理由: より学習コストが低い - - メリット: シンプルな構文、段階的導入可能 - - 学習コスト: 低 - -❌ **Angular** （非推奨） - - 理由: 中期プロジェクトには重すぎる - - デメリット: 学習コスト高、小規模チームに不向き +⚠️ **[代替案]** （代替案） + - 理由: [選択理由] + - メリット: [メリット] + - 学習コスト: [低/中/高] ### バックエンド -✅ **Node.js + Express + TypeScript** - - 理由: フロントエンドとの言語統一 - - メリット: 開発効率、人材リソースの有効活用 - - 学習コスト: 低（既存JavaScript経験） +✅ **[推奨技術]** + - 理由: [選択理由] + - メリット: [メリット] + - 学習コスト: [低/中/高] ### データベース -✅ **PostgreSQL** - - 理由: 中期プロジェクトの成長に対応 - - メリット: ACID準拠、拡張性、JSON対応 - - 学習コスト: 中 - -✅ **Redis** （キャッシュ） - - 理由: パフォーマンス向上 - - メリット: セッション管理、高速キャッシュ - - 学習コスト: 低 - -### 開発環境 -✅ **Docker + Docker Compose** - - 理由: 環境統一、デプロイ簡素化 - - メリット: 開発環境の一貫性 - - 学習コスト: 中 - -✅ **Jest + Testing Library** - - 理由: React標準、TypeScript親和性 - - メリット: 豊富なドキュメント - - 学習コスト: 低 - -## ⚙️ 整合性チェック +✅ **[推奨技術]** + - 理由: [選択理由] + - メリット: [メリット] + - 学習コスト: [低/中/高] -✅ **技術選択の整合性**: 問題なし -- React + Node.js: 言語統一によるシナジー効果 -- TypeScript: フロント・バック全体での型安全性 -- PostgreSQL: 将来の成長に対応可能 +### 開発環境・ツール +✅ **[コンテナ技術]** +✅ **[テストツール]** +✅ **[E2Eテスト]** +✅ **[リンター・フォーマッター]**: ESLint + Prettier -✅ **チームスキルとのマッチング**: 良好 -- 既存JavaScript/TypeScript経験を最大活用 -- 学習が必要な新技術は最小限 - -✅ **プロジェクト要件との適合性**: 適合 -- 中期プロジェクト向けの拡張性 -- 小規模チームでの管理容易性 +## ⚙️ 整合性チェック -この推奨で進めますか？ +✅ **技術選択の整合性**: [問題なし/要確認] +- [整合性の説明] -1. **はい** - この推奨で `docs/tech-stack.md` を生成 -2. **一部変更したい** - 個別技術を調整 -3. **全体的に見直したい** - ヒアリングからやり直し +✅ **チームスキルとのマッチング**: [良好/要学習あり] +- [マッチング状況の説明] -**あなたの選択**: [ユーザー入力を待つ] +✅ **プロジェクト要件との適合性**: [適合/一部要調整] +- [適合性の説明] ``` -## カスタマイズ対応 - -「一部変更したい」を選択された場合： - -```markdown -# 技術スタックのカスタマイズ - -どの部分を変更しますか？ - -1. **フロントエンド** (現在: React 18 + TypeScript) -2. **バックエンド** (現在: Node.js + Express + TypeScript) -3. **データベース** (現在: PostgreSQL + Redis) -4. **開発環境・ツール** (現在: Docker, Jest等) -5. **全て確認して個別調整** - -**選択**: [ユーザー入力を待つ] - ---- - -## フロントエンドの変更 - -現在の推奨: **React 18 + TypeScript** - -利用可能な選択肢： +## 最終確認 -1. **React 18 + TypeScript** ⭐ (現在の推奨) -2. **React 18 + JavaScript** - TypeScriptを使わない場合 -3. **Vue 3 + TypeScript** - より軽量なフレームワーク -4. **Vue 3 + JavaScript** - 最も学習コストが低い -5. **Next.js + TypeScript** - フルスタックフレームワーク -6. **Svelte/SvelteKit** - 新しいアプローチ -7. **Angular + TypeScript** - エンタープライズ向け -8. **Vanilla JavaScript + TypeScript** - フレームワークなし -9. **その他** - 具体的に指定 +推奨結果を表示した後、以下の質問をAskUserQuestionツールで提示してください： -**あなたの選択**: [ユーザー入力を待つ] - -**選択理由があれば**: [ユーザー入力を待つ] ``` - -## 最終生成処理 - -最終確認後、以下の処理を実行： - -1. **ディレクトリ作成** -```bash -mkdir -p docs +AskUserQuestion({ + questions: [ + { + question: "この推奨で進めますか？", + header: "最終確認", + multiSelect: false, + options: [ + { label: "はい", description: "この推奨でdocs/tech-stack.mdを生成" }, + { label: "一部変更したい", description: "個別技術を調整" }, + { label: "やり直し", description: "ヒアリングからやり直す" } + ] + } + ] +}) ``` -2. **`docs/tech-stack.md` 生成** +### 「はい」を選択された場合 -生成されるファイル例： +`docs/tech-stack.md` ファイルを生成してください。テンプレートは以下の通り： ```markdown # プロジェクト技術スタック定義 ## 🔧 生成情報 -- **生成日**: 2025-01-08 -- **生成ツール**: init-tech-stack.md -- **プロジェクトタイプ**: Webアプリケーション -- **チーム規模**: 小規模チーム（3人） -- **開発期間**: 中期プロジェクト（8ヶ月） +- **生成日**: [YYYY-MM-DD] +- **生成ツール**: init-tech-stack +- **プロジェクトタイプ**: [回答] +- **チーム規模**: [回答] +- **開発期間**: [回答] ## 🎯 プロジェクト要件サマリー -- **パフォーマンス**: 中負荷（同時利用者数100人程度） -- **セキュリティ**: 基本的なWebセキュリティ対策 -- **技術スキル**: JavaScript/TypeScript経験豊富 -- **学習コスト許容度**: バランス重視 -- **デプロイ先**: クラウド（AWS/Azure/GCP） -- **予算**: バランス重視 +- **パフォーマンス**: [回答] +- **セキュリティ**: [回答] +- **技術スキル**: [回答] +- **学習コスト許容度**: [回答] +- **デプロイ先**: [回答] +- **予算**: [回答] ## 🚀 フロントエンド -- **フレームワーク**: React 18.2 -- **言語**: TypeScript 5.0+ -- **状態管理**: Redux Toolkit -- **UIライブラリ**: Material-UI v5 -- **バンドラー**: Vite -- **ルーティング**: React Router v6 +- **フレームワーク**: [技術名とバージョン] +- **言語**: [言語とバージョン] +- **状態管理**: [選択されたツール] +- **バンドラー**: [選択されたツール] +- **ルーティング**: [選択されたツール] ### 選択理由 -- チームのReact経験を活かせる -- TypeScriptで型安全性を確保 -- Material-UIで開発速度向上 -- Viteで高速な開発環境 +- [理由1] +- [理由2] +- [理由3] ## ⚙️ バックエンド -- **フレームワーク**: Express.js 4.18 -- **言語**: TypeScript 5.0+ -- **データベース**: PostgreSQL 15 -- **ORM**: Prisma -- **認証**: JWT + Refresh Token -- **キャッシュ**: Redis 7+ +- **フレームワーク**: [技術名とバージョン] +- **言語**: [言語とバージョン] +- **データベース**: [データベース名とバージョン] +- **ORM**: [選択されたツール] +- **認証**: [選択された方式] +- **キャッシュ**: [選択されたツール（必要な場合）] ### 選択理由 -- フロントエンドとの言語統一 -- Prismaで型安全なDB操作 -- PostgreSQLで将来のスケーリングに対応 -- Redisでセッション管理とキャッシュ +- [理由1] +- [理由2] +- [理由3] ## 💾 データベース設計 -- **メインDB**: PostgreSQL 15+ -- **キャッシュ**: Redis 7+ -- **ファイルストレージ**: AWS S3 / Azure Blob (本番), ローカル (開発) +- **メインDB**: [データベース名とバージョン] +- **キャッシュ**: [キャッシュツール（必要な場合）] +- **ファイルストレージ**: [ストレージ戦略] ### 設計方針 -- ACID準拠のトランザクション -- JSON型でNoSQL的な柔軟性も確保 -- インデックス戦略でクエリ最適化 -- 適切な正規化レベル +- [方針1] +- [方針2] +- [方針3] ## 🛠️ 開発環境 - **コンテナ**: Docker + Docker Compose -- **パッケージマネージャー**: npm -- **Node.js**: 18+ LTS +- **パッケージマネージャー**: + - Python: uv (高速・モダン) + - Node.js: pnpm (高速・ディスク効率) + - Java/Kotlin: Gradle (Kotlin DSL) +- **ランタイムバージョン**: [バージョン情報] ### 開発ツール -- **テストフレームワーク**: Jest -- **テストライブラリ**: React Testing Library -- **E2Eテスト**: Playwright -- **リンター**: ESLint + Prettier -- **型チェック**: TypeScript +- **テストフレームワーク**: + - Python: pytest + pytest-asyncio + - TypeScript/JavaScript: Vitest (Vite使用時) / Jest (その他) + - Java/Kotlin: JUnit 5 + Kotest +- **E2Eテスト**: Playwright (全言語対応・高速・信頼性高) +- **リンター・フォーマッター**: + - Python: Ruff (高速・オールインワン) + - TypeScript/JavaScript: Biome (高速) / ESLint + Prettier + - Java/Kotlin: ktlint + detekt +- **型チェック**: + - Python: mypy + - TypeScript: tsc (TypeScript Compiler) ### CI/CD -- **CI/CD**: GitHub Actions -- **コード品質**: ESLint, Prettier, TypeScript +- **CI/CD**: GitHub Actions (推奨) +- **コード品質**: ESLint, Prettier, [型チェック] - **テスト**: Unit, Integration, E2E - **デプロイ**: 自動デプロイ with approval ## ☁️ インフラ・デプロイ -- **フロントエンド**: Vercel / Netlify -- **バックエンド**: AWS ECS / Azure Container Apps -- **データベース**: AWS RDS / Azure Database -- **キャッシュ**: AWS ElastiCache / Azure Cache -- **CDN**: CloudFlare / AWS CloudFront +- **フロントエンド**: [デプロイ先] +- **バックエンド**: [デプロイ先] +- **データベース**: [DBホスティング] +- **キャッシュ**: [キャッシュホスティング（該当する場合）] +- **CDN**: [CDNサービス（該当する場合）] ## 🔒 セキュリティ - **HTTPS**: 必須 (証明書自動更新) -- **認証**: JWT + Refresh Token +- **認証**: [認証方式] - **CORS**: 適切な設定 - **バリデーション**: サーバーサイドバリデーション - **環境変数**: 機密情報の適切な管理 @@ -436,79 +457,73 @@ mkdir -p docs ## 📊 品質基準 - **テストカバレッジ**: 80%以上 - **コード品質**: ESLint + Prettier -- **型安全性**: TypeScript strict mode -- **パフォーマンス**: Lighthouse 90+点 -- **アクセシビリティ**: WCAG 2.1 AA準拠 +- **型安全性**: [型安全性要件] +- **パフォーマンス**: Lighthouse 90+点（Web系の場合） +- **アクセシビリティ**: WCAG 2.1 AA準拠（Web系の場合） ## 📁 推奨ディレクトリ構造 ``` -project-root/ -├── frontend/ # React アプリケーション +./ (カレントディレクトリ = プロジェクトルート) +├── frontend/ # フロントエンド │ ├── src/ -│ │ ├── components/ # 再利用可能コンポーネント +│ │ ├── components/ # Reactコンポーネント │ │ ├── pages/ # ページコンポーネント │ │ ├── hooks/ # カスタムフック -│ │ ├── store/ # Redux store -│ │ ├── types/ # 型定義 -│ │ └── utils/ # ユーティリティ +│ │ ├── utils/ # ユーティリティ関数 +│ │ ├── types/ # TypeScript型定義 +│ │ ├── api/ # APIクライアント +│ │ └── App.tsx │ ├── public/ # 静的ファイル +│ ├── tests/ # テスト │ ├── package.json -│ └── vite.config.ts -├── backend/ # Express API -│ ├── src/ -│ │ ├── controllers/ # API コントローラー +│ ├── tsconfig.json +│ ├── vite.config.ts # or next.config.js +│ └── tailwind.config.js +├── backend/ # バックエンド +│ ├── app/ # (Python/FastAPI/Djangoの場合) +│ │ ├── main.py # エントリポイント +│ │ ├── api/ # APIルート +│ │ │ └── v1/ +│ │ ├── core/ # 設定・セキュリティ +│ │ ├── models/ # ORMモデル +│ │ ├── schemas/ # スキーマ定義 │ │ ├── services/ # ビジネスロジック -│ │ ├── models/ # データモデル -│ │ ├── middleware/ # Express ミドルウェア -│ │ ├── routes/ # API ルート定義 -│ │ ├── types/ # 型定義 +│ │ ├── db/ # データベース接続 │ │ └── utils/ # ユーティリティ -│ ├── prisma/ # データベーススキーマ -│ ├── tests/ # テストファイル -│ ├── package.json -│ └── tsconfig.json -├── docs/ # プロジェクトドキュメント -├── docker-compose.yml # 開発環境 -└── README.md # プロジェクト概要 +│ ├── src/ # (Node.js/Java/Kotlin/Go等の場合) +│ │ └── ... +│ ├── tests/ # テスト +│ ├── migrations/ # DBマイグレーション +│ ├── pyproject.toml # (Python) or package.json (Node.js) or build.gradle.kts (Kotlin) +│ └── Dockerfile +├── docker-compose.yml # Docker構成 +├── .github/ +│ └── workflows/ # GitHub Actions +│ ├── ci.yml +│ └── deploy.yml +├── docs/ # ドキュメント +│ ├── tech-stack.md # このファイル +│ ├── requirements/ # 要件定義書 +│ ├── design/ # 設計書 +│ └── tasks/ # タスク管理 +├── .env.example # 環境変数テンプレート +├── .gitignore +└── README.md ``` +**重要**: 上記の `./` はカレントディレクトリ（現在作業中のディレクトリ）を指します。新しいディレクトリを作成するのではなく、既存のプロジェクトルートに直接配置してください。 + ## 🚀 セットアップ手順 ### 1. 開発環境準備 ```bash -# Docker環境起動 -docker-compose up -d - -# フロントエンド セットアップ -cd frontend -npm install -npm run dev - -# バックエンド セットアップ -cd backend -npm install -npx prisma migrate dev -npm run dev +[セットアップコマンド] ``` ### 2. 主要コマンド ```bash -# 開発サーバー起動 -npm run dev # フロントエンド -npm run dev:api # バックエンド - -# テスト実行 -npm test # 単体テスト -npm run test:e2e # E2Eテスト - -# ビルド -npm run build # 本番ビルド -npm run preview # ビルド確認 - -# データベース -npx prisma studio # DB管理画面 -npx prisma generate # クライアント生成 +[開発に必要な主要コマンド] ``` ## 📝 カスタマイズ方法 @@ -516,58 +531,88 @@ npx prisma generate # クライアント生成 このファイルはプロジェクトの進行に応じて更新してください： 1. **技術の追加**: 新しいライブラリ・ツールを追加 -2. **要件の変更**: パフォーマンス・セキュリティ要件の更新 +2. **要件の変更**: パフォーマンス・セキュリティ要件の更新 3. **インフラの変更**: デプロイ先・スケール要件の変更 4. **チーム変更**: メンバー増減に応じた技術選択の見直し ## 🔄 更新履歴 -- 2025-01-08: 初回生成 (init-tech-stack.mdにより自動生成) +- [生成日]: 初回生成 (init-tech-stackにより自動生成) ``` -3. **確認メッセージ表示** +生成後、以下の確認メッセージを表示してください： ```markdown ✅ 技術スタック定義ファイルを生成しました！ 📄 **生成ファイル**: `docs/tech-stack.md` -📊 **技術数**: フロントエンド6技術、バックエンド6技術、開発環境8ツール 🎯 **推奨理由**: チーム経験との適合性、プロジェクト要件への最適化 ## 次のステップ 1. **ファイル確認**: `docs/tech-stack.md` の内容を確認 -2. **カスタマイズ**: 必要に応じて技術選択を微調整 +2. **カスタマイズ**: 必要に応じて技術選択を微調整 3. **チーム共有**: 技術選択をチームで合意 4. **開発開始**: 他のkairo-*コマンドで要件定義・設計に進む -## 技術スタック更新 +このファイルは他の全てのコマンド（kairo-*, tdd-*, direct-*）で自動参照されます。 +``` -技術選択を変更する場合は： -- `docs/tech-stack.md` を直接編集 -- または `init-tech-stack.md` を再実行 +### 「一部変更したい」を選択された場合 + +以下の質問をAskUserQuestionツールで提示してください： -このファイルは他の全てのコマンド（kairo-*, tdd-*, direct-*）で自動参照されます。 ``` +AskUserQuestion({ + questions: [ + { + question: "どの部分を変更しますか？", + header: "カスタマイズ", + multiSelect: true, + options: [ + { label: "フロントエンド", description: "現在: [推奨技術]" }, + { label: "バックエンド", description: "現在: [推奨技術]" }, + { label: "データベース", description: "現在: [推奨技術]" }, + { label: "開発環境・ツール", description: "現在: [推奨技術]" } + ] + } + ] +}) +``` + +選択された部分について、個別に詳細な選択肢を提示し、調整後に再度最終確認を行ってください。 + +### 「やり直し」を選択された場合 + +Phase 1から再度ヒアリングを開始してください。 ## エラーハンドリング -```markdown -## よくある問題と解決方法 - -### ❌ ファイル作成エラー -**原因**: `docs/` ディレクトリへの書き込み権限なし -**解決**: `mkdir -p docs && chmod 755 docs` - -### ❌ 既存ファイル上書き警告 -**原因**: `docs/tech-stack.md` が既に存在 -**選択肢**: -1. 上書きする -2. バックアップを作成してから上書き -3. 別名で保存（例：`tech-stack-new.md`） - -### ❌ 推奨技術が見つからない -**原因**: 特殊な技術要件や制約 -**対処**: カスタマイズモードで手動選択 +### 既存ファイルの扱い + +`docs/tech-stack.md` が既に存在する場合、以下の質問をAskUserQuestionツールで提示してください： + +``` +AskUserQuestion({ + questions: [ + { + question: "docs/tech-stack.mdが既に存在します。どうしますか？", + header: "既存ファイル", + multiSelect: false, + options: [ + { label: "上書き", description: "既存ファイルを上書きする" }, + { label: "バックアップして上書き", description: "既存ファイルを.bakとして保存" }, + { label: "別名で保存", description: "tech-stack-new.mdとして保存" }, + { label: "キャンセル", description: "処理を中止する" } + ] + } + ] +}) ``` -このように、段階的なヒアリングとインテリジェントな推奨機能により、プロジェクトに最適な技術スタック定義が自動生成される仕組みを作成しました。 \ No newline at end of file +## 重要な注意事項 + +1. **AskUserQuestionツールの使用**: 全ての質問はAskUserQuestionツールを使用して提示してください +2. **並列質問**: 関連する質問は同時に提示して効率化してください +3. **回答の保存**: ユーザーの回答は全て保存し、最終的なファイル生成に使用してください +4. **最新バージョン確認**: 技術スタックを推奨する際は、可能な限り最新の安定版バージョンを推奨してください +5. **整合性確認**: 推奨する技術スタック間の整合性を必ず確認してください diff --git a/commands/kairo-design.md b/commands/kairo-design.md index 119868d..06e7482 100644 --- a/commands/kairo-design.md +++ b/commands/kairo-design.md @@ -1,240 +1,1556 @@ --- description: 承認された要件定義書に基づいて、技術設計文書を生成する。データフロー図、TypeScriptインターフェース、データベーススキーマ、APIエンドポイントを含む包括的な設計を行います。 +allowed-tools: Read, Glob, Grep, Task, Write, Edit, TodoWrite, WebFetch, AskUserQuestion +argument-hint: [要件名] --- +Kairo開発の技術設計を実施し、PRD・EARS要件定義書・既存設計文書を参照しながら技術仕様を明確化します。信頼性レベルを示しながら設計文書を作成します。 -# kairo-design +# context -## 目的 +出力ディレクトリ="docs/design" +要件名={{requirement_name}} +作業規模={{work_scope}} +信頼性評価=[] -承認された要件定義書に基づいて、技術設計文書を生成する。データフロー図、TypeScriptインターフェース、データベーススキーマ、APIエンドポイントを含む包括的な設計を行う。 +# step -## 前提条件 +- $ARGUMENTS がない場合、「引数に要件名を指定してください（例: ユーザー認証システム）」と言って終了する +- $ARGUMENTS の内容と context の内容をまとめてユーザに宣言する +- step2 を実行する -- `docs/spec/` に要件定義書が存在する -- 要件がユーザによって承認されている +## step2: 作業規模の確認 -## 事前準備 +- AskUserQuestion ツールを使って作業規模を質問する： + - question: "この設計の作業規模について教えてください" + - header: "設計規模" + - multiSelect: false + - options: + - label: "フル設計（推奨）" + description: "包括的なアーキテクチャ設計、詳細なデータフロー、完全な型定義、DBスキーマ、API仕様を含む" + - label: "軽量設計" + description: "必要最小限の設計、基本的なアーキテクチャとデータフロー、主要な型定義のみ" + - label: "カスタム" + description: "含めたい設計項目を個別に選択" -1. **追加ルールの読み込み** - - `docs/rule` ディレクトリが存在する場合は読み込み - - `docs/rule/kairo` ディレクトリが存在する場合は読み込み - - `docs/rule/kairo/design` ディレクトリが存在する場合は読み込み - - 各ディレクトリ内のすべてのファイルを読み込み、追加ルールとして適用 +- ユーザーの選択を context の {{work_scope}} に保存 -## 実行内容 +- カスタムを選択した場合は、AskUserQuestion ツールを使って以下を質問： + - question: "設計文書に含める項目を選択してください（複数選択可）" + - header: "含める項目" + - multiSelect: true + - options: + - label: "詳細なデータフロー図" + description: "包括的なデータフロー図とシーケンス図を作成" + - label: "TypeScript型定義" + description: "詳細な型定義ファイルを作成" + - label: "データベーススキーマ" + description: "データベース設計とスキーマ定義" + - label: "API仕様" + description: "APIエンドポイントとリクエスト/レスポンス定義" -**【信頼性レベル指示】**: -各項目について、元の資料（EARS要件定義書・設計文書含む）との照合状況を以下の信号でコメントしてください： +- step3 を実行する -- 🔵 **青信号**: EARS要件定義書・設計文書を参考にしてほぼ推測していない場合 -- 🟡 **黄信号**: EARS要件定義書・設計文書から妥当な推測の場合 -- 🔴 **赤信号**: EARS要件定義書・設計文書にない推測の場合 +## step3: 開発コンテキストの準備 -2. **技術スタック定義の読み込み** - - `docs/tech-stack.md` が存在する場合は読み込み - - 存在しない場合は `CLAUDE.md` から技術スタックセクションを読み込み - - どちらも存在しない場合は `.claude/commands/tech-stack.md` のデフォルト定義を使用 +- **タスクノートの読み込み** + - `docs/spec/{要件名}/note.md` が存在する場合は読み込み + - 存在しない場合: + - Task ツールを使用して subagent_type: "general-purpose" で `/tsumiki:kairo-tasknote {要件名}` コマンドを実行してノートを生成 + - 生成されたノートファイルを読み込み + - ノートには技術スタック、開発ルール、関連実装、設計文書、注意事項が含まれる -3. **要件の分析** - - @agent-symbol-searcher で要件定義書を検索し、見つかったファイルをReadツールで読み込み - - @agent-symbol-searcher で関連する既存設計文書を確認し、見つかったファイルをReadツールで読み込み - - 読み込んだ技術スタック定義に基づいて技術選択を決定 - - 機能要件と非機能要件を整理する - - システムの境界を明確にする +- **要件定義書の読み込み** + - `./docs/spec/{要件名}-requirements.md` を読み込み + - `./docs/spec/{要件名}/requirements.md` を読み込み + - `./docs/spec/{要件名}-user-stories.md` が存在する場合は読み込み + - `./docs/spec/{要件名}/user-stories.md` が存在する場合は読み込み + - `./docs/spec/{要件名}-acceptance-criteria.md` が存在する場合は読み込み + - `./docs/spec/{要件名}/acceptance-criteria.md` が存在する場合は読み込み + - EARS要件定義から機能要件と非機能要件を抽出 -4. **アーキテクチャ設計** - - システム全体のアーキテクチャを決定 - - フロントエンド/バックエンドの分離 - - マイクロサービスの必要性を検討 +- **追加ルールの読み込み** + - `docs/rule` ディレクトリが存在する場合は読み込み + - `docs/rule/kairo` ディレクトリが存在する場合は読み込み + - `docs/rule/kairo/design` ディレクトリが存在する場合は読み込み + - 各ディレクトリ内のすべてのファイルを読み込み、追加ルールとして適用 -5. **データフロー図の作成** - - Mermaid記法でデータフローを可視化 - - ユーザーインタラクションの流れ - - システム間のデータの流れ +- **技術スタック定義の読み込み** + - `docs/tech-stack.md` が存在する場合は読み込み + - 存在しない場合は `CLAUDE.md` から技術スタックセクションを読み込み + - どちらも存在しない場合は note.md の技術スタック情報を使用 -6. **TypeScriptインターフェースの定義** - - NEVER 対象言語がTypeScriptで無い場合はそれに合わせたファイル形式に変更する。インタフェース定義が不要なら生成しない - - エンティティの型定義 - - APIリクエスト/レスポンスの型定義 - - 共通型の定義 +- **既存設計文書の調査** + - `docs/design/` ディレクトリ配下の既存設計文書を確認 + - 既存のアーキテクチャ設計・データフロー図を読み込み + - 既存のTypeScript型定義・DBスキーマ・API仕様を読み込み + - @task agent-symbol-searcher で関連設計文書を検索 -8. **データベーススキーマの設計** - - NEVER 対象がデータベーススキーマが不要の場合は生成しない - - テーブル定義 - - リレーションシップ - - インデックス戦略 - - 正規化レベルの決定 +- **既存コードベース・実装の分析**（オプション） + - AskUserQuestion ツールを使ってユーザーに確認: + - question: "既存実装の詳細分析が必要ですか？" + - header: "コード分析" + - multiSelect: false + - options: + - label: "必要" + description: "既存実装の網羅的調査、アーキテクチャパターンの確認、技術的制約の特定" + - label: "不要" + description: "要件定義と設計文書のみで設計を作成" + - 「必要」を選択した場合のみ: + - @task agent-symbol-searcher で既存実装の網羅的調査 + - アーキテクチャパターン・実装パターンの確認 + - 技術的制約・依存関係の特定 + - 既存型定義・インターフェースの確認 -9. **APIエンドポイントの設計** - - NEVER 対象にAPIではない場合、または既存のAPIを利用する場合は生成しない - - RESTful API設計 - - エンドポイントの命名規則 - - HTTPメソッドの適切な使用 - - リクエスト/レスポンスの構造 +- **収集情報のサマリー作成** + - 既存プロジェクトのアーキテクチャ全体像整理 + - 定義済み設計・未定義部分の特定 + - 技術制約・非機能要件の整理 + - ギャップ分析（要件 vs 既存設計 vs 実装） -10. **ファイルの作成** - - `docs/design/{要件名}/` ディレクトリに以下を作成： - - `architecture.md` - アーキテクチャ概要 - - `dataflow.md` - データフロー図 - - `interfaces.ts` - TypeScript型定義 - - `database-schema.sql` - DBスキーマ - - `api-endpoints.md` - API仕様 +- 読み込み完了後、step4 を実行する -## 出力フォーマット例 +## step4: 既存情報ベースの差分ヒアリング -### architecture.md +作業規模に応じてヒアリング項目を調整。 +**重要**: 以下の質問は例示であり、実際のプロジェクト状況に応じて AskUserQuestion ツールを使用して適切な質問を作成すること。 -```markdown +### フル設計の場合 + +以下のカテゴリごとに、既存情報（要件定義、設計文書、実装）から特定した具体的な課題・不明点について AskUserQuestion ツールで質問する： + +**既存アーキテクチャの妥当性確認** +- 既存のアーキテクチャパターンが要件に適合するか確認が必要な場合、その内容について質問 +- 技術スタック選択について確認が必要な場合、その理由とともに質問 +- 既存設計で実現困難・非効率な部分を発見した場合、代替案とともに質問 + +例: AskUserQuestion ツールで以下のように質問 +- question: "現在のアーキテクチャは{具体的なパターン}ですが、{新要件}には{別のパターン}の方が適している可能性があります。変更を検討しますか？" +- header: "アーキテクチャ" +- multiSelect: false +- options: + - label: "現行維持" + description: "現在のアーキテクチャを維持" + - label: "変更検討" + description: "新しいアーキテクチャパターンを検討（その他で詳細を記入）" + +**未定義設計の詳細化ヒアリング** +- データモデルの詳細について質問 +- 状態管理方法について質問 +- 認証・認可方式について質問 +- エラーハンドリング戦略について質問 + +**技術選択の確認** +- 使用するライブラリ・フレームワークの選択について質問 +- データベース種別・ORMの選択について質問 +- キャッシュ戦略について質問 +- 外部サービス連携方法について質問 + +**パフォーマンス・スケーラビリティ要件** +- パフォーマンス要件の具体的な数値について質問 +- スケーラビリティの要件について質問 +- データ量・トラフィック予測について質問 + +**セキュリティ・コンプライアンス要件** +- セキュリティ要件の詳細について質問 +- データ保護要件について質問 +- コンプライアンス要件について質問 + +**優先順位・フェーズ分け** +複数の設計要素がある場合、AskUserQuestion ツールで優先順位を質問: +- question: "以下の設計要素の優先順位を教えてください（複数選択可）" +- header: "優先順位" +- multiSelect: true +- options: （実際の設計要素リストから動的に生成） + +### 軽量設計の場合 + +**必須項目のみ確認** +AskUserQuestion ツールを使って、以下の項目について簡潔に質問: +- 基本的なアーキテクチャ方針の確認 +- 主要な技術選択の確認（3-5項目程度） +- 最低限のデータモデル確認 +- 優先順位（Phase 1 のみ） + +### カスタム設計の場合 + +step2 で選択した項目に関連するヒアリングのみ実施。 +AskUserQuestion ツールを使って、選択された項目に応じた質問を作成する。 + +**注意事項**: +- すべての質問を一度に投げるのではなく、文脈に応じて段階的に質問する +- ユーザーの回答を受けて、必要に応じて追加質問を行う +- 質問は具体的で、はい/いいえで答えられるか、選択肢から選べる形式にする +- 自由記述が必要な場合は「その他」オプションを用意する + +**ヒアリング記録の作成**: +- すべての質問と回答を記録する +- 各質問について、以下を記録： + - 質問内容 + - 質問日時 + - カテゴリ（アーキテクチャ/データモデル/技術選択/パフォーマンス/セキュリティ） + - 質問の背景（なぜこの質問が必要だったか） + - ユーザーからの回答 + - 信頼性への影響（この回答により信頼性レベルがどう変化したか） +- ヒアリング結果のサマリーを作成： + - 確認できた事項 + - 設計方針の決定事項 + - 残課題 + - 信頼性レベル分布（ヒアリング前後の比較） +- この記録は後で `{要件名}-design-interview.md` として出力する + +- step5 を実行する + +## step5: 統合設計文書作成 + +- 作業規模に応じた設計テンプレートを選択： + - フル設計: 全ファイルを作成 + - 軽量設計: architecture.md と dataflow.md のみ作成 + - カスタム: 選択項目に応じた組み合わせ + +- context の情報でテンプレートを埋めて、以下のファイルを直接作成する + - 読み込んだコンテキスト情報（タスクノート、追加ルール、要件定義等）を活用 + - **重要**: すべてのファイルのすべての項目に信頼性レベル（🔵🟡🔴）を記載 + - Write ツールを使用して出力ファイルに保存 + +- **出力ファイル**: + 1. `docs/design/{要件名}/architecture.md`: アーキテクチャ概要 + - を使用 + - 各設計決定に信頼性レベル（🔵🟡🔴）と出典を記載 + + 2. `docs/design/{要件名}/dataflow.md`: データフロー図 + - を使用 + - 各フローに信頼性レベル（🔵🟡🔴）と出典を記載 + + 3. `docs/design/{要件名}/design-interview.md`: ヒアリング記録 + - を使用 + - step4の質問と回答を記録 + - 信頼性レベルの変化を記録 + + 4. フル設計の場合: + - `docs/design/{要件名}/interfaces.ts` または対応する型定義ファイル: 型定義 + - を使用 + - **重要**: 対象言語がTypeScriptでない場合はそれに合わせたファイル形式に変更 + - **重要**: インターフェース定義が不要なら生成しない + - 既存のnote.mdやtech-stack.mdの型定義パターンに合わせる + - 既存の設計文書に型定義がある場合はそれを参照して追加 + - 各型定義に信頼性レベル（🔵🟡🔴）と出典をコメントで記載 + + - `docs/design/{要件名}/database-schema.sql` または対応するスキーマファイル: DBスキーマ + - を使用 + - **重要**: 対象がデータベーススキーマが不要の場合は生成しない + - 各テーブル定義に信頼性レベル（🔵🟡🔴）と出典をコメントで記載 + + - `docs/design/{要件名}/api-endpoints.md`: API仕様 + - を使用 + - **重要**: 対象にAPIではない場合、または既存のAPIを利用する場合は生成しない + - 各エンドポイントに信頼性レベル（🔵🟡🔴）と出典を記載 + +- 作成した設計文書の内容について、品質判定基準に基づいて以下を評価： + - 設計の完全性 + - 技術的実現可能性 + - パフォーマンス・スケーラビリティ + - セキュリティ考慮 + - 信頼性レベル（🔵🟡🔴の分布）- すべてのファイルを通じて集計 + +- 品質判定結果をユーザーに表示する（全ファイル統合の信頼性レベル分布を含む） +- step6 を実行する + +## step6: 完了報告とTODO更新 + +- TodoWrite ツールで TODO ステータスを更新する + - 現在のTODOを「completed」にマーク + - 設計フェーズの完了をTODO内容に反映 + - 次のフェーズ「タスク分割」をTODOに追加 + - 品質判定結果をTODO内容に記録 + +- 完了報告を表示： + - 収集した既存設計情報のサマリー + - ヒアリング結果と既存設計との差分 + - 作成したファイルのパス一覧（architecture.md, dataflow.md, design-interview.md, interfaces.ts, database-schema.sql, api-endpoints.md） + - 各ファイルの信頼性レベル分布 + - 全体の信頼性レベル分布（すべてのファイルを通じた集計） + - 既存設計からの変更点・追加点の件数 + - 各ファイル内のリンクが正しく設定されていることを確認 + - 既存実装との整合性確認を促すメッセージ + +- 次のステップ表示: 「次のお勧めステップ: `/tsumiki:kairo-tasks {要件名}` でタスク分割を実施します。」 + +# rules + +## ファイル名のルール + +### 出力ファイルのパス形式 +- `docs/design/{要件名}/architecture.md` +- `docs/design/{要件名}/dataflow.md` +- `docs/design/{要件名}/design-interview.md` +- `docs/design/{要件名}/interfaces.ts` (または対応する型定義ファイル) +- `docs/design/{要件名}/database-schema.sql` (または対応するスキーマファイル) +- `docs/design/{要件名}/api-endpoints.md` + +### ディレクトリ作成 +- `docs/design/{要件名}/` ディレクトリが存在しない場合は自動作成 +- 必要に応じて親ディレクトリも作成 + +### ファイル名の命名規則 +- 要件名を簡潔な英語に変換する +- ケバブケース（kebab-case）を使用 +- 最大50文字程度に収める +- 例: + - "ユーザー認証システム" → "user-auth-system" + - "データエクスポート機能" → "data-export" + - "パスワードリセット" → "password-reset" + +## 品質判定基準 + +``` +✅ 高品質: +- 設計の完全性: 完全 +- 技術的実現可能性: 確実 +- パフォーマンス・スケーラビリティ: 考慮済み +- セキュリティ考慮: 十分 +- 信頼性レベル: 🔵（青信号）が多い + +⚠️ 要改善: +- 設計に曖昧な部分がある +- 技術的制約が不明確 +- パフォーマンス考慮が不十分 +- セキュリティリスクが残る +- 信頼性レベル: 🟡🔴（黄・赤信号）が多い +``` + +## TODO更新パターン + +``` +- 現在のTODOを「completed」にマーク +- 設計フェーズの完了をTODO内容に反映 +- 次のフェーズ「タスク分割」をTODOに追加 +- 品質判定結果をTODO内容に記録 +``` + +## 信頼性レベル指示 + +各項目について、元の資料（PRD・EARS要件定義書・設計文書・ユーザヒアリング含む）との照合状況を以下の信号でコメントしてください： + +- 🔵 **青信号**: EARS要件定義書・設計文書・ユーザヒアリングを参考にしてほぼ推測していない場合 +- 🟡 **黄信号**: EARS要件定義書・設計文書・ユーザヒアリングから妥当な推測の場合 +- 🔴 **赤信号**: EARS要件定義書・設計文書・ユーザヒアリングにない推測の場合 + +## ファイルパスの記載ルール + +- **プロジェクトルートを基準とした相対パスを使用する** +- フルパス（絶対パス）は記載しない +- 例: + - ❌ `/Users/username/projects/myapp/src/utils/helper.ts` + - ✅ `src/utils/helper.ts` + +## 作業規模別の出力調整 + +### フル設計 +- すべてのセクションを含む +- 詳細なアーキテクチャ設計 +- 包括的なデータフロー図 +- 完全な型定義・DBスキーマ・API仕様 + +### 軽量設計 +- architecture.md と dataflow.md のみ +- 基本的なアーキテクチャ概要 +- 主要なデータフローのみ + +### カスタム +- 選択された項目のみ含める +- 必要に応じてファイルを分割 + +## 既存設計との整合性 + +- 既存の設計文書がある場合は必ず参照する +- 既存の型定義パターンに合わせる +- 既存のアーキテクチャパターンとの整合性を保つ +- 変更が必要な場合は理由を明記する + +# info + +## AskUserQuestion ツールの使用例 + +すべてのヒアリングは AskUserQuestion ツールを使用して行います。以下は具体的な使用例です。 + +### アーキテクチャ確認系質問 + +``` +AskUserQuestion({ + questions: [{ + question: "現在のアーキテクチャは{具体的なパターン}ですが、{新要件}には{別のパターン}の方が適している可能性があります。変更を検討しますか？", + header: "アーキテクチャ", + multiSelect: false, + options: [ + { + label: "現行維持", + description: "現在のアーキテクチャを維持" + }, + { + label: "変更検討", + description: "新しいアーキテクチャパターンを検討" + } + ] + }] +}) +``` + +### 技術選択系質問（複数選択） + +``` +AskUserQuestion({ + questions: [{ + question: "この機能で使用する技術を選択してください", + header: "技術選択", + multiSelect: true, + options: [ + { + label: "REST API", + description: "RESTful API を使用" + }, + { + label: "GraphQL", + description: "GraphQL を使用" + }, + { + label: "WebSocket", + description: "リアルタイム通信が必要" + } + ] + }] +}) +``` + +### データモデル確認 + +``` +AskUserQuestion({ + questions: [{ + question: "ユーザーデータの保存方法について教えてください", + header: "データ保存", + multiSelect: false, + options: [ + { + label: "リレーショナルDB", + description: "PostgreSQL/MySQL等を使用" + }, + { + label: "NoSQL", + description: "MongoDB/DynamoDB等を使用" + }, + { + label: "ハイブリッド", + description: "用途に応じて使い分け" + } + ] + }] +}) +``` + +### パフォーマンス要件確認 + +``` +AskUserQuestion({ + questions: [{ + question: "APIレスポンスタイムの目標値を教えてください", + header: "レスポンス目標", + multiSelect: false, + options: [ + { + label: "100ms以内", + description: "高速レスポンスが必要" + }, + { + label: "500ms以内", + description: "一般的なレスポンス" + }, + { + label: "1秒以内", + description: "許容範囲内" + } + ] + }] +}) +``` + +### 優先順位確認（複数質問） + +``` +AskUserQuestion({ + questions: [ + { + question: "以下の設計要素の中で、Phase 1（必須）の項目を選択してください", + header: "Phase 1", + multiSelect: true, + options: [ + { + label: "ユーザー認証", + description: "認証・認可機能" + }, + { + label: "データ管理", + description: "CRUD操作" + }, + { + label: "レポート機能", + description: "データの集計・出力" + } + ] + }, + { + question: "設計のフェーズ分けについて教えてください", + header: "フェーズ計画", + multiSelect: false, + options: [ + { + label: "一括設計", + description: "すべての設計を一度に実施" + }, + { + label: "段階的設計", + description: "フェーズごとに段階的に設計" + } + ] + } + ] +}) +``` + +### 注意事項 + +- **header** は12文字以内の短いラベル +- **question** は明確で具体的な質問文 +- **options** は2-4個の選択肢 +- **multiSelect** は複数選択可能にする場合true +- ユーザーは常に「その他」を選択して自由記述できる（自動提供） + + # {要件名} アーキテクチャ設計 -## システム概要 +**作成日**: {作成日時} +**関連要件定義**: [requirements.md](../../spec/{要件名}/requirements.md) +**ヒアリング記録**: [design-interview.md](design-interview.md) + +**【信頼性レベル凡例】**: +- 🔵 **青信号**: EARS要件定義書・設計文書・ユーザヒアリングを参考にした確実な設計 +- 🟡 **黄信号**: EARS要件定義書・設計文書・ユーザヒアリングから妥当な推測による設計 +- 🔴 **赤信号**: EARS要件定義書・設計文書・ユーザヒアリングにない推測による設計 + +--- + +## システム概要 🔵 + +**信頼性**: 🔵 *要件定義書第1章より* {システムの概要説明} -## アーキテクチャパターン +## アーキテクチャパターン 🔵 -- パターン: {選択したパターン} -- 理由: {選択理由} +**信頼性**: 🔵 *CLAUDE.md技術スタック・既存設計より* + +- **パターン**: {選択したパターン（例: クリーンアーキテクチャ、レイヤードアーキテクチャ、マイクロサービス）} +- **選択理由**: {選択理由の説明} ## コンポーネント構成 -### フロントエンド +### フロントエンド 🔵 + +**信頼性**: 🔵 *tech-stack.md・既存設計より* + +- **フレームワーク**: {使用フレームワーク（例: React, Vue.js, Next.js）} +- **状態管理**: {状態管理方法（例: Redux, Zustand, Context API）} +- **UIライブラリ**: {UIライブラリ（例: Material-UI, Tailwind CSS）} +- **ルーティング**: {ルーティング方法} + +### バックエンド 🔵 + +**信頼性**: 🔵 *tech-stack.md・既存設計より* -- フレームワーク: {使用フレームワーク} -- 状態管理: {状態管理方法} +- **フレームワーク**: {使用フレームワーク（例: Express.js, NestJS, FastAPI）} +- **認証方式**: {認証方法（例: JWT, OAuth2, Session）} +- **API設計**: {API設計方針（例: REST, GraphQL, gRPC）} +- **ミドルウェア**: {使用するミドルウェア} -### バックエンド +### データベース 🟡 -- フレームワーク: {使用フレームワーク} -- 認証方式: {認証方法} +**信頼性**: 🟡 *要件から妥当な推測* -### データベース +- **DBMS**: {使用するDBMS（例: PostgreSQL, MySQL, MongoDB）} +- **キャッシュ**: {キャッシュ戦略（例: Redis, Memcached）} +- **接続方法**: {ORM/ODM（例: Prisma, TypeORM, Mongoose）} -- DBMS: {使用するDBMS} -- キャッシュ: {キャッシュ戦略} +## システム構成図 + +```mermaid +graph TB + Client[クライアント] + FE[フロントエンド] + API[API Gateway] + BE[バックエンド] + DB[(データベース)] + Cache[(キャッシュ)] + + Client --> FE + FE --> API + API --> BE + BE --> DB + BE --> Cache +``` + +**信頼性**: 🔵 *要件定義・既存設計より* + +## ディレクトリ構造 🔵 + +**信頼性**: 🔵 *既存プロジェクト構造より* + +``` +./ +├── src/ +│ ├── {主要ディレクトリ1}/ +│ ├── {主要ディレクトリ2}/ +│ └── {主要ディレクトリ3}/ +├── tests/ +├── docs/ +└── {その他の主要ディレクトリ} ``` -### dataflow.md +## 非機能要件の実現方法 + +### パフォーマンス 🟡 + +**信頼性**: 🟡 *NFR要件から妥当な推測* + +- **レスポンスタイム**: {目標値と実現方法} +- **スループット**: {目標値と実現方法} +- **最適化戦略**: {キャッシング、レイジーロード等} + +### セキュリティ 🔵 + +**信頼性**: 🔵 *NFR要件・セキュリティ設計より* + +- **認証・認可**: {実装方法} +- **データ暗号化**: {暗号化方式} +- **脆弱性対策**: {XSS, CSRF, SQLインジェクション等の対策} + +### スケーラビリティ 🟡 + +**信頼性**: 🟡 *NFR要件から妥当な推測* + +- **水平スケーリング**: {スケーリング戦略} +- **負荷分散**: {ロードバランサー等} +- **データベースシャーディング**: {必要に応じて} + +### 可用性 🟡 + +**信頼性**: 🟡 *NFR要件から妥当な推測* + +- **目標稼働率**: {SLA目標} +- **障害対策**: {フェイルオーバー、リトライ等} +- **監視・アラート**: {監視方法} + +## 技術的制約 + +### パフォーマンス制約 🔵 + +**信頼性**: 🔵 *CLAUDE.md・要件定義より* -```markdown -# データフロー図 +- {制約事項1} +- {制約事項2} -## ユーザーインタラクションフロー +### セキュリティ制約 🔵 -\`\`\`mermaid +**信頼性**: 🔵 *CLAUDE.md・要件定義より* + +- {制約事項1} +- {制約事項2} + +### 互換性制約 🔵 + +**信頼性**: 🔵 *CLAUDE.md・tech-stack.mdより* + +- {制約事項1} +- {制約事項2} + +## 関連文書 + +- **データフロー**: [dataflow.md](dataflow.md) +- **型定義**: [interfaces.ts](interfaces.ts) +- **DBスキーマ**: [database-schema.sql](database-schema.sql) +- **API仕様**: [api-endpoints.md](api-endpoints.md) +- **要件定義**: [requirements.md](../../spec/{要件名}/requirements.md) + +## 信頼性レベルサマリー + +- 🔵 青信号: {件数}件 ({割合}%) +- 🟡 黄信号: {件数}件 ({割合}%) +- 🔴 赤信号: {件数}件 ({割合}%) + +**品質評価**: {高品質/要改善/要ヒアリング} + + + +# {要件名} データフロー図 + +**作成日**: {作成日時} +**関連アーキテクチャ**: [architecture.md](architecture.md) +**関連要件定義**: [requirements.md](../../spec/{要件名}/requirements.md) + +**【信頼性レベル凡例】**: +- 🔵 **青信号**: EARS要件定義書・設計文書・ユーザヒアリングを参考にした確実なフロー +- 🟡 **黄信号**: EARS要件定義書・設計文書・ユーザヒアリングから妥当な推測によるフロー +- 🔴 **赤信号**: EARS要件定義書・設計文書・ユーザヒアリングにない推測によるフロー + +--- + +## システム全体のデータフロー 🔵 + +**信頼性**: 🔵 *要件定義・ユーザーストーリーより* + +```mermaid flowchart TD -A[ユーザー] --> B[フロントエンド] -B --> C[API Gateway] -C --> D[バックエンド] -D --> E[データベース] -\`\`\` + A[ユーザー] --> B[フロントエンド] + B --> C[API Gateway] + C --> D[バックエンド] + D --> E[(データベース)] + D --> F[(キャッシュ)] + D --> G[外部サービス] -## データ処理フロー + E --> D + F --> D + G --> D + D --> C + C --> B + B --> A +``` -\`\`\`mermaid +## 主要機能のデータフロー + +### 機能1: {機能名} 🔵 + +**信頼性**: 🔵 *ユーザーストーリー1.1・受け入れ基準TC-001より* + +**関連要件**: REQ-001, REQ-002 + +```mermaid sequenceDiagram -participant U as ユーザー -participant F as フロントエンド -participant B as バックエンド -participant D as データベース - - U->>F: アクション - F->>B: APIリクエスト - B->>D: クエリ実行 - D-->>B: 結果返却 + participant U as ユーザー + participant F as フロントエンド + participant A as API + participant B as バックエンド + participant D as データベース + + U->>F: {アクション} + F->>A: POST /api/{endpoint} + A->>B: {処理} + B->>D: {クエリ} + D-->>B: {結果} + B->>B: {ビジネスロジック} + B-->>A: {レスポンス} + A-->>F: {データ} + F-->>U: {画面更新} +``` + +**詳細ステップ**: +1. {ステップ1の詳細説明} +2. {ステップ2の詳細説明} +3. {ステップ3の詳細説明} + +### 機能2: {機能名} 🟡 + +**信頼性**: 🟡 *要件から妥当な推測* + +**関連要件**: REQ-101 + +```mermaid +sequenceDiagram + participant U as ユーザー + participant F as フロントエンド + participant B as バックエンド + participant C as キャッシュ + participant D as データベース + + U->>F: {アクション} + F->>B: GET /api/{endpoint} + B->>C: キャッシュ確認 + alt キャッシュヒット + C-->>B: キャッシュデータ + else キャッシュミス + B->>D: クエリ実行 + D-->>B: データ取得 + B->>C: キャッシュ更新 + end B-->>F: レスポンス - F-->>U: 画面更新 + F-->>U: 表示更新 +``` + +**備考**: {この推測の根拠や確認が必要な理由} + +## データ処理パターン + +### 同期処理 🔵 -\`\`\` +**信頼性**: 🔵 *アーキテクチャ設計より* + +{同期処理が必要な機能とその理由} + +### 非同期処理 🟡 + +**信頼性**: 🟡 *パフォーマンス要件から妥当な推測* + +{非同期処理が必要な機能とその理由} + +### バッチ処理 🟡 + +**信頼性**: 🟡 *要件から妥当な推測* + +{バッチ処理が必要な機能とその理由} + +## エラーハンドリングフロー 🟡 + +**信頼性**: 🟡 *既存実装パターンから妥当な推測* + +```mermaid +flowchart TD + A[エラー発生] --> B{エラー種別} + B -->|バリデーションエラー| C[400 Bad Request] + B -->|認証エラー| D[401 Unauthorized] + B -->|権限エラー| E[403 Forbidden] + B -->|リソース未存在| F[404 Not Found] + B -->|サーバーエラー| G[500 Internal Server Error] + + C --> H[エラーメッセージ返却] + D --> H + E --> H + F --> H + G --> I[ログ記録] + I --> H + H --> J[フロントエンドでエラー表示] +``` + +## 状態管理フロー + +### フロントエンド状態管理 🔵 + +**信頼性**: 🔵 *tech-stack.md・既存実装より* + +```mermaid +stateDiagram-v2 + [*] --> 初期状態 + 初期状態 --> ローディング: データ取得開始 + ローディング --> 成功: データ取得成功 + ローディング --> エラー: データ取得失敗 + 成功 --> ローディング: 再取得 + エラー --> ローディング: リトライ ``` -### interfaces.ts +### バックエンド状態管理 🟡 + +**信頼性**: 🟡 *要件から妥当な推測* + +{状態管理の詳細} + +## データ整合性の保証 🟡 + +**信頼性**: 🟡 *NFR要件から妥当な推測* + +- **トランザクション管理**: {トランザクション戦略} +- **楽観的ロック/悲観的ロック**: {ロック戦略} +- **整合性チェック**: {整合性確認方法} + +## 関連文書 + +- **アーキテクチャ**: [architecture.md](architecture.md) +- **型定義**: [interfaces.ts](interfaces.ts) +- **DBスキーマ**: [database-schema.sql](database-schema.sql) +- **API仕様**: [api-endpoints.md](api-endpoints.md) + +## 信頼性レベルサマリー + +- 🔵 青信号: {件数}件 ({割合}%) +- 🟡 黄信号: {件数}件 ({割合}%) +- 🔴 赤信号: {件数}件 ({割合}%) + +**品質評価**: {高品質/要改善/要ヒアリング} + + + +# {要件名} 設計ヒアリング記録 + +**作成日**: {作成日時} +**ヒアリング実施**: step4 既存情報ベースの差分ヒアリング + +## ヒアリング目的 + +既存の要件定義・設計文書・実装を確認し、不明点や曖昧な部分を明確化するためのヒアリングを実施しました。 + +## 質問と回答 + +### Q1: {質問内容} -```typescript +**質問日時**: {日時} +**カテゴリ**: {アーキテクチャ/データモデル/技術選択/パフォーマンス/セキュリティ} +**背景**: {なぜこの質問が必要だったか} + +**回答**: {ユーザーからの回答} + +**信頼性への影響**: +- この回答により、{影響を受けた設計項目} の信頼性レベルが 🔴 → 🔵 に向上 +- {具体的な影響内容} + +--- + +### Q2: {質問内容} + +**質問日時**: {日時} +**カテゴリ**: {カテゴリ名} +**背景**: {背景説明} + +**回答**: {ユーザーからの回答} + +**信頼性への影響**: +- この回答により、新規設計項目 {項目名} を追加（信頼性レベル: 🔵） + +--- + +## ヒアリング結果サマリー + +### 確認できた事項 +- {確認できた事項1} +- {確認できた事項2} + +### 設計方針の決定事項 +- {決定事項1} +- {決定事項2} + +### 残課題 +- {まだ不明確な点1} +- {まだ不明確な点2} + +### 信頼性レベル分布 + +**ヒアリング前**: +- 🔵 青信号: {件数} +- 🟡 黄信号: {件数} +- 🔴 赤信号: {件数} + +**ヒアリング後**: +- 🔵 青信号: {件数} (+{増加数}) +- 🟡 黄信号: {件数} ({増減数}) +- 🔴 赤信号: {件数} (-{減少数}) + +## 関連文書 + +- **アーキテクチャ設計**: [architecture.md](architecture.md) +- **データフロー**: [dataflow.md](dataflow.md) +- **型定義**: [interfaces.ts](interfaces.ts) +- **DBスキーマ**: [database-schema.sql](database-schema.sql) +- **API仕様**: [api-endpoints.md](api-endpoints.md) +- **要件定義**: [requirements.md](../../spec/{要件名}/requirements.md) + + + +/** + * {要件名} 型定義 + * + * 作成日: {作成日時} + * 関連設計: architecture.md + * + * 信頼性レベル: + * - 🔵 青信号: EARS要件定義書・設計文書・既存実装を参考にした確実な型定義 + * - 🟡 黄信号: EARS要件定義書・設計文書・既存実装から妥当な推測による型定義 + * - 🔴 赤信号: EARS要件定義書・設計文書・既存実装にない推測による型定義 + */ + +// ======================================== // エンティティ定義 -export interface User { - id: string; - email: string; - name: string; - createdAt: Date; - updatedAt: Date; +// ======================================== + +/** + * {エンティティ名} + * 🔵 信頼性: 要件定義REQ-001・DBスキーマより + */ +export interface {EntityName} { + id: string; // 🔵 DBスキーマより + {field1}: {type1}; // 🔵 要件定義より + {field2}: {type2}; // 🟡 既存実装から妥当な推測 + createdAt: Date; // 🔵 共通パターン + updatedAt: Date; // 🔵 共通パターン +} + +/** + * {エンティティ名2} + * 🟡 信頼性: 要件から妥当な推測 + * 備考: {確認が必要な理由} + */ +export interface {EntityName2} { + id: string; // 🔵 DBスキーマより + {field1}: {type1}; // 🟡 要件から推測 + // ... 他のフィールド } +// ======================================== // APIリクエスト/レスポンス -export interface CreateUserRequest { - email: string; - name: string; - password: string; +// ======================================== + +/** + * {機能名} リクエスト + * 🔵 信頼性: API仕様書・受け入れ基準TC-001より + */ +export interface {FunctionName}Request { + {param1}: {type1}; // 🔵 API仕様より + {param2}: {type2}; // 🔵 受け入れ基準より + // ... 他のパラメータ +} + +/** + * {機能名} レスポンス + * 🔵 信頼性: API仕様書より + */ +export interface {FunctionName}Response { + success: boolean; // 🔵 共通パターン + data?: {DataType}; // 🔵 API仕様より + error?: ErrorResponse; // 🔵 共通パターン +} + +/** + * エラーレスポンス + * 🔵 信頼性: 既存実装の共通パターンより + */ +export interface ErrorResponse { + code: string; // 🔵 既存実装より + message: string; // 🔵 既存実装より + details?: unknown; // 🔵 既存実装より } +// ======================================== +// 共通型定義 +// ======================================== + +/** + * ページネーション + * 🔵 信頼性: 既存実装の共通パターンより + */ +export interface Pagination { + page: number; // 🔵 既存実装より + limit: number; // 🔵 既存実装より + total: number; // 🔵 既存実装より +} + +/** + * APIレスポンス共通型 + * 🔵 信頼性: 既存実装の共通パターンより + */ export interface ApiResponse { - success: boolean; - data?: T; - error?: { - code: string; - message: string; - }; + success: boolean; // 🔵 既存実装より + data?: T; // 🔵 既存実装より + error?: ErrorResponse; // 🔵 既存実装より + pagination?: Pagination; // 🔵 既存実装より } -``` -### database-schema.sql +// ======================================== +// 列挙型 +// ======================================== + +/** + * {列挙型名} + * 🔵 信頼性: 要件定義・DBスキーマより + */ +export enum {EnumName} { + {VALUE1} = '{value1}', // 🔵 要件定義より + {VALUE2} = '{value2}', // 🔵 DBスキーマより + // ... 他の値 +} -```sql --- ユーザーテーブル -CREATE TABLE users ( - id UUID PRIMARY KEY DEFAULT gen_random_uuid(), - email VARCHAR(255) UNIQUE NOT NULL, - name VARCHAR(255) NOT NULL, - created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, - updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP +// ======================================== +// ユーティリティ型 +// ======================================== + +/** + * 部分的な更新用型 + * 🔵 信頼性: 既存実装の共通パターンより + */ +export type Partial{EntityName} = Partial<{EntityName}>; + +/** + * 作成用型（IDなし） + * 🔵 信頼性: 既存実装の共通パターンより + */ +export type Create{EntityName}Input = Omit<{EntityName}, 'id' | 'createdAt' | 'updatedAt'>; + +// ======================================== +// 信頼性レベルサマリー +// ======================================== +/** + * - 🔵 青信号: {件数}件 ({割合}%) + * - 🟡 黄信号: {件数}件 ({割合}%) + * - 🔴 赤信号: {件数}件 ({割合}%) + * + * 品質評価: {高品質/要改善/要ヒアリング} + */ + + + +-- ======================================== +-- {要件名} データベーススキーマ +-- ======================================== +-- +-- 作成日: {作成日時} +-- 関連設計: architecture.md +-- +-- 信頼性レベル: +-- - 🔵 青信号: EARS要件定義書・設計文書・既存DBスキーマを参考にした確実な定義 +-- - 🟡 黄信号: EARS要件定義書・設計文書・既存DBスキーマから妥当な推測による定義 +-- - 🔴 赤信号: EARS要件定義書・設計文書・既存DBスキーマにない推測による定義 +-- + +-- ======================================== +-- テーブル定義 +-- ======================================== + +-- {テーブル名1} +-- 🔵 信頼性: 要件定義REQ-001・既存DBスキーマより +CREATE TABLE {table_name1} ( + id UUID PRIMARY KEY DEFAULT gen_random_uuid(), -- 🔵 既存DBスキーマの共通パターン + {column1} VARCHAR(255) NOT NULL, -- 🔵 要件定義より + {column2} INTEGER DEFAULT 0, -- 🟡 要件から妥当な推測 + {column3} TIMESTAMP WITH TIME ZONE, -- 🔵 要件定義より + created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, -- 🔵 共通パターン + updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, -- 🔵 共通パターン + + -- 制約 + CONSTRAINT {constraint_name} CHECK ({column2} >= 0) -- 🔵 要件定義の制約より +); + +-- {テーブル名2} +-- 🟡 信頼性: 要件から妥当な推測 +-- 備考: {確認が必要な理由} +CREATE TABLE {table_name2} ( + id UUID PRIMARY KEY DEFAULT gen_random_uuid(), -- 🔵 既存DBスキーマの共通パターン + {column1} VARCHAR(255) UNIQUE NOT NULL, -- 🟡 要件から推測 + {foreign_key_column} UUID REFERENCES {table_name1}(id), -- 🔵 リレーションシップより + created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, -- 🔵 共通パターン + updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP -- 🔵 共通パターン ); +-- ======================================== -- インデックス -CREATE INDEX idx_users_email ON users(email); +-- ======================================== + +-- 検索パフォーマンス向上のためのインデックス +-- 🔵 信頼性: パフォーマンス要件・既存DBスキーマより +CREATE INDEX idx_{table_name1}_{column1} ON {table_name1}({column1}); -- 🔵 頻繁な検索条件より + +-- 🟡 信頼性: パフォーマンス要件から妥当な推測 +CREATE INDEX idx_{table_name2}_{column1} ON {table_name2}({column1}); -- 🟡 検索の可能性を考慮 + +-- ======================================== +-- リレーションシップ（外部キー制約） +-- ======================================== + +-- {table_name2} と {table_name1} の関連 +-- 🔵 信頼性: データモデル設計・要件定義より +ALTER TABLE {table_name2} + ADD CONSTRAINT fk_{table_name2}_{table_name1} + FOREIGN KEY ({foreign_key_column}) + REFERENCES {table_name1}(id) + ON DELETE CASCADE; -- 🔵 要件定義の削除動作より + +-- ======================================== +-- トリガー +-- ======================================== + +-- updated_at 自動更新トリガー +-- 🔵 信頼性: 既存DBスキーマの共通パターンより +CREATE OR REPLACE FUNCTION update_updated_at_column() +RETURNS TRIGGER AS $$ +BEGIN + NEW.updated_at = CURRENT_TIMESTAMP; + RETURN NEW; +END; +$$ language 'plpgsql'; + +CREATE TRIGGER update_{table_name1}_updated_at + BEFORE UPDATE ON {table_name1} + FOR EACH ROW + EXECUTE FUNCTION update_updated_at_column(); -- 🔵 共通パターン + +-- ======================================== +-- 初期データ（必要に応じて） +-- ======================================== + +-- マスターデータの初期投入 +-- 🔵 信頼性: 要件定義・既存データより +INSERT INTO {table_name1} ({column1}, {column2}) VALUES + ('{value1}', {num1}), -- 🔵 要件定義より + ('{value2}', {num2}); -- 🔵 要件定義より + +-- ======================================== +-- パフォーマンス最適化 +-- ======================================== + +-- ANALYZE文（統計情報更新） +-- 🔵 信頼性: 既存DBスキーマの運用パターンより +ANALYZE {table_name1}; +ANALYZE {table_name2}; + +-- ======================================== +-- 信頼性レベルサマリー +-- ======================================== +-- - 🔵 青信号: {件数}件 ({割合}%) +-- - 🟡 黄信号: {件数}件 ({割合}%) +-- - 🔴 赤信号: {件数}件 ({割合}%) +-- +-- 品質評価: {高品質/要改善/要ヒアリング} + + + +# {要件名} API エンドポイント仕様 + +**作成日**: {作成日時} +**関連設計**: [architecture.md](architecture.md) +**関連要件定義**: [requirements.md](../../spec/{要件名}/requirements.md) + +**【信頼性レベル凡例】**: +- 🔵 **青信号**: EARS要件定義書・設計文書・既存API仕様を参考にした確実な定義 +- 🟡 **黄信号**: EARS要件定義書・設計文書・既存API仕様から妥当な推測による定義 +- 🔴 **赤信号**: EARS要件定義書・設計文書・既存API仕様にない推測による定義 + +--- + +## 共通仕様 + +### ベースURL 🔵 + +**信頼性**: 🔵 *既存API仕様より* + +``` +{base_url}/api/v1 +``` + +### 認証 🔵 + +**信頼性**: 🔵 *アーキテクチャ設計・既存API仕様より* + +すべてのエンドポイント（一部の公開エンドポイントを除く）は認証が必要です。 + +```http +Authorization: Bearer {jwt_token} +``` + +### エラーレスポンス共通フォーマット 🔵 + +**信頼性**: 🔵 *既存API仕様の共通パターンより* + +```json +{ + "success": false, + "error": { + "code": "ERROR_CODE", + "message": "エラーメッセージ", + "details": {} + } +} +``` + +### ページネーション 🔵 + +**信頼性**: 🔵 *既存API仕様の共通パターンより* + +リストを返すエンドポイントはページネーションをサポートします。 + +**クエリパラメータ**: +- `page`: ページ番号（デフォルト: 1） +- `limit`: 1ページあたりの件数（デフォルト: 20、最大: 100） + +**レスポンス形式**: +```json +{ + "success": true, + "data": [...], + "pagination": { + "page": 1, + "limit": 20, + "total": 100 + } +} +``` + +--- + +## エンドポイント一覧 + +### 認証 + +#### POST /auth/login 🔵 + +**信頼性**: 🔵 *要件定義REQ-001・受け入れ基準TC-001より* + +**関連要件**: REQ-001 + +**説明**: ユーザーログイン + +**リクエスト**: +```json +{ + "email": "user@example.com", + "password": "password123" +} ``` -### api-endpoints.md +**レスポンス（成功）**: +```json +{ + "success": true, + "data": { + "token": "jwt-token-here", + "user": { + "id": "user-id", + "email": "user@example.com", + "name": "User Name" + } + } +} +``` + +**エラーコード**: +- `INVALID_CREDENTIALS`: 認証情報が無効 +- `ACCOUNT_LOCKED`: アカウントがロックされている + +--- -```markdown -# API エンドポイント仕様 +#### POST /auth/logout 🔵 -## 認証 +**信頼性**: 🔵 *要件定義REQ-002より* -### POST /auth/login +**関連要件**: REQ-002 -リクエスト: -\`\`\`json +**説明**: ユーザーログアウト + +**リクエスト**: なし + +**レスポンス（成功）**: +```json { -"email": "user@example.com", -"password": "password" + "success": true } -\`\`\` +``` + +--- + +### {リソース名1} + +#### GET /{resource1} 🔵 + +**信頼性**: 🔵 *要件定義REQ-101・API仕様より* + +**関連要件**: REQ-101 + +**説明**: {リソース}一覧取得 + +**クエリパラメータ**: +- `page` (optional): ページ番号 +- `limit` (optional): 1ページあたりの件数 +- `{filter_param}` (optional): フィルター条件 -レスポンス: -\`\`\`json +**レスポンス（成功）**: +```json { -"success": true, -"data": { -"token": "jwt-token", -"user": { ... } + "success": true, + "data": [ + { + "id": "resource-id", + "field1": "value1", + "field2": "value2", + "createdAt": "2024-01-15T10:00:00Z", + "updatedAt": "2024-01-15T10:00:00Z" + } + ], + "pagination": { + "page": 1, + "limit": 20, + "total": 100 + } } +``` + +--- + +#### GET /{resource1}/:id 🔵 + +**信頼性**: 🔵 *要件定義REQ-102・受け入れ基準TC-102より* + +**関連要件**: REQ-102 + +**説明**: {リソース}詳細取得 + +**パスパラメータ**: +- `id`: リソースID + +**レスポンス（成功）**: +```json +{ + "success": true, + "data": { + "id": "resource-id", + "field1": "value1", + "field2": "value2", + "createdAt": "2024-01-15T10:00:00Z", + "updatedAt": "2024-01-15T10:00:00Z" + } } -\`\`\` +``` -## ユーザー管理 +**エラーコード**: +- `RESOURCE_NOT_FOUND`: リソースが見つからない -### GET /users/:id +--- -### POST /users +#### POST /{resource1} 🔵 -### PUT /users/:id +**信頼性**: 🔵 *要件定義REQ-103・受け入れ基準TC-103より* -### DELETE /users/:id +**関連要件**: REQ-103 + +**説明**: {リソース}作成 + +**リクエスト**: +```json +{ + "field1": "value1", + "field2": "value2" +} ``` -## 実行後の確認 +**レスポンス（成功）**: +```json +{ + "success": true, + "data": { + "id": "new-resource-id", + "field1": "value1", + "field2": "value2", + "createdAt": "2024-01-15T10:00:00Z", + "updatedAt": "2024-01-15T10:00:00Z" + } +} +``` + +**エラーコード**: +- `VALIDATION_ERROR`: バリデーションエラー +- `DUPLICATE_RESOURCE`: 重複エラー + +--- + +#### PUT /{resource1}/:id 🟡 + +**信頼性**: 🟡 *要件から妥当な推測* + +**関連要件**: REQ-104 + +**説明**: {リソース}更新 + +**備考**: {確認が必要な理由} + +**パスパラメータ**: +- `id`: リソースID + +**リクエスト**: +```json +{ + "field1": "updated-value1", + "field2": "updated-value2" +} +``` + +**レスポンス（成功）**: +```json +{ + "success": true, + "data": { + "id": "resource-id", + "field1": "updated-value1", + "field2": "updated-value2", + "createdAt": "2024-01-15T10:00:00Z", + "updatedAt": "2024-01-15T12:00:00Z" + } +} +``` + +**エラーコード**: +- `RESOURCE_NOT_FOUND`: リソースが見つからない +- `VALIDATION_ERROR`: バリデーションエラー + +--- + +#### DELETE /{resource1}/:id 🔵 + +**信頼性**: 🔵 *要件定義REQ-105より* + +**関連要件**: REQ-105 + +**説明**: {リソース}削除 + +**パスパラメータ**: +- `id`: リソースID + +**レスポンス（成功）**: +```json +{ + "success": true +} +``` + +**エラーコード**: +- `RESOURCE_NOT_FOUND`: リソースが見つからない +- `RESOURCE_IN_USE`: リソースが使用中のため削除不可 + +--- + +## レート制限 🟡 + +**信頼性**: 🟡 *NFR要件から妥当な推測* + +- 認証済みユーザー: {制限値}/分 +- 未認証ユーザー: {制限値}/分 + +レート制限超過時のレスポンス: +```json +{ + "success": false, + "error": { + "code": "RATE_LIMIT_EXCEEDED", + "message": "レート制限を超過しました", + "details": { + "retryAfter": 60 + } + } +} +``` + +## バージョニング 🔵 + +**信頼性**: 🔵 *既存API仕様より* + +APIバージョンはURLパスに含めます（例: `/api/v1/`）。 + +## CORS設定 🔵 + +**信頼性**: 🔵 *セキュリティ設計より* + +許可されたオリジン: {allowed_origins} + +## 関連文書 + +- **アーキテクチャ**: [architecture.md](architecture.md) +- **型定義**: [interfaces.ts](interfaces.ts) +- **データフロー**: [dataflow.md](dataflow.md) +- **要件定義**: [requirements.md](../../spec/{要件名}/requirements.md) + +## 信頼性レベルサマリー + +- 🔵 青信号: {件数}件 ({割合}%) +- 🟡 黄信号: {件数}件 ({割合}%) +- 🔴 赤信号: {件数}件 ({割合}%) -- @agent-symbol-searcher で作成した設計と既存システムとの整合性を確認 -- 作成したファイルの一覧を表示 -- 設計の主要なポイントをサマリーで表示 -- ユーザに確認を促すメッセージを表示 +**品質評価**: {高品質/要改善/要ヒアリング} + diff --git a/commands/kairo-implement.md b/commands/kairo-implement.md index 4011d87..b632a64 100644 --- a/commands/kairo-implement.md +++ b/commands/kairo-implement.md @@ -1,5 +1,6 @@ --- description: 分割されたタスクを順番に、またはユーザが指定したタスクを実装します。既存のTDDコマンドを活用して品質の高い実装を行います。 +argument-hint: [要件名（省略可）] [TASK-ID (TASK-00001)] [--hil] --- あなたは実装担当者です。残タスクを調べて 指定されたコマンドを駆使して実装をしてください @@ -9,6 +10,10 @@ description: 分割されたタスクを順番に、またはユーザが指定 分割されたタスクを順番に、またはユーザが指定したタスクを実装する。既存のTDDコマンドを活用して品質の高い実装を行う。 +## オプション + +- `--hil` (Human-in-the-Loop): テストケース作成後にユーザーの確認を求め、承認後にtdd-red以降のフェーズを実行する + ## 前提条件 - `docs/tasks/{要件名}-tasks.md` にタスク一覧が存在する @@ -27,15 +32,14 @@ description: 分割されたタスクを順番に、またはユーザが指定 - 🔴 **赤信号**: EARS要件定義書・設計文書にない推測の場合 1. **追加ルールの読み込み** - - `docs/rule` ディレクトリが存在する場合は読み込み - - `docs/rule/kairo` ディレクトリが存在する場合は読み込み - - `docs/rule/kairo/implement` ディレクトリが存在する場合は読み込み - - 各ディレクトリ内のすべてのファイルを読み込み、追加ルールとして適用 + - `docs/spec/{要件名}/note.md` が存在する場合は読み込み + +2. **プロジェクト文書の読み込み** -2. **技術スタック定義の読み込み** - - `docs/tech-stack.md` が存在する場合は読み込み - - 存在しない場合は `CLAUDE.md` から技術スタックセクションを読み込み - - どちらも存在しない場合は `.claude/commands/tech-stack.md` のデフォルト定義を使用 + - **タスク関連文書の読み込み**: + - `docs/tasks/{要件名}/overview.md` or `docs/tasks/{要件名}-overview.md` - タスク全体概要 + - `docs/tasks/{要件名}/TASK-{task_id}.md` or `docs/tasks/{要件名}-tasks.md` - 対象タスクファイル + - 依存タスクのファイルも読み込み、実装の順序と関連性を理解 3. **タスクの選択** - @agent-symbol-searcher で指定されたタスクID(TASK-0000形式)を検索し、見つかったタスクファイルをReadツールで読み込み @@ -61,15 +65,31 @@ description: 分割されたタスクを順番に、またはユーザが指定 ### A. **TDDプロセス**（コード実装タスク用） - a. **要件定義** - `@task general-purpose /tsumiki:tdd-requirements` + a. **コンテキスト準備** - `@task general-purpose /tsumiki:tdd-tasknote` + ``` + Task実行: TDDコンテキスト準備フェーズ + 目的: タスクノートを生成し、開発に必要なコンテキスト情報を収集する + 収集内容: + - 技術スタック（使用技術・フレームワーク・アーキテクチャパターン） + - 開発ルール（コーディング規約・型チェック・テスト要件） + - 関連実装（既存の実装パターン・参考コード） + - 設計文書（データモデル・ディレクトリ構造） + - 注意事項（技術的制約・セキュリティ要件・パフォーマンス要件） + コマンド: /tsumiki:tdd-tasknote {要件名} {TASK-ID} + 実行方式: 個別Task実行 + 出力ファイル: docs/implements/{要件名}/{TASK-ID}/note.md + ``` + + b. **要件定義** - `@task general-purpose /tsumiki:tdd-requirements` ``` Task実行: TDD要件定義フェーズ 目的: タスクの詳細要件を記述し、受け入れ基準を明確化する - コマンド: /tsumiki:tdd-requirements + 前提条件: タスクノート（note.md）が存在すること + コマンド: /tsumiki:tdd-requirements {要件名} {TASK-ID} 実行方式: 個別Task実行 ``` - b. **テストケース作成** - `@task general-purpose /tsumiki:tdd-testcases` + c. **テストケース作成** - `@task general-purpose /tsumiki:tdd-testcases` ``` Task実行: TDDテストケース作成フェーズ 目的: 単体テストケースを作成し、エッジケースを考慮する @@ -77,7 +97,23 @@ description: 分割されたタスクを順番に、またはユーザが指定 実行方式: 個別Task実行 ``` - c. **テスト実装** - `@task general-purpose /tsumiki:tdd-red` + c-1. **ユーザー確認** (--hilオプション指定時のみ) + ``` + テストケース確認フェーズ: + - 作成されたテストケース一覧を表示 + - テストケースの妥当性をユーザーに確認 + - ユーザーからのフィードバックを受け取る + - 必要に応じてテストケースを修正 + - 承認後、d. tdd-red以降のフェーズを実行 + + 確認内容: + - テストケースが要件を満たしているか + - エッジケース・エラーケースが十分か + - テストケースの数と粒度が適切か + - 追加・修正が必要なテストケースはないか + ``` + + d. **テスト実装** - `@task general-purpose /tsumiki:tdd-red` ``` Task実行: TDDレッドフェーズ 目的: 失敗するテストを実装し、テストが失敗することを確認する @@ -85,7 +121,7 @@ description: 分割されたタスクを順番に、またはユーザが指定 実行方式: 個別Task実行 ``` - d. **最小実装** - `@task general-purpose /tsumiki:tdd-green` + e. **最小実装** - `@task general-purpose /tsumiki:tdd-green` ``` Task実行: TDDグリーンフェーズ 目的: テストが通る最小限の実装を行い、過度な実装を避ける @@ -93,7 +129,7 @@ description: 分割されたタスクを順番に、またはユーザが指定 実行方式: 個別Task実行 ``` - e. **リファクタリング** - `@task general-purpose /tsumiki:tdd-refactor` + f. **リファクタリング** - `@task general-purpose /tsumiki:tdd-refactor` ``` Task実行: TDDリファクタリングフェーズ 目的: コードの品質向上と保守性の改善を行う @@ -101,14 +137,33 @@ description: 分割されたタスクを順番に、またはユーザが指定 実行方式: 個別Task実行 ``` - f. **品質確認** - `@task general-purpose /tsumiki:tdd-verify-complete` + g. **品質確認** - `@task general-purpose /tsumiki:tdd-verify-complete` ``` Task実行: TDD品質確認フェーズ - 目的: 実装の完成度を確認し、不足があればc-fを繰り返す + 目的: 実装の完成度とテストケースの充足度を確認する + 確認項目: + - すべてのテストケースが実装されているか + - すべてのテストケースが成功しているか + - テストカバレッジが要求水準を満たしているか + - エッジケースがすべてカバーされているか + + 判定基準: + - テストケースが不足している場合: d(tdd-red)から繰り返す + - テストケースは十分だが実装が不足している場合: e(tdd-green)から繰り返す + - 実装・テストともに十分な場合: 次のステップ（h. タスク完了処理）へ + コマンド: /tsumiki:tdd-verify-complete 実行方式: 個別Task実行 ``` + h. **タスク完了処理** + ``` + 品質確認が成功した後の処理: + - タスクファイルの完了チェックボックスを更新 + - 実装サマリーの作成 + - 次のタスクの提案 + ``` + ### B. **直接作業プロセス**（準備作業タスク用） a. **準備作業の実行** - `@task general-purpose /tsumiki:direct-setup` @@ -134,7 +189,15 @@ description: 分割されたタスクを順番に、またはユーザが指定 実行方式: 個別Task実行 ``` -8. **タスクの完了処理** + c. **タスク完了処理** + ``` + 作業確認が成功した後の処理: + - タスクファイルの完了チェックボックスを更新 + - 実装サマリーの作成 + - 次のタスクの提案 + ``` + +8. **全体の完了確認** - タスクのステータスを更新（タスクファイルのチェックボックスにチェックを入れる） - 実装結果をドキュメント化 - 次のタスクを提案 @@ -143,29 +206,43 @@ description: 分割されたタスクを順番に、またはユーザが指定 ```mermaid flowchart TD - A[タスク選択] --> B{依存関係OK?} - B -->|No| C[警告表示] - B -->|Yes| D[実装開始] - D --> E{タスクタイプ判定} - E -->|コード実装| F[TDDプロセス] - E -->|準備作業| G[直接作業プロセス] - - F --> F1[tdd-requirements] - F1 --> F2[tdd-testcases] - F2 --> F3[tdd-red] - F3 --> F4[tdd-green] - F4 --> F5[tdd-refactor] - F5 --> F6[tdd-verify-complete] - F6 --> F7{品質OK?} - F7 -->|No| F3 - F7 -->|Yes| H[タスク完了] - - G --> G1[準備作業実行] - G1 --> G2[作業結果確認] - G2 --> H - - H --> I{他のタスク?} - I -->|Yes| A + A[1. 追加ルール読み込み] --> A1[2. プロジェクト文書読み込み] + A1 --> A2[要件定義書・設計文書] + A2 --> B[3. 技術スタック読み込み] + B --> C[4. タスク選択] + C --> D{5. 依存関係OK?} + D -->|No| E[警告表示] + D -->|Yes| F[6. ディレクトリ準備] + F --> G{7. タスクタイプ判定} + + G -->|コード実装| H[TDDプロセス] + G -->|準備作業| M[直接作業プロセス] + + H --> H0[a. tdd-tasknote] + H0 --> H1[b. tdd-requirements] + H1 --> H2[c. tdd-testcases] + H2 --> H2_1{--hil指定?} + H2_1 -->|Yes| H2_2[c-1. ユーザー確認] + H2_1 -->|No| H3[d. tdd-red] + H2_2 --> H2_3{承認?} + H2_3 -->|修正必要| H2[c. tdd-testcases] + H2_3 -->|承認| H3 + H3 --> H4[e. tdd-green] + H4 --> H5[f. tdd-refactor] + H5 --> H6[g. tdd-verify-complete] + + H6 --> H7{品質判定} + H7 -->|テストケース不足| H3 + H7 -->|実装不足| H4 + H7 -->|OK| H8[h. タスク完了処理] + + M --> M1[a. direct-setup] + M1 --> M2[b. direct-verify] + M2 --> M3[c. タスク完了処理] + + H8 --> I{9. 他のタスク?} + M3 --> I + I -->|Yes| C I -->|No| J[全タスク完了] ``` @@ -173,16 +250,16 @@ flowchart TD ```bash # 全タスクを順番に実装 -$ claude code kairo-implement --all +$ /tsumiki:kairo-implement {要件名} # 特定のタスクを実装 -$ claude code kairo-implement --task {{task_id}} +$ /tsumiki:kairo-implement {要件名} TASK-0001 -# 並行実行可能なタスクを一覧表示 -$ claude code kairo-implement --list-parallel +# Human-in-the-Loopモードで実装（テストケース作成後に確認） +$ /tsumiki:kairo-implement {要件名} TASK-0001 --hil -# 現在の進捗を表示 -$ claude code kairo-implement --status +# Human-in-the-Loopモードで全タスクを実装 +$ /tsumiki:kairo-implement {要件名} --hil ``` ## 実装タイプ判定基準 @@ -225,8 +302,9 @@ $ claude code kairo-implement --status ```bash # TDDプロセスの場合 -@task general-purpose /tsumiki:tdd-requirements -@task general-purpose /tsumiki:tdd-testcases +@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 @@ -239,19 +317,68 @@ $ claude code kairo-implement --status ## 実装時の注意事項 +### 全般 + +1. **プロジェクト文書の活用** + - 要件定義書（EARS記法）を常に参照し、実装の根拠を明確にする + - 設計文書に記載されたアーキテクチャ、データフロー、API仕様に従う + - タスクファイルの「関連文書」セクションから必要な文書を確認 + - 信頼性レベル（🔵🟡🔴）を参考に、推測が必要な箇所を特定 + +2. **ファイル構造の理解** + - `docs/spec/{要件名}/` - 要件定義書 + - `docs/design/{要件名}/` - 設計文書 + - `docs/tasks/{要件名}/` - タスク管理 + - 各タスクファイルには依存関係と関連文書へのリンクが含まれる + ### TDDプロセス用 -1. **テストファースト** +1. **--hilオプション使用時の注意** + - テストケース作成後、必ずユーザーの確認を待つ + - ユーザーが承認するまでtdd-red以降のフェーズを実行しない + - 修正指示があった場合は、tdd-testcasesフェーズから再実行 + - AskUserQuestion ツールを使用してユーザーの選択を取得 + +2. **テストファースト** - 必ずテストを先に書く - テストが失敗することを確認してから実装 -2. **インクリメンタルな実装** +3. **インクリメンタルな実装** - 一度に全てを実装しない - 小さなステップで進める -3. **継続的な品質確認** +4. **品質確認の徹底** - 各ステップで品質を確認 - 技術的負債を作らない + - **テストケース充足度の確認**: + - すべての要件に対してテストケースが存在するか + - エッジケース、エラーケース、境界値テストが含まれているか + - テストカバレッジが基準を満たしているか（目安: 80%以上） + - **実装完成度の確認**: + - すべてのテストケースが成功しているか + - 要件定義書・設計文書に記載された仕様を満たしているか + - コード品質（可読性、保守性）が基準を満たしているか + +5. **品質確認後の対応** + - テストケース不足の場合: + - d. tdd-red に戻り、不足しているテストケースを追加 + - e. tdd-green で実装を追加 + - f. tdd-refactor でリファクタリング + - g. tdd-verify-complete で再確認 + - 実装不足の場合（テストケースは十分）: + - e. tdd-green に戻り、失敗しているテストを通す実装を追加 + - f. tdd-refactor でリファクタリング + - g. tdd-verify-complete で再確認 + +6. **Human-in-the-Loop実行フロー** + - --hilオプション指定時: + 1. c. tdd-testcases でテストケースを作成 + 2. c-1. 作成されたテストケースの一覧と分析結果を表示 + 3. AskUserQuestionツールでユーザーの選択を取得: + - 「承認」: d. tdd-red以降のフェーズを続行 + - 「修正」: ユーザーの指示に基づいてテストケースを修正後、c-1に戻る + - 「キャンセル」: 実装を中断し、現在の状態を保存 + 4. 承認後、通常のTDDプロセスを続行 ### 直接作業プロセス用 @@ -300,12 +427,70 @@ $ claude code kairo-implement --status ### 各ステップ完了時（TDD） ``` -✅ Task 1/6: @task /tsumiki:tdd-requirements 完了 +✅ Task 1/8: @task /tsumiki:tdd-tasknote 完了 + ファイル: docs/implements/{要件名}/{{task_id}}/note.md + Task実行結果: タスクノート作成完了 + +✅ Task 2/8: @task /tsumiki:tdd-requirements 完了 ファイル: docs/implements/{要件名}/{{task_id}}/{要件名}-requirements.md Task実行結果: 要件定義書作成完了 -🏃 Task 2/6: @task /tsumiki:tdd-testcases 実行中... +🏃 Task 3/8: @task /tsumiki:tdd-testcases 実行中... Task実行: TDDテストケース作成フェーズを開始 + +... + +✅ Task 7/8: @task /tsumiki:tdd-verify-complete 完了 + 品質確認結果: + - テストケース充足度: 95% (26/27件実装済み) + - テストケース成功率: 92% (24/26件成功) + - テストカバレッジ: 88% + + 判定: テストケース不足あり & 実装不足あり + → Task 4/8 (tdd-red) から再実行します + +🏃 Task 4/8: @task /tsumiki:tdd-red 実行中... + 不足しているテストケースを追加します +``` + +### ユーザー確認時（--hilオプション指定時） + +``` +✅ Task 3/8: @task /tsumiki:tdd-testcases 完了 + ファイル: docs/implements/{要件名}/{{task_id}}/testcases.md + +📋 作成されたテストケース (27個): + +【正常系テストケース】 +1. ✓ 有効なタスクIDでタスクが正常に作成できる +2. ✓ 必須フィールドが全て設定された状態でタスクが作成できる +3. ✓ オプションフィールドを省略してもタスクが作成できる +... + +【異常系テストケース】 +15. ✓ 無効なタスクID形式でエラーが返される +16. ✓ 必須フィールド不足でバリデーションエラーが返される +17. ✓ 重複するタスクIDでエラーが返される +... + +【境界値テストケース】 +24. ✓ タスク名の最小文字数(1文字)で作成できる +25. ✓ タスク名の最大文字数(200文字)で作成できる +... + +🔍 テストケースレビューポイント: +- 要件カバレッジ: 100% (全要件に対応) +- エッジケースカバレッジ: 85% (主要なエッジケースをカバー) +- エラーケースカバレッジ: 90% (主要なエラーパターンをカバー) + +⏸️ このテストケースで実装を進めてよろしいですか? + +選択肢: +1. [承認] テストケースを承認してtdd-red以降を実行 +2. [修正] テストケースの修正・追加を指示 +3. [キャンセル] 実装を中断 + +あなたの選択: _ ``` ### 各ステップ完了時（直接作業） @@ -329,11 +514,13 @@ $ claude code kairo-implement --status 📊 実装サマリー: - 実装タイプ: TDDプロセス (個別Task実行) -- 実行Taskステップ: 6個 (全て成功) -- 作成ファイル: 12個 -- テストケース: 25個 (全て成功) -- カバレッジ: 95% -- 所要時間: 3時間45分 +- 実行Taskステップ: 8個 (全て成功) +- 品質確認の繰り返し: 2回 (初回: テストケース不足検出 → 追加実装 → 2回目: 成功) +- 作成ファイル: 13個 (タスクノート含む) +- テストケース: 27個 (全て成功) +- テストカバレッジ: 95% +- 要件充足度: 100% +- 所要時間: 4時間15分 📝 次の推奨タスク: - {{次のタスクID}}: {{次のタスク名}} diff --git a/commands/kairo-requirements.md b/commands/kairo-requirements.md index 3a08717..53b9adf 100644 --- a/commands/kairo-requirements.md +++ b/commands/kairo-requirements.md @@ -1,128 +1,505 @@ --- description: ユーザから提供された要件の概要を分析し、EARS（Easy Approach to Requirements Syntax）記法を使用して詳細な受け入れ基準を含む要件定義書を作成します。 +allowed-tools: Read, Glob, Grep, Task, Write, Edit, TodoWrite, WebFetch, AskUserQuestion +argument-hint: [要件名] [PRDファイルパス(optional)] --- +Kairo開発の要件整理を実施し、PRD・EARS要件定義書・設計文書を参照しながら機能仕様を明確化します。信頼性レベルを示しながら要件定義を作成します。 + +# context + +出力ディレクトリ="docs/spec" +要件名={{requirement_name}} +PRDファイル={{prd_file_path}} +作業規模={{work_scope}} +信頼性評価=[] + +# step + +- $ARGUMENTS がない場合、「引数に要件名を指定してください（例: ユーザー認証システム）。PRDファイルがあればパスも指定してください（例: ユーザー認証システム docs/prd/auth-prd.md）」と言って終了する +- $ARGUMENTS の内容と context の内容をまとめてユーザに宣言する +- step2 を実行する + +## step2: 作業規模の確認 + +- AskUserQuestion ツールを使って作業規模を質問する： + - question: "この要件の作業規模について教えてください" + - header: "作業規模" + - multiSelect: false + - options: + - label: "フル機能開発（推奨）" + description: "詳細なEARS要件定義、包括的なユーザーストーリー、完全な受け入れ基準、非機能要件・エッジケース含む" + - label: "軽量開発" + description: "必要最小限の要件定義、基本的なユーザーストーリーのみ、主要な受け入れ基準のみ、非機能要件は最低限" + - label: "カスタム" + description: "含めたい項目を個別に選択" + +- ユーザーの選択を context の {{work_scope}} に保存 + +- カスタムを選択した場合は、AskUserQuestion ツールを使って以下を質問： + - question: "要件定義書に含める項目を選択してください（複数選択可）" + - header: "含める項目" + - multiSelect: true + - options: + - label: "詳細なユーザーストーリー" + description: "包括的なユーザーストーリーを作成" + - label: "非機能要件の詳細化" + description: "パフォーマンス・セキュリティ等の詳細な非機能要件" + - label: "エッジケースの洗い出し" + description: "エラー処理・境界値等のエッジケース" + - label: "パフォーマンス要件" + description: "詳細なパフォーマンス要件の定義" + +- step3 を実行する + +## step3: 開発コンテキストの準備 + +- **タスクノートの読み込み** + - `docs/spec/{要件名}/note.md` が存在する場合は読み込み + - 存在しない場合: + - Task ツールを使用して subagent_type: "general-purpose" で `/tsumiki:kairo-tasknote {要件名}` コマンドを実行してノートを生成 + - 生成されたノートファイルを読み込み + - ノートには技術スタック、開発ルール、関連実装、設計文書、注意事項が含まれる + +- **PRDファイルの読み込み**（引数で指定された場合） + - {{prd_file_path}} が指定されている場合は読み込み + - PRD（Product Requirements Document）には以下が含まれることを期待： + - プロダクトビジョン + - ターゲットユーザー + - 主要機能 + - ビジネス要件 + - 成功指標 + +- **追加ルールの読み込み** + - `docs/rule` ディレクトリが存在する場合は読み込み + - `docs/rule/kairo` ディレクトリが存在する場合は読み込み + - `docs/rule/kairo/requirements` ディレクトリが存在する場合は読み込み + - 各ディレクトリ内のすべてのファイルを読み込み、追加ルールとして適用 + +- **プロジェクト基本情報収集** + - `CLAUDE.md` の内容を読み込み（プロジェクト概要・技術スタック・制約） + - `README.md` が存在する場合は読み込み + - プロジェクト構造（ディレクトリ構成）を把握 + +- **既存設計文書・仕様書の調査** + - `docs/` ディレクトリ配下の関連設計文書を確認 + - 既存の要件定義書・設計書を読み込み + - タスク管理ファイル（phase*.md）の内容確認 + - API仕様書・DB設計書があれば確認 + +- **既存コードベース・開発状況の分析**（オプション） + - AskUserQuestion ツールを使ってユーザーに確認: + - question: "既存コードベースの詳細分析が必要ですか？" + - header: "コード分析" + - multiSelect: false + - options: + - label: "必要" + description: "既存仕様・実装の網羅的調査、開発状況・進捗確認、差分分析を実施" + - label: "不要" + description: "設計文書のみで要件定義を作成" + - 「必要」を選択した場合のみ: + - @task agent-symbol-searcher で既存仕様・実装の網羅的調査 + - git status/log で現在の開発状況・進捗確認 + - 実装済み機能 vs 設計書の差分分析 + - 残タスク・未実装部分の特定 + +- **収集情報のサマリー作成** + - 既存プロジェクトの全体像整理 + - 定義済み要件・未定義部分の特定 + - 技術制約・非機能要件の整理 + - ギャップ分析（設計 vs 実装 vs ユーザー期待） + +- 読み込み完了後、step4 を実行する + +## step4: 既存情報ベースの差分ヒアリング + +作業規模に応じてヒアリング項目を調整。 +**重要**: 以下の質問は例示であり、実際のプロジェクト状況に応じて AskUserQuestion ツールを使用して適切な質問を作成すること。 + +### フル機能開発の場合 + +以下のカテゴリごとに、既存情報（PRD、設計文書、実装）から特定した具体的な課題・不明点について AskUserQuestion ツールで質問する： + +**既存設計の妥当性・過不足確認** +- 既存の機能要件・非機能要件の確認が必要な場合、具体的な項目について質問 +- 現在の制約事項（性能・データ制限等）の妥当性に疑問がある場合、その内容について質問 +- 技術スタック選択について確認が必要な場合、その理由とともに質問 +- 既存設計で実現困難・不適切な部分を発見した場合、代替案とともに質問 + +例: AskUserQuestion ツールで以下のように質問 +- question: "現在のCLAUDE.mdで定義されている{具体的な制約事項}について、実際の運用で問題ないでしょうか？" +- header: "制約確認" +- multiSelect: false +- options: + - label: "問題ない" + description: "現在の制約事項で運用可能" + - label: "変更が必要" + description: "制約の見直しが必要（その他で詳細を記入）" + +**未定義・曖昧部分の詳細化ヒアリング** +- 設計文書で詳細が不明な機能について、具体的な動作を質問 +- ユーザーの実際の業務フロー・ユースケースについて質問 +- 入出力データの詳細仕様について質問 +- UI/UX の具体的な期待値について質問 + +**追加・変更要件の特定** +- 既存設計にない新規機能要件について質問 +- 外部システム連携の追加需要について質問 +- レポート・分析機能等の追加需要について質問 +- 運用・メンテナンス要件の追加について質問 + +**既存機能への影響範囲確認** +- 新規要件による既存機能への影響について質問 +- パフォーマンス要件への影響について質問 +- セキュリティ・アクセシビリティ要件への影響について質問 +- データ移行・互換性要件について質問 + +**優先順位・スコープ調整** +複数の要件がある場合、AskUserQuestion ツールで優先順位を質問: +- question: "以下の要件の優先順位を教えてください（複数選択可）" +- header: "優先順位" +- multiSelect: true +- options: （実際の要件リストから動的に生成） + +### 軽量開発の場合 + +**必須項目のみ確認** +AskUserQuestion ツールを使って、以下の項目について簡潔に質問: +- 主要な機能要件の確認（3-5項目程度） +- 基本的な制約事項の確認 +- 最低限のエラーケース確認 +- 優先順位（Must Have のみ） + +### カスタム開発の場合 + +step2 で選択した項目に関連するヒアリングのみ実施。 +AskUserQuestion ツールを使って、選択された項目に応じた質問を作成する。 + +**注意事項**: +- すべての質問を一度に投げるのではなく、文脈に応じて段階的に質問する +- ユーザーの回答を受けて、必要に応じて追加質問を行う +- 質問は具体的で、はい/いいえで答えられるか、選択肢から選べる形式にする +- 自由記述が必要な場合は「その他」オプションを用意する + +**ヒアリング記録の作成**: +- すべての質問と回答を記録する +- 各質問について、以下を記録： + - 質問内容 + - 質問日時 + - カテゴリ（既存設計確認/未定義部分詳細化/追加要件/影響範囲/優先順位） + - 質問の背景（なぜこの質問が必要だったか） + - ユーザーからの回答 + - 信頼性への影響（この回答により信頼性レベルがどう変化したか） +- ヒアリング結果のサマリーを作成： + - 確認できた事項 + - 追加/変更要件 + - 残課題 + - 信頼性レベル分布（ヒアリング前後の比較） +- この記録は後で `interview-record.md` として出力する + +- step5 を実行する + +## step5: 統合要件定義書作成 + +- 作業規模に応じた を選択： + - フル機能開発: + - 軽量開発: + - カスタム: 選択項目に応じた組み合わせ + +- context の情報でテンプレートを埋めて、以下のファイルを直接作成する + - 読み込んだコンテキスト情報（タスクノート、追加ルール、PRD等）を活用 + - **重要**: すべてのファイルのすべての項目に信頼性レベル（🔵🟡🔴）を記載 + - Write ツールを使用して出力ファイルに保存 + +- **出力ファイル**: + 1. `docs/spec/{要件名}/requirements.md`: 統合機能要件と関連文書へのリンク + - または を使用 + - 各要件に信頼性レベル（🔵🟡🔴）と出典を記載 + + 2. `docs/spec/{要件名}/interview-record.md`: ヒアリング記録 + - を使用 + - step4の質問と回答を記録 + - 信頼性レベルの変化を記録 + + 3. フル機能開発の場合: + - `docs/spec/{要件名}/user-stories.md`: 詳細なユーザストーリー + - を使用 + - **重要**: 各ストーリーに信頼性レベル（🔵🟡🔴）と出典を記載 + - 信頼性レベルサマリーを含める + + - `docs/spec/{要件名}/acceptance-criteria.md`: 受け入れ基準とテスト項目 + - を使用 + - **重要**: 各受け入れ基準とテストケースに信頼性レベル（🔵🟡🔴）と出典を記載 + - 信頼性レベル分布を含める + +- 作成した要件定義書の内容について、品質判定基準に基づいて以下を評価： + - 要件の曖昧さの有無 + - 入出力定義の完全性 + - 制約条件の明確性 + - 実装可能性 + - 信頼性レベル（🔵🟡🔴の分布）- すべてのファイルを通じて集計 + +- 品質判定結果をユーザーに表示する（全ファイル統合の信頼性レベル分布を含む） +- step6 を実行する + +## step6: 完了報告とTODO更新 + +- TodoWrite ツールで TODO ステータスを更新する + - 現在のTODOを「completed」にマーク + - 要件定義フェーズの完了をTODO内容に反映 + - 次のフェーズ「設計文書作成」をTODOに追加 + - 品質判定結果をTODO内容に記録 + +- 完了報告を表示： + - Phase 0で収集した既存プロジェクト情報のサマリー + - Phase 1でのヒアリング結果と既存情報との差分 + - 作成したファイルのパス一覧（requirements.md, interview-record.md, user-stories.md, acceptance-criteria.md） + - 各ファイルの信頼性レベル分布 + - 全体の信頼性レベル分布（すべてのファイルを通じた集計） + - 既存要件からの変更点・追加点の件数 + - 各ファイル内のリンクが正しく設定されていることを確認 + - 既存設計書・実装との整合性確認を促すメッセージ + +- 次のステップ表示: 「次のお勧めステップ: `/tsumiki:kairo-design {要件名}` で技術設計文書を作成します。」 + +# rules + +## ファイル名のルール + +### 出力ファイルのパス形式 +- `docs/spec/{要件名}/requirements.md` +- `docs/spec/{要件名}/interview-record.md` +- `docs/spec/{要件名}/user-stories.md` (フル機能開発のみ) +- `docs/spec/{要件名}/acceptance-criteria.md` (フル機能開発のみ) +- `docs/spec/{要件名}/note.md` (コンテキストノート) + +### ファイル名の命名規則 +- 要件名を簡潔な英語に変換する +- ケバブケース（kebab-case）を使用 +- 最大50文字程度に収める +- 例: + - "ユーザー認証システム" → "user-auth-system" + - "データエクスポート機能" → "data-export" + - "パスワードリセット" → "password-reset" + +## 品質判定基準 -# kairo-requirements - -## 目的 - -既存プロジェクトの情報を収集・分析し、ユーザから要件をヒアリングして、EARS（Easy Approach to Requirements Syntax）記法を使用した詳細な受け入れ基準を含む要件定義書を作成する。 -ユーザに要件をヒアリングするときは一問一答形式で選択肢から選ぶか自由入力を可能にする - -## 前提条件 - -- 既存プロジェクト（コードベース、設計文書等）が存在する -- `docs/spec/` ディレクトリが存在する（なければ作成） - -## 実行フロー - -### Phase 0: 既存プロジェクト情報の網羅的収集 - -**【信頼性レベル指示】**: -各項目について、元の資料（EARS要件定義書・設計文書・ユーザヒアリング含む）との照合状況を以下の信号でコメントしてください： - -- 🔵 **青信号**: EARS要件定義書・設計文書・ユーザヒアリングを参考にしてほぼ推測していない場合 -- 🟡 **黄信号**: EARS要件定義書・設計文書・ユーザヒアリングから妥当な推測の場合 -- 🔴 **赤信号**: EARS要件定義書・設計文書・ユーザヒアリングにない推測の場合 - -1. **追加ルールの読み込み** - - `docs/rule` ディレクトリが存在する場合は読み込み - - `docs/rule/kairo` ディレクトリが存在する場合は読み込み - - `docs/rule/kairo/requirements` ディレクトリが存在する場合は読み込み - - 各ディレクトリ内のすべてのファイルを読み込み、追加ルールとして適用 - -2. **プロジェクト基本情報収集** - - `CLAUDE.md` の内容を読み込み（プロジェクト概要・技術スタック・制約） - - `README.md` が存在する場合は読み込み - - プロジェクト構造（ディレクトリ構成）を把握 - -3. **既存設計文書・仕様書の調査** - - `docs/` ディレクトリ配下の全設計文書を確認 - - 既存の要件定義書・設計書を読み込み - - タスク管理ファイル（phase*.md）の内容確認 - - API仕様書・DB設計書があれば確認 - -4. **既存コードベース・開発状況の分析** - - @agent-symbol-searcher で既存仕様・実装の網羅的調査 - - git status/log で現在の開発状況・進捗確認 - - 実装済み機能 vs 設計書の差分分析 - - 残タスク・未実装部分の特定 - -5. **収集情報のサマリー作成** - - 既存プロジェクトの全体像整理 - - 定義済み要件・未定義部分の特定 - - 技術制約・非機能要件の整理 - - ギャップ分析（設計 vs 実装 vs ユーザー期待） - -### Phase 1: 既存情報ベースの差分ヒアリング - -6. **既存設計の妥当性・過不足確認** - - 既存の機能要件・非機能要件の確認質問 - - 現在の制約事項（性能・データ制限等）の妥当性確認 - - 技術スタック選択の再確認 - - 既存設計で実現困難・不適切な部分の特定 - -7. **未定義・曖昧部分の詳細化ヒアリング** - - 設計文書で詳細が不明な機能の具体化 - - ユーザーの実際の業務フロー・ユースケースの確認 - - 入出力データの詳細仕様確認 - - UI/UX の具体的な期待値確認 - -8. **追加・変更要件の特定** - - 既存設計にない新規機能要件の聞き出し - - 外部システム連携の追加需要確認 - - レポート・分析機能等の追加需要確認 - - 運用・メンテナンス要件の追加確認 - -9. **既存機能への影響範囲確認** - - 新規要件による既存機能への影響許容度確認 - - パフォーマンス要件への影響確認 - - セキュリティ・アクセシビリティ要件への影響確認 - - データ移行・互換性要件の確認 - -10. **優先順位・スコープ調整** - - Must Have / Should Have / Could Have / Won't Have の分類 - - リリーススコープ・段階的リリース計画の確認 - - 予算・スケジュール制約に基づく優先順位調整 - -### Phase 2: 統合要件定義書作成 - -11. **ユーザストーリーの作成・更新** - - WHO（誰が）、WHAT（何を）、WHY（なぜ）の形式で記述 - - 既存ユーザストーリーの更新・新規ストーリーの追加 - - 各機能の価値・優先順位を明確化 - -12. **EARS記法による統合要件定義** - - **通常要件（SHALL）**: システムが通常実行すべき動作 - - **条件付き要件（WHEN/IF-THEN）**: 特定の条件下での動作 - - **不要要件（WHERE）**: 特定の状態での動作 - - **オプション要件（MAY）**: 任意の機能 - - **制約要件（MUST）**: システムの制約事項 - - 既存要件との統合・重複排除・矛盾解決 - -13. **Edgeケース・非機能要件の定義** - - 異常系の処理・エラーハンドリング - - 境界値の処理・データ制限 - - パフォーマンス・セキュリティ・ユーザビリティ要件 - - 運用・保守・移行要件 - -14. **統合要件定義書ファイルの作成** - - `docs/spec/{要件名}-requirements.md`: 統合機能要件と関連文書へのリンク - - `docs/spec/{要件名}-user-stories.md`: 詳細なユーザストーリー - - `docs/spec/{要件名}-acceptance-criteria.md`: 受け入れ基準とテスト項目 - - 既存要件からの変更点・追加点を明記 - **【信頼性レベル指示】**: - 各項目について、元の資料（EARS要件定義書・設計文書・ユーザヒアリング含む）との照合状況を以下の信号でコメントしてください： - - - 🔵 **青信号**: EARS要件定義書・設計文書・ユーザヒアリングを参考にしてほぼ推測していない場合 - - 🟡 **黄信号**: EARS要件定義書・設計文書・ユーザヒアリングから妥当な推測の場合 - - 🔴 **赤信号**: EARS要件定義書・設計文書・ユーザヒアリングにない推測の場合 - -## 出力フォーマット例 - -### 1. requirements.md（メインファイル） - -```markdown +``` +✅ 高品質: +- 要件の曖昧さ: なし +- 入出力定義: 完全 +- 制約条件: 明確 +- 実装可能性: 確実 +- 信頼性レベル: 🔵（青信号）が多い + +⚠️ 要改善: +- 要件に曖昧な部分がある +- 入出力の詳細が不明確 +- 技術的制約が不明 +- ユーザー意図の確認が必要 +- 信頼性レベル: 🟡🔴（黄・赤信号）が多い +``` + +## TODO更新パターン + +``` +- 現在のTODOを「completed」にマーク +- 要件定義フェーズの完了をTODO内容に反映 +- 次のフェーズ「設計文書作成」をTODOに追加 +- 品質判定結果をTODO内容に記録 +``` + +## 信頼性レベル指示 + +各項目について、元の資料（PRD・EARS要件定義書・設計文書・ユーザヒアリング含む）との照合状況を以下の信号でコメントしてください： + +- 🔵 **青信号**: PRD・EARS要件定義書・設計文書・ユーザヒアリングを参考にしてほぼ推測していない場合 +- 🟡 **黄信号**: PRD・EARS要件定義書・設計文書・ユーザヒアリングから妥当な推測の場合 +- 🔴 **赤信号**: PRD・EARS要件定義書・設計文書・ユーザヒアリングにない推測の場合 + +## ファイルパスの記載ルール + +- **プロジェクトルートを基準とした相対パスを使用する** +- フルパス（絶対パス）は記載しない +- 例: + - ❌ `/Users/username/projects/myapp/src/utils/helper.ts` + - ✅ `src/utils/helper.ts` + +## 作業規模別の出力調整 + +### フル機能開発 +- すべてのセクションを含む +- 詳細なユーザーストーリー作成 +- 包括的な受け入れ基準作成 +- 非機能要件・エッジケースを網羅 + +### 軽量開発 +- 機能要件の主要項目のみ（3-5項目） +- ユーザーストーリーは requirements.md 内に簡易記載 +- 受け入れ基準は基本項目のみ +- 非機能要件は最低限 + +### カスタム +- 選択された項目のみ含める +- 必要に応じてファイルを分割 + +# info + +## AskUserQuestion ツールの使用例 + +すべてのヒアリングは AskUserQuestion ツールを使用して行います。以下は具体的な使用例です。 + +### 既存設計確認系質問 + +``` +AskUserQuestion({ + questions: [{ + question: "現在のCLAUDE.mdで定義されている{具体的な制約事項}について、実際の運用で問題ないでしょうか？", + header: "制約確認", + multiSelect: false, + options: [ + { + label: "問題ない", + description: "現在の制約事項で運用可能" + }, + { + label: "変更が必要", + description: "制約の見直しが必要" + } + ] + }] +}) +``` + +### 詳細化系質問（複数選択） + +``` +AskUserQuestion({ + questions: [{ + question: "この機能で必要な操作を選択してください", + header: "必要な操作", + multiSelect: true, + options: [ + { + label: "データの追加", + description: "新しいデータを追加する機能" + }, + { + label: "データの編集", + description: "既存データを編集する機能" + }, + { + label: "データの削除", + description: "データを削除する機能" + }, + { + label: "データの検索", + description: "データを検索する機能" + } + ] + }] +}) +``` + +### 追加要件系質問 + +``` +AskUserQuestion({ + questions: [{ + question: "レポート・分析機能は必要ですか？", + header: "レポート機能", + multiSelect: false, + options: [ + { + label: "必要", + description: "レポート・分析機能を実装する" + }, + { + label: "不要", + description: "レポート機能は不要" + } + ] + }] +}) +``` + +### 優先順位確認（複数質問） + +``` +AskUserQuestion({ + questions: [ + { + question: "以下の要件の中で、Must Have（必須）の項目を選択してください", + header: "Must Have", + multiSelect: true, + options: [ + { + label: "ユーザー認証", + description: "ログイン・ログアウト機能" + }, + { + label: "データ管理", + description: "CRUD操作" + }, + { + label: "レポート機能", + description: "データの集計・出力" + } + ] + }, + { + question: "リリーススコープについて教えてください", + header: "リリース計画", + multiSelect: false, + options: [ + { + label: "一括リリース", + description: "すべての機能を同時にリリース" + }, + { + label: "段階的リリース", + description: "フェーズごとに段階的にリリース" + } + ] + } + ] +}) +``` + +### 影響確認系質問 + +``` +AskUserQuestion({ + questions: [{ + question: "この新機能により、既存の{機能名}の変更は許容できますか？", + header: "影響許容度", + multiSelect: false, + options: [ + { + label: "許容できる", + description: "既存機能の変更を許容" + }, + { + label: "最小限にしてほしい", + description: "既存機能への影響を最小限に" + }, + { + label: "変更不可", + description: "既存機能は変更しない" + } + ] + }] +}) +``` + +### 注意事項 + +- **header** は12文字以内の短いラベル +- **question** は明確で具体的な質問文 +- **options** は2-4個の選択肢 +- **multiSelect** は複数選択可能にする場合true +- ユーザーは常に「その他」を選択して自由記述できる（自動提供） + + # {要件名} 要件定義書 ## 概要 @@ -131,27 +508,27 @@ description: ユーザから提供された要件の概要を分析し、EARS（ ## 関連文書 -- **ユーザストーリー**: [📖 {要件名}-user-stories.md]({要件名}-user-stories.md) -- **受け入れ基準**: [✅ {要件名}-acceptance-criteria.md]({要件名}-acceptance-criteria.md) +- **ヒアリング記録**: [💬 interview-record.md](interview-record.md) +- **ユーザストーリー**: [📖 user-stories.md](user-stories.md) +- **受け入れ基準**: [✅ acceptance-criteria.md](acceptance-criteria.md) +- **コンテキストノート**: [📝 note.md](note.md) +{PRDがある場合: - **PRD**: [{PRDファイル名}]({PRDファイルパス})} ## 機能要件（EARS記法） **【信頼性レベル凡例】**: -- 🔵 **青信号**: EARS要件定義書・設計文書・ユーザヒアリングを参考にした確実な要件 -- 🟡 **黄信号**: EARS要件定義書・設計文書・ユーザヒアリングから妥当な推測による要件 -- 🔴 **赤信号**: EARS要件定義書・設計文書・ユーザヒアリングにない推測による要件 +- 🔵 **青信号**: PRD・EARS要件定義書・設計文書・ユーザヒアリングを参考にした確実な要件 +- 🟡 **黄信号**: PRD・EARS要件定義書・設計文書・ユーザヒアリングから妥当な推測による要件 +- 🔴 **赤信号**: PRD・EARS要件定義書・設計文書・ユーザヒアリングにない推測による要件 ### 通常要件 -- REQ-001: システムは {通常の動作} しなければならない 🔵 *EARS要件定義書第3章より* +- REQ-001: システムは {通常の動作} しなければならない 🔵 *PRD第3章より* - REQ-002: システムは {通常の動作} しなければならない 🟡 *設計文書から妥当な推測* -- REQ-003: システムは {通常の動作} しなければならない 🔵 *ユーザヒアリング2024-01-15より* ### 条件付き要件 -- REQ-101: {条件} の場合、システムは {動作} しなければならない 🔵 *ユーザー要件・API仕様書より* -- REQ-102: {条件} の場合、システムは {動作} しなければならない 🔴 *設計文書にない推測* -- REQ-103: {条件} の場合、システムは {動作} しなければならない 🟡 *ユーザヒアリング内容から妥当な推測* +- REQ-101: {条件} の場合、システムは {動作} しなければならない 🔵 *ユーザヒアリング2024-01-15より* ### 状態要件 @@ -177,8 +554,7 @@ description: ユーザから提供された要件の概要を分析し、EARS（ ### ユーザビリティ -- NFR-201: {ユーザビリティ要件} 🔴 *ユーザー要件にない推測* -- NFR-202: {ユーザビリティ要件} 🔵 *ユーザヒアリング2024-01-20 UX要望より* +- NFR-201: {ユーザビリティ要件} 🔵 *ユーザヒアリング2024-01-20 UX要望より* ## Edgeケース @@ -189,285 +565,414 @@ description: ユーザから提供された要件の概要を分析し、EARS（ ### 境界値 - EDGE-101: {境界値ケース} 🔵 *API仕様書・テストケースより* -``` + -### 2. user-stories.md（詳細なユーザストーリー） - -```markdown -# {要件名} ユーザストーリー + +# {要件名} 要件定義書（軽量版） ## 概要 -このドキュメントは{要件名}機能の詳細なユーザストーリーを記載します。 +{要件の概要} + +## 関連文書 + +- **ヒアリング記録**: [💬 interview-record.md](interview-record.md) +- **コンテキストノート**: [📝 note.md](note.md) +{PRDがある場合: - **PRD**: [{PRDファイル名}]({PRDファイルパス})} + +## 主要機能要件 + +**【信頼性レベル凡例】**: +- 🔵 **青信号**: PRD・設計文書・ユーザヒアリングを参考にした確実な要件 +- 🟡 **黄信号**: PRD・設計文書・ユーザヒアリングから妥当な推測による要件 +- 🔴 **赤信号**: PRD・設計文書・ユーザヒアリングにない推測による要件 + +### 必須機能（Must Have） + +- REQ-001: {主要機能1} 🔵 *PRDより* +- REQ-002: {主要機能2} 🔵 *ユーザヒアリングより* +- REQ-003: {主要機能3} 🟡 *設計文書から妥当な推測* + +### 基本的な制約 + +- REQ-401: {基本的な制約事項} 🔵 *CLAUDE.mdより* + +## 簡易ユーザーストーリー + +### ストーリー1: {機能名} + +**私は** {ユーザー種別} **として** +**{具体的な行動} をしたい** +**そうすることで** {得られる価値} + +**関連要件**: REQ-001 + +## 基本的な受け入れ基準 + +### REQ-001: {要件名} + +**Given（前提条件）**: {テスト実行前の状態} +**When（実行条件）**: {実行するアクション} +**Then（期待結果）**: {期待される出力・状態} -## ユーザー種別の定義 +**テストケース**: +- [ ] 正常系: {正常なケースの詳細} +- [ ] 主要な異常系: {主要な異常ケース} + +## 最小限の非機能要件 + +- **パフォーマンス**: {基本的な性能要求} +- **セキュリティ**: {最低限のセキュリティ要求} + + + +# {要件名} ヒアリング記録 + +**作成日**: {作成日時} +**ヒアリング実施**: step4 既存情報ベースの差分ヒアリング + +## ヒアリング目的 + +既存の設計文書・PRD・実装を確認し、不明点や曖昧な部分を明確化するためのヒアリングを実施しました。 + +## 質問と回答 -### プライマリユーザー +### Q1: {質問内容} -- **エンドユーザー**: {エンドユーザーの詳細説明} -- **管理者**: {管理者の詳細説明} -- **開発者**: {開発者の詳細説明} +**質問日時**: {日時} +**カテゴリ**: {既存設計確認/未定義部分詳細化/追加要件/影響範囲/優先順位} +**背景**: {なぜこの質問が必要だったか} -### セカンダリユーザー +**回答**: {ユーザーからの回答} -- **システム管理者**: {システム管理者の詳細説明} -- **外部システム**: {外部システムの詳細説明} +**信頼性への影響**: +- この回答により、{影響を受けた要件ID} の信頼性レベルが 🔴 → 🔵 に向上 +- {具体的な影響内容} + +--- + +### Q2: {質問内容} + +**質問日時**: {日時} +**カテゴリ**: {カテゴリ名} +**背景**: {背景説明} + +**回答**: {ユーザーからの回答} + +**信頼性への影響**: +- この回答により、新規要件 {要件ID} を追加（信頼性レベル: 🔵） + +--- -## ユーザストーリー +## ヒアリング結果サマリー + +### 確認できた事項 +- {確認できた事項1} +- {確認できた事項2} + +### 追加/変更要件 +- {追加要件1} +- {変更要件1} + +### 残課題 +- {まだ不明確な点1} +- {まだ不明確な点2} + +### 信頼性レベル分布 + +**ヒアリング前**: +- 🔵 青信号: {件数} +- 🟡 黄信号: {件数} +- 🔴 赤信号: {件数} + +**ヒアリング後**: +- 🔵 青信号: {件数} (+{増加数}) +- 🟡 黄信号: {件数} ({増減数}) +- 🔴 赤信号: {件数} (-{減少数}) + +## 関連文書 + +- **要件定義書**: [requirements.md](requirements.md) +- **ユーザストーリー**: [user-stories.md](user-stories.md) +- **受け入れ基準**: [acceptance-criteria.md](acceptance-criteria.md) + + + +# {要件名} ユーザストーリー + +**作成日**: {作成日時} +**関連要件定義**: [requirements.md](requirements.md) +**ヒアリング記録**: [interview-record.md](interview-record.md) **【信頼性レベル凡例】**: -- 🔵 **青信号**: EARS要件定義書・設計文書・ユーザヒアリングを参考にした確実なストーリー -- 🟡 **黄信号**: EARS要件定義書・設計文書・ユーザヒアリングから妥当な推測によるストーリー -- 🔴 **赤信号**: EARS要件定義書・設計文書・ユーザヒアリングにない推測によるストーリー +- 🔵 **青信号**: PRD・EARS要件定義書・設計文書・ユーザヒアリングを参考にした確実なストーリー +- 🟡 **黄信号**: PRD・EARS要件定義書・設計文書・ユーザヒアリングから妥当な推測によるストーリー +- 🔴 **赤信号**: PRD・EARS要件定義書・設計文書・ユーザヒアリングにない推測によるストーリー -### 📚 エピック1: {大きな機能グループ} 🔵 *ユーザヒアリング2024-01-15より* +--- + +## エピック1: {エピック名} -#### ストーリー1.1: {具体的なストーリー名} 🔵 *EARS要件定義書・ユーザヒアリングより* +### ストーリー 1.1: {ストーリー名} 🔵 -**ユーザストーリー**: -- **私は** {ユーザー種別} **として** -- **{具体的な状況・コンテキスト} において** -- **{実現したい行動・操作} をしたい** -- **そうすることで** {得られる価値・解決される問題} +**信頼性**: 🔵 *PRD第2章・ユーザヒアリング2024-01-15より* -**詳細説明**: -- **背景**: {なぜこの機能が必要なのか} -- **前提条件**: {このストーリーの前提となる状況} -- **利用シーン**: {具体的な利用場面の例} -- **期待する体験**: {ユーザーが期待する体験の詳細} +**私は** {ユーザー種別（例: 一般ユーザー）} **として** +**{具体的な行動（例: タスクを作成したい）}** +**そうすることで** {得られる価値（例: 日々のタスクを管理できる）} **関連要件**: REQ-001, REQ-002 -**優先度**: 高/中/低 +**詳細シナリオ**: +1. {ステップ1の説明} +2. {ステップ2の説明} +3. {ステップ3の説明} -**見積もり**: {ストーリーポイントまたは工数} +**前提条件**: +- {前提条件1} +- {前提条件2} -#### ストーリー1.2: {具体的なストーリー名} 🟡 *設計文書から妥当な推測* +**制約事項**: +- {制約事項1} +- {制約事項2} -{同様の形式で記載} +**優先度**: Must Have / Should Have / Could Have / Won't Have -### 📚 エピック2: {大きな機能グループ} 🔴 *既存資料にない推測* +--- -{同様の形式で記載} +### ストーリー 1.2: {ストーリー名} 🟡 -## ユーザージャーニー +**信頼性**: 🟡 *設計文書から妥当な推測* -### ジャーニー1: {代表的な利用フロー} 🔵 *ユーザヒアリング業務フローより* +**私は** {ユーザー種別} **として** +**{具体的な行動}** +**そうすることで** {得られる価値} -```mermaid -journey - title {ユーザージャーニーのタイトル} - section {フェーズ1} - {アクション1}: 5: {ユーザー種別} - {アクション2}: 3: {ユーザー種別} - section {フェーズ2} - {アクション3}: 4: {ユーザー種別} - {アクション4}: 5: {ユーザー種別} -``` +**関連要件**: REQ-003 -**詳細**: -1. **{アクション1}**: {詳細な説明} -2. **{アクション2}**: {詳細な説明} +**詳細シナリオ**: +1. {ステップ1の説明} +2. {ステップ2の説明} -## ペルソナ定義 +**前提条件**: +- {前提条件1} -### ペルソナ1: {代表的ユーザー名} 🔵 *ユーザヒアリング2024-01-18 ペルソナ調査より* +**優先度**: Should Have -- **基本情報**: {年齢、職業、技術レベル等} -- **ゴール**: {このユーザーが達成したいこと} -- **課題**: {現在抱えている問題} -- **行動パターン**: {典型的な行動の特徴} -- **利用環境**: {使用するデバイス、環境等} +**備考**: {この推測の根拠や確認が必要な理由} -## 非機能的ユーザー要求 +--- + +## エピック2: {エピック名} + +### ストーリー 2.1: {ストーリー名} 🔵 + +**信頼性**: 🔵 *ユーザヒアリング2024-01-20より* -### ユーザビリティ要求 +**私は** {ユーザー種別} **として** +**{具体的な行動}** +**そうすることで** {得られる価値} -- **学習容易性**: {初回利用時の学習コスト} -- **効率性**: {熟練後の作業効率} -- **記憶しやすさ**: {再利用時の記憶のしやすさ} -- **エラー対応**: {エラー時の対応しやすさ} -- **満足度**: {主観的な満足度} +**関連要件**: REQ-101, REQ-102 + +**詳細シナリオ**: +1. {ステップ1の説明} +2. {ステップ2の説明} +3. {ステップ3の説明} + +**優先度**: Must Have + +--- -### アクセシビリティ要求 +## ストーリーマップ -- **視覚**: {視覚障害者への配慮} -- **聴覚**: {聴覚障害者への配慮} -- **運動**: {運動機能障害者への配慮} -- **認知**: {認知障害者への配慮} +``` +エピック1: {エピック名} +├── ストーリー 1.1 (🔵 Must Have) +├── ストーリー 1.2 (🟡 Should Have) +└── ストーリー 1.3 (🔵 Could Have) + +エピック2: {エピック名} +├── ストーリー 2.1 (🔵 Must Have) +└── ストーリー 2.2 (🟡 Should Have) ``` -### 3. acceptance-criteria.md（受け入れ基準） +## 信頼性レベルサマリー -```markdown -# {要件名} 受け入れ基準 +- 🔵 青信号: {件数}件 ({割合}%) +- 🟡 黄信号: {件数}件 ({割合}%) +- 🔴 赤信号: {件数}件 ({割合}%) -## 概要 +**品質評価**: {高品質/要改善/要ヒアリング} + -このドキュメントは{要件名}機能の受け入れ基準とテスト項目を記載します。 + +# {要件名} 受け入れ基準 -## 機能テスト基準 +**作成日**: {作成日時} +**関連要件定義**: [requirements.md](requirements.md) +**関連ユーザストーリー**: [user-stories.md](user-stories.md) +**ヒアリング記録**: [interview-record.md](interview-record.md) **【信頼性レベル凡例】**: -- 🔵 **青信号**: EARS要件定義書・設計文書・ユーザヒアリングを参考にした確実なテスト基準 -- 🟡 **黄信号**: EARS要件定義書・設計文書・ユーザヒアリングから妥当な推測によるテスト基準 -- 🔴 **赤信号**: EARS要件定義書・設計文書・ユーザヒアリングにない推測によるテスト基準 +- 🔵 **青信号**: PRD・EARS要件定義書・設計文書・ユーザヒアリングを参考にした確実な基準 +- 🟡 **黄信号**: PRD・EARS要件定義書・設計文書・ユーザヒアリングから妥当な推測による基準 +- 🔴 **赤信号**: PRD・EARS要件定義書・設計文書・ユーザヒアリングにない推測による基準 -### REQ-001: {要件名} の受け入れ基準 🔵 *EARS要件定義書・既存テスト仕様より* +--- -**Given（前提条件）**: -- {テスト実行前の状態} -- {必要な初期データ} +## REQ-001: {要件名} 🔵 -**When（実行条件）**: -- {実行するアクション} -- {入力するデータ} +**信頼性**: 🔵 *PRD第3章・テストケース仕様書より* -**Then（期待結果）**: -- {期待される出力・状態} -- {確認すべき副作用} +### Given（前提条件） +- {テスト実行前の状態1} +- {テスト実行前の状態2} -**テストケース**: -- [ ] 正常系: {正常なケースの詳細} -- [ ] 異常系: {異常なケースの詳細} -- [ ] 境界値: {境界値テストの詳細} +### When（実行条件） +- {ユーザーが実行するアクション} -### REQ-002: {要件名} の受け入れ基準 🟡 *ユーザヒアリング要望から妥当な推測* +### Then（期待結果） +- {期待される出力1} +- {期待される状態変化2} -{同様の形式で記載} +### テストケース -## 非機能テスト基準 +#### 正常系 -### パフォーマンステスト +- [ ] **TC-001-01**: {テストケース名} 🔵 + - **入力**: {入力データ} + - **期待結果**: {期待される出力} + - **信頼性**: 🔵 *既存テストケースより* -**NFR-001: {パフォーマンス要件} 🔵 *CLAUDE.md制約・ユーザヒアリングより*** +- [ ] **TC-001-02**: {テストケース名} 🔵 + - **入力**: {入力データ} + - **期待結果**: {期待される出力} + - **信頼性**: 🔵 *ユーザヒアリングより* -- [ ] 応答時間: {具体的な時間基準} -- [ ] スループット: {処理量の基準} -- [ ] 同時接続数: {同時利用者数の基準} -- [ ] リソース使用量: {CPU・メモリ使用量の基準} +#### 異常系 -**テスト方法**: -- 負荷テストツール: {使用するツール} -- テストシナリオ: {具体的なテスト手順} -- 合格基準: {定量的な合格ライン} +- [ ] **TC-001-E01**: {エラーケース名} 🟡 + - **入力**: {異常な入力データ} + - **期待結果**: {エラーメッセージ/エラー処理} + - **信頼性**: 🟡 *既存実装から妥当な推測* -### セキュリティテスト +- [ ] **TC-001-E02**: {エラーケース名} 🔵 + - **入力**: {異常な入力データ} + - **期待結果**: {エラーメッセージ/エラー処理} + - **信頼性**: 🔵 *エラー処理仕様書より* -**NFR-101: {セキュリティ要件} 🟡 *セキュリティ設計書から妥当な推測*** +#### 境界値 -- [ ] 認証: {認証機能のテスト項目} -- [ ] 認可: {権限制御のテスト項目} -- [ ] データ保護: {データ暗号化のテスト項目} -- [ ] 脆弱性: {セキュリティ脆弱性のテスト項目} +- [ ] **TC-001-B01**: {境界値ケース名} 🔵 + - **入力**: {境界値データ} + - **期待結果**: {期待される動作} + - **信頼性**: 🔵 *API仕様書より* -## ユーザビリティテスト基準 +--- -### UX/UIテスト +## REQ-002: {要件名} 🟡 -- [ ] 直感的操作性: {操作の分かりやすさ} -- [ ] レスポンシブデザイン: {各デバイスでの表示} -- [ ] アクセシビリティ: {WCAG 2.1準拠} -- [ ] エラーメッセージ: {分かりやすいエラー表示} +**信頼性**: 🟡 *設計文書から妥当な推測* -**テスト方法**: -- ユーザビリティテスト: {実施方法} -- A/Bテスト: {比較テストの方法} -- アクセシビリティチェック: {使用するツール} +### Given（前提条件） +- {テスト実行前の状態} -## Edgeケーステスト基準 +### When（実行条件） +- {ユーザーが実行するアクション} -### EDGE-001: {エラーケース} の受け入れ基準 🔴 *既存資料にない推測* +### Then（期待結果） +- {期待される出力} -**テストシナリオ**: -- {異常な状況の設定} -- {期待されるエラーハンドリング} -- {ユーザーへの適切な通知} +### テストケース -**合格基準**: -- [ ] システムがクラッシュしない -- [ ] 適切なエラーメッセージが表示される -- [ ] データの整合性が保たれる -- [ ] 復旧可能な状態を維持する +#### 正常系 -## 統合テスト基準 +- [ ] **TC-002-01**: {テストケース名} 🟡 + - **入力**: {入力データ} + - **期待結果**: {期待される出力} + - **信頼性**: 🟡 *設計文書から推測* + - **備考**: {確認が必要な理由} -### システム間連携テスト +--- -- [ ] 外部API連携: {外部システムとの連携テスト} -- [ ] データベース連携: {DB操作の整合性テスト} -- [ ] ファイルシステム: {ファイル操作のテスト} +## 非機能要件テスト -## リグレッションテスト基準 +### NFR-001: パフォーマンス 🟡 -### 既存機能影響確認 +**信頼性**: 🟡 *CLAUDE.md制約から妥当な推測* -- [ ] 既存機能の動作確認: {影響範囲の特定と確認} -- [ ] パフォーマンス劣化確認: {既存機能の性能確認} -- [ ] セキュリティ設定確認: {セキュリティ機能の継続確認} +- [ ] **TC-NFR-001-01**: {パフォーマンステスト名} + - **測定項目**: {レスポンスタイム/スループット等} + - **目標値**: {具体的な数値} + - **測定条件**: {負荷条件等} + - **信頼性**: 🟡 *技術制約から推測* -## 受け入れテスト実行チェックリスト +### NFR-101: セキュリティ 🔵 -### テスト実行前 +**信頼性**: 🔵 *セキュリティ設計書・実装より* -- [ ] テスト環境の準備完了 -- [ ] テストデータの準備完了 -- [ ] テストツールの準備完了 -- [ ] 実行担当者の確認完了 +- [ ] **TC-NFR-101-01**: {セキュリティテスト名} + - **検証内容**: {検証する脆弱性} + - **期待結果**: {期待される防御動作} + - **信頼性**: 🔵 *セキュリティ設計書より* -### テスト実行中 +--- -- [ ] 全機能テストの実行 -- [ ] 全非機能テストの実行 -- [ ] 問題発見時の記録 -- [ ] 修正後の再テスト +## Edgeケーステスト -### テスト完了後 +### EDGE-001: {エラー処理ケース} 🟡 -- [ ] テスト結果の記録 -- [ ] 残存問題の整理 -- [ ] 受け入れ可否の判定 -- [ ] ステークホルダーへの報告 -``` +**信頼性**: 🟡 *既存実装から妥当な推測* -## ヒアリング質問例 +- [ ] **TC-EDGE-001-01**: {エッジケーステスト名} + - **条件**: {特殊な条件} + - **期待結果**: {期待される動作} + - **信頼性**: 🟡 *実装から推測* -### 既存設計確認系質問 +--- -- "現在のCLAUDE.mdで定義されている{制約事項}について、実際の運用で問題ないでしょうか？" -- "技術スタック（{技術名}）について、変更希望や追加制約はありますか？" -- "既存の{機能名}機能で、想定しているユースケースに追加はありますか？" -- "パフォーマンス要件（{具体的な数値}）で、実際の業務に支障はないでしょうか？" +## テストケースサマリー -### 詳細化系質問 +### カテゴリ別件数 -- "{機能名}で、具体的にどのような操作フローを想定していますか？" -- "データの入力項目について、{項目名}以外に必要なものはありますか？" -- "エラーが発生した場合、どのような通知・対応を期待しますか？" -- "外部システムとの連携で、{システム名}との接続は必要ですか？" +| カテゴリ | 正常系 | 異常系 | 境界値 | 合計 | +|---------|--------|--------|--------|------| +| 機能要件 | {件数} | {件数} | {件数} | {件数} | +| 非機能要件 | {件数} | {件数} | {件数} | {件数} | +| Edgeケース | {件数} | {件数} | {件数} | {件数} | +| **合計** | {件数} | {件数} | {件数} | {件数} | -### 追加要件系質問 +### 信頼性レベル分布 -- "現在の設計にない機能で、実現したいものはありますか？" -- "レポート・分析機能は必要ですか？必要な場合、どのような情報が欲しいですか？" -- "モバイルアプリでの利用は想定していますか？" -- "複数人での同時利用・権限管理は必要ですか？" +- 🔵 青信号: {件数}件 ({割合}%) +- 🟡 黄信号: {件数}件 ({割合}%) +- 🔴 赤信号: {件数}件 ({割合}%) -### 影響確認系質問 +**品質評価**: {高品質/要改善/要ヒアリング} + +### 優先度別テストケース + +- **Must Have**: {件数}件 +- **Should Have**: {件数}件 +- **Could Have**: {件数}件 + +--- + +## テスト実施計画 + +### Phase 1: 基本機能テスト +- REQ-001 ~ REQ-050 +- 優先度: Must Have +- 実施予定: {日付} + +### Phase 2: 拡張機能テスト +- REQ-051 ~ REQ-100 +- 優先度: Should Have +- 実施予定: {日付} -- "この新機能により、既存の{機能名}の変更は許容できますか？" -- "データ移行が発生する場合、どの程度の作業時間が許容できますか？" -- "パフォーマンスへの影響で、許容できる範囲を教えてください" -- "セキュリティ要件で、追加で考慮すべき点はありますか？" - -## 実行後の確認 - -- Phase 0で収集した既存プロジェクト情報のサマリーを表示 -- Phase 1でのヒアリング結果と既存情報との差分を明確化 -- 作成した3つのファイルのパスを表示 - - `docs/spec/{要件名}-requirements.md` - - `docs/spec/{要件名}-user-stories.md` - - `docs/spec/{要件名}-acceptance-criteria.md` -- 既存要件からの変更点・追加点の件数を報告 -- 各ファイル内のリンクが正しく設定されていることを確認 -- 既存設計書・実装との整合性確認を促すメッセージを表示 +### Phase 3: 非機能・Edgeケーステスト +- NFR-001 ~ NFR-999, EDGE-001 ~ EDGE-999 +- 優先度: Must Have + Should Have +- 実施予定: {日付} + diff --git a/commands/kairo-task-verify.md b/commands/kairo-task-verify.md deleted file mode 100644 index b13db42..0000000 --- a/commands/kairo-task-verify.md +++ /dev/null @@ -1,67 +0,0 @@ ---- -description: 作成されたタスクファイルの内容を確認し、出力フォーマット例に沿った情報が抜けていたら追加します。 ---- - -# kairo-task-verify - -## 目的 - -作成されたタスクファイルの内容を確認し、出力フォーマット例に沿った情報が抜けていたら追加する。 - -## 前提条件 - -- `docs/tasks/{要件名}-tasks.md` が存在する -- kairo-tasksコマンドによってタスクファイルが作成済みである - -## 実行内容 - -**【信頼性レベル指示】**: -各項目について、元の資料（EARS要件定義書・設計文書含む）との照合状況を以下の信号でコメントしてください： - -- 🔵 **青信号**: EARS要件定義書・設計文書を参考にしてほぼ推測していない場合 -- 🟡 **黄信号**: EARS要件定義書・設計文書から妥当な推測の場合 -- 🔴 **赤信号**: EARS要件定義書・設計文書にない推測の場合 - -1. **追加ルールの読み込み** - - `docs/rule` ディレクトリが存在する場合は読み込み - - `docs/rule/kairo` ディレクトリが存在する場合は読み込み - - `docs/rule/kairo/task-verify` ディレクトリが存在する場合は読み込み - - 各ディレクトリ内のすべてのファイルを読み込み、追加ルールとして適用 - -2. **技術スタック定義の読み込み** - - `docs/tech-stack.md` が存在する場合は読み込み - - 存在しない場合は `CLAUDE.md` から技術スタックセクションを読み込み - - どちらも存在しない場合は `.claude/commands/tech-stack.md` のデフォルト定義を使用 - -3. **タスクファイルの確認** - - @agent-symbol-searcher でタスクファイルを検索し、見つかったファイルをReadツールで読み込み - - `docs/tasks/{要件名}-tasks.md` をReadツールで読み込み - -4. **出力フォーマット例との比較** - - @agent-symbol-searcher で関連するタスクフォーマットを検索し、見つかったファイルをReadツールで読み込み - - kairo-tasksコマンドファイルをReadツールで読み込み、出力フォーマット例を確認 - - 作成されたタスクファイルに不足している情報を特定 - -5. **不足情報の追加** - 以下の項目が含まれているか確認し、不足していれば追加： - - 概要セクション（全タスク数、推定作業時間、クリティカルパス） - - 各タスクのチェックボックス - - タスクタイプ（TDD/DIRECT）の明記 - - 要件リンク - - 依存タスク - - 実装詳細 - - テスト要件 - - UI/UX要件（フロントエンドタスクの場合） - - エラーハンドリング要件 - - 完了条件 - - 実行順序（Mermaidガントチャート） - - サブタスクテンプレート情報 - -6. **ファイルの更新** - - 不足している情報を追加してファイルを更新 - -## 実行後の確認 - -- 更新したファイルのパスを表示 -- 追加した情報の概要を表示 -- タスクファイルが完全になったことを確認 diff --git a/commands/kairo-tasknote.md b/commands/kairo-tasknote.md new file mode 100644 index 0000000..135a598 --- /dev/null +++ b/commands/kairo-tasknote.md @@ -0,0 +1,343 @@ +--- +description: Kairo開発のコンテキスト情報を収集してノートにまとめます。技術スタック、追加ルール、関連ファイルの情報を整理します。 +allowed-tools: Read, Glob, Grep, Task, Write, TodoWrite, Bash +argument-hint: [要件名] +--- +Kairo開発の前にコンテキスト情報を収集し、開発に必要な情報をノートファイルにまとめます。 + +# context + +出力ディレクトリ="docs/spec" +要件名={{requirement_name}} +収集情報=[] + +# step + +- $ARGUMENTS がない場合、「引数に要件名を指定してください（例: ユーザー認証システム）」と言って終了する +- $ARGUMENTS の内容と context の内容をまとめてユーザに宣言する +- step2 を実行する + +## step2: 既存ノートの確認 + +- `{{出力ディレクトリ}}/{要件名}/note.md` が既にある場合: + - 既存ファイルの内容を表示 + - ユーザに確認: 「既存のノートファイルがあります。更新しますか？（y/n）」 + - ユーザが「y」と回答した場合: step3 を実行 + - ユーザが「n」と回答した場合: 終了する +- 存在しない場合: step3 を実行する + +## step3: 開発コンテキストの収集 + +### Phase 1: プロジェクト基本情報の収集 + +**追加ルールの読み込み** +- `CLAUDE.md` ファイルが存在する場合は読み込み（技術スタック・制約） +- `AGENTS.md` ファイルが存在する場合は読み込み +- `README.md` が存在する場合は読み込み +- `docs/rule` ディレクトリが存在する場合は読み込み +- `docs/rule/kairo` ディレクトリが存在する場合は読み込み +- 各ディレクトリ内のすべてのファイルを読み込み、追加ルールとして適用 + +### Phase 2: 既存設計文書・仕様書の収集 + +**既存の要件定義・設計書の検索** +- `docs/spec/{要件名}-requirements.md`: 統合機能要件 +- `docs/spec/{要件名}-user-stories.md`: 詳細なユーザストーリー +- `docs/spec/{要件名}-acceptance-criteria.md`: 受け入れ基準 +- `docs/spec/{要件名}-*.md`: その他関連ドキュメント +- `docs/design/*.md`: 設計文書ディレクトリ +- `docs/tech-stack.md`: 技術スタック +- 見つかったファイルをすべて Read ツールで読み込み + +### Phase 3: 既存実装の調査（オプション） + +- ユーザーに確認: 「既存コードベースの詳細分析が必要ですか？（y/n）」 +- 必要な場合のみ実行: + - **@task agent-symbol-searcher で実装関連情報を検索** + - 類似機能の実装例を検索 + - ユーティリティ関数・共通モジュールを検索 + - 実装パターンやアーキテクチャガイドラインを特定 + - 依存関係やインポートパスを確認 + - 見つかった関連ファイルを Read ツールで読み込み + +### Phase 4: Git情報の収集 + +- `git status` で現在の開発状況を確認 +- `git log --oneline -20` で最近のコミット履歴を確認 +- 既存のブランチ情報を確認 + +### Phase 5: プロジェクト構造の把握 + +- ディレクトリ構造を把握（主要ディレクトリのみ） +- 設定ファイルの確認（package.json, tsconfig.json等） + +- step4 を実行する + +## step4: 収集情報の整理と保存 + +- 収集した情報を の形式で整理 +- 以下の内容を含める: + 1. **プロジェクト概要** + 2. **技術スタック** + 3. **開発ルール** + 4. **既存の要件定義** + 5. **既存の設計文書** + 6. **関連実装**（オプション） + 7. **技術的制約** + 8. **注意事項** + +- Write ツールを使用して `{{出力ディレクトリ}}/{要件名}/note.md` に保存 +- step5 を実行する + +## step5: 完了報告 + +- TodoWrite ツールで TODO ステータスを更新する + - 現在のTODOを「completed」にマーク + - コンテキスト収集フェーズの完了をTODO内容に反映 + - 次のフェーズ「要件定義作成」をTODOに追加 + +- 完了報告を表示： + - 収集したファイルの一覧 + - プロジェクトの概要サマリー + - 作成したノートファイルのパス + +# rules + +## ファイル名のルール + +### 出力ファイルのパス形式 +- `docs/spec/{要件名}/note.md` +- 例: `docs/spec/user-auth-system/note.md` + +### ディレクトリ作成 +- `docs/spec/{要件名}/` ディレクトリが存在しない場合は自動作成 +- 必要に応じて親ディレクトリも作成 + +### ファイル名の命名規則 +- 要件名を簡潔な英語に変換する +- ケバブケース（kebab-case）を使用 +- 最大50文字程度に収める +- 例: + - "ユーザー認証システム" → "user-auth-system" + - "データエクスポート機能" → "data-export" + - "パスワードリセット" → "password-reset" + +## ファイルパスの記載ルール + +- **プロジェクトルートを基準とした相対パスを使用する** +- フルパス（絶対パス）は記載しない +- 例: + - ❌ `/Users/username/projects/myapp/src/utils/helper.ts` + - ✅ `src/utils/helper.ts` + +## 情報収集の優先順位 + +1. **必須**: CLAUDE.md, README.md, 既存の要件定義・設計書 +2. **推奨**: 追加ルール、設定ファイル、Git情報 +3. **オプション**: 既存実装の詳細分析 + +## TODO更新パターン + +``` +- 現在のTODOを「completed」にマーク +- コンテキスト収集フェーズの完了をTODO内容に反映 +- 次のフェーズ「要件定義作成」をTODOに追加 +``` + +# info + + +# {要件名} 開発コンテキストノート + +## 作成日時 +{作成日時} + +## プロジェクト概要 + +### プロジェクト名 +{プロジェクト名} + +### プロジェクトの目的 +{プロジェクトの目的・概要} + +**参照元**: {README.md または CLAUDE.md のパス} + +## 技術スタック + +### 使用技術・フレームワーク +- **言語**: {プログラミング言語} +- **フレームワーク**: {使用フレームワーク} +- **ランタイム**: {Node.js, Python等} +- **パッケージマネージャー**: {npm, yarn, pip等} + +### アーキテクチャパターン +- **アーキテクチャスタイル**: {MVC, クリーンアーキテクチャ, マイクロサービス等} +- **設計パターン**: {使用している設計パターン} +- **ディレクトリ構造**: {プロジェクトの構造} + +**参照元**: +- [CLAUDE.md](CLAUDE.md) +- [architecture.md](docs/design/architecture.md) + +## 開発ルール + +### プロジェクト固有のルール +{プロジェクト固有の開発ルール} + +### コーディング規約 +- **命名規則**: {命名規則の詳細} +- **型チェック**: {TypeScript strict mode等} +- **コメント**: {コメントのルール} +- **フォーマット**: {Prettier, ESLint等の設定} + +### テスト要件 +- **テストフレームワーク**: {Jest, Pytest等} +- **カバレッジ要件**: {最低カバレッジ率} +- **テストパターン**: {AAA, Given-When-Then等} + +**参照元**: +- [AGENTS.md](AGENTS.md) +- [docs/rule/](docs/rule/) +- [docs/rule/kairo/](docs/rule/kairo/) + +## 既存の要件定義 + +### 要件定義書 +{既存の要件定義の要約} + +**参照元**: +- [requirements.md](docs/spec/{要件名}-requirements.md) +- [user-stories.md](docs/spec/{要件名}-user-stories.md) +- [acceptance-criteria.md](docs/spec/{要件名}-acceptance-criteria.md) + +### 主要な機能要件（EARS記法） +- REQ-001: {要件の概要} +- REQ-002: {要件の概要} +- ... + +### 主要な非機能要件 +- NFR-001: {パフォーマンス要件} +- NFR-101: {セキュリティ要件} +- ... + +## 既存の設計文書 + +### アーキテクチャ設計 +{アーキテクチャの要約} + +**参照元**: [architecture.md](docs/design/architecture.md) + +### データフロー +{データフローの要約} + +**参照元**: [dataflow.md](docs/design/dataflow.md) + +### TypeScript型定義 +{主要な型定義の要約} + +**参照元**: [interfaces.ts](docs/design/interfaces.ts) + +### データベース設計 +{DBスキーマの要約} + +**参照元**: [database-schema.sql](docs/design/database-schema.sql) + +### API仕様 +{APIエンドポイントの要約} + +**参照元**: [api-endpoints.md](docs/design/api-endpoints.md) + +## 関連実装 + +### 類似機能の実装例 +{既存の類似実装の参照先} + +**参照元**: +- [{ファイルパス1}]({ファイルパス1}) +- [{ファイルパス2}]({ファイルパス2}) + +### 参考パターン +{実装パターンの要約} + +### 共通モジュール・ユーティリティ +{使用可能な共通機能} + +**参照元**: +- [{ユーティリティファイル1}]({ユーティリティファイル1}) +- [{ユーティリティファイル2}]({ユーティリティファイル2}) + +### 依存関係・インポートパス +{重要な依存関係の情報} + +## 技術的制約 + +### パフォーマンス制約 +- {パフォーマンス要件の詳細} + +### セキュリティ制約 +- {セキュリティ要件の詳細} + +### 互換性制約 +- {ブラウザ互換性、バージョン制約等} + +### データ制約 +- {データサイズ、形式等の制約} + +**参照元**: [CLAUDE.md](CLAUDE.md) + +## 注意事項 + +### 開発時の注意点 +- {開発時に注意すべき事項} + +### デプロイ・運用時の注意点 +- {デプロイ・運用時の注意事項} + +### セキュリティ上の注意点 +- {セキュリティ関連の注意事項} + +### パフォーマンス上の注意点 +- {パフォーマンス関連の注意事項} + +## Git情報 + +### 現在のブランチ +{現在のブランチ名} + +### 最近のコミット +{最近のコミット履歴（抜粋）} + +### 開発状況 +{現在の開発状況のサマリー} + +## 収集したファイル一覧 + +### プロジェクト基本情報 +- [CLAUDE.md](CLAUDE.md) +- [README.md](README.md) +- [AGENTS.md](AGENTS.md) + +### 追加ルール +- [docs/rule/](docs/rule/) +- [docs/rule/kairo/](docs/rule/kairo/) + +### 要件定義・仕様書 +- [docs/spec/{要件名}-requirements.md](docs/spec/{要件名}-requirements.md) +- [docs/spec/{要件名}-user-stories.md](docs/spec/{要件名}-user-stories.md) +- [docs/spec/{要件名}-acceptance-criteria.md](docs/spec/{要件名}-acceptance-criteria.md) + +### 設計文書 +- [docs/design/architecture.md](docs/design/architecture.md) +- [docs/design/dataflow.md](docs/design/dataflow.md) +- [docs/design/interfaces.ts](docs/design/interfaces.ts) +- [docs/design/database-schema.sql](docs/design/database-schema.sql) +- [docs/design/api-endpoints.md](docs/design/api-endpoints.md) + +### 関連実装（オプション） +- [{実装ファイル1}]({実装ファイル1}) +- [{実装ファイル2}]({実装ファイル2}) + +--- + +**注意**: すべてのファイルパスはプロジェクトルートからの相対パスで記載しています。 + diff --git a/commands/kairo-tasks.md b/commands/kairo-tasks.md index 6ecc275..b13f4f5 100644 --- a/commands/kairo-tasks.md +++ b/commands/kairo-tasks.md @@ -1,12 +1,14 @@ --- -description: 設計文書に基づいて実装タスクを1日単位の粒度で分割し、1ヶ月単位のフェーズに整理します。各フェーズ毎に個別のタスクファイルを作成し、依存関係を考慮した適切な順序で管理します。 +description: 設計文書に基づいて実装タスクを1日単位の粒度で分割し、1ヶ月単位のフェーズに整理します。各タスクを個別ファイルで管理し、依存関係を考慮した適切な順序で管理します。 +allowed-tools: Read, Glob, Grep, Task, Write, Edit, TodoWrite, WebFetch, AskUserQuestion +argument-hint: [要件名] --- # kairo-tasks ## 目的 -設計文書に基づいて実装タスクを1日単位の粒度で分割し、1ヶ月単位のフェーズに整理する。各フェーズ毎に個別のタスクファイルを作成し、依存関係を考慮した適切な順序で管理する。 +設計文書に基づいて実装タスクを1日単位の粒度で分割し、1ヶ月単位のフェーズに整理する。各タスクを個別ファイルで作成し、依存関係を考慮した適切な順序で管理する。 ## 前提条件 @@ -14,127 +16,403 @@ description: 設計文書に基づいて実装タスクを1日単位の粒度で - 設計がユーザによって承認されている（または承認が省略されている） - `docs/tasks/` ディレクトリが存在する（なければ作成） - 思考は英語で実施。ファイルは日本語で記述 -- NEVER: task_id は　`TASK-{4桁の数字}` (例 TASK-0001 )にする +- task_id は `TASK-{4桁の数字}` (例 TASK-0001)にする -## 実行内容 +# context + +出力ディレクトリ="docs/tasks" +要件名={{requirement_name}} +作業規模={{work_scope}} +信頼性評価=[] + +# step + +- $ARGUMENTS がない場合、「引数に要件名を指定してください（例: ユーザー認証システム）」と言って終了する +- $ARGUMENTS の内容と context の内容をまとめてユーザに宣言する +- step2 を実行する + +## step2: 作業規模の確認 + +- AskUserQuestion ツールを使って作業規模を質問する： + - question: "このタスク分割の作業規模について教えてください" + - header: "作業規模" + - multiSelect: false + - options: + - label: "詳細タスク分割（推奨）" + description: "詳細な実装手順、包括的なテストケース、完全な依存関係分析、UI/UX要件含む" + - label: "軽量タスク分割" + description: "必要最小限のタスク定義、基本的な実装手順のみ、主要な依存関係のみ" + - label: "カスタム" + description: "含めたい項目を個別に選択" + +- ユーザーの選択を context の {{work_scope}} に保存 + +- カスタムを選択した場合は、AskUserQuestion ツールを使って以下を質問： + - question: "タスク定義に含める項目を選択してください（複数選択可）" + - header: "含める項目" + - multiSelect: true + - options: + - label: "詳細な実装手順" + description: "ステップバイステップの実装ガイド" + - label: "包括的なテストケース" + description: "単体・統合テストの詳細な定義" + - label: "UI/UX要件の詳細化" + description: "ローディング状態・エラー表示・モバイル対応等" + - label: "依存関係の詳細分析" + description: "タスク間の依存関係の詳細な分析" + +- step3 を実行する + +## step3: 開発コンテキストの準備 + +- **タスクノートの読み込み** + - `docs/spec/{要件名}/note.md` が存在する場合は読み込み + - 存在しない場合: + - Task ツールを使用して subagent_type: "general-purpose" で `/tsumiki:kairo-tasknote {要件名}` コマンドを実行してノートを生成 + - 生成されたノートファイルを読み込み + - ノートには技術スタック、開発ルール、関連実装、設計文書、注意事項が含まれる + +- **追加ルールの読み込み** + - `docs/rule` ディレクトリが存在する場合は読み込み + - `docs/rule/kairo` ディレクトリが存在する場合は読み込み + - `docs/rule/kairo/tasks` ディレクトリが存在する場合は読み込み + - 各ディレクトリ内のすべてのファイルを読み込み、追加ルールとして適用 + +- **技術スタック定義の読み込み** + - `docs/tech-stack.md` が存在する場合は読み込み + - 存在しない場合は `CLAUDE.md` から技術スタックセクションを読み込み + - どちらも存在しない場合は `.claude/commands/tech-stack.md` のデフォルト定義を使用 + +- **要件定義・設計文書の読み込み** + - `docs/spec/{要件名}-requirements.md` または `docs/spec/{要件名}/requirements.md` を読み込み + - `docs/design/{要件名}/architecture.md` を読み込み + - `docs/design/{要件名}/database-schema.sql` を読み込み + - `docs/design/{要件名}/api-endpoints.md` を読み込み + - `docs/design/{要件名}/interfaces.ts` を読み込み + - `docs/design/{要件名}/dataflow.md` を読み込み + - 読み込んだ技術スタック定義に基づいて実装技術を特定 + +- **既存タスクファイルの確認** + - @agent-symbol-searcher で既存タスクIDを検索し、見つかったタスクファイルをReadツールで読み込み + - 既存の`docs/tasks/{要件名}-TASK-*.md`ファイルをReadツールで読み込み + - 使用済みタスク番号（TASK-0000形式）を抽出 + - 新規タスクで重複しない番号を割り当て + +- step4 を実行する + +## step4: タスク分析とヒアリング + +作業規模に応じてヒアリング項目を調整。 +**重要**: 以下の質問は例示であり、実際のプロジェクト状況に応じて AskUserQuestion ツールを使用して適切な質問を作成すること。 + +### 詳細タスク分割の場合 + +以下のカテゴリごとに、設計文書から特定した具体的な課題・不明点について AskUserQuestion ツールで質問する： + +**タスク粒度の確認** +- 1日単位（8時間）のタスク粒度で問題ないか確認 +- より細かい分割が必要な場合は具体的な単位を質問 + +例: AskUserQuestion ツールで以下のように質問 +- question: "タスクの粒度について、1日（8時間）単位で問題ないでしょうか？" +- header: "タスク粒度" +- multiSelect: false +- options: + - label: "1日単位で問題ない" + description: "8時間単位のタスク分割" + - label: "より細かい分割が必要" + description: "半日（4時間）単位など、より細かい分割（その他で詳細を記入）" + +**実装優先順位の確認** +- 設計文書の実装順序について確認が必要な場合質問 +- 並行実行可能なタスクの優先順位について質問 +- フェーズ分割の基準について質問 + +**技術的制約の確認** +- 技術スタックの選択について確認が必要な場合質問 +- パフォーマンス要件の実装方法について質問 +- 外部システム連携のタイミングについて質問 + +**テスト要件の詳細化** +- 単体テストのカバレッジ目標について質問 +- 統合テストの実施範囲について質問 +- E2Eテストの実施タイミングについて質問 + +**UI/UX実装の詳細確認** +- ローディング状態の実装方針について質問 +- エラー表示の詳細について質問 +- モバイル対応の範囲について質問 +- アクセシビリティ要件の詳細について質問 + +### 軽量タスク分割の場合 + +**必須項目のみ確認** +AskUserQuestion ツールを使って、以下の項目について簡潔に質問: +- 主要なタスクの実行順序の確認 +- 基本的な依存関係の確認 +- 最低限のテスト要件確認 + +### カスタムの場合 + +step2 で選択した項目に関連するヒアリングのみ実施。 +AskUserQuestion ツールを使って、選択された項目に応じた質問を作成する。 + +**注意事項**: +- すべての質問を一度に投げるのではなく、文脈に応じて段階的に質問する +- ユーザーの回答を受けて、必要に応じて追加質問を行う +- 質問は具体的で、はい/いいえで答えられるか、選択肢から選べる形式にする +- 自由記述が必要な場合は「その他」オプションを用意する + +**ヒアリング記録の作成**: +- すべての質問と回答を記録する +- 各質問について、以下を記録： + - 質問内容 + - 質問日時 + - カテゴリ（タスク粒度/優先順位/技術制約/テスト要件/UI要件） + - 質問の背景（なぜこの質問が必要だったか） + - ユーザーからの回答 + - 信頼性への影響（この回答により信頼性レベルがどう変化したか） +- ヒアリング結果のサマリーを作成 + +- step5 を実行する + +## step5: タスク作成 + +**【重要】**: このステップでは、洗い出したすべてのタスクファイルを作成する必要があります。途中で止めないでください。 **【信頼性レベル指示】**: -各項目について、元の資料（EARS要件定義書・設計文書含む）との照合状況を以下の信号でコメントしてください： - -- 🔵 **青信号**: EARS要件定義書・設計文書を参考にしてほぼ推測していない場合 -- 🟡 **黄信号**: EARS要件定義書・設計文書から妥当な推測の場合 -- 🔴 **赤信号**: EARS要件定義書・設計文書にない推測の場合 - -1. **追加ルールの読み込み** - - `docs/rule` ディレクトリが存在する場合は読み込み - - `docs/rule/kairo` ディレクトリが存在する場合は読み込み - - `docs/rule/kairo/tasks` ディレクトリが存在する場合は読み込み - - 各ディレクトリ内のすべてのファイルを読み込み、追加ルールとして適用 - -2. **技術スタック定義の読み込み** - - `docs/tech-stack.md` が存在する場合は読み込み - - 存在しない場合は `CLAUDE.md` から技術スタックセクションを読み込み - - どちらも存在しない場合は `.claude/commands/tech-stack.md` のデフォルト定義を使用 - -3. **設計文書の分析** - - @agent-symbol-searcher で設計文書を検索し、見つかったファイルをReadツールで読み込み - - `docs/design/{要件名}/architecture.md` をReadツールで読み込み - - `docs/design/{要件名}/database-schema.sql` をReadツールで読み込み - - `docs/design/{要件名}/api-endpoints.md` をReadツールで読み込み - - `docs/design/{要件名}/interfaces.ts` をReadツールで読み込み - - `docs/design/{要件名}/dataflow.md` をReadツールで読み込み - - 読み込んだ技術スタック定義に基づいて実装技術を特定 - -4. **既存タスクファイルの確認** - - @agent-symbol-searcher で既存タスクIDを検索し、見つかったタスクファイルをReadツールで読み込み - - 既存の`docs/tasks/{要件名}-*.md`ファイルをReadツールで読み込み - - 使用済みタスク番号（TASK-0000形式）を抽出 - - 新規タスクで重複しない番号を割り当て - -5. **タスクの洗い出し** - - 基盤タスク（DB設定、環境構築など） - - バックエンドタスク（API実装） - - フロントエンドタスク（UI実装） - - 画面のグループ毎に細かく分割する - - 統合タスク（E2Eテストなど） - -6. **依存関係の分析** - - タスク間の依存関係を明確化 - - 並行実行可能なタスクを識別 - - クリティカルパスを特定 - -7. **タスクの詳細化** - 各タスクに以下を含める： - - タスクID（TASK-0000形式） - - タスク名 - - タスクタイプ（TDD/DIRECT） - - **TDD**: コーディング、ビジネスロジック実装、UI実装、テスト実装など開発作業 - - **DIRECT**: 環境構築、設定ファイル作成、ドキュメント作成、ビルド設定など準備作業 - - 要件へのリンク - - 依存タスク - - 実装詳細 - - 単体テスト要件 - - 統合テスト要件 - - UI/UX要件（該当する場合） - - ローディング状態 - - エラー表示 - - モバイル対応 - - アクセシビリティ要件 - -8. **タスクの順序付け** - - 依存関係に基づいて実行順序を決定 - - マイルストーンを設定 - - 並行実行可能なタスクをグループ化 - -9. **フェーズ分割** - - 各タスクを1日単位の粒度で設計 - - タスクを1ヶ月(20日想定)以内の期間でフェーズに分割 - - NEVER タスクの情報の省略 - - YOU MUST 180時間を超えるようなフェーズは分割する - - IMPORTANT フェーズ数は固定しない - - IMPORTANT フェーズは500行未満で分割する - - YOU MUST フェーズの分割はアーキテクチャのレイヤーを基準にする - - NEVER 事前検討した分割基準を前提としない - -10. **ファイル作成** - - ファイル作成は ファイル毎に @task で実行する - - 各フェーズ毎に個別のタスクファイルを日本語で作成 - - NEVER タスクの情報の省略 - - `docs/tasks/{要件名}-phase1.md`: フェーズ1の詳細タスク - - `docs/tasks/{要件名}-phase2.md`: フェーズ2の詳細タスク - - （以下、フェーズ数に応じて継続） - - `docs/tasks/{要件名}-overview.md`: 全体概要とフェーズ一覧 - - 各タスクにチェックボックスを追加してタスクの完了状況を追跡可能にする - - 各タスクには 要件名 の定義を含める - -## 出力ファイル構造 - -作成するファイル: -- `docs/tasks/{要件名}-overview.md`: 全体概要とフェーズ一覧 -- `docs/tasks/{要件名}-phase1.md`: フェーズ1詳細タスク -- `docs/tasks/{要件名}-phase2.md`: フェーズ2詳細タスク -- （フェーズ数に応じて継続） - -## 必須構成要素 - -### Overview.mdの必須項目 -- プロジェクト概要（期間・工数・総タスク数） -- フェーズ構成テーブル（期間・成果物・タスク数・工数・ファイルリンク） -- 既存タスク番号管理（使用済み番号・次回開始番号） -- 全体進捗チェックボックス -- マイルストーン定義 - -### Phase.mdの必須項目 -- フェーズ概要（期間・目標・成果物） -- 週次計画（Week 1-4の目標・成果物） -- 日次タスク（TASK-0000形式、8時間単位） -- 各タスクの詳細構成: - - タスク完了チェックボックス - - 推定工数・タスクタイプ（TDD/DIRECT） - - 要件リンク・依存タスク - - 要件名 - - 実装詳細・完了条件 - - テスト要件（TDDタスクの場合） +各項目について、元の資料（要件定義書・設計文書・ユーザヒアリング含む）との照合状況を以下の信号でコメントしてください： + +- 🔵 **青信号**: 要件定義書・設計文書・ユーザヒアリングを参考にしてほぼ推測していない場合 +- 🟡 **黄信号**: 要件定義書・設計文書・ユーザヒアリングから妥当な推測の場合 +- 🔴 **赤信号**: 要件定義書・設計文書・ユーザヒアリングにない推測の場合 + +### 5.1 タスクの洗い出し + +設計文書に基づいて、以下のカテゴリでタスクを洗い出す： + +- 基盤タスク（DB設定、環境構築など） +- バックエンドタスク（API実装） +- フロントエンドタスク（UI実装） + - 画面のグループ毎に細かく分割する +- 統合タスク（E2Eテストなど） + +**洗い出しの記録**: +- 洗い出したタスクの総数を記録する +- 各カテゴリごとのタスク数を記録する +- この総数が、step5.6で作成するファイル数と一致する必要がある + +### 5.2 依存関係の分析 + +- タスク間の依存関係を明確化 +- 並行実行可能なタスクを識別 +- クリティカルパスを特定 + +### 5.3 タスクの詳細化 + +各タスクに以下を含める： +- タスクID（TASK-0000形式） +- タスク名 +- タスクタイプ（TDD/DIRECT） + - **TDD**: コーディング、ビジネスロジック実装、UI実装、テスト実装など開発作業 + - **DIRECT**: 環境構築、設定ファイル作成、ドキュメント作成、ビルド設定など準備作業 +- 要件へのリンク +- 依存タスク +- 実装詳細（信頼性レベル付き） +- 単体テスト要件（信頼性レベル付き） +- 統合テスト要件（信頼性レベル付き） +- UI/UX要件（該当する場合、信頼性レベル付き） + - ローディング状態 + - エラー表示 + - モバイル対応 + - アクセシビリティ要件 +- タスク全体の信頼性レベル評価 + +### 5.4 タスクの順序付け + +- 依存関係に基づいて実行順序を決定 +- マイルストーンを設定 +- 並行実行可能なタスクをグループ化 + +### 5.5 フェーズ分割 + +- 各タスクを1日単位の粒度で設計 +- タスクを1ヶ月(20日想定)以内の期間でフェーズに分割 + - フェーズは180時間以内を目標にする + - フェーズの分割はアーキテクチャのレイヤーを基準にする + - 事前検討した分割基準を前提としない + +### 5.6 個別タスクファイルの作成 + +- **重要**: 各タスクを個別ファイルで作成 +- **必須**: step5.1で洗い出したすべてのタスクファイルを作成する（途中で止めない） +- **フェーズ別並列処理**: フェーズ毎にTaskツールを使い、複数フェーズを並列実行して効率的にファイルを作成する +- 作業規模に応じた を選択： + - 詳細タスク分割: + - 軽量タスク分割: + - カスタム: 選択項目に応じた組み合わせ + +- **作成プロセス**: + 1. step5.1で洗い出した全タスクリストを確認 + 2. 洗い出した全タスク情報（タスクID、タスク名、タイプ、工数、フェーズ、依存関係、実装詳細、テスト要件等）をフェーズ別に整理 + 3. **フェーズ毎に並列でTaskツールを実行** (1つのメッセージで複数のTask tool callsを送信): + - Phase 1タスク用のTask tool call + - Phase 2タスク用のTask tool call + - Phase 3タスク用のTask tool call + - Phase 4タスク用のTask tool call + - (フェーズ数に応じて調整) + 4. 各Task tool callには以下を含む詳細なプロンプトを指定： + - 該当フェーズのタスクリスト（タスク番号、タスク名、タイプ、依存関係等） + - 各タスクの詳細情報（実装詳細、テスト要件、UI/UX要件等） + - 使用するテンプレート（または） + - ファイル出力先: `docs/tasks/{要件名}/TASK-XXXX.md` + - 信頼性レベルの付与ルール + - 注意事項: "このフェーズのすべてのタスクファイルを作成すること。途中で止めないこと。" + 5. すべてのTaskツールの実行完了を待つ + 6. 作成されたファイル数と洗い出したタスク数が一致することを確認 + +- 各タスクファイルには以下を含める： + - タスク全体の信頼性レベル（🔵🟡🔴） + - 実装詳細の各項目に信頼性レベル（🔵🟡🔴） + - テスト要件の各項目に信頼性レベル（🔵🟡🔴） + - ファイル末尾に信頼性レベルサマリー + - 関連文書へのリンク（overview、要件定義、設計文書） + +- **チェックポイント**: + - 洗い出したタスク数: {N}件 + - 作成したファイル数: {N}件 + - フェーズ別作成数の確認（Phase 1: X件, Phase 2: Y件, ...） + - すべてのタスクファイルが作成されたことを確認 + +**重要**: +- 各Taskツールに渡すプロンプトには、該当フェーズの全タスクの完全な情報を含めること +- エージェントが追加のコンテキスト収集なしで全ファイルを作成できるようにする +- 複数のフェーズのTask tool callsを1つのメッセージで送信し、並列実行を最大化する + +- step6 を実行する + +## step6: overview作成と完了報告 + +### 6.1 overviewファイルの作成 + +- 全タスクファイル作成後に overview を作成 +- 作成したタスクファイルの情報を集約 +- を使用してファイルを作成 +- `docs/tasks/{要件名}/overview.md` に出力 + +### 6.2 品質評価 + +作成したタスクファイルの内容について、品質判定基準に基づいて以下を評価： +- タスクの粒度の適切性 +- 依存関係の完全性 +- 実装可能性 +- 信頼性レベル（🔵🟡🔴の分布）- すべてのタスクファイルを通じて集計 + +品質判定結果をユーザーに表示する（全ファイル統合の信頼性レベル分布を含む） + +### 6.3 TODO更新 + +- TodoWrite ツールで TODO ステータスを更新する + - 現在のTODOを「completed」にマーク + - タスク分割フェーズの完了をTODO内容に反映 + - 次のフェーズ「タスク実装」をTODOに追加 + - 品質判定結果をTODO内容に記録 + +### 6.4 完了報告 + +完了報告を表示： +- step3で収集した開発コンテキスト情報のサマリー +- step4でのヒアリング結果と設計文書との差分 +- **作成ファイル数の確認**: + - 洗い出したタスク総数: {N}件 + - 作成したタスクファイル数: {N}件 + - overviewファイル: 1件 + - ✅ すべてのタスクファイルが作成されたことを確認 +- 作成したファイルのパス一覧（overview.md、各タスクファイル） +- 各タスクファイルの信頼性レベル分布 +- 全体の信頼性レベル分布（すべてのタスクファイルを通じた集計） +- タスク総数、推定工数、フェーズ数 +- 各ファイル内のリンクが正しく設定されていることを確認 + +次のステップ表示: 「次のお勧めステップ: `/tsumiki:kairo-implement` でタスクを実装します。特定のタスクを実装する場合は `/tsumiki:kairo-implement TASK-0001` のように指定してください。」 + +# rules + +## ファイル名のルール + +### 出力ファイルのパス形式 +- `docs/tasks/{要件名}/overview.md` +- `docs/tasks/{要件名}/TASK-0001.md` (1ファイル1タスク) +- `docs/tasks/{要件名}/TASK-0002.md` +- （全タスク分） + +### ファイル名の命名規則 +- 要件名を簡潔な英語に変換する +- ケバブケース（kebab-case）を使用 +- 最大50文字程度に収める +- 例: + - "ユーザー認証システム" → "user-auth-system" + - "データエクスポート機能" → "data-export" + - "パスワードリセット" → "password-reset" + +## 品質判定基準 + +``` +✅ 高品質: +- タスク粒度: 適切（1日単位） +- 依存関係: 完全に定義 +- 実装可能性: 確実 +- 信頼性レベル: 🔵（青信号）が多い + +⚠️ 要改善: +- タスクに曖昧な部分がある +- 依存関係が不明確 +- 技術的制約が不明 +- 実装手順の確認が必要 +- 信頼性レベル: 🟡🔴（黄・赤信号）が多い +``` + +## TODO更新パターン + +``` +- 現在のTODOを「completed」にマーク +- タスク分割フェーズの完了をTODO内容に反映 +- 次のフェーズ「タスク実装」をTODOに追加 +- 品質判定結果をTODO内容に記録 +``` + +## 信頼性レベル指示 + +各項目について、元の資料（要件定義書・設計文書・ユーザヒアリング含む）との照合状況を以下の信号でコメントしてください： + +- 🔵 **青信号**: 要件定義書・設計文書・ユーザヒアリングを参考にしてほぼ推測していない場合 +- 🟡 **黄信号**: 要件定義書・設計文書・ユーザヒアリングから妥当な推測の場合 +- 🔴 **赤信号**: 要件定義書・設計文書・ユーザヒアリングにない推測の場合 + +## ファイルパスの記載ルール + +- **プロジェクトルートを基準とした相対パスを使用する** +- フルパス（絶対パス）は記載しない +- 例: + - ❌ `/Users/username/projects/myapp/src/utils/helper.ts` + - ✅ `src/utils/helper.ts` + +## 作業規模別の出力調整 + +### 詳細タスク分割 +- すべてのセクションを含む +- 詳細な実装手順作成 +- 包括的なテストケース作成 +- UI/UX要件を網羅 + +### 軽量タスク分割 +- 基本的なタスク定義のみ +- 主要な実装手順のみ +- 基本的なテスト要件のみ +- UI/UX要件は最低限 + +### カスタム +- 選択された項目のみ含める ## タスクプロセス定義 @@ -150,20 +428,526 @@ description: 設計文書に基づいて実装タスクを1日単位の粒度で 1. `/tsumiki:direct-setup` - 直接実装・設定 2. `/tsumiki:direct-verify` - 動作確認・品質確認 -## 実行フロー +# info + +## AskUserQuestion ツールの使用例 + +すべてのヒアリングは AskUserQuestion ツールを使用して行います。以下は具体的な使用例です。 + +### タスク粒度確認 + +``` +AskUserQuestion({ + questions: [{ + question: "タスクの粒度について、1日（8時間）単位で問題ないでしょうか？", + header: "タスク粒度", + multiSelect: false, + options: [ + { + label: "1日単位で問題ない", + description: "8時間単位のタスク分割" + }, + { + label: "より細かい分割が必要", + description: "半日（4時間）単位など" + } + ] + }] +}) +``` + +### 優先順位確認 + +``` +AskUserQuestion({ + questions: [{ + question: "以下のタスクグループの実装優先順位を教えてください", + header: "優先順位", + multiSelect: false, + options: [ + { + label: "基盤→バックエンド→フロントエンド", + description: "標準的な実装順序" + }, + { + label: "フロントエンド優先", + description: "UI/UXの早期確認を重視" + }, + { + label: "並行開発", + description: "可能な限り並行して開発" + } + ] + }] +}) +``` + +### テスト要件確認 + +``` +AskUserQuestion({ + questions: [{ + question: "単体テストのカバレッジ目標を教えてください", + header: "カバレッジ", + multiSelect: false, + options: [ + { + label: "80%以上", + description: "高いカバレッジを目指す" + }, + { + label: "60%以上", + description: "標準的なカバレッジ" + }, + { + label: "主要機能のみ", + description: "最小限のテスト" + } + ] + }] +}) +``` + +### 注意事項 + +- **header** は12文字以内の短いラベル +- **question** は明確で具体的な質問文 +- **options** は2-4個の選択肢 +- **multiSelect** は複数選択可能にする場合true +- ユーザーは常に「その他」を選択して自由記述できる（自動提供） + +# templates + + +# {要件名} タスク概要 + +**作成日**: {作成日時} +**プロジェクト期間**: {開始日} - {終了日}（{総日数}日） +**推定工数**: {総工数}時間 +**総タスク数**: {タスク数}件 + +## 関連文書 + +- **要件定義書**: [📋 requirements.md](../spec/{要件名}/requirements.md) +- **設計文書**: [📐 architecture.md](../design/{要件名}/architecture.md) +- **API仕様**: [🔌 api-endpoints.md](../design/{要件名}/api-endpoints.md) +- **データベース設計**: [🗄️ database-schema.sql](../design/{要件名}/database-schema.sql) +- **インターフェース定義**: [📝 interfaces.ts](../design/{要件名}/interfaces.ts) +- **データフロー図**: [🔄 dataflow.md](../design/{要件名}/dataflow.md) +- **コンテキストノート**: [📝 note.md](../spec/{要件名}/note.md) + +## フェーズ構成 + +| フェーズ | 期間 | 成果物 | タスク数 | 工数 | ファイル | +|---------|------|--------|----------|------|----------| +| Phase 1 | {期間} | {成果物} | {件数} | {工数}h | [TASK-0001~0010](#phase-1-基盤構築) | +| Phase 2 | {期間} | {成果物} | {件数} | {工数}h | [TASK-0011~0020](#phase-2-バックエンド実装) | +| Phase 3 | {期間} | {成果物} | {件数} | {工数}h | [TASK-0021~0030](#phase-3-フロントエンド実装) | +| Phase 4 | {期間} | {成果物} | {件数} | {工数}h | [TASK-0031~0040](#phase-4-統合テスト) | + +## タスク番号管理 + +**使用済みタスク番号**: TASK-0001 ~ TASK-{最終番号} +**次回開始番号**: TASK-{次の番号} + +## 全体進捗 + +- [ ] Phase 1: 基盤構築 +- [ ] Phase 2: バックエンド実装 +- [ ] Phase 3: フロントエンド実装 +- [ ] Phase 4: 統合テスト + +## マイルストーン + +- **M1: 基盤完成** ({日付}): データベース・環境構築完了 +- **M2: API完成** ({日付}): バックエンドAPI実装完了 +- **M3: UI完成** ({日付}): フロントエンド実装完了 +- **M4: リリース準備完了** ({日付}): 全テスト完了 + +--- + +## Phase 1: 基盤構築 + +**期間**: {期間} +**目標**: {目標} +**成果物**: {成果物} + +### タスク一覧 + +- [ ] [TASK-0001: {タスク名}](TASK-0001.md) - {推定工数}h ({タイプ}) 🔵 +- [ ] [TASK-0002: {タスク名}](TASK-0002.md) - {推定工数}h ({タイプ}) 🔵 +- [ ] [TASK-0003: {タスク名}](TASK-0003.md) - {推定工数}h ({タイプ}) 🟡 + +### 依存関係 + +``` +TASK-0001 → TASK-0002 +TASK-0001 → TASK-0003 +``` + +--- + +## Phase 2: バックエンド実装 + +**期間**: {期間} +**目標**: {目標} +**成果物**: {成果物} + +### タスク一覧 + +- [ ] [TASK-0011: {タスク名}](TASK-0011.md) - {推定工数}h ({タイプ}) 🔵 +- [ ] [TASK-0012: {タスク名}](TASK-0012.md) - {推定工数}h ({タイプ}) 🔵 + +### 依存関係 + +``` +TASK-0003 → TASK-0011 +TASK-0011 → TASK-0012 +``` + +--- + +## Phase 3: フロントエンド実装 + +**期間**: {期間} +**目標**: {目標} +**成果物**: {成果物} + +### タスク一覧 + +- [ ] [TASK-0021: {タスク名}](TASK-0021.md) - {推定工数}h ({タイプ}) 🔵 +- [ ] [TASK-0022: {タスク名}](TASK-0022.md) - {推定工数}h ({タイプ}) 🟡 + +### 依存関係 + +``` +TASK-0012 → TASK-0021 +TASK-0021 → TASK-0022 +``` + +--- + +## Phase 4: 統合テスト + +**期間**: {期間} +**目標**: {目標} +**成果物**: {成果物} + +### タスク一覧 + +- [ ] [TASK-0031: {タスク名}](TASK-0031.md) - {推定工数}h ({タイプ}) 🔵 +- [ ] [TASK-0032: {タスク名}](TASK-0032.md) - {推定工数}h ({タイプ}) 🔵 + +### 依存関係 + +``` +TASK-0022 → TASK-0031 +TASK-0031 → TASK-0032 +``` + +--- + +## 信頼性レベルサマリー + +### 全タスク統計 + +- **総タスク数**: {件数}件 +- 🔵 **青信号**: {件数}件 ({割合}%) +- 🟡 **黄信号**: {件数}件 ({割合}%) +- 🔴 **赤信号**: {件数}件 ({割合}%) + +### フェーズ別信頼性 + +| フェーズ | 🔵 青 | 🟡 黄 | 🔴 赤 | 合計 | +|---------|-------|-------|-------|------| +| Phase 1 | {件数} | {件数} | {件数} | {件数} | +| Phase 2 | {件数} | {件数} | {件数} | {件数} | +| Phase 3 | {件数} | {件数} | {件数} | {件数} | +| Phase 4 | {件数} | {件数} | {件数} | {件数} | + +**品質評価**: {高品質/要改善/要ヒアリング} + +## クリティカルパス + +``` +TASK-0001 → TASK-0002 → TASK-0011 → TASK-0012 → TASK-0021 → TASK-0031 → TASK-0032 +``` + +**クリティカルパス工数**: {工数}時間 +**並行作業可能工数**: {工数}時間 + +## 次のステップ + +タスクを実装するには: +- 全タスク順番に実装: `/tsumiki:kairo-implement` +- 特定タスクを実装: `/tsumiki:kairo-implement TASK-0001` + + + +# TASK-{タスク番号}: {タスク名} + +**タスクID**: TASK-{タスク番号} +**タスクタイプ**: {TDD/DIRECT} +**推定工数**: {工数}時間 +**フェーズ**: Phase {フェーズ番号} - {フェーズ名} +**信頼性レベル**: {🔵/🟡/🔴} *{出典}* + +## 関連文書 + +- **概要**: [📋 overview.md](overview.md) +- **要件定義**: [📋 requirements.md](../../spec/{要件名}/requirements.md) - {関連要件ID} +- **設計文書**: [📐 architecture.md](../../design/{要件名}/architecture.md) +- **API仕様**: [🔌 api-endpoints.md](../../design/{要件名}/api-endpoints.md) + +## タスク概要 + +{タスクの概要説明} + +## 依存タスク + +- **前提タスク**: [TASK-{番号}: {タスク名}](TASK-{番号}.md) +- **後続タスク**: [TASK-{番号}: {タスク名}](TASK-{番号}.md) + +## 完了条件 + +- [ ] {完了条件1} +- [ ] {完了条件2} +- [ ] {完了条件3} + +--- + +## 実装詳細 + +### 1. {実装項目1} 🔵 + +**信頼性**: 🔵 *設計文書 architecture.md より* + +{実装内容の詳細} + +**実装ファイル**: `{ファイルパス}` + +```typescript +// 実装例 +{コード例} +``` + +### 2. {実装項目2} 🟡 + +**信頼性**: 🟡 *設計文書から妥当な推測* + +{実装内容の詳細} + +**実装ファイル**: `{ファイルパス}` + +### 3. {実装項目3} 🔵 + +**信頼性**: 🔵 *API仕様書より* + +{実装内容の詳細} + +--- + +## 単体テスト要件 + +### テストケース1: {テストケース名} 🔵 + +**信頼性**: 🔵 *要件定義書 REQ-001 より* + +**Given**: {前提条件} +**When**: {実行条件} +**Then**: {期待結果} + +**テストファイル**: `{テストファイルパス}` + +```typescript +// テストコード例 +describe('{テスト対象}', () => { + it('{テストケース}', async () => { + // テスト実装 + }); +}); +``` + +### テストケース2: {テストケース名} 🟡 + +**信頼性**: 🟡 *既存実装から妥当な推測* + +**Given**: {前提条件} +**When**: {実行条件} +**Then**: {期待結果} + +--- + +## 統合テスト要件 + +### 統合テスト1: {テスト名} 🔵 + +**信頼性**: 🔵 *dataflow.md より* + +**テスト内容**: {テスト内容} +**期待結果**: {期待結果} + +--- + +## UI/UX要件 + +### ローディング状態 🔵 + +**信頼性**: 🔵 *要件定義書 NFR-201 より* + +- {ローディング状態の詳細} + +### エラー表示 🟡 + +**信頼性**: 🟡 *既存実装から妥当な推測* + +- {エラー表示の詳細} + +### モバイル対応 🔵 + +**信頼性**: 🔵 *要件定義書 NFR-202 より* + +- {モバイル対応の詳細} + +### アクセシビリティ 🔵 + +**信頼性**: 🔵 *要件定義書 NFR-203 より* + +- {アクセシビリティ要件の詳細} + +--- + +## 実装手順 + +### TDDタスクの場合 + +1. `/tsumiki:tdd-requirements TASK-{番号}` - 詳細要件定義 +2. `/tsumiki:tdd-testcases` - テストケース作成 +3. `/tsumiki:tdd-red` - テスト実装（失敗） +4. `/tsumiki:tdd-green` - 最小実装 +5. `/tsumiki:tdd-refactor` - リファクタリング +6. `/tsumiki:tdd-verify-complete` - 品質確認 + +### DIRECTタスクの場合 + +1. `/tsumiki:direct-setup` - 直接実装・設定 +2. `/tsumiki:direct-verify` - 動作確認・品質確認 + +--- + +## 注意事項 + +- {注意事項1} +- {注意事項2} + +--- + +## 信頼性レベルサマリー + +### 項目別信頼性 + +| カテゴリ | 🔵 青 | 🟡 黄 | 🔴 赤 | 合計 | +|---------|-------|-------|-------|------| +| 実装詳細 | {件数} | {件数} | {件数} | {件数} | +| 単体テスト | {件数} | {件数} | {件数} | {件数} | +| 統合テスト | {件数} | {件数} | {件数} | {件数} | +| UI/UX要件 | {件数} | {件数} | {件数} | {件数} | + +### 全体評価 + +- **総項目数**: {件数}項目 +- 🔵 **青信号**: {件数}項目 ({割合}%) +- 🟡 **黄信号**: {件数}項目 ({割合}%) +- 🔴 **赤信号**: {件数}項目 ({割合}%) + +**品質評価**: {高品質/要改善/要ヒアリング} + +**推測が多い項目**: {推測が多い項目のリスト} + + + +# TASK-{タスク番号}: {タスク名} + +**タスクID**: TASK-{タスク番号} +**タスクタイプ**: {TDD/DIRECT} +**推定工数**: {工数}時間 +**フェーズ**: Phase {フェーズ番号} - {フェーズ名} +**信頼性レベル**: {🔵/🟡/🔴} *{出典}* + +## 関連文書 + +- **概要**: [📋 overview.md](overview.md) +- **要件定義**: [📋 requirements.md](../../spec/{要件名}/requirements.md) - {関連要件ID} +- **設計文書**: [📐 architecture.md](../../design/{要件名}/architecture.md) + +## タスク概要 + +{タスクの概要説明} + +## 依存タスク + +- **前提タスク**: [TASK-{番号}](TASK-{番号}.md) +- **後続タスク**: [TASK-{番号}](TASK-{番号}.md) + +## 完了条件 + +- [ ] {完了条件1} +- [ ] {完了条件2} + +--- + +## 主要実装項目 + +### {実装項目1} 🔵 + +**信頼性**: 🔵 *{出典}* + +{実装内容} + +**実装ファイル**: `{ファイルパス}` + +### {実装項目2} 🟡 + +**信頼性**: 🟡 *{出典}* + +{実装内容} + +--- + +## 基本的なテスト要件 + +### {テストケース名} 🔵 + +**信頼性**: 🔵 *{出典}* + +- {テスト内容} + +--- + +## 実装手順 + +### TDDタスクの場合 + +1. `/tsumiki:tdd-requirements TASK-{番号}` - 詳細要件定義 +2. `/tsumiki:tdd-testcases` - テストケース作成 +3. `/tsumiki:tdd-red` - テスト実装（失敗） +4. `/tsumiki:tdd-green` - 最小実装 +5. `/tsumiki:tdd-refactor` - リファクタリング +6. `/tsumiki:tdd-verify-complete` - 品質確認 + +### DIRECTタスクの場合 + +1. `/tsumiki:direct-setup` - 直接実装・設定 +2. `/tsumiki:direct-verify` - 動作確認・品質確認 + +--- -1. **追加ルール読み込み**: `docs/rule` → `docs/rule/kairo` → `docs/rule/kairo/tasks` -2. **技術スタック読み込み**: `docs/tech-stack.md` → `CLAUDE.md` → `.claude/commands/tech-stack.md` -3. **設計文書分析**: @agent-symbol-searcher で検索後、Readツールで各ファイル読み込み -4. **既存タスク確認**: @agent-symbol-searcher + Readで使用済み番号抽出 -5. **タスク洗い出し**: 基盤→バックエンド→フロントエンド→統合の順 -6. **フェーズ分割**: 180時間・500行を超えない単位で分割 -7. **ファイル作成**: overview.md + phase*.md作成 +## 信頼性レベルサマリー -## 品質基準 +- **総項目数**: {件数}項目 +- 🔵 **青信号**: {件数}項目 ({割合}%) +- 🟡 **黄信号**: {件数}項目 ({割合}%) +- 🔴 **赤信号**: {件数}項目 ({割合}%) -- **フェーズ制限**: 180時間以内、500行未満 -- **タスク粒度**: 1日8時間単位 -- **番号管理**: TASK-0000形式、重複なし -- **完了条件**: 各タスクにチェックボックスと完了条件 -- **依存関係**: 前タスク完了後の実行順序明記 +**品質評価**: {高品質/要改善/要ヒアリング} + diff --git a/commands/start-server.md b/commands/start-server.md deleted file mode 100644 index ab65708..0000000 --- a/commands/start-server.md +++ /dev/null @@ -1,83 +0,0 @@ ---- -description: 開発環境のサーバを起動・管理するコマンドです。 ---- - -# 開発サーバ起動・管理 - -開発環境のサーバを起動・管理するコマンドです。 - -## サーバ起動確認・管理 - -開発開始前にサーバの状態を確認し、必要に応じて起動します： - -```bash -# 既存のViteサーバ確認 -ps aux | grep -E "vite.*--port 3000" | grep -v grep - -# サーバが起動していない場合は新規起動 -if ! ps aux | grep -E "vite.*--port 3000" | grep -v grep > /dev/null; then - echo "サーバが起動していません。開発サーバを起動します..." - npm run dev & - echo "サーバ起動中... 5秒待機します" - sleep 5 -else - echo "既存のサーバが見つかりました。そのまま利用します。" - ps aux | grep -E "vite.*--port 3000" | grep -v grep | awk '{print "PID: " $2 " - Viteサーバが既に起動中"}' -fi - -# サーバ動作確認 -echo "サーバ動作確認中..." -curl -s http://localhost:3000 > /dev/null && echo "✅ サーバは正常に動作しています" || echo "⚠️ サーバに接続できません" -``` - -## サーバ管理コマンド - -### サーバ状態確認 - -```bash -# 現在動作中のサーバプロセス確認 -ps aux | grep -E "vite.*--port 3000" | grep -v grep - -# ポート使用状況確認 -lsof -i :3000 -``` - -### サーバ停止 - -```bash -# Viteサーバの停止 -pkill -f "vite.*--port 3000" - -# 強制停止（上記で停止しない場合） -ps aux | grep -E "vite.*--port 3000" | grep -v grep | awk '{print $2}' | xargs kill -9 -``` - -### サーバ再起動 - -```bash -# サーバ停止 -pkill -f "vite.*--port 3000" - -# 少し待機 -sleep 2 - -# サーバ再起動 -npm run dev & - -# 起動確認 -sleep 5 -curl -s http://localhost:3000 > /dev/null && echo "✅ サーバは正常に動作しています" || echo "⚠️ サーバに接続できません" -``` - -## 使用場面 - -- TDD開発開始前の環境準備 -- サーバが停止している場合の復旧 -- サーバの状態確認が必要な場合 -- 開発環境のセットアップ時 - -## 注意事項 - -- ポート3000が他のプロセスに使用されている場合は、該当プロセスを終了してください -- サーバ起動後は、ブラウザで http://localhost:3000 にアクセスして動作確認できます -- バックグラウンドで起動したサーバは、作業終了時に適切に停止することを推奨します \ No newline at end of file diff --git a/commands/tdd-cycle-full.sh b/commands/tdd-cycle-full.sh deleted file mode 100755 index 2bb0b02..0000000 --- a/commands/tdd-cycle-full.sh +++ /dev/null @@ -1,158 +0,0 @@ -#!/bin/bash - -# TDD フルサイクル実行スクリプト -# Usage: ./tdd-cycle-full.sh - -# 開始時間記録 -START_TIME=$(date +%s) - -if [ $# -ne 1 ]; then - echo "Usage: $0 " - exit 1 -fi - -TEST_CASE_NAME=$1 - -# カラー定義 -RED='\033[0;31m' -GREEN='\033[0;32m' -BLUE='\033[0;34m' -YELLOW='\033[1;33m' -NC='\033[0m' # No Color - -# Claude コマンド共通設定 -ALLOWED_TOOLS="Write,Edit,Bash(npm:*),Bash(node:*)" -DISALLOWED_TOOLS="Bash(git *)" -VERIFY_ALLOWED_TOOLS="Write,Edit,Bash(npm:*),Bash(node:*),Bash(git status),Bash(git diff)" -VERIFY_DISALLOWED_TOOLS="Bash(git add),Bash(git commit),Bash(git push)" - -# TDDサイクル実行関数 -run_tdd_cycle() { - local test_case=$1 - - echo "🔴 RED フェーズ開始..." - if ! claude -p "/tsumiki:tdd-red $test_case 不足テストの追加実装" --allowedTools "$ALLOWED_TOOLS" --disallowedTools "$DISALLOWED_TOOLS"; then - echo -e "${RED}❌ RED フェーズ失敗${NC}" - exit 1 - fi - echo -e "${GREEN}✅ RED フェーズ完了${NC}" - - echo "🟢 GREEN フェーズ開始..." - if ! claude -p "/tsumiki:tdd-green $test_case" --allowedTools "$ALLOWED_TOOLS" --disallowedTools "$DISALLOWED_TOOLS"; then - echo -e "${RED}❌ GREEN フェーズ失敗${NC}" - exit 1 - fi - echo -e "${GREEN}✅ GREEN フェーズ完了${NC}" - - echo "🔵 REFACTOR フェーズ開始..." - if ! claude -p "/tsumiki:tdd-refactor $test_case" --allowedTools "$ALLOWED_TOOLS" --disallowedTools "$DISALLOWED_TOOLS"; then - echo -e "${RED}❌ REFACTOR フェーズ失敗${NC}" - exit 1 - fi - echo -e "${GREEN}✅ REFACTOR フェーズ完了${NC}" - - echo "🔍 VERIFY COMPLETE フェーズ開始..." - local verify_result - verify_result=$(claude -p "/tsumiki:tdd-verify-complete $test_case" --allowedTools "$VERIFY_ALLOWED_TOOLS" --disallowedTools "$VERIFY_DISALLOWED_TOOLS" 2>&1) - local verify_exit_code=$? - - if [ $verify_exit_code -ne 0 ]; then - echo -e "${RED}❌ VERIFY COMPLETE フェーズ失敗${NC}" - exit 1 - fi - - echo -e "${GREEN}✅ VERIFY COMPLETE フェーズ完了${NC}" - echo -e "${verify_result} - - # 結果の判定 - if echo "$verify_result" | grep -E "(完全性検証: 合格)" > /dev/null; then - echo -e "${GREEN}🎉 TDDサイクル完了${NC}: $test_case のTDDサイクルが正常に完了しました" - return 0 - elif echo "$verify_result" | grep -E "(未実装|品質基準に満たない|追加実装が必要)" > /dev/null; then - echo -e "${YELLOW}🔄 TDDサイクル継続${NC}: 品質基準に満たない項目が見つかりました。RED フェーズに戻ります..." - return 1 - else - echo -e "${YELLOW}⚠️ 判定結果が不明確です${NC}" - echo "--- VERIFY COMPLETE フェーズの出力 ---" - echo "$verify_result" - echo "--- 出力終了 ---" - echo "" - echo -e "${BLUE}以下から選択してください:${NC}" - echo "1) 完了として扱う（TDDサイクルを終了）" - echo "2) RED フェーズから継続する" - echo "3) スクリプトを終了する" - echo "" - - while true; do - read -p "選択 (1/2/3): " choice - case $choice in - 1) - echo -e "${GREEN}🎉 TDDサイクル完了${NC}: ユーザー判断により完了とします" - return 0 - ;; - 2) - echo -e "${YELLOW}🔄 TDDサイクル継続${NC}: ユーザー判断により RED フェーズに戻ります" - return 1 - ;; - 3) - echo -e "${BLUE}👋 スクリプトを終了します${NC}" - exit 0 - ;; - *) - echo "無効な選択です。1, 2, または 3 を入力してください。" - ;; - esac - done - fi -} - -# 完了時間表示関数 -show_completion_time() { - local exit_code=$1 - local end_time=$(date +%s) - local duration=$((end_time - START_TIME)) - local hours=$((duration / 3600)) - local minutes=$(((duration % 3600) / 60)) - local seconds=$((duration % 60)) - - printf "⏱️ 実行時間: " - if [ $hours -gt 0 ]; then - printf "%d時間%d分%d秒\n" $hours $minutes $seconds - elif [ $minutes -gt 0 ]; then - printf "%d分%d秒\n" $minutes $seconds - else - printf "%d秒\n" $seconds - fi - - printf "🕐 終了時刻: %s\n" "$(date +'%Y-%m-%d %H:%M:%S')" - - if [ $exit_code -eq 0 ]; then - echo -e "${GREEN}✅ 正常終了${NC}" - else - echo -e "${RED}❌ エラー終了${NC}" - fi -} - -# trap設定（エラー終了時にも時間表示） -trap 'show_completion_time $?' EXIT - -# メインループ -echo "TDD フルサイクル実行開始: $TEST_CASE_NAME" -max_cycles=5 -cycle_count=0 - -while [ $cycle_count -lt $max_cycles ]; do - cycle_count=$((cycle_count + 1)) - echo -e "${BLUE}=== サイクル $cycle_count 開始 ===${NC}" - - if run_tdd_cycle "$TEST_CASE_NAME"; then - echo -e "${GREEN}🎉 全体完了: TDDサイクルが正常に完了しました${NC}" - exit 0 - fi - - echo -e "${YELLOW}サイクル $cycle_count 完了、次のサイクルに進みます...${NC}" - echo "" -done - -echo -e "${RED}❌ 最大サイクル数($max_cycles)に達しました。手動で確認してください。${NC}" -exit 1 \ No newline at end of file diff --git a/commands/tdd-green.md b/commands/tdd-green.md index ab03a01..b3fadc0 100644 --- a/commands/tdd-green.md +++ b/commands/tdd-green.md @@ -1,37 +1,199 @@ --- description: TDDのGreenフェーズを実行します。失敗しているテストケースを通すための実装を行い、テストが成功することを確認します。 +allowed-tools: Read, Glob, Grep, Task, Write, Edit, TodoWrite +argument-hint: [要件名] [TASK-ID] --- - -# TDD Greenフェーズ（実装） - -TDDのGreenフェーズを実行します。 - -## 事前準備 - -開発コンテキストの準備を行います： - -1. **追加ルールの読み込み** +TDDのGreenフェーズを実行し、Redフェーズで作成したテストを通すための実装を行います。 + +# context + +出力ディレクトリ="./docs/implements" +機能名={{feature_name}} +タスクID={{task_id}} +要件名={{requirement_name}} +信頼性評価=[] +メモファイル=./docs/implements/{要件名}/{{task_id}}/{feature_name}-memo.md +要件定義ファイル=./docs/implements/{要件名}/{{task_id}}/{feature_name}-requirements.md +テストケースファイル=./docs/implements/{要件名}/{{task_id}}/{feature_name}-testcases.md +Redフェーズファイル=./docs/implements/{要件名}/{{task_id}}/{feature_name}-red-phase.md +Greenフェーズファイル=./docs/implements/{要件名}/{{task_id}}/{feature_name}-green-phase.md + +# step + +- $ARGUMENTS がない場合、「引数に要件名とTASK-IDを指定してください（例: ユーザー認証機能 TASK-0001）」と言って終了する +- $ARGUMENTS の内容と context の内容をまとめてユーザに宣言する +- step2 を実行する + +## step2: コンテキスト準備 + +開発コンテキストの準備を実行する： + +1. **既存の実装ドキュメントの確認** + - `./docs/implements/{要件名}/{{task_id}}/` ディレクトリ内の全てのMDファイルを確認 + - 特に以下のファイルを優先的に読み込み： + - `note.md` - タスクノート（技術スタック、開発ルール、関連実装） + - `{feature_name}-requirements.md` - 要件定義 + - `{feature_name}-testcases.md` - テストケース定義 + - `{feature_name}-red-phase.md` - Redフェーズのテスト記録 + - `{feature_name}-green-phase.md` - 既存のGreenフェーズ記録 + - `{feature_name}-memo.md` - 開発履歴メモ + - その他の関連MDファイル + - これらのファイルから既存の実装状況、設計判断、注意事項を把握 + +2. **追加ルールの読み込み** - `AGENTS.md` ファイルが存在する場合は読み込み - - `docs/rule` ディレクトリが存在する場合は読み込み - - `docs/rule/tdd` ディレクトリが存在する場合は読み込み - - `docs/rule/tdd/green` ディレクトリが存在する場合は読み込み + - `./docs/rule` ディレクトリが存在する場合は読み込み + - `./docs/rule/tdd` ディレクトリが存在する場合は読み込み + - `./docs/rule/tdd/green` ディレクトリが存在する場合は読み込み - 各ディレクトリ内のすべてのファイルを読み込み、追加ルールとして適用 -2. **@agent-symbol-searcher で実装関連情報を検索し、見つかったファイルを読み込み** +3. **@agent-symbol-searcher で実装関連情報を検索し、見つかったファイルを読み込み** - 既存の類似機能やユーティリティ関数を検索し、該当ファイルをReadツールで読み込み - 実装パターンやアーキテクチャガイドラインを特定し、設計文書をReadツールで読み込み - 依存関係やインポートパスを確認し、関連ファイルをReadツールで読み込み -3. **関連ファイルを直接読み込み** - - `docs/implements/{要件名}/{{task_id}}/{feature_name}-memo.md` - 既存の開発履歴を確認 - - `docs/implements/{要件名}/{{task_id}}/{feature_name}-requirements.md` - 要件定義を確認 - - `docs/implements/{要件名}/{{task_id}}/{feature_name}-testcases.md` - テストケース定義を確認 - - `docs/implements/{要件名}/{{task_id}}/{feature_name}-red-phase.md` - Redフェーズのテストを確認 +4. **関連する外部ファイルを直接読み込み** - 関連する設計文書やタスクファイルも必要に応じて読み込み + - プロジェクト全体の設計文書、アーキテクチャ文書など + +読み込み完了後、step3 を実行する + +## step3: 実装の実行 + +- **仕様との差異確認**: + - 実装前に要件定義ファイルとテストケースファイルの内容を精査 + - 現在の実装コードと仕様の間に差異を発見した場合： + 1. 差異の内容を具体的に特定 + 2. どちらが正しいか判断できない場合は AskUserQuestion ツールを使用してユーザに確認 + 3. 「仕様: [仕様の記述]」「実装: [実装の内容]」を明示して質問 + 4. ユーザの判断を待ってから実装を進める + +- の方針に従って実装を行う + - 読み込んだコンテキスト情報を活用 + - 信頼性レベル（🔵🟡🔴）を各実装に記載 + - 必須の日本語コメントを含める + - ファイルサイズを意識（800行制限） + - モック使用の制限を遵守 + +- @task でテストを実行し、結果を確認する + - 全てのテストが通ることを確認 + - 失敗した場合は原因を調査し、修正を繰り返す + - 既存のテストがエラーになった場合は仕様を元に適切に修正 + +- 実装内容について、品質判定基準に基づいて以下を評価： + - テスト成功状況 + - 実装のシンプルさ + - リファクタリング箇所の明確性 + - 機能的問題の有無 + - ファイルサイズ（800行制限） + - モック使用の適切性 + +- 品質判定結果をユーザーに表示する +- step4 を実行する + +## step4: ドキュメント更新 + +- **Green-phaseファイルの作成・更新**： + - 実装コードと設計内容を {{Greenフェーズファイル}} に保存 + - 既存ファイルがある場合は追記 + - 以下の内容を記録： + - 実装したコードの全文 + - 実装方針と判断理由 + - テスト実行結果 + - 課題・改善点（Refactorフェーズで対応） + +- **メモファイルの更新**： + - {{メモファイル}} のGreenフェーズセクションを更新 + - 既存のメモファイルがない場合は新規作成（TDDメモファイル形式に従う） + - 以下の内容を記録： + - 実装日時 + - 実装方針 + - 実装コード + - テスト結果 + - 課題・改善点 + +- step5 を実行する + +## step5: TODO更新と次ステップ判定 + +- TodoWrite ツールで TODO ステータスを更新する + - 現在のTODO「Greenフェーズ（最小実装）」を「completed」にマーク + - 最小実装フェーズの完了をTODO内容に反映 + - 品質判定結果をTODO内容に記録 + - 次のフェーズ「Refactorフェーズ（品質改善）」をTODOに追加 + +- **自動遷移判定**: 以下の条件を満たす場合は自動で `/tsumiki:tdd-refactor {要件名} {TASK-ID}` を実行 + - Taskツールを使用して全てのテストが成功していることを確認済み + - 実装がシンプルで理解しやすい + - 明らかなリファクタリング箇所がある + - 機能的な問題がない + +- **手動確認**: 自動遷移条件を満たさない場合は以下を提供： + - 「Taskツールを使用してテストが通ったことを確認しました。」 + - 「現在の実装: [簡潔な説明]」 + - 「実装に含めた日本語コメント: [コメントの目的と内容]」 + - 「リファクタリングの候補: [改善すべき点]」 + - 「次のRefactorフェーズに進んでよろしいですか？」 + +# rules + +## 実装の原則 + +- **仕様との整合性確認が最優先** +- 実装前に必ず仕様（要件定義・テストケース）と現在の実装を照合する +- 差異を発見した場合は独断で進めず、AskUserQuestion ツールでユーザに確認を求める +- **テストが確実に通ること最優先** +- コードの美しさは二の次（次のRefactorフェーズで改善） +- 「とりあえず動く」レベルでOK +- 複雑なロジックは後回し、シンプルな実装を心がける +- テストがなかなか通らないときは、Taskツールを使用して失敗原因を調べてから修正の計画を立てて実装する +- 既存のテストがエラーになった場合は仕様を元に適切に修正する + +## 禁止事項（NEVER） + +- 必要なテストのスキップ禁止 +- 必要なテストの削除禁止 +- 実装コード内でのモック・スタブの記述禁止 +- 実装コード内でDBに代わるインメモリーストレージの利用禁止 +- 実装コード内でDB操作の省略禁止 + +## ファイルサイズ管理 + +- **800行制限**: 実装ファイルが800行を超えた時点でファイル分割を検討 +- **モジュール設計**: 機能単位でファイルを適切に分離 +- **関数分割**: 長大な関数は小さな単位に分割して実装 +- **責任境界**: 各ファイルの責任範囲を明確にして実装 +- **分割戦略**: 機能・レイヤー・ドメインでファイルを分離 + +## モック使用の制限 + +- **実装コード制限**: 実装コード内でモック・スタブを使用しない +- **テストコード限定**: モックはテストコード内でのみ使用 +- **実際のロジック実装**: 実装コードは実際の処理を記述する +- **依存関係注入**: 必要に応じて依存性注入パターンで実装 + +## 段階的実装のガイドライン -読み込み完了後、準備されたコンテキスト情報を基にGreenフェーズ（実装）の作業を開始します。 +1. **まず1つのテストケースだけ通す** + - 複数テストの同時対応は複雑化を招くため避ける + - 1つずつ確実に実装することで品質を担保 + +2. **最も簡単な方法で実装** + - 複雑なアルゴリズムは後のリファクタで追加 + - 可読性重視：現段階では理解しやすさを最優先 -**テスト実行時はTaskツールを利用する** +3. **コード品質基準の考慮** + - 静的解析対応：lintやtypecheckでエラーが出ない実装を心がける + - フォーマット統一：プロジェクトの既存フォーマットに合わせた実装 + - 命名規則遵守：プロジェクトの命名規則に従った実装 + +4. **他のテストケースは後回し** + - TDDの原則に従い、1ステップずつ進める + - 変更の影響を最小限に抑える + +5. **エラーハンドリングも最小限** + - テストで要求される部分のみ実装 + - リファクタ段階で詳細なエラー処理を追加予定 ## 信頼性レベル指示 @@ -41,31 +203,44 @@ TDDのGreenフェーズを実行します。 - 🟡 **黄信号**: 元の資料から妥当な推測の場合 - 🔴 **赤信号**: 元の資料にない推測の場合 -## 目標 +## 品質判定基準 -Redフェーズで作成したテストを通すための**実装**を行ってください。 +``` +✅ 高品質: +- テスト結果: Taskツールによる実行で全て成功 +- 実装品質: シンプルかつ動作する +- リファクタ箇所: 明確に特定可能 +- 機能的問題: なし +- コンパイルエラー: なし +- ファイルサイズ: 800行以下または分割計画が明確 +- モック使用: 実装コードにモック・スタブが含まれていない -## 実装の原則 +⚠️ 要改善: +- テストの一部が失敗（Taskツールで検出） +- 実装が複雑すぎる +- リファクタ方針が不明 +- 機能に懸念がある +- コンパイルエラーが存在 +- ファイルサイズが800行を超過し分割計画が不明 +- 実装コードにモック・スタブが含まれている +``` -- **テストが確実に通ること最優先** -- コードの美しさは二の次（次のRefactorフェーズで改善） -- 「とりあえず動く」レベルでOK -- 複雑なロジックは後回し、シンプルな実装を心がける -- テストがなかなか通らないときは、Taskツールを使用して失敗原因を調べてから修正の計画を立てて実装する -- 既存のテストがエラーになった場合は仕様を元に適切に修正する -- **モック使用の制限**: テストコード以外でモックを記述しない（実装コードは実際のロジックを書く） -- **ファイルサイズ管理**: 実装ファイルが800行を超えた時点でファイル分割を検討する -- NEVER: 必要なテストのスキップ禁止 -- NEVER: 必要なテストの削除禁止 -- NEVER: 実装コード内でのモック・スタブの記述禁止 -- NEVER: 実装コード内でDBに代わるインメモリーストレージの利用禁止 -- NEVER: 実装コード内でDB操作の省略禁止 +## ファイルパスの記載ルール + +- **プロジェクトルートを基準とした相対パスを使用する** +- フルパス（絶対パス）は記載しない +- 例: + - ❌ `/Users/username/projects/myapp/src/utils/helper.ts` + - ✅ `src/utils/helper.ts` + +# info -## 実装時の日本語コメント要件 + +# 実装時の日本語コメント要件 実装コードには以下の日本語コメントを必ず含めてください： -### 関数・メソッドレベルのコメント +## 関数・メソッドレベルのコメント ```javascript /** @@ -81,7 +256,7 @@ function {{function_name}}(paramName) { } ``` -### 処理ブロックレベルのコメント +## 処理ブロックレベルのコメント ```javascript function processData(input) { @@ -104,7 +279,7 @@ function processData(input) { } ``` -### 変数・定数のコメント +## 変数・定数のコメント ```javascript // 【定数定義】: [この定数が必要な理由と使用目的] @@ -114,7 +289,7 @@ const MAX_FILE_SIZE = 1024 * 1024; // 【制限値】: ファイルサイズの let processedCount = 0; // 【カウンタ】: 処理済みファイル数を追跡するためのカウンタ ``` -### エラーハンドリングのコメント +## エラーハンドリングのコメント ```javascript try { @@ -130,7 +305,7 @@ try { } ``` -## 実装例 +# 実装例 ```javascript /** @@ -151,37 +326,7 @@ function {{function_name}}(input) { } ``` -## 段階的実装のガイドライン - -1. **まず1つのテストケースだけ通す** - - 【実装戦略】: 複数テストの同時対応は複雑化を招くため避ける - - 【品質確保】: 1つずつ確実に実装することで品質を担保 -2. **最も簡単な方法で実装** - - 【シンプル実装】: 複雑なアルゴリズムは後のリファクタで追加 - - 【可読性重視】: 現段階では理解しやすさを最優先 -3. **ファイルサイズを意識した実装** - - 【800行制限】: 実装ファイルが800行を超えた時点で分割を検討 - - 【モジュール設計】: 機能単位でファイルを適切に分離 - - 【関数分割】: 長大な関数は小さな単位に分割して実装 - - 【責任境界】: 各ファイルの責任範囲を明確にして実装 - - 【分割戦略】: 機能・レイヤー・ドメインでファイルを分離 -4. **コード品質基準の考慮** - - 【静的解析対応】: lintやtypecheckでエラーが出ない実装を心がける - - 【フォーマット統一】: プロジェクトの既存フォーマットに合わせた実装 - - 【命名規則遵守】: プロジェクトの命名規則に従った実装 -5. **他のテストケースは後回し** - - 【段階的開発】: TDDの原則に従い、1ステップずつ進める - - 【影響範囲限定】: 変更の影響を最小限に抑える -6. **エラーハンドリングも最小限** - - 【必要最小限】: テストで要求される部分のみ実装 - - 【将来拡張可能】: リファクタ段階で詳細なエラー処理を追加予定 -7. **モック使用の制限** - - 【実装コード制限】: 実装コード内でモック・スタブを使用しない - - 【テストコード限定】: モックはテストコード内でのみ使用 - - 【実際のロジック実装】: 実装コードは実際の処理を記述する - - 【依存関係注入】: 必要に応じて依存性注入パターンで実装 - -## 提供してください +# 提供する情報 1. **実装コード**: テストを通すコード（必須の日本語コメント付き） 2. **テスト実行結果**: Taskツールを使用して実際にテストが通ることの確認 @@ -189,55 +334,4 @@ function {{function_name}}(input) { 4. **課題の特定**: 現在の実装の問題点（リファクタ対象の明確化） 5. **ファイルサイズチェック**: 実装ファイルの行数確認（800行超過時の分割計画） 6. **モック使用確認**: 実装コードにモック・スタブが含まれていないことの確認 - -実装完了後、以下を実行してください： - -1. **メモファイル更新**: `docs/implements/{要件名}/{{task_id}}/{feature_name}-memo.md` ファイルのGreenフェーズセクションを更新 - - 実装方針、実装コード、テスト結果、課題・改善点を記録 - - 次のRefactorフェーズで参照できるよう詳細に記録 -2. 実装コードと設計内容を `docs/implements/{要件名}/{{task_id}}/{feature_name}-green-phase.md` に保存（既存ファイルがある場合は追記） -3. TODOステータスを更新（Greenフェーズ完了をマーク） -4. **自動遷移判定**: 以下の条件を満たす場合は自動で `/tdd-refactor` を実行 - - Taskツールを使用して全てのテストが成功していることを確認済み - - 実装がシンプルで理解しやすい - - 明らかなリファクタリング箇所がある - - 機能的な問題がない -5. **手動確認**: 自動遷移条件を満たさない場合は以下を提供してください： - - 「Taskツールを使用してテストが通ったことを確認しました。」 - - 「現在の実装: [簡潔な説明]」 - - 「実装に含めた日本語コメント: [コメントの目的と内容]」 - - 「リファクタリングの候補: [改善すべき点]」 - - 「次のRefactorフェーズに進んでよろしいですか？」 - -## 品質判定基準 - -``` -✅ 高品質: -- テスト結果: Taskツールによる実行で全て成功 -- 実装品質: シンプルかつ動作する -- リファクタ箇所: 明確に特定可能 -- 機能的問題: なし -- コンパイルエラー: なし -- ファイルサイズ: 800行以下または分割計画が明確 -- モック使用: 実装コードにモック・スタブが含まれていない - -⚠️ 要改善: -- テストの一部が失敗（Taskツールで検出） -- 実装が複雑すぎる -- リファクタ方針が不明 -- 機能に懸念がある -- コンパイルエラーが存在 -- ファイルサイズが800行を超過し分割計画が不明 -- 実装コードにモック・スタブが含まれている -``` - -## TODO更新パターン - -``` -- 現在のTODO「Greenフェーズ（最小実装）」を「completed」にマーク -- 最小実装フェーズの完了をTODO内容に反映 -- 品質判定結果をTODO内容に記録 -- 次のフェーズ「Refactorフェーズ（品質改善）」をTODOに追加 -``` - -次のステップ: `/tdd-refactor` でコードの品質を改善します。 + diff --git a/commands/tdd-load-context.md b/commands/tdd-load-context.md deleted file mode 100644 index 7b3a720..0000000 --- a/commands/tdd-load-context.md +++ /dev/null @@ -1,120 +0,0 @@ ---- -description: TDD関連ファイル読み込み・コンテキスト準備を行います (非推奨) ---- - -# TDD関連ファイル読み込み・コンテキスト準備 (非推奨) - -**注意**: このコマンドは非推奨です。他のTDDコマンドでは@agent-symbol-searcherとReadツールを直接使用してコンテキストを準備します。 - -以下は参考情報として保持しています。 - -## 実行タスク - -以下の@agent-symbol-searcherとTaskツールによる並列読み込み・検索を実行します： - -### 0. **@agent-symbol-searcher で関連情報を検索** - - 対象機能に関連する既存シンボル・関数・クラスを検索 - - 類似機能の実装パターンやアーキテクチャを特定 - - TDD関連のツール・フレームワークの使用方法を確認 - -``` -1. 【読み込み】TDDメモファイルの確認 - - Readツール: `docs/implements/{要件名}/{{task_id}}/{feature_name}-memo.md` - - 既存の開発履歴、フェーズ情報、検証結果を把握 - -2. 【読み込み】要件定義文書の確認 - - Readツール: `docs/implements/{要件名}/{{task_id}}/{feature_name}-requirements.md` - - 機能仕様、入出力、制約条件を把握 - -3. 【読み込み】テストケース定義の確認 - - Readツール: `docs/implements/{要件名}/{{task_id}}/{feature_name}-testcases.md` - - 予定テストケース、分類、期待値を把握 - -4. 【探索のみ】プロジェクト設計文書の特定 - - Globツール: `docs/spec/{feature_name}-requirements.md` の存在確認 - - Globツール: `docs/design/{feature_name}/` ディレクトリ内ファイルの特定 - - 見つかったファイルパスを記録（読み込みは実行せず） - -5. 【探索のみ】プロジェクト構造・ライブラリファイルの特定 - - Globツール: `package.json` の存在確認 - - Globツール: 既存テストファイル構造の把握（`**/*test*.js`, `**/*spec*.js`等） - - Grepツール: 類似機能の実装パターン調査（関連キーワード検索） - - 見つかったファイルパスを記録（読み込みは実行せず） - -6. 【探索のみ】タスク管理文書の特定 - - Globツール: `docs/tasks/{要件名}-tasks.md` の存在確認 - - 見つかったファイルパスを記録（読み込みは実行せず） -``` - -## 読み込み結果の整理 - -読み込み・探索完了後、以下の形式で情報を整理します： - -### 📋 開発コンテキスト情報 - -```markdown -## TDD開発コンテキスト - -### 🎯 現在のフェーズ・状況 -- **対象機能**: {feature_name} -- **現在のTDDフェーズ**: [Requirements/TestCases/Red/Green/Refactor/Verify] -- **前回の完了フェーズ**: [前回完了したフェーズ] -- **今回の実行予定**: [実行すべき次のステップ] - -### 📄 要件・仕様情報 -- **機能概要**: [要件定義書から抽出した機能の概要] -- **入力仕様**: [入力パラメータの型・制約・範囲] -- **出力仕様**: [出力形式・構造・期待値] -- **制約条件**: [パフォーマンス・セキュリティ・技術制約] -- **参照EARS要件**: [REQ-XXX, NFR-XXX等の要件ID] - -### 🔧 技術・実装情報 -- **使用言語**: [JavaScript/TypeScript等] -- **テストフレームワーク**: [Jest/Mocha等] -- **関連ファイル**: [探索で見つかった関連ファイルパス一覧] -- **設計文書パス**: [見つかった設計文書のパス一覧] -- **類似実装パス**: [参考にできる既存実装のファイルパス] - -### 📈 進捗・品質情報 -- **全体タスク進捗**: [完了数]/[総数] ([%]) -- **前回の検証結果**: [合格/不合格/未実施] -- **品質課題**: [セキュリティ・パフォーマンス課題] -- **改善要求事項**: [前回記録された改善点] - -### ⚠️ 注意事項・制約 -- **技術的制約**: [アーキテクチャ・互換性制約] -- **実装時の注意点**: [前回記録された重要な注意事項] -- **未解決課題**: [継続対応が必要な課題] -``` - -## 信頼性レベル判定 - -読み込んだ各情報について信頼性レベルを判定： - -- 🔵 **青信号**: ファイルが存在し、詳細な情報が利用可能 -- 🟡 **黄信号**: ファイルが存在するが情報が部分的 -- 🔴 **赤信号**: ファイルが存在しない、または推測が必要 - -## 使用方法 - -各TDDコマンドの冒頭で以下のように使用： - -```markdown -## 事前準備 - -開発コンテキストの準備を行います： - -**Taskツール実行**: `/tsumiki:tdd-load-context` でTDD関連ファイルの読み込み・探索とコンテキスト準備を実行 - -読み込み完了後、準備されたコンテキスト情報を基に{現在のフェーズ}の作業を開始します。 -``` - -## 効果 - -- **効率化**: メモ・要件・テストケースは読み込み、その他は探索のみで時間短縮 -- **一貫性**: 全TDDフェーズで統一されたコンテキスト準備 -- **品質向上**: 必要情報の読み込み漏れ防止 -- **保守性**: ファイル読み込み・探索ロジックの一元管理 -- **軽量化**: 関連ファイルは特定のみで、必要に応じて個別に読み込み可能 - -このタスクにより、@agent-symbol-searcherでの検索結果と既存TDDファイルの情報を組み合わせ、TDD開発の各フェーズで必要な情報を効率的に準備できます。 \ No newline at end of file diff --git a/commands/tdd-red.md b/commands/tdd-red.md index 0548984..f120324 100644 --- a/commands/tdd-red.md +++ b/commands/tdd-red.md @@ -1,45 +1,151 @@ --- description: TDDのRedフェーズを実行します。失敗するテストケースを作成し、実装すべき機能を明確に定義します。 +allowed-tools: Read, Glob, Grep, Task, Write, TodoWrite, Edit +argument-hint: [要件名] [TASK-ID] --- - -# TDD Redフェーズ（失敗するテストを書く） - -TDDのRedフェーズを実行します。 - -## 事前準備 - -開発コンテキストの準備を行います： - -1. **追加ルールの読み込み** - - `AGENTS.md` ファイルが存在する場合は読み込み - - `docs/rule` ディレクトリが存在する場合は読み込み - - `docs/rule/tdd` ディレクトリが存在する場合は読み込み - - `docs/rule/tdd/red` ディレクトリが存在する場合は読み込み - - 各ディレクトリ内のすべてのファイルを読み込み、追加ルールとして適用 - -2. **技術スタック定義の読み込み** - - `docs/tech-stack.md` が存在する場合は読み込み - - 存在しない場合は `CLAUDE.md` から技術スタックセクションを読み込み - - どちらも存在しない場合は `.claude/commands/tech-stack.md` のデフォルト定義を使用 - -3. **@agent-symbol-searcher でテスト実装関連情報を検索し、見つかったファイルを読み込み** - - 読み込んだ技術スタック定義に基づいてテストフレームワークを特定 - - **UIタスクの場合**: E2Eテストフレームワーク（Playwright等）の設定とサンプルを優先的に確認 - - 既存のテストファイルやテスト関数を検索し、該当ファイルをReadツールで読み込み - - テストセットアップやモックの使用パターンを特定し、関連ファイルをReadツールで読み込み - - **E2Eテスト設定確認**: playwright.config.js、cypress.config.js等の設定ファイルをReadツールで読み込み - -4. **関連ファイルを直接読み込み** - - `docs/implements/{要件名}/{{task_id}}/{feature_name}-memo.md` - 既存の開発履歴を確認 - - `docs/implements/{要件名}/{{task_id}}/{feature_name}-requirements.md` - 要件定義を確認 - - `docs/implements/{要件名}/{{task_id}}/{feature_name}-testcases.md` - テストケース定義を確認 - - 関連する設計文書やタスクファイルも必要に応じて読み込み - -読み込み完了後、準備されたコンテキスト情報を基にRedフェーズ（失敗テスト作成）の作業を開始します。 - -## 対象テストケース - -**【対象テストケース】**: {{test_case_name}} +TDDのRedフェーズを実行します。失敗するテストケースを作成し、実装すべき機能を明確に定義します。 + +# context + +出力ディレクトリ="./docs/implements" +機能名={{feature_name}} +タスクID={{task_id}} +要件名={{requirement_name}} +対象テストケース={{test_case_name}} +テストケース追加目標数=10以上 +信頼性評価=[] +要件定義ファイル=./docs/implements/{要件名}/{{task_id}}/{feature_name}-requirements.md +テストケース定義ファイル=./docs/implements/{要件名}/{{task_id}}/{feature_name}-testcases.md +Redフェーズファイル=./docs/implements/{要件名}/{{task_id}}/{feature_name}-red-phase.md +メモファイル=./docs/implements/{要件名}/{{task_id}}/{feature_name}-memo.md +タスクノートファイル=./docs/implements/{要件名}/{{task_id}}/note.md + +# step + +- $ARGUMENTS がある場合は対象テストケース名として設定、ない場合は全テストケースを対象とする +- context の内容をまとめてユーザに宣言する +- step2 を実行する + +## step2 + +開発コンテキストの準備を実行する： + +**1. 既存の実装ドキュメントの確認** +- `./docs/implements/{要件名}/{{task_id}}/` ディレクトリ内の全てのMDファイルを確認 +- 特に以下のファイルを優先的に読み込み： + - `note.md` - タスクノート（技術スタック、開発ルール、関連実装） + - `{feature_name}-requirements.md` - 要件定義 + - `{feature_name}-testcases.md` - テストケース定義 + - `{feature_name}-red-phase.md` - 既存のRedフェーズ記録 + - `{feature_name}-memo.md` - 開発履歴メモ + - その他の関連MDファイル +- これらのファイルから既存の実装状況、設計判断、注意事項を把握 + +**2. 追加ルールの読み込み** +- `AGENTS.md` ファイルが存在する場合は読み込み +- `./docs/rule` ディレクトリが存在する場合は読み込み +- `./docs/rule/tdd` ディレクトリが存在する場合は読み込み +- `./docs/rule/tdd/red` ディレクトリが存在する場合は読み込み +- 各ディレクトリ内のすべてのファイルを読み込み、追加ルールとして適用 + +**3. 技術スタック定義の読み込み** +- `./docs/tech-stack.md` が存在する場合は読み込み +- 存在しない場合は `CLAUDE.md` から技術スタックセクションを読み込み +- どちらも存在しない場合は `.claude/commands/tech-stack.md` のデフォルト定義を使用 + +**4. タスクノートの読み込み** +- `./docs/implements/{要件名}/{{task_id}}/note.md` が既存ドキュメント確認でまだ読み込まれていない場合 +- 存在しない場合: + - @task で `/tsumiki:tdd-tasknote {要件名} {{task_id}}` コマンドを実行してノートを生成 + - 生成されたノートファイルを読み込み +- ノートには技術スタック、開発ルール、関連実装、設計文書、注意事項が含まれる + +**5. @agent-symbol-searcher でテスト実装関連情報を検索し、見つかったファイルを読み込み** +- 読み込んだ技術スタック定義に基づいてテストフレームワークを特定 +- **UIタスクの場合**: E2Eテストフレームワーク（Playwright等）の設定とサンプルを優先的に確認 +- 既存のテストファイルやテスト関数を検索し、該当ファイルをReadツールで読み込み +- テストセットアップやモックの使用パターンを特定し、関連ファイルをReadツールで読み込み +- **E2Eテスト設定確認**: playwright.config.js、cypress.config.js等の設定ファイルをReadツールで読み込み + +**6. 関連する外部ファイルを直接読み込み** +- 関連する設計文書やタスクファイルも必要に応じて読み込み +- プロジェクト全体の設計文書、アーキテクチャ文書など + +読み込み完了後、step3 を実行する + +## step3 + +- の内容を context の情報で埋めて、テストコードを作成する + - 読み込んだコンテキスト情報（タスクノート、追加ルール等）を活用 + - 信頼性レベル（🔵🟡🔴）を各テストケースに記載 + - 対象テストケース名が指定されている場合は、そのテストケースのみ実装 + - 指定がない場合は、未実装のテストケースから10個以上を選択して実装 + - Write ツールを使用してテストファイルに保存 + - Bash ツールを使用してテストを実行し、失敗することを確認 + +- 作成したテストコードについて、品質判定基準に基づいて以下を評価： + - テスト実行: 実行可能で失敗することを確認済み + - 期待値: 明確で具体的 + - アサーション: 適切 + - 実装方針: 明確 + - 信頼性レベル（🔵🟡🔴の分布） + +- 品質判定結果をユーザーに表示する +- step4 を実行する + +## step4: ドキュメント更新 + +- **Red-phaseファイルの作成・更新**： + - テストコードと設計内容を {{Redフェーズファイル}} に保存 + - 既存ファイルがある場合は追記 + - 以下の内容を記録： + - 作成したテストケースの一覧 + - テストコードの全文 + - 期待される失敗内容 + - Greenフェーズで実装すべき内容 + +- **メモファイルの作成・更新**： + - {{メモファイル}} にRedフェーズの内容を作成または追記 + - 既存のメモファイルがある場合は、Redフェーズセクションを更新 + - メモファイルが存在しない場合は新規作成（TDDメモファイル形式に従う） + - 以下の内容を記録： + - 作成日時 + - テストケースの概要 + - テストコード + - 期待される失敗 + - 次のフェーズへの要求事項 + +- step5 を実行する + +## step5: TODO更新と次ステップ + +- TodoWrite ツールで TODO ステータスを更新する + - 現在のTODO「Redフェーズ（失敗テスト作成）」を「completed」にマーク + - 失敗テスト作成フェーズの完了をTODO内容に反映 + - 品質判定結果をTODO内容に記録 + - 次のフェーズ「Greenフェーズ（最小実装）」をTODOに追加 + +- 次のステップ表示: 「次のお勧めステップ: `/tsumiki:tdd-green` でGreenフェーズ（最小実装）を開始します。」 + +# rules + +## ファイル名のルール + +### 出力ファイルのパス形式 +- テストファイル: プロジェクトの技術スタックに応じた適切なディレクトリ + - 例: `tests/unit/{feature_name}.test.js` + - 例: `tests/e2e/{feature_name}.spec.js` +- メモファイル: `docs/implements/{要件名}/{task_id}/{feature_name}-memo.md` +- Redフェーズ記録: `docs/implements/{要件名}/{task_id}/{feature_name}-red-phase.md` + +### ファイル名の命名規則 +- 機能名を簡潔な英語に変換する +- ケバブケース（kebab-case）を使用 +- 最大50文字程度に収める +- 例: + - "ユーザー認証機能" → "user-auth" + - "データエクスポート機能" → "data-export" + - "パスワードリセット機能" → "password-reset" ## テストケース追加目標数 @@ -58,13 +164,40 @@ NEVER テストケースの最大行数を500行を目標に分割してくだ - 🟡 **黄信号**: 元の資料から妥当な推測の場合 - 🔴 **赤信号**: 元の資料にない推測の場合 -## 要件 +## 品質判定基準 -- **使用言語/フレームワーク**: 読み込んだ技術スタック定義に基づく -- テストは必ず失敗する状態で作成 -- テスト名は分かりやすく日本語で記述 -- アサーション（期待値の検証）を明確に記述 -- まだ実装されていない関数・メソッドを呼び出す形で作成 +``` +✅ 高品質: +- テスト実行: 成功（失敗することを確認） +- 期待値: 明確で具体的 +- アサーション: 適切 +- 実装方針: 明確 +- 信頼性レベル: 🔵（青信号）が多い + +⚠️ 要改善: +- テストが実行できない +- 期待値が曖昧 +- 実装アプローチが不明 +- 複雑なテストケース +- 信頼性レベル: 🟡🔴（黄・赤信号）が多い +``` + +## TODO更新パターン + +``` +- 現在のTODO「Redフェーズ（失敗テスト作成）」を「completed」にマーク +- 失敗テスト作成フェーズの完了をTODO内容に反映 +- 品質判定結果をTODO内容に記録 +- 次のフェーズ「Greenフェーズ（最小実装）」をTODOに追加 +``` + +## ファイルパスの記載ルール + +- **プロジェクトルートを基準とした相対パスを使用する** +- フルパス（絶対パス）は記載しない +- 例: + - ❌ `/Users/username/projects/myapp/src/utils/helper.ts` + - ✅ `src/utils/helper.ts` ## 🎯 UI開発タスクでの**E2Eテスト優先**方針 @@ -81,13 +214,6 @@ NEVER テストケースの最大行数を500行を目標に分割してくだ - **アクセシビリティの確認** - キーボード操作、スクリーンリーダー対応 - **パフォーマンスの確認** - 読み込み時間、レンダリング速度 -#### E2Eテストの作成方針 -- **実際のユーザー操作を模倣**: クリック、入力、ナビゲーション等の実際の操作をテストに含める -- **エンドツーエンドのシナリオ**: ログインから目的の操作完了まで、完全なユーザージャーニーをテスト -- **視覚的な検証**: 画面表示、要素の配置、スタイリングの確認を含める -- **複数ブラウザでの検証**: 主要ブラウザでの動作確認を実施 -- **レスポンシブ対応**: 様々な画面サイズでの動作確認 - ### 🥇 **Playwright強力推奨**フレームワーク **UIタスクでは原則としてPlaywrightを使用してください：** @@ -196,9 +322,218 @@ expect(result.array).toHaveLength(3); // 【確認内容】: [配列の長さが expect(result.errors).toContain('error message'); // 【確認内容】: [特定のエラーメッセージが含まれることを確認する理由] ``` -## 作成するテストコードの例 +## TDDメモファイル形式 + +`docs/implements/{要件名}/{{task_id}}/{feature_name}-memo.md` ファイルの形式： + +```markdown +# TDD開発メモ: {feature_name} + +## 概要 + +- 機能名: [機能名] +- 開発開始: [日時] +- 現在のフェーズ: [Red/Green/Refactor] + +## 関連ファイル + +- 元タスクファイル: `docs/tasks/{taskファイルのパス}.md` +- 要件定義: `docs/implements/{要件名}/{{task_id}}/{feature_name}-requirements.md` +- テストケース定義: `docs/implements/{要件名}/{{task_id}}/{feature_name}-testcases.md` +- 実装ファイル: `[実装ファイルのパス]` +- テストファイル: `[テストファイルのパス]` + +## Redフェーズ（失敗するテスト作成） + +### 作成日時 + +[日時] + +### テストケース + +[作成したテストケースの概要] + +### テストコード + +[実際のテストコード] + +### 期待される失敗 + +[どのような失敗が期待されるか] + +### 次のフェーズへの要求事項 + +[Greenフェーズで実装すべき内容] + +## Greenフェーズ（最小実装） + +### 実装日時 + +[日時] + +### 実装方針 + +[最小実装の方針] + +### 実装コード + +[実際の実装コード] + +### テスト結果 + +[テストが通った結果] + +### 課題・改善点 + +[Refactorフェーズで改善すべき点] + +## Refactorフェーズ（品質改善） + +### リファクタ日時 + +[日時] + +### 改善内容 + +[具体的な改善内容] + +### セキュリティレビュー + +[セキュリティ面での確認結果] + +### パフォーマンスレビュー + +[パフォーマンス面での確認結果] + +### 最終コード + +[リファクタ後のコード] + +### 品質評価 + +[最終的な品質評価] +``` + +# info + +## テスト実行コマンドの例 + +### Playwrightの場合 +```bash +# 全E2Eテスト実行 +npx playwright test + +# 特定のテストファイル実行 +npx playwright test tests/e2e/{{feature_name}}.spec.js + +# ヘッドレスモードでない実行（ブラウザ表示） +npx playwright test --headed + +# 特定のブラウザでのテスト実行 +npx playwright test --project=chromium +npx playwright test --project=firefox +npx playwright test --project=webkit + +# デバッグモードでの実行 +npx playwright test --debug + +# レポート生成 +npx playwright show-report +``` + +### Cypressの場合 +```bash +# Cypress Test Runnerを開く +npx cypress open + +# ヘッドレスモードでテスト実行 +npx cypress run + +# 特定のテストファイル実行 +npx cypress run --spec "cypress/e2e/{{feature_name}}.cy.js" + +# 特定のブラウザでの実行 +npx cypress run --browser chrome +``` + +### 単体テスト（Jest等）の場合 +```bash +# 全テスト実行 +npm test + +# 特定のテストファイル実行 +npm test {{feature_name}}.test.js + +# ウォッチモードで実行 +npm test -- --watch + +# カバレッジレポート生成 +npm test -- --coverage +``` + + +あなたはTDD開発のRedフェーズ担当者です。以下の情報に基づいて、失敗するテストケースを作成してください。 + +# Redフェーズ対象の情報 + +機能名: {{機能名}} +タスクID: {{タスクID}} +要件名: {{要件名}} +対象テストケース: {{対象テストケース名}}（未指定の場合は全テストケース） +テストケース追加目標数: {{テストケース追加目標数}} +出力ファイル名: {{出力ファイル名}} + +# 重要な注意事項 + +**すべてのファイルパスは、プロジェクトルートを基準とした相対パスで記載してください。** +**絶対パス（/Users/... や C:\... など）は使用しないでください。** -### 単体テスト・統合テストの例 +例: +- ❌ `/Users/username/projects/myapp/src/utils/helper.ts` +- ✅ `src/utils/helper.ts` + +# テスト作成手順 + +既に読み込まれた以下のコンテキスト情報を活用してください： +- **タスクノート**（`note.md`） + - 技術スタック（使用技術・フレームワーク・テストフレームワーク） + - 開発ルール（コーディング規約・型チェック・テスト要件） + - 関連実装（既存のテストパターン・参考コード） + - 設計文書（データモデル・ディレクトリ構造） + - 注意事項（技術的制約・セキュリティ要件・パフォーマンス要件） +- **追加ルール**（`docs/rule`, `docs/rule/tdd`, `docs/rule/tdd/red`） +- **既存のテスト実装パターン**（symbol-searcherで検索したテストファイル） +- **要件定義・テストケース定義** + +これらの情報を基に、以下の要件を満たすテストコードを作成してください。 + +## テストコード作成要件 + +- **使用言語/フレームワーク**: 読み込んだ技術スタック定義に基づく +- **テストは必ず失敗する状態で作成** +- **テスト名は分かりやすく日本語で記述** +- **アサーション（期待値の検証）を明確に記述** +- **まだ実装されていない関数・メソッドを呼び出す形で作成** +- **日本語コメント必須**（テスト目的、内容、期待動作、信頼性レベル） +- **Given-When-Then パターンを使用**（E2Eの場合はScenario-Given-When-Then） + +## テスト戦略 + +### UI関連タスクの場合 → **E2Eテスト（Playwright優先）** +- コンポーネント作成・修正 +- ページ作成・レイアウト変更 +- ユーザーインタラクション実装 +- フォーム機能実装 +- ナビゲーション・ルーティング + +### ビジネスロジック・API関連タスク → **単体・統合テスト** +- データ処理アルゴリズム +- バリデーション関数 +- API エンドポイント +- データベース操作 +- ユーティリティ関数 + +## 単体テスト・統合テストの例 ```javascript // テストファイル: {{test_file_name}} @@ -234,7 +569,7 @@ describe('{{feature_name}}', () => { }); ``` -### UIタスク向けE2Eテストの例（Playwright） +## UIタスク向けE2Eテストの例（Playwright） ```javascript // E2Eテストファイル: tests/e2e/{{feature_name}}.spec.js @@ -283,14 +618,14 @@ describe('{{feature_name}} E2Eテスト', () => { // 【画面サイズ設定】: モバイルサイズでの表示確認 // 【レスポンシブ確認】: 小さい画面での要素配置とユーザビリティをテスト await page.setViewportSize({ width: 375, height: 667 }); - + // 【モバイル表示確認】: モバイル向けレイアウトが適用されることを確認 await expect(page.locator('{{mobile_navigation_selector}}')).toBeVisible(); // 【確認内容】: モバイル用ナビゲーションが表示されている // 【タブレットサイズ設定】: 中間サイズでの表示確認 await page.setViewportSize({ width: 768, height: 1024 }); - + // 【タブレット表示確認】: タブレット向けレイアウトの動作を確認 await expect(page.locator('{{tablet_layout_selector}}')).toBeVisible(); // 【確認内容】: タブレット用レイアウトが適切に表示されている @@ -298,7 +633,7 @@ describe('{{feature_name}} E2Eテスト', () => { }); ``` -### アクセシビリティテストの例 +## アクセシビリティテストの例 ```javascript // アクセシビリティテストファイル: tests/e2e/accessibility/{{feature_name}}.spec.js @@ -330,183 +665,13 @@ describe('{{feature_name}} アクセシビリティテスト', () => { }); ``` -## 提供してください +# 提供してください 1. **テストコード**: 実行可能な形式で、必須の日本語コメント付き 2. **テスト実行コマンド**: どのように実行するか 3. **期待される失敗メッセージ**: どのようなエラーが出るか -4. **コメントの説明**: 各日本語コメントの意図と目的 - -### E2Eテスト実行コマンドの例 - -#### Playwrightの場合 -```bash -# 全E2Eテスト実行 -npx playwright test - -# 特定のテストファイル実行 -npx playwright test tests/e2e/{{feature_name}}.spec.js - -# ヘッドレスモードでない実行（ブラウザ表示） -npx playwright test --headed - -# 特定のブラウザでのテスト実行 -npx playwright test --project=chromium -npx playwright test --project=firefox -npx playwright test --project=webkit - -# デバッグモードでの実行 -npx playwright test --debug - -# レポート生成 -npx playwright show-report -``` - -#### Cypressの場合 -```bash -# Cypress Test Runnerを開く -npx cypress open - -# ヘッドレスモードでテスト実行 -npx cypress run - -# 特定のテストファイル実行 -npx cypress run --spec "cypress/e2e/{{feature_name}}.cy.js" - -# 特定のブラウザでの実行 -npx cypress run --browser chrome -``` - -テストコード作成後、以下を実行してください： - -1. **メモファイル作成・更新**: `docs/implements/{要件名}/{{task_id}}/{feature_name}-memo.md` ファイルにRedフェーズの内容を作成または追記 - - 既存のメモファイルがある場合は、Redフェーズセクションを更新 - - メモファイルが存在しない場合は新規作成 -2. テストコードの設計内容を `docs/implements/{要件名}/{{task_id}}/{feature_name}-red-phase.md` に保存（既存ファイルがある場合は追記） -3. TODOステータスを更新（Redフェーズ完了をマーク） -4. **品質判定**: テストコードの品質を以下の基準で判定 - - テスト実行: 実行可能で失敗することを確認済み - - 期待値: 明確で具体的 - - アサーション: 適切 - - 実装方針: 明確 -5. **次のステップ表示**: 判定結果に関わらず、次のお勧めコマンドを表示 - - 「次のお勧めステップ: `/tsumiki:tdd-green` でGreenフェーズ（最小実装）を開始します。」 - -## TDDメモファイル形式 - -`docs/implements/{要件名}/{{task_id}}/{feature_name}-memo.md` ファイルの形式： - -```markdown -# TDD開発メモ: {feature_name} - -## 概要 - -- 機能名: [機能名] -- 開発開始: [日時] -- 現在のフェーズ: [Red/Green/Refactor] - -## 関連ファイル - -- 元タスクファイル: `docs/tasks/{taskファイルのパス}.md` -- 要件定義: `docs/implements/{要件名}/{{task_id}}/{feature_name}-requirements.md` -- テストケース定義: `docs/implements/{要件名}/{{task_id}}/{feature_name}-testcases.md` -- 実装ファイル: `[実装ファイルのパス]` -- テストファイル: `[テストファイルのパス]` - -## Redフェーズ（失敗するテスト作成） - -### 作成日時 - -[日時] - -### テストケース - -[作成したテストケースの概要] - -### テストコード - -[実際のテストコード] - -### 期待される失敗 - -[どのような失敗が期待されるか] - -### 次のフェーズへの要求事項 - -[Greenフェーズで実装すべき内容] - -## Greenフェーズ（最小実装） - -### 実装日時 - -[日時] - -### 実装方針 - -[最小実装の方針] - -### 実装コード - -[実際の実装コード] - -### テスト結果 - -[テストが通った結果] - -### 課題・改善点 - -[Refactorフェーズで改善すべき点] - -## Refactorフェーズ（品質改善） - -### リファクタ日時 - -[日時] - -### 改善内容 - -[具体的な改善内容] - -### セキュリティレビュー - -[セキュリティ面での確認結果] - -### パフォーマンスレビュー - -[パフォーマンス面での確認結果] - -### 最終コード - -[リファクタ後のコード] - -### 品質評価 - -[最終的な品質評価] -``` - -## 品質判定基準 - -``` -✅ 高品質: -- テスト実行: 成功（失敗することを確認） -- 期待値: 明確で具体的 -- アサーション: 適切 -- 実装方針: 明確 - -⚠️ 要改善: -- テストが実行できない -- 期待値が曖昧 -- 実装アプローチが不明 -- 複雑なテストケース -``` - -## TODO更新パターン - -``` -- 現在のTODO「Redフェーズ（失敗テスト作成）」を「completed」にマーク -- 失敗テスト作成フェーズの完了をTODO内容に反映 -- 品質判定結果をTODO内容に記録 -- 次のフェーズ「Greenフェーズ（最小実装）」をTODOに追加 -``` +4. **実装後の期待**: テストが通るために必要な実装の概要 -次のステップ: `/tsumiki:tdd-green` でテストを通すための最小限の実装を行います。 +必ず Write ツールを使用して、{{出力ファイル名}} にテストコードを保存してください。 +その後、Bash ツールを使用してテストを実行し、失敗することを確認してください。 + diff --git a/commands/tdd-refactor.md b/commands/tdd-refactor.md index 1fdcfcd..1372025 100644 --- a/commands/tdd-refactor.md +++ b/commands/tdd-refactor.md @@ -1,95 +1,293 @@ --- description: TDDのRefactorフェーズを実行します。テストを通す実装が完了した後、コード品質の改善とリファクタリングを行います。 +allowed-tools: Read, Glob, Grep, Task, Write, Edit, TodoWrite +argument-hint: [要件名] [TASK-ID] --- - -# TDD Refactorフェーズ（コード改善） - -TDDのRefactorフェーズを実行します。 - -## 事前準備 - -開発コンテキストの準備を行います： - -1. **追加ルールの読み込み** +TDDのRefactorフェーズを実行し、Greenフェーズで作成した実装コードの品質を改善します。 + +# context + +出力ディレクトリ="./docs/implements" +機能名={{feature_name}} +タスクID={{task_id}} +要件名={{requirement_name}} +信頼性評価=[] +メモファイル=./docs/implements/{要件名}/{{task_id}}/{feature_name}-memo.md +要件定義ファイル=./docs/implements/{要件名}/{{task_id}}/{feature_name}-requirements.md +テストケースファイル=./docs/implements/{要件名}/{{task_id}}/{feature_name}-testcases.md +Greenフェーズファイル=./docs/implements/{要件名}/{{task_id}}/{feature_name}-green-phase.md +Refactorフェーズファイル=./docs/implements/{要件名}/{{task_id}}/{feature_name}-refactor-phase.md + +# step + +- $ARGUMENTS がない場合、「引数に要件名とTASK-IDを指定してください(例: ユーザー認証機能 TASK-0001)」と言って終了する +- $ARGUMENTS の内容と context の内容をまとめてユーザに宣言する +- step2 を実行する + +## step2: コンテキスト準備 + +開発コンテキストの準備を実行する: + +1. **既存の実装ドキュメントの確認** + - `./docs/implements/{要件名}/{{task_id}}/` ディレクトリ内の全てのMDファイルを確認 + - 特に以下のファイルを優先的に読み込み： + - `note.md` - タスクノート（技術スタック、開発ルール、関連実装） + - `{feature_name}-requirements.md` - 要件定義 + - `{feature_name}-testcases.md` - テストケース定義 + - `{feature_name}-green-phase.md` - Greenフェーズの実装記録 + - `{feature_name}-refactor-phase.md` - 既存のRefactorフェーズ記録 + - `{feature_name}-memo.md` - 開発履歴メモ + - その他の関連MDファイル + - これらのファイルから既存の実装状況、設計判断、注意事項を把握 + +2. **追加ルールの読み込み** - `AGENTS.md` ファイルが存在する場合は読み込み - - `docs/rule` ディレクトリが存在する場合は読み込み - - `docs/rule/tdd` ディレクトリが存在する場合は読み込み - - `docs/rule/tdd/refactor` ディレクトリが存在する場合は読み込み + - `./docs/rule` ディレクトリが存在する場合は読み込み + - `./docs/rule/tdd` ディレクトリが存在する場合は読み込み + - `./docs/rule/tdd/refactor` ディレクトリが存在する場合は読み込み - 各ディレクトリ内のすべてのファイルを読み込み、追加ルールとして適用 -2. **@agent-symbol-searcher でリファクタリング関連情報を検索し、見つかったファイルを読み込み** +3. **@agent-symbol-searcher でリファクタリング関連情報を検索し、見つかったファイルを読み込み** - 既存のコードスタイルやベストプラクティスを検索し、スタイルガイドをReadツールで読み込み - プロジェクト全体のアーキテクチャパターンを特定し、設計文書をReadツールで読み込み - 再利用可能なユーティリティ関数やコンポーネントを確認し、関連ファイルをReadツールで読み込み -3. **関連ファイルを直接読み込み** - - `docs/implements/{要件名}/{{task_id}}/{feature_name}-memo.md` - 既存の開発履歴を確認 - - `docs/implements/{要件名}/{{task_id}}/{feature_name}-requirements.md` - 要件定義を確認 - - `docs/implements/{要件名}/{{task_id}}/{feature_name}-testcases.md` - テストケース定義を確認 - - `docs/implements/{要件名}/{{task_id}}/{feature_name}-green-phase.md` - Greenフェーズの実装を確認 +4. **関連する外部ファイルを直接読み込み** - 関連する設計文書やタスクファイルも必要に応じて読み込み + - プロジェクト全体の設計文書、アーキテクチャ文書など + +読み込み完了後、step3 を実行する + +## step3: テスト実行とコード品質確認 + +- **現在のテストが全て通ることを確認** + - 【品質保証】: リファクタ前の動作確認 + - 【安全性確保】: 変更による機能破綻の防止 + - 【実行方法】: Taskツールを使用してテストを実行し、結果を詳細に分析 + +- **コード・テスト除外チェック** + - 【.gitignore確認】: 本来確認対象のコードファイルが除外されていないかチェック + - 【テスト除外確認】: `describe.skip`, `it.skip`, `test.skip`等でテストが無効化されていないかチェック + - 【jest設定確認】: `jest.config.js`や`package.json`の`testPathIgnorePatterns`等でテストファイルが除外されていないかチェック + - 【実行対象確認】: 実際に実行されるべきテストとコードが適切に対象に含まれているかチェック + +- **開発時生成ファイルのクリーンアップ** + - 【不要ファイル検出】: 開発中に作成された一時的なファイルを検出・削除 + - 【対象ファイルパターン】: 以下のパターンに該当するファイルを確認 + - `debug-*.js`, `debug-*.ts`: デバッグ用スクリプト + - `test-*.js`, `test-*.ts`, `temp-*.js`: 一時テストファイル + - `*.tmp`, `*.temp`, `*.bak`, `*.orig`: 一時・バックアップファイル + - `*~`, `.DS_Store`: エディタ・システム生成ファイル + - `test-output-*`, `*.test-output`: テスト出力ファイル + - 【安全確認】: 削除前に各ファイルの内容を確認し、重要なコードが含まれていないかチェック + - 【選択的削除】: 不要と判断されたファイルのみを削除し、必要なファイルは保持 + - 【削除ログ】: 削除したファイルと削除理由をログとして記録 + - 【実行手順】: + 1. `find . -name "debug-*" -o -name "test-*" -o -name "temp-*" -o -name "*.tmp" -o -name "*.temp" -o -name "*.bak" -o -name "*.orig" -o -name "*~" -o -name ".DS_Store" | grep -v node_modules` でファイル検出 + 2. 各ファイルの内容をReadツールで確認 + 3. 不要と判断されたファイルは削除し、削除理由を記録 + +- step4 を実行する + +## step4: レビューと改善計画 + +- **セキュリティレビューの実施** + - 【脆弱性検査】: コード全体のセキュリティホールの特定 + - 【入力検証確認】: 不正な入力値に対する防御機能の確認 + - 【セキュリティガイドライン適用】: 業界標準のセキュリティベストプラクティスの適用 + - レビュー結果を文書化 + +- **パフォーマンスレビューの実施** + - 【計算量解析】: アルゴリズムの時間計算量・空間計算量の評価 + - 【ボトルネック特定】: 処理速度やメモリ使用量の問題箇所の特定 + - 【最適化戦略】: 具体的なパフォーマンス改善施策の立案 + - レビュー結果を文書化 + +- **改善計画の作成** + - を参考に改善計画を立てる + - 各改善項目に信頼性レベル(🔵🟡🔴)を付与 + - 改善の優先順位を決定 + +- step5 を実行する + +## step5: リファクタリング実行 + +- **小さな改善を1つずつ適用** + - 【段階的改善】: 影響範囲を限定した安全な変更 + - 【トレーサビリティ】: 変更内容の追跡可能性確保 + - の各観点に従って改善を実施 + - に従って日本語コメントを強化 + +- **各改善後にテストを実行** + - 【継続的検証】: 改善の度に動作確認 + - 【早期発見】: 問題の早期発見と修正 + - 【実行方法】: Taskツールを使用してテストを実行し、改善の影響を確認 + +- **テストが失敗したら即座に戻す** + - 【迅速復旧】: 問題発生時の素早い対応 + - 【安定性維持】: システムの安定した状態を保持 + +- リファクタリング内容について、品質判定基準に基づいて以下を評価: + - テスト成功状況 + - セキュリティ品質 + - パフォーマンス品質 + - コード品質の向上度 + - ファイルサイズ(500行制限) + - 日本語コメントの品質 + +- 品質判定結果をユーザーに表示する +- step6 を実行する + +## step6: ドキュメント更新 + +- **Refactor-phaseファイルの作成・更新**: + - リファクタリング内容と設計改善を {{Refactorフェーズファイル}} に保存 + - 既存ファイルがある場合は追記 + - 以下の内容を記録: + - 改善されたコードの全文 + - 改善ポイントの説明 + - セキュリティレビュー結果 + - パフォーマンスレビュー結果 + - テスト実行結果 + - コメント改善内容 + +- **メモファイルの最終更新**: + - {{メモファイル}} のRefactorフェーズセクションと概要を更新 + - 既存のメモファイルがない場合は新規作成(TDDメモファイル形式に従う) + - 以下の内容を記録: + - リファクタリング日時 + - 改善内容 + - セキュリティレビュー結果 + - パフォーマンスレビュー結果 + - 最終コード + - 品質評価 + - 概要セクションの現在のフェーズを「完了」に更新 + +- step7 を実行する + +## step7: TODO更新と完了判定 + +- TodoWrite ツールで TODO ステータスを更新する + - 現在のTODO「Refactorフェーズ(品質改善)」を「completed」にマーク + - リファクタリングフェーズの完了をTODO内容に反映 + - 品質判定結果をTODO内容に記録 + - 次のフェーズ「完全性検証」をTODOに追加 + - 改善が必要な箇所がある場合は新たなTODOとして追加 + +- **品質判定**: リファクタリング成果の品質を以下の基準で判定 + - テスト結果: 全てのテストが引き続き成功 + - セキュリティ: 重大な脆弱性が発見されていない + - パフォーマンス: 重大な性能課題が発見されていない + - リファクタ品質: 目標が達成されている + - コード品質: 適切なレベルに向上 + +- **次のステップ表示**: 判定結果に関わらず、次のお勧めコマンドを表示 + - 「次のお勧めステップ: `/tsumiki:tdd-verify-complete` で完全性検証を実行します。」 + +# rules + +## リファクタリングの原則 + +- **機能的な変更は行わない**(新機能追加はNG) +- **テストが通らなくなったら即座に修正** +- **一度に大きな変更をしない** +- **日本語コメントの品質も向上させる** +- **品質確認のためのテスト実行時はTaskツールを利用する** -読み込み完了後、準備されたコンテキスト情報を基にRefactorフェーズ（コード改善）の作業を開始します。 +## 禁止事項(NEVER) + +- 実装コード内でのモック・スタブの記述 +- 実装コード内でDBに代わるインメモリーストレージの利用 + +## ファイルサイズ管理 + +- **500行制限**: ファイルサイズが500行未満になるよう分割・最適化 +- **長大なファイルの機能別分割** +- **適切なモジュール境界の設定** ## 信頼性レベル指示 -リファクタリング時には、各改善内容について元の資料との照合状況を以下の信号でコメントしてください： +リファクタリング時には、各改善内容について元の資料との照合状況を以下の信号でコメントしてください: - 🔵 **青信号**: 元の資料を参考にしてほぼ推測していない場合 - 🟡 **黄信号**: 元の資料から妥当な推測の場合 - 🔴 **赤信号**: 元の資料にない推測の場合 -## 目標 +## 品質判定基準 -Greenフェーズで実装されたコードを以下の観点で改善してください。**テストは必ず通り続けること**が大前提です。 +``` +✅ 高品質: +- テスト結果: Taskツールによる実行で全て継続成功 +- セキュリティ: 重大な脆弱性なし +- パフォーマンス: 重大な性能課題なし +- リファクタ品質: 目標達成 +- コード品質: 適切なレベル +- ドキュメント: 完成 + +⚠️ 要改善: +- テストの一部失敗(Taskツールで検出) +- セキュリティ脆弱性発見 +- パフォーマンス課題発見 +- リファクタ目標未達成 +- 品質改善不十分 +- ドキュメント不備 +``` -## 改善の観点 +## ファイルパスの記載ルール -### 1. 可読性の向上 +- **プロジェクトルートを基準とした相対パスを使用する** +- フルパス(絶対パス)は記載しない +- 例: + - ❌ `/Users/username/projects/myapp/src/utils/helper.ts` + - ✅ `src/utils/helper.ts` + +# info + + +# リファクタリングの観点 + +## 1. 可読性の向上 - 変数名・関数名の改善 - 日本語コメントの充実 - コードの構造を分かりやすく -### 2. 重複コードの除去（DRY原則） +## 2. 重複コードの除去(DRY原則) - 同じような処理の共通化 - 定数の抽出 - ヘルパー関数の作成 -### 3. 設計の改善 +## 3. 設計の改善 - 単一責任原則の適用 - 依存関係の整理 - モジュール化の検討 -- NEVER: 実装コード内でのモック・スタブの記述 -- NEVER: 実装コード内でDBに代わるインメモリーストレージの利用 - -### 4. ファイルサイズの最適化 +## 4. ファイルサイズの最適化 - ファイルサイズが500行未満になるよう分割・最適化 - 長大なファイルの機能別分割 - 適切なモジュール境界の設定 -### 5. コード品質の確保 +## 5. コード品質の確保 - lintエラーの解消 - typecheckエラーの解消 - フォーマットの統一 - 静的解析ツールのチェッククリア -### 6. セキュリティレビュー +## 6. セキュリティレビュー - 脆弱性に繋がる実装の検出と修正 - 入力値検証の強化 - SQLインジェクション対策の確認 -- XSS（Cross-Site Scripting）対策の確認 -- CSRF（Cross-Site Request Forgery）対策の確認 +- XSS(Cross-Site Scripting)対策の確認 +- CSRF(Cross-Site Request Forgery)対策の確認 - データ漏洩リスクの回避 - 認証・認可の適切な実装 -### 7. パフォーマンスレビュー +## 7. パフォーマンスレビュー - アルゴリズムの計算量解析 - メモリ使用量の最適化 @@ -99,17 +297,19 @@ Greenフェーズで実装されたコードを以下の観点で改善してく - ループ処理の効率化 - 非同期処理の適切な実装 -### 8. エラーハンドリングの充実 +## 8. エラーハンドリングの充実 - 入力値の検証 - 適切なエラーメッセージ - 例外処理の改善 + -## リファクタリング時の日本語コメント強化要件 + +# リファクタリング時の日本語コメント強化要件 -リファクタリングでは既存の日本語コメントを改善し、新たなコメントを追加してください： +リファクタリングでは既存の日本語コメントを改善し、新たなコメントを追加してください: -### 改善された関数・メソッドのコメント +## 改善された関数・メソッドのコメント ```javascript /** @@ -127,7 +327,7 @@ function improvedFunction(paramName) { } ``` -### ヘルパー関数・ユーティリティのコメント +## ヘルパー関数・ユーティリティのコメント ```javascript /** @@ -141,7 +341,7 @@ function helperFunction(input) { } ``` -### 定数・設定値のコメント +## 定数・設定値のコメント ```javascript // 【設定定数】: [この定数の役割と設定理由] 🔵🟡🔴 @@ -156,7 +356,7 @@ const CONFIG = { }; ``` -### エラーハンドリング改善のコメント +## エラーハンドリング改善のコメント ```javascript try { @@ -173,72 +373,10 @@ try { return handleGenericError(error); } ``` + -## リファクタリングの手順 - -1. **現在のテストが全て通ることを確認** - - 【品質保証】: リファクタ前の動作確認 - - 【安全性確保】: 変更による機能破綻の防止 - - 【実行方法】: Taskツールを使用してテストを実行し、結果を詳細に分析 -2. **コード・テスト除外チェック** - - 【.gitignore確認】: 本来確認対象のコードファイルが除外されていないかチェック - - 【テスト除外確認】: `describe.skip`, `it.skip`, `test.skip`等でテストが無効化されていないかチェック - - 【jest設定確認】: `jest.config.js`や`package.json`の`testPathIgnorePatterns`等でテストファイルが除外されていないかチェック - - 【実行対象確認】: 実際に実行されるべきテストとコードが適切に対象に含まれているかチェック -3. **開発時生成ファイルのクリーンアップ** - - 【不要ファイル検出】: 開発中に作成された一時的なファイルを検出・削除 - - 【対象ファイルパターン】: 以下のパターンに該当するファイルを確認 - - `debug-*.js`, `debug-*.ts`: デバッグ用スクリプト - - `test-*.js`, `test-*.ts`, `temp-*.js`: 一時テストファイル - - `*.tmp`, `*.temp`, `*.bak`, `*.orig`: 一時・バックアップファイル - - `*~`, `.DS_Store`: エディタ・システム生成ファイル - - `test-output-*`, `*.test-output`: テスト出力ファイル - - 【安全確認】: 削除前に各ファイルの内容を確認し、重要なコードが含まれていないかチェック - - 【選択的削除】: 不要と判断されたファイルのみを削除し、必要なファイルは保持 - - 【削除ログ】: 削除したファイルと削除理由をログとして記録 - - 【実行手順】: - 1. `find . -name "debug-*" -o -name "test-*" -o -name "temp-*" -o -name "*.tmp" -o -name "*.temp" -o -name "*.bak" -o -name "*.orig" -o -name "*~" -o -name ".DS_Store" | grep -v node_modules` でファイル検出 - 2. 各ファイルの内容をReadツールで確認 - 3. 不要と判断されたファイルは削除し、削除理由を記録 -4. **セキュリティレビューの実施** - - 【脆弱性検査】: コード全体のセキュリティホールの特定 - - 【入力検証確認】: 不正な入力値に対する防御機能の確認 - - 【セキュリティガイドライン適用】: 業界標準のセキュリティベストプラクティスの適用 -5. **パフォーマンスレビューの実施** - - 【計算量解析】: アルゴリズムの時間計算量・空間計算量の評価 - - 【ボトルネック特定】: 処理速度やメモリ使用量の問題箇所の特定 - - 【最適化戦略】: 具体的なパフォーマンス改善施策の立案 -6. **小さな改善を1つずつ適用** - - 【段階的改善】: 影響範囲を限定した安全な変更 - - 【トレーサビリティ】: 変更内容の追跡可能性確保 -7. **各改善後にテストを実行** - - 【継続的検証】: 改善の度に動作確認 - - 【早期発見】: 問題の早期発見と修正 - - 【実行方法】: Taskツールを使用してテストを実行し、改善の影響を確認 -8. **テストが失敗したら即座に戻す** - - 【迅速復旧】: 問題発生時の素早い対応 - - 【安定性維持】: システムの安定した状態を保持 - -## 注意事項 - -- **機能的な変更は行わない**（新機能追加はNG） -- **テストが通らなくなったら即座に修正** -- **一度に大きな変更をしない** -- **日本語コメントの品質も向上させる** -- **品質確認のためのテスト実行時はTaskツールを利用する** - - -## 提供してください - -1. **セキュリティレビュー結果**: 脆弱性の有無と対応策 -2. **パフォーマンスレビュー結果**: 性能課題の分析と改善策 -3. **改善されたコード**: リファクタリング後のコード（強化された日本語コメント付き） -4. **改善ポイントの説明**: 何をどのように改善したか（セキュリティ・パフォーマンス観点を含む） -5. **テスト実行結果**: Taskツールを使用して全てのテストが引き続き通ることの確認 -6. **品質評価**: 現在のコードの品質レベル（セキュリティ・パフォーマンス評価を含む） -7. **コメント改善内容**: 日本語コメントをどのように強化したか - -## リファクタリング例 + +# リファクタリング例 ```javascript // Before: ハードコーディング @@ -246,7 +384,7 @@ function add(a, b) { return 5; // とりあえず動く実装 } -// After: 適切な実装（改善された日本語コメント付き） +// After: 適切な実装(改善された日本語コメント付き) /** * 【機能概要】: 2つの数値を加算し、結果を返す * 【改善内容】: ハードコーディングを削除し、実際の加算処理を実装 @@ -266,50 +404,4 @@ function add(firstNumber, secondNumber) { return firstNumber + secondNumber; } ``` - -リファクタリング完了後、以下を実行してください： - -1. **メモファイル最終更新**: `docs/implements/{要件名}/{{task_id}}/{feature_name}-memo.md` ファイルのRefactorフェーズセクションと概要を更新 - - 改善内容、セキュリティレビュー結果、パフォーマンスレビュー結果を記録 - - 最終コード、品質評価を記録 - - 概要セクションの現在のフェーズを「完了」に更新 -2. リファクタリング内容と設計改善を `docs/implements/{要件名}/{{task_id}}/{feature_name}-refactor-phase.md` に保存（既存ファイルがある場合は追記） -3. TODOステータスを更新（Refactorフェーズ完了をマーク） -4. **品質判定**: リファクタリング成果の品質を以下の基準で判定 - - テスト結果: 全てのテストが引き続き成功 - - セキュリティ: 重大な脆弱性が発見されていない - - パフォーマンス: 重大な性能課題が発見されていない - - リファクタ品質: 目標が達成されている - - コード品質: 適切なレベルに向上 -5. **次のステップ表示**: 判定結果に関わらず、次のお勧めコマンドを表示 - - 「次のお勧めステップ: `/tsumiki:tdd-verify-complete` で完全性検証を実行します。」 - -## 品質判定基準 - -``` -✅ 高品質: -- テスト結果: Taskツールによる実行で全て継続成功 -- セキュリティ: 重大な脆弱性なし -- パフォーマンス: 重大な性能課題なし -- リファクタ品質: 目標達成 -- コード品質: 適切なレベル -- ドキュメント: 完成 - -⚠️ 要改善: -- テストの一部失敗（Taskツールで検出） -- セキュリティ脆弱性発見 -- パフォーマンス課題発見 -- リファクタ目標未達成 -- 品質改善不十分 -- ドキュメント不備 -``` - -## TODO更新パターン - -``` -- 現在のTODO「Refactorフェーズ（品質改善）」を「completed」にマーク -- リファクタリングフェーズの完了をTODO内容に反映 -- 品質判定結果をTODO内容に記録 -- 次のフェーズ「完全性検証」をTODOに追加 -- 改善が必要な箇所がある場合は新たなTODOとして追加 -``` + diff --git a/commands/tdd-requirements.md b/commands/tdd-requirements.md index 83b0c28..be4b3e0 100644 --- a/commands/tdd-requirements.md +++ b/commands/tdd-requirements.md @@ -1,42 +1,160 @@ --- description: TDD開発の要件整理を行います。機能要件を明確化し、テスト駆動開発のための準備を行います。 +allowed-tools: Read, Glob, Grep, Task, Write, TodoWrite, Edit +argument-hint: [要件名] [TASK-ID] --- -あなたは開発の要件整理担当者です。TASKから必要な情報を集めて必要な機能を網羅的に整理してください。 +TDD開発の要件整理を実施し、EARS要件定義書・設計文書を参照しながら機能仕様を明確化します。信頼性レベルを示しながら要件定義を作成します。 -# TDD要件定義・機能仕様の整理 +# context -TDD開発を始めます。以下の機能について要件を整理してください： +出力ディレクトリ="./docs/implements" +機能名={{feature_name}} +タスクID={{task_id}} +要件名={{requirement_name}} +信頼性評価=[] +タスクファイル1=./docs/tasks/{要件名}/{{task_id}}.md +タスクファイル2=./docs/tasks/{要件名}-phase*.md +タスクoverviewファイル1=./docs/tasks/{要件名}/overview.md +タスクoverviewファイル2=./docs/tasks/{要件名}-overview.md -**【機能名】**: {{feature_name}} +# step -## 事前準備 +- $ARGUMENTS がない場合、「引数に要件名とTASK-IDを指定してください（例: ユーザー認証機能 TASK-0001）」と言って終了する +- $ARGUMENTS の内容と context の内容をまとめてユーザに宣言する +- step2 を実行する -開発コンテキストの準備を行います： +## step2 -1. **追加ルールの読み込み** - - `docs/rule` ディレクトリが存在する場合は読み込み - - `docs/rule/tdd` ディレクトリが存在する場合は読み込み - - `docs/rule/tdd/requirements` ディレクトリが存在する場合は読み込み - - 各ディレクトリ内のすべてのファイルを読み込み、追加ルールとして適用 +- 開発コンテキストの準備を実行する： + **タスクノートの読み込み** + - `./docs/implements/{要件名}/{{task_id}}/note.md` が存在する場合は読み込み + - 存在しない場合: + - @task で `/tsumiki:tdd-tasknote {要件名} {{task_id}}` コマンドを実行してノートを生成 + - 生成されたノートファイルを読み込み + - ノートには技術スタック、開発ルール、関連実装、設計文書、注意事項が含まれる -2. **技術スタック定義の読み込み** - - `docs/tech-stack.md` が存在する場合は読み込み - - 存在しない場合は `CLAUDE.md` から技術スタックセクションを読み込み - - どちらも存在しない場合は `.claude/commands/tech-stack.md` のデフォルト定義を使用 +- 読み込み完了後、step3 を実行する -3. **@agent-symbol-searcher で機能関連情報を検索し、見つかったファイルを読み込み** - - 読み込んだ技術スタック定義に基づいて関連ファイルを検索 - - 関連する既存機能・コンポーネントを検索し、該当ファイルをReadツールで読み込み - - 類似した実装パターンやアーキテクチャを特定し、設計文書をReadツールで読み込み - - 既存のインターフェースやAPI仕様を確認し、関連ファイルをReadツールで読み込み +## step3 -4. **関連ファイルを直接読み込み** - - `docs/implements/{要件名}/{{task_id}}/{feature_name}-memo.md` - 既存の開発履歴を確認 - - `docs/implements/{要件名}/{{task_id}}/{feature_name}-requirements.md` - 既存の要件定義を確認 - - `docs/implements/{要件名}/{{task_id}}/{feature_name}-testcases.md` - 既存のテストケースを確認 - - 関連する設計文書やタスクファイルも必要に応じて読み込み +- の内容を context の情報で埋めて、要件定義書を直接作成する + - 読み込んだコンテキスト情報（タスクノート、追加ルール等）を活用 + - 信頼性レベル（🔵🟡🔴）を各項目に記載 + - Write ツールを使用して出力ファイルに保存 -読み込み完了後、準備されたコンテキスト情報を基にTDD要件定義の作業を開始します。 +- 作成した要件定義書の内容について、品質判定基準に基づいて以下を評価： + - 要件の曖昧さの有無 + - 入出力定義の完全性 + - 制約条件の明確性 + - 実装可能性 + - 信頼性レベル（🔵🟡🔴の分布） + +- 品質判定結果をユーザーに表示する +- step4 を実行する + +## step4 + +- TodoWrite ツールで TODO ステータスを更新する + - 現在のTODOを「completed」にマーク + - 要件定義フェーズの完了をTODO内容に反映 + - 次のフェーズ「テストケース洗い出し」をTODOに追加 + - 品質判定結果をTODO内容に記録 +- 次のステップ表示: 「次のお勧めステップ: `/tsumiki:tdd-testcases {{要件名}} {{TASK-ID}}` でテストケースの洗い出しを行います。」 + +# rules + +## ファイル名のルール + +### 出力ファイルのパス形式 +- `docs/implements/{要件名}/{task_id}/{feature_name}-requirements.md` +- 例: `docs/implements/user-auth/task-001/login-requirements.md` + +### ファイル名の命名規則 +- 機能名を簡潔な英語に変換する +- ケバブケース（kebab-case）を使用 +- 最大50文字程度に収める +- 例: + - "ユーザー認証機能" → "user-auth" + - "データエクスポート機能" → "data-export" + - "パスワードリセット機能" → "password-reset" + +## 品質判定基準 + +``` +✅ 高品質: +- 要件の曖昧さ: なし +- 入出力定義: 完全 +- 制約条件: 明確 +- 実装可能性: 確実 +- 信頼性レベル: 🔵（青信号）が多い + +⚠️ 要改善: +- 要件に曖昧な部分がある +- 入出力の詳細が不明確 +- 技術的制約が不明 +- ユーザー意図の確認が必要 +- 信頼性レベル: 🟡🔴（黄・赤信号）が多い +``` + +## TODO更新パターン + +``` +- 現在のTODOを「completed」にマーク +- 要件定義フェーズの完了をTODO内容に反映 +- 次のフェーズ「テストケース洗い出し」をTODOに追加 +- 品質判定結果をTODO内容に記録 +``` + +## 信頼性レベル指示 + +各項目について、元の資料（EARS要件定義書・設計文書含む）との照合状況を以下の信号でコメントしてください： + +- 🔵 **青信号**: EARS要件定義書・設計文書を参考にしてほぼ推測していない場合 +- 🟡 **黄信号**: EARS要件定義書・設計文書から妥当な推測の場合 +- 🔴 **赤信号**: EARS要件定義書・設計文書にない推測の場合 + +## ファイルパスの記載ルール + +- **プロジェクトルートを基準とした相対パスを使用する** +- フルパス（絶対パス）は記載しない +- 例: + - ❌ `/Users/username/projects/myapp/src/utils/helper.ts` + - ✅ `src/utils/helper.ts` + +# info + + +あなたはTDD開発の要件整理担当者です。以下の情報に基づいて、機能要件を明確化してください。 + +# 要件整理対象の情報 + +機能名: {{機能名}} +タスクID: {{タスクID}} +要件名: {{要件名}} +出力ファイル名: {{出力ファイル名}} + +# 重要な注意事項 + +**すべてのファイルパスは、プロジェクトルートを基準とした相対パスで記載してください。** +**絶対パス（/Users/... や C:\\... など）は使用しないでください。** + +例: +- ❌ `/Users/username/projects/myapp/src/utils/helper.ts` +- ✅ `src/utils/helper.ts` + +# 要件整理手順 + +既に読み込まれた以下のコンテキスト情報を活用してください： +- **タスクノート**（`note.md`） + - 技術スタック（使用技術・フレームワーク・アーキテクチャパターン） + - 開発ルール（コーディング規約・型チェック・テスト要件） + - 関連実装（既存の実装パターン・参考コード） + - 設計文書（データモデル・ディレクトリ構造） + - 注意事項（技術的制約・セキュリティ要件・パフォーマンス要件） +- 追加ルール（`docs/rule`, `docs/rule/tdd`, `docs/rule/tdd/requirements`） +- 既存の要件定義・テストケース + +これらの情報を基に、以下のフォーマットで要件を整理してください。 ## TDD用要件整理フォーマット @@ -47,7 +165,7 @@ TDD開発を始めます。以下の機能について要件を整理してく - 🟡 **黄信号**: EARS要件定義書・設計文書から妥当な推測の場合 - 🔴 **赤信号**: EARS要件定義書・設計文書にない推測の場合 -## 1. 機能の概要（EARS要件定義書・設計文書ベース） +### 1. 機能の概要（EARS要件定義書・設計文書ベース） - 🔵🟡🔴 各項目の信頼性レベルを記載 - 何をする機能か（ユーザストーリーから抽出） @@ -57,7 +175,7 @@ TDD開発を始めます。以下の機能について要件を整理してく - **参照したEARS要件**: [具体的な要件ID] - **参照した設計文書**: [architecture.md の該当セクション] -## 2. 入力・出力の仕様（EARS機能要件・TypeScript型定義ベース） +### 2. 入力・出力の仕様（EARS機能要件・TypeScript型定義ベース） - 🔵🟡🔴 各項目の信頼性レベルを記載 - 入力パラメータ（型、範囲、制約）- interfaces.tsから抽出 @@ -67,7 +185,7 @@ TDD開発を始めます。以下の機能について要件を整理してく - **参照したEARS要件**: [具体的なREQ-XXX] - **参照した設計文書**: [interfaces.ts の該当インターフェース] -## 3. 制約条件（EARS非機能要件・アーキテクチャ設計ベース） +### 3. 制約条件（EARS非機能要件・アーキテクチャ設計ベース） - 🔵🟡🔴 各項目の信頼性レベルを記載 - パフォーマンス要件（NFR-XXXから抽出） @@ -79,7 +197,7 @@ TDD開発を始めます。以下の機能について要件を整理してく - **参照したEARS要件**: [具体的なNFR-XXX, REQ-XXX] - **参照した設計文書**: [architecture.md, database-schema.sql等の該当セクション] -## 4. 想定される使用例（EARSEdgeケース・データフローベース） +### 4. 想定される使用例（EARSEdgeケース・データフローベース） - 🔵🟡🔴 各項目の信頼性レベルを記載 - 基本的な使用パターン（通常要件REQ-XXXから抽出） @@ -89,7 +207,7 @@ TDD開発を始めます。以下の機能について要件を整理してく - **参照したEARS要件**: [具体的なEDGE-XXX] - **参照した設計文書**: [dataflow.md の該当フロー図] -## 5. EARS要件・設計文書との対応関係 +### 5. EARS要件・設計文書との対応関係 既存のEARS要件定義書・設計文書を参照した場合、以下の対応関係を明記してください： @@ -105,41 +223,9 @@ TDD開発を始めます。以下の機能について要件を整理してく - **データベース**: [database-schema.sql の該当テーブル] - **API仕様**: [api-endpoints.md の該当エンドポイント] -整理後、以下を実行してください： - -1. 要件定義書を `docs/implements/{要件名}/{{task_id}}/{feature_name}-requirements.md` に保存（既存ファイルがある場合は追記） -2. TODOステータスを更新（要件定義完了をマーク） -3. **品質判定**: 要件の品質を以下の基準で判定 - - 要件が明確で曖昧さがない - - 入出力仕様が具体的に定義されている - - 制約条件が明確 - - 実装可能性が確実 -4. **次のステップ表示**: 判定結果に関わらず、次のお勧めコマンドを表示 - - 「次のお勧めステップ: `/tdd-testcases` でテストケースの洗い出しを行います。」 - -## 品質判定基準 - -``` -✅ 高品質: -- 要件の曖昧さ: なし -- 入出力定義: 完全 -- 制約条件: 明確 -- 実装可能性: 確実 - -⚠️ 要改善: -- 要件に曖昧な部分がある -- 入出力の詳細が不明確 -- 技術的制約が不明 -- ユーザー意図の確認が必要 -``` - -## TODO更新パターン +# 出力形式 -``` -- 現在のTODOを「completed」にマーク -- 要件定義フェーズの完了をTODO内容に反映 -- 次のフェーズ「テストケース洗い出し」をTODOに追加 -- 品質判定結果をTODO内容に記録 -``` +上記のフォーマットに従って、要件定義書を作成してください。 -次のステップ: `/tdd-testcases` でテストケースの洗い出しを行います。 +必ず Write ツールを使用して、{{出力ファイル名}} に結果を保存してください。 + diff --git a/commands/tdd-tasknote.md b/commands/tdd-tasknote.md new file mode 100644 index 0000000..7997a9c --- /dev/null +++ b/commands/tdd-tasknote.md @@ -0,0 +1,133 @@ +--- +description: TDD開発のコンテキスト情報を収集してノートにまとめます。技術スタック、追加ルール、関連ファイルの情報を整理します。 +allowed-tools: Read, Glob, Grep, Task, Write, TodoWrite, Edit +argument-hint: [要件名] [TASK-ID] +--- +TDD開発の前にコンテキスト情報を収集し、開発に必要な情報をノートファイルにまとめます。 + +# context + +出力ディレクトリ="./docs/implements" +機能名={{feature_name}} +タスクID={{task_id}} +要件名={{requirement_name}} +収集情報=[] +noteファイル="./docs/implements/{要件名}/{{task_id}}/note.md" + +# step + +- $ARGUMENTS がない場合、「引数に要件名とTASK-IDを指定してください（例: ユーザー認証機能 TASK-0001）」と言って終了する +- {{noteファイル}} が既にある場合、存在しているので更新して良いかをユーザに確認する。 + - ユーザが良いといった場合は再作成をする。 + - ユーザが更新しないとした場合は終了する +- 開発コンテキストを収集する： + **追加ルールの読み込み** + - `AGENTS.md` ファイルが存在する場合は読み込み + - `./docs/rule` ディレクトリが存在する場合は読み込み + - `./docs/rule/tdd` ディレクトリが存在する場合は読み込み + - `./docs/rule/tdd/green` ディレクトリが存在する場合は読み込み + - 各ディレクトリ内のすべてのファイルを読み込み、追加ルールとして適用 + + **@agent-symbol-searcher で実装関連情報を検索し、見つかったファイルを読み込み** + - `./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に関係する全てのファイルを読み込み + - 関連する設計文書やタスクファイルも必要に応じて読み込み + +- 収集した情報を整理して {{noteファイル}} に保存する + - **重要**: ノートファイル内のすべてのファイルパスは、プロジェクトルートからの相対パスで記載すること（絶対パスは使用しない） + +# rules + +## ファイル名のルール + +### 出力ファイルのパス形式 +- `./docs/implements/{要件名}/{{task_id}}/note.md` +- 例: `docs/implements/user-auth/task-0001/note.md` + +### ファイル名の命名規則 +- 機能名を簡潔な英語に変換する +- ケバブケース（kebab-case）を使用 +- 最大50文字程度に収める +- 例: + - "ユーザー認証機能" → "user-auth" + - "データエクスポート機能" → "data-export" + - "パスワードリセット機能" → "password-reset" + +## ファイルパスの記載ルール（必須） + +- **プロジェクトルートを基準とした相対パスを使用する** +- **絶対パス（フルパス）は絶対に記載しない** +- **ディレクトリパスも相対パスで記載する** +- 例: + - ❌ `/Users/username/projects/myapp/src/utils/helper.ts` + - ❌ `/Users/username/projects/myapp/docs/spec/` + - ✅ `src/utils/helper.ts` + - ✅ `docs/spec/` + - ✅ `backend/app/main.py` + - ✅ `frontend/src/components/` + +# output_format + +## ノート構成 + +### 1. 技術スタック +- 使用技術・フレームワーク +- アーキテクチャパターン +- 参照元: [相対ファイルパス] + +### 2. 開発ルール +- プロジェクト固有のルール +- コーディング規約 +- 参照元: [相対ファイルパス一覧] + +### 3. 関連実装 +- 類似機能の実装例 +- 参考パターン +- 参照元: [相対ファイルパス一覧] + +### 4. 設計文書 +- アーキテクチャ・API仕様 +- データモデル +- 参照元: [相対ファイルパス一覧] + +### 5. 注意事項 +- 技術的制約 +- セキュリティ・パフォーマンス要件 +- 参照元: [相対ファイルパス] + +--- + +## 🚨 重要な記載ルール + +**すべてのファイルパス・ディレクトリパスは、プロジェクトルートからの相対パスで記載すること** + +### 相対パス記載の例 + +✅ **正しい記載例**: +``` +- 参照元: docs/tech-stack.md +- 参照元: backend/app/main.py +- 参照元: frontend/src/components/TodoList.tsx +- ディレクトリ: docs/spec/personal-todo-app/ +``` + +❌ **誤った記載例（絶対に避ける）**: +``` +- 参照元: /Users/username/projects/ai/test02/docs/tech-stack.md +- 参照元: /Users/username/projects/ai/test02/backend/app/main.py +- ディレクトリ: /Users/username/projects/ai/test02/docs/spec/ +``` + +### 実装時の注意 + +1. **Read ツールで読み込むとき**: 絶対パスを使用して読み込む +2. **ノートファイルに記載するとき**: 必ず相対パスに変換して記載する +3. **ディレクトリパスも同様**: `/Users/.../docs/spec/` → `docs/spec/` diff --git a/commands/tdd-testcases.md b/commands/tdd-testcases.md index 1205947..60f0180 100644 --- a/commands/tdd-testcases.md +++ b/commands/tdd-testcases.md @@ -1,44 +1,207 @@ --- description: TDD開発のためのテストケース洗い出しを行います。整理された要件に基づいて包括的なテストケースを特定します。 +allowed-tools: Read, Glob, Grep, Task, Write, TodoWrite, Edit +argument-hint: [要件名] [TASK-ID] --- -あなたはテスト設計の担当者です。指定されたtask_idの要件を確認して。網羅的なテストケースを作成してください。 +TDD開発のテストケース洗い出しを実施し、要件定義書を参照しながら網羅的なテストケースを作成します。信頼性レベルを示しながらテストケースを定義します。 + +# context + +出力ディレクトリ="./docs/implements" +機能名={{feature_name}} +タスクID={{task_id}} +要件名={{requirement_name}} +信頼性評価=[] +要件定義ファイル=./docs/implements/{要件名}/{{task_id}}/{feature_name}-requirements.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 +タスクoverviewファイル2=./docs/tasks/{要件名}-overview.md + +# step + +- $ARGUMENTS がない場合、「引数に要件名とTASK-IDを指定してください（例: ユーザー認証機能 TASK-0001）」と言って終了する +- $ARGUMENTS の内容と context の内容をまとめてユーザに宣言する +- step2 を実行する + +## step2 + +- 開発コンテキストの準備を実行する： + **既存の実装ドキュメントの確認** + - `./docs/implements/{要件名}/{{task_id}}/` ディレクトリ内の全てのMDファイルを確認 + - 特に以下のファイルを優先的に読み込み： + - `note.md` - タスクノート（技術スタック、開発ルール、関連実装） + - `{feature_name}-requirements.md` - 既存の要件定義 + - `{feature_name}-testcases.md` - 既存のテストケース + - `{feature_name}-memo.md` - 開発履歴メモ + - その他の関連MDファイル + - これらのファイルから既存の実装状況、設計判断、注意事項を把握 + + **タスクノートの読み込み** + - `./docs/implements/{要件名}/{{task_id}}/note.md` が存在しない場合: + - @task で `/tsumiki:tdd-tasknote {要件名} {{task_id}}` コマンドを実行してノートを生成 + - 生成されたノートファイルを読み込み + - ノートには技術スタック、開発ルール、関連実装、設計文書、注意事項が含まれる + + **追加ルールの読み込み** + - `./docs/rule` ディレクトリが存在する場合は読み込み + - `./docs/rule/tdd` ディレクトリが存在する場合は読み込み + - `./docs/rule/tdd/testcases` ディレクトリが存在する場合は読み込み + - 各ディレクトリ内のすべてのファイルを読み込み、追加ルールとして適用 + + **@agent-symbol-searcher でテスト関連情報を検索し、見つかったファイルを読み込み** + - 既存のテストパターンやテストケースを検索し、該当テストファイルをReadツールで読み込み + - 類似機能のテスト方法やモック戦略を特定し、関連ファイルをReadツールで読み込み + - テストフレームワークの使用方法を確認し、設定ファイルをReadツールで読み込み + + **関連ファイルを直接読み込み** + - `./docs/implements/{要件名}/{{task_id}}/{feature_name}-memo.md` - 既存の開発履歴を確認 + - `./docs/implements/{要件名}/{{task_id}}/{feature_name}-requirements.md` - 要件定義を確認 + - `./docs/implements/{要件名}/{{task_id}}/{feature_name}-testcases.md` - 既存のテストケースを確認 + - 関連する設計文書やタスクファイルも必要に応じて読み込み + +- 読み込み完了後、step3 を実行する + +## step3 + +- の内容を context の情報で埋めて、テストケースを直接作成する + - 読み込んだコンテキスト情報（タスクノート、要件定義、追加ルール等）を活用 + - 信頼性レベル（🔵🟡🔴）を各テストケースに記載 + - Write ツールを使用して出力ファイルに保存（既存ファイルがある場合は追記） + +- 作成したテストケースの内容について、品質判定基準に基づいて以下を評価： + - テストケース分類: 正常系・異常系・境界値が網羅されている + - 期待値定義: 各テストケースの期待値が明確 + - 技術選択: プログラミング言語・テストフレームワークが確定 + - 実装可能性: 現在の技術スタックで実現可能 + - 信頼性レベル（🔵🟡🔴の分布） + +- 品質判定結果をユーザーに表示する +- step4 を実行する + +## step4 + +- TodoWrite ツールで TODO ステータスを更新する + - 現在のTODOを「completed」にマーク + - テストケース定義フェーズの完了をTODO内容に反映 + - 次のフェーズ「Redフェーズ（失敗テスト作成）」をTODOに追加 + - 品質判定結果をTODO内容に記録 +- 次のステップ表示: 「次のお勧めステップ: `/tsumiki:tdd-red {要件名} {{TASK-ID}}` でRedフェーズ（失敗テスト作成）を開始します。」 + +# rules + +## ファイル名のルール + +### 出力ファイルのパス形式 +- `docs/implements/{要件名}/{task_id}/{feature_name}-testcases.md` +- 例: `docs/implements/user-auth/task-001/login-testcases.md` + +### ファイル名の命名規則 +- 機能名を簡潔な英語に変換する +- ケバブケース（kebab-case）を使用 +- 最大50文字程度に収める +- 例: + - "ユーザー認証機能" → "user-auth" + - "データエクスポート機能" → "data-export" + - "パスワードリセット機能" → "password-reset" -# TDDテストケースの洗い出し - -先ほど整理した要件に基づいて、要件網羅率と機能網羅率が十分に高いテストケースを洗い出します。 - -## 事前準備 +## 品質判定基準 -開発コンテキストの準備を行います： +``` +✅ 高品質: +- テストケース分類: 正常系・異常系・境界値が網羅されている +- 期待値定義: 各テストケースの期待値が明確 +- 技術選択: プログラミング言語・テストフレームワークが確定 +- 実装可能性: 現在の技術スタックで実現可能 +- 信頼性レベル: 🔵（青信号）が多い -1. **追加ルールの読み込み** - - `docs/rule` ディレクトリが存在する場合は読み込み - - `docs/rule/tdd` ディレクトリが存在する場合は読み込み - - `docs/rule/tdd/testcases` ディレクトリが存在する場合は読み込み - - 各ディレクトリ内のすべてのファイルを読み込み、追加ルールとして適用 +⚠️ 要改善: +- テストケースに漏れや重複がある +- 期待値が曖昧または不十分 +- 技術選択に迷いがある +- 複雑すぎて実装困難 +- 信頼性レベル: 🟡🔴（黄・赤信号）が多い -2. **@agent-symbol-searcher でテスト関連情報を検索し、見つかったファイルを読み込み** - - 既存のテストパターンやテストケースを検索し、該当テストファイルをReadツールで読み込み - - 類似機能のテスト方法やモック戦略を特定し、関連ファイルをReadツールで読み込み - - テストフレームワークの使用方法を確認し、設定ファイルをReadツールで読み込み +❌ 不適切: +- 要件との整合性が取れていない +- テストケースが不足している +- 技術的実現性に問題がある +``` -3. **関連ファイルを直接読み込み** - - `docs/implements/{要件名}/{{task_id}}/{feature_name}-memo.md` - 既存の開発履歴を確認 - - `docs/implements/{要件名}/{{task_id}}/{feature_name}-requirements.md` - 要件定義を確認 - - `docs/implements/{要件名}/{{task_id}}/{feature_name}-testcases.md` - 既存のテストケースを確認 - - 関連する設計文書やタスクファイルも必要に応じて読み込み +## TODO更新パターン -読み込み完了後、準備されたコンテキスト情報を基にテストケースの洗い出しを行います。 +``` +- 現在のTODO「テストケース洗い出し」を「completed」にマーク +- テストケース定義フェーズの完了をTODO内容に反映 +- 次のフェーズ「Redフェーズ（失敗テスト作成）」をTODOに追加 +- 品質判定結果をTODO内容に記録 +``` ## 信頼性レベル指示 -各テストケースの作成時には、元の資料（要件定義、既存実装、ライブラリドキュメント等）との照合状況を以下の信号で必ずコメントしてください： +各テストケースについて、元の資料（要件定義、既存実装、ライブラリドキュメント等）との照合状況を以下の信号でコメントしてください： - 🔵 **青信号**: 元の資料を参考にしてほぼ推測していない場合 - 🟡 **黄信号**: 元の資料から妥当な推測の場合 - 🔴 **赤信号**: 元の資料にない推測の場合 -## テストケースの分類 +## ファイルパスの記載ルール + +- **プロジェクトルートを基準とした相対パスを使用する** +- フルパス（絶対パス）は記載しない +- 例: + - ❌ `/Users/username/projects/myapp/src/utils/helper.ts` + - ✅ `src/utils/helper.ts` + +# info + + +あなたはテスト設計の担当者です。以下の情報に基づいて、網羅的なテストケースを作成してください。 + +# テストケース作成対象の情報 + +機能名: {{機能名}} +タスクID: {{タスクID}} +要件名: {{要件名}} +出力ファイル名: {{出力ファイル名}} + +# 重要な注意事項 + +**すべてのファイルパスは、プロジェクトルートを基準とした相対パスで記載してください。** +**絶対パス（/Users/... や C:\... など）は使用しないでください。** + +例: +- ❌ `/Users/username/projects/myapp/src/utils/helper.ts` +- ✅ `src/utils/helper.ts` + +# テストケース作成手順 + +既に読み込まれた以下のコンテキスト情報を活用してください： +- **タスクノート**（`note.md`） + - 技術スタック（使用技術・フレームワーク・アーキテクチャパターン） + - 開発ルール（コーディング規約・型チェック・テスト要件） + - 関連実装（既存の実装パターン・参考コード） + - 設計文書（データモデル・ディレクトリ構造） + - 注意事項（技術的制約・セキュリティ要件・パフォーマンス要件） +- **要件定義書**（`{feature_name}-requirements.md`） + - 機能の概要 + - 入力・出力の仕様 + - 制約条件 + - 想定される使用例 +- 追加ルール（`docs/rule`, `docs/rule/tdd`, `docs/rule/tdd/testcases`） +- 既存のテストケース・テストパターン + +これらの情報を基に、以下のフォーマットでテストケースを作成してください。 + +## TDD用テストケースフォーマット + +**【信頼性レベル指示】**: +各テストケースについて、元の資料（要件定義、既存実装、ライブラリドキュメント等）との照合状況を以下の信号でコメントしてください： + +- 🔵 **青信号**: 元の資料を参考にしてほぼ推測していない場合 +- 🟡 **黄信号**: 元の資料から妥当な推測の場合 +- 🔴 **赤信号**: 元の資料にない推測の場合 ### 1. 正常系テストケース（基本的な動作） @@ -85,7 +248,7 @@ description: TDD開発のためのテストケース洗い出しを行います - **堅牢性の確認**: [システムが極端な条件下でも安定動作するか] - 🔵🟡🔴 このテストケースの信頼性レベルを記載 -## 開発言語・フレームワーク +### 4. 開発言語・フレームワーク 実装に使用する言語・テストフレームワークも併せて指定してください： @@ -97,11 +260,11 @@ description: TDD開発のためのテストケース洗い出しを行います - **テスト実行環境**: [どのような環境でテストを実行するか] - 🔵🟡🔴 この内容の信頼性レベルを記載 -## テストケース実装時の日本語コメント指針 +### 5. テストケース実装時の日本語コメント指針 各テストケースの実装時には以下の日本語コメントを必ず含めてください： -### テストケース開始時のコメント +#### テストケース開始時のコメント ```javascript // 【テスト目的】: [このテストで何を確認するかを日本語で明記] @@ -110,7 +273,7 @@ description: TDD開発のためのテストケース洗い出しを行います // 🔵🟡🔴 この内容の信頼性レベルを記載 ``` -### Given（準備フェーズ）のコメント +#### Given（準備フェーズ）のコメント ```javascript // 【テストデータ準備】: [なぜこのデータを用意するかの理由] @@ -118,7 +281,7 @@ description: TDD開発のためのテストケース洗い出しを行います // 【前提条件確認】: [テスト実行に必要な前提条件を明記] ``` -### When（実行フェーズ）のコメント +#### When（実行フェーズ）のコメント ```javascript // 【実際の処理実行】: [どの機能/メソッドを呼び出すかを説明] @@ -126,7 +289,7 @@ description: TDD開発のためのテストケース洗い出しを行います // 【実行タイミング】: [なぜこのタイミングで実行するかを説明] ``` -### Then（検証フェーズ）のコメント +#### Then（検証フェーズ）のコメント ```javascript // 【結果検証】: [何を検証するかを具体的に説明] @@ -134,7 +297,7 @@ description: TDD開発のためのテストケース洗い出しを行います // 【品質保証】: [この検証がシステム品質にどう貢献するかを説明] ``` -### 各expectステートメントのコメント +#### 各expectステートメントのコメント ```javascript // 【検証項目】: [この検証で確認している具体的な項目] @@ -143,7 +306,7 @@ expect(result.validPaths).toHaveLength(2); // 【確認内容】: 有効なパ expect(result.invalidPaths).toContain('nonexistent.json'); // 【確認内容】: 存在しないファイルが無効パスとして適切に分類されることを確認 ``` -### セットアップ・クリーンアップのコメント +#### セットアップ・クリーンアップのコメント ```javascript beforeEach(() => { @@ -157,46 +320,19 @@ afterEach(() => { }); ``` -すべて洗い出したら以下を実行してください： +### 6. 要件定義との対応関係 -1. テストケース一覧を `docs/implements/{要件名}/{{task_id}}/{feature_name}-testcases.md` に保存（既存ファイルがある場合は追記） -2. TODOステータスを更新（テストケース洗い出し完了をマーク） -3. **品質判定**: テストケースの品質を以下の基準で判定 - - テストケース分類: 正常系・異常系・境界値が網羅されている - - 期待値定義: 各テストケースの期待値が明確 - - 技術選択: プログラミング言語・テストフレームワークが確定 - - 実装可能性: 現在の技術スタックで実現可能 -4. **次のステップ表示**: 判定結果に関わらず、次のお勧めコマンドを表示 - - 「次のお勧めステップ: `/tsumiki:tdd-red` でRedフェーズ（失敗テスト作成）を開始します。」 +要件定義書を参照した場合、以下の対応関係を明記してください： -## 品質判定基準 +- **参照した機能概要**: [要件定義の該当セクション] +- **参照した入力・出力仕様**: [要件定義の該当セクション] +- **参照した制約条件**: [要件定義の該当セクション] +- **参照した使用例**: [要件定義の該当セクション] -以下の基準でテストケースの品質を判定します： +# 出力形式 -``` -✅ 高品質: -- テストケース分類: 正常系・異常系・境界値が網羅されている -- 期待値定義: 各テストケースの期待値が明確 -- 技術選択: プログラミング言語・テストフレームワークが確定 -- 実装可能性: 現在の技術スタックで実現可能 +上記のフォーマットに従って、テストケースを作成してください。 -⚠️ 要改善: -- テストケースに漏れや重複がある -- 期待値が曖昧または不十分 -- 技術選択に迷いがある -- 複雑すぎて実装困難 - -❌ 不適切: -- 要件との整合性が取れていない -- テストケースが不足している -- 技術的実現性に問題がある -``` - -## TODO更新パターン - -``` -- 現在のTODO「テストケース洗い出し」を「completed」にマーク -- テストケース定義フェーズの完了をTODO内容に反映 -- 品質判定結果をTODO内容に記録 -- 次のフェーズ「Redフェーズ（失敗テスト作成）」をTODOに追加 -``` +必ず Write ツールを使用して、{{出力ファイル名}} に結果を保存してください。 +既存ファイルがある場合は、内容を追記してください。 + diff --git a/commands/tdd-verify-complete.md b/commands/tdd-verify-complete.md index 970ca24..2b1deca 100644 --- a/commands/tdd-verify-complete.md +++ b/commands/tdd-verify-complete.md @@ -1,71 +1,187 @@ --- description: TDD開発でテストケースの実装が完全に完了しているかを検証します。すべてのテストが通ることを確認し、開発完了を保証します。 +allowed-tools: Read, Glob, Grep, Task, Write, Edit, TodoWrite +argument-hint: [要件名] [TASK-ID] --- - -# TDD テストケース完全性検証 - TDD開発でテストケースの実装が完全に完了しているかを検証します。 -## 検証の目的 - -リファクタリング後に、予定していたテストケースがすべて実装されているかを確認し、実装漏れを防ぎます。 - -## 重要な原則 +# context -**⚠️ この工程では修正を行わない** -- この検証フェーズではコードやテストの修正は一切行わない -- 問題を発見した場合は内容をmemoファイルに記載する -- 修正作業は後の工程（次のTDDサイクルや別のタスク）に委ねる -- 検証・記録・報告に専念する -- テストの実行は @task で実行する -- NEVER 全体のテストケースの実装率と成功率のレポートは省略しない +出力ディレクトリ="./docs/implements" +機能名={{feature_name}} +タスクID={{task_id}} +要件名={{requirement_name}} +メモファイル=./docs/implements/{要件名}/{{task_id}}/{feature_name}-memo.md +要件定義ファイル=./docs/implements/{要件名}/{{task_id}}/{feature_name}-requirements.md +テストケースファイル=./docs/implements/{要件名}/{{task_id}}/{feature_name}-testcases.md +Refactorフェーズファイル=./docs/implements/{要件名}/{{task_id}}/{feature_name}-refactor-phase.md +元タスクファイル=docs/tasks/{taskfile}.md -## 検証手順 +# step -### 1. 既存テストのグリーン状態確認 +- $ARGUMENTS がない場合、「引数に要件名とTASK-IDを指定してください（例: ユーザー認証機能 TASK-0001）」と言って終了する +- $ARGUMENTS の内容と context の内容をまとめてユーザに宣言する +- step2 を実行する -- **必須**: 全ての既存テストが成功していることを確認 -- `npm test` または `jest` を実行してテスト結果を確認 -- **テスト失敗がある場合**: memoファイルに記載し、後の工程で修正対応 -- **この工程では修正禁止**: テスト失敗を発見してもここでは修正しない -- テスト状態を記録し、次のステップに進む +## step2: コンテキスト準備 -### 2. 事前準備 +検証コンテキストの準備を実行する： -検証コンテキストの準備を行います： +1. **既存の実装ドキュメントの確認** + - `./docs/implements/{要件名}/{{task_id}}/` ディレクトリ内の全てのMDファイルを確認 + - 特に以下のファイルを優先的に読み込み： + - `note.md` - タスクノート（技術スタック、開発ルール、関連実装） + - `{feature_name}-requirements.md` - 要件定義 + - `{feature_name}-testcases.md` - テストケース定義 + - `{feature_name}-refactor-phase.md` - Refactorフェーズの結果 + - `{feature_name}-memo.md` - 開発履歴メモ + - その他の関連MDファイル + - これらのファイルから既存の実装状況、設計判断、注意事項を把握 -1. **追加ルールの読み込み** +2. **追加ルールの読み込み** - `AGENTS.md` ファイルが存在する場合は読み込み - - `docs/rule` ディレクトリが存在する場合は読み込み - - `docs/rule/tdd` ディレクトリが存在する場合は読み込み - - `docs/rule/tdd/verify-complete` ディレクトリが存在する場合は読み込み + - `./docs/rule` ディレクトリが存在する場合は読み込み + - `./docs/rule/tdd` ディレクトリが存在する場合は読み込み + - `./docs/rule/tdd/verify-complete` ディレクトリが存在する場合は読み込み - 各ディレクトリ内のすべてのファイルを読み込み、追加ルールとして適用 -2. **@agent-symbol-searcher で検証関連情報を検索し、見つかったファイルを読み込み** +3. **@agent-symbol-searcher で検証関連情報を検索し、見つかったファイルを読み込み** - 完了予定のテストケースや機能を検索し、該当ファイルをReadツールで読み込み - 既存のテストカバレッジや品質基準を確認し、関連ファイルをReadツールで読み込み - 実装完了タスクのマーキングパターンを特定し、タスクファイルをReadツールで読み込み -3. **関連ファイルを直接読み込み** - - `docs/implements/{要件名}/{{task_id}}/{feature_name}-memo.md` - 既存の開発履歴を確認 - - `docs/implements/{要件名}/{{task_id}}/{feature_name}-requirements.md` - 要件定義を確認 - - `docs/implements/{要件名}/{{task_id}}/{feature_name}-testcases.md` - テストケース定義を確認 - - `docs/implements/{要件名}/{{task_id}}/{feature_name}-refactor-phase.md` - Refactorフェーズの結果を確認 - - 元タスクファイル (`docs/tasks/{taskfile}.md`) - タスクの完了状態を確認 +4. **元タスクファイルを直接読み込み** + - `docs/tasks/{taskfile}.md` - タスクの完了状態を確認 + - プロジェクト全体のタスク進捗を把握 + +読み込み完了後、step3 を実行する + +## step3: 既存テストのグリーン状態確認 -読み込み完了後、準備されたコンテキスト情報を基にテストケース完全性検証を開始します。 +- **必須**: @task で全ての既存テストが成功していることを確認 +- **テスト失敗がある場合**: memoファイルに記載し、後の工程で修正対応することを記録 +- **この工程では修正禁止**: テスト失敗を発見してもここでは修正しない +- テスト状態を記録し、step4 に進む -### 2. 実装済みテストケースの確認 +## step4: 実装状況の分析 - 現在のテストファイルを確認 - 実装済みテストケース数をカウント -- 各テストケースの内容を予定と照合 +- 各テストケースの内容を予定（テストケース定義ファイル）と照合 +- の形式で分析結果を提供する +- 品質判定基準に基づいて合否判定を行う +- step5 を実行する + +## step5: 検証結果のメモファイル記録 + +- {{メモファイル}} の既存内容を整理・統合し、 の形式で更新 +- **統合更新ルール**に従って、重要情報を保持し重複を削除 +- 実装パターン、テスト設計、品質保証の学習ポイントを記録 +- 修正が必要な項目がある場合、後工程での対応方針を記載して step7 を実行する +- 修正が必要ない場合、step6 を実行する + +## step6: 元タスクファイル完了マーク更新 + +検証が完了した場合、以下の手順で元タスクファイルを自動更新： + +1. **完了タスクの特定**: 現在のTDD開発対象タスクを元タスクファイルから特定 +2. **完了マーク追加**: 該当タスクに `✅ **完了**` マークを追加 +3. **完了理由記載**: `(TDD開発完了 - [テスト数]テストケース全通過)` を追記 +4. **サブタスク更新**: 関連するサブタスクにも `[x]` チェックマークを追加 + +例： + +```markdown +### 1. JSONファイルパス引数処理機能 ✅ **完了** (TDD開発完了 - 15テストケース全通過) + +- [x] コマンドライン引数でJSONファイルパスを受け取る機能を追加 +- [x] 複数のJSONファイルパスに対応（sample/ディレクトリ全体の読み込み） +- [x] 引数バリデーション機能 +``` + +step7 を実行する + +## step7: TODO更新と次ステップ判定 + +- TodoWrite ツールで TODO ステータスを更新する + - 現在のTODO「検証フェーズ（完全性確認）」を「completed」にマーク + - 検証結果をTODO内容に反映 + - 品質判定結果をTODO内容に記録 + +- **完全実装済み判定**: 以下の条件を満たす場合は 完全実装済み とする + - 既存テスト状態: すべてグリーン + - 要件網羅率: 100%（全要件項目実装・テスト済み） + - テスト成功率: 100% + - 未実装重要要件: 0個 + +- **完全実装済みの場合**: の形式で出力し、次のステップを提案 + +- **実装不足がある場合**: の形式で出力し、状況を報告 + +# rules + +## 検証の原則 + +- **この工程では修正を行わない** +- この検証フェーズではコードやテストの修正は一切行わない +- 問題を発見した場合は内容をmemoファイルに記載する +- 修正作業は後の工程（次のTDDサイクルや別のタスク）に委ねる +- 検証・記録・報告に専念する +- テストの実行は @task で実行する + +## 禁止事項（NEVER） + +- コードやテストの修正禁止 +- 新規実装の追加禁止 +- テストケースの削除・変更禁止 +- 全体のテストケースの実装率と成功率のレポートは省略禁止 + +## 品質基準 + +### 最低品質基準 + +- **実装率**: 80%以上 +- **成功率**: 100% +- **重要テスト**: すべて実装 +- **要件網羅性**: 要件定義書の主要機能をすべて網羅 +- **コンパイルエラー**: なし + +### 理想品質基準 + +- **実装率**: 100% +- **成功率**: 100% +- **網羅性**: 全ケース対応 +- **要件完全網羅**: 要件定義書の全項目を網羅 -### 3. 実装状況の分析とTODO.md更新判定 +## 品質判定基準 -以下の形式で分析結果を提供してください： +``` +✅ 高品質（要件充実度完全達成）: +- 既存テスト状態: すべてグリーン +- 要件網羅率: 100%（要件定義書の全項目に対する完全な実装・テスト） +- テスト成功率: 100% +- 未実装重要要件: 0個 +- 要件充実度: 要件定義に対する完全な充実度を達成 +⚠️ 要改善（要件充実度不足）: +- 既存テスト状態: 失敗テストあり または +- 要件網羅率: 100%未満（要件定義書の項目に対する実装・テスト不足） +- 重要な要件項目が未実装・未テスト +- 要件充実度: 要件定義に対する充実度が不十分 +- 追加実装による要件充実度向上が必要 ``` + +## ファイルパスの記載ルール + +- **プロジェクトルートを基準とした相対パスを使用する** +- フルパス（絶対パス）は記載しない +- 例: + - ❌ `/Users/username/projects/myapp/src/utils/helper.ts` + - ✅ `src/utils/helper.ts` + +# info + + ## テストケース実装状況 ### 📋 TODO.md対象タスク確認 @@ -115,36 +231,43 @@ TDD開発でテストケースの実装が完全に完了しているかを検 - **正常系実装率**: [実装数]/[予定数] = [実装率]% - **異常系実装率**: [実装数]/[予定数] = [実装率]% - **エッジケース実装率**: [実装数]/[予定数] = [実装率]% -``` -### 4. 判定基準 +## 要件定義書の網羅性チェック -#### ✅ 完全実装済み（自動で次ステップ） +要件定義書（requirements.md）に記載された以下の項目が実装・テストされているかを確認： -``` -- 既存テスト状態: すべてグリーン -- 要件網羅率: 100%（全要件項目実装・テスト済み） -- テスト成功率: 100% -- 未実装重要要件: 0個 -- 品質基準: 要件定義に対する完全な充実度を達成 -``` +### 必須チェック項目 + +- **入力パラメータ**: 全ての必須・オプション引数の処理 +- **出力仕様**: 期待される出力形式・構造の実装 +- **制約条件**: パフォーマンス・セキュリティ・互換性要件 +- **基本使用例**: 想定される基本的な使用パターン +- **エッジケース**: 境界値・例外条件の処理 +- **エラーケース**: 異常系の適切な処理 +- **主要アルゴリズム**: 機能の核となる処理ロジック -#### ⚠️ 実装不足あり（追加実装必要） +### 網羅性判定基準 ``` -- 既存テスト状態: 失敗テストあり または -- 要件網羅率: 100%未満（要件定義の項目に対する実装不足） -- 重要な要件項目が未実装・未テスト -- 要件充実度に品質リスクあり -``` - -### 5. 検証結果のメモファイル記録とTODO.md更新 +✅ 完全網羅 (100%): +- 要件定義書の全項目が実装・テストされている +- 入力パラメータの全パターンをテスト +- 出力仕様の全形式を検証 +- エラーケース・エッジケースを全て網羅 -#### メモファイルの統合更新 +⚠️ 部分網羅 (80-99%): +- 主要機能は実装されているが一部項目が未実装 +- 基本的な使用例は網羅されている +- 重要でないエラーケースの一部が未実装 -検証完了後、`docs/implements/{要件名}/{{task_id}}/{feature_name}-memo.md` の既存内容を整理・統合し、以下の情報に更新： +❌ 不十分 (<80%): +- 要件定義書の重要な項目が未実装 +- 基本的な使用例に漏れがある +- エラーハンドリングが不十分 +``` + -```markdown + # [機能名] TDD開発完了記録 ## 確認すべきドキュメント @@ -155,7 +278,7 @@ TDD開発でテストケースの実装が完全に完了しているかを検 ## 🎯 最終結果 ([日時]) - **実装率**: [数]% ([実装数]/[予定数]テストケース) -- **品質判定**: [合格/不合格] +- **品質判定**: [合格/不合格] - **TODO更新**: [✅完了マーク追加/要改善] ## 💡 重要な技術学習 @@ -189,186 +312,17 @@ TDD開発でテストケースの実装が完全に完了しているかを検 --- *既存のメモ内容から重要な情報を統合し、重複・詳細な経過記録は削除* -``` -**統合更新ルール:** +## 統合更新ルール + 1. **重要情報保持**: 既存メモの技術的学習ポイント・再利用可能パターンを統合 -2. **重複削除**: 類似の記録・詳細な経過は最新情報に集約 +2. **重複削除**: 類似の記録・詳細な経過は最新情報に集約 3. **簡潔化**: 日付・数値などの詳細は最終結果のみ保持 4. **再利用重視**: 今後の開発で参考になる情報を優先して残す 5. **関連情報重視**: 仕様情報などの情報は優先して残す + -#### 元タスクファイル完了マーク自動更新 - -検証が完了した場合、以下の手順で元タスクファイルを自動更新： - -1. **完了タスクの特定**: 現在のTDD開発対象タスクを元タスクファイルから特定 -2. **完了マーク追加**: 該当タスクに `✅ **完了**` マークを追加 -3. **完了理由記載**: `(TDD開発完了 - [テスト数]テストケース全通過)` を追記 -4. **サブタスク更新**: 関連するサブタスクにも `[x]` チェックマークを追加 - -例： - -```markdown -### 1. JSONファイルパス引数処理機能 ✅ **完了** (TDD開発完了 - 15テストケース全通過) - -- [x] コマンドライン引数でJSONファイルパスを受け取る機能を追加 -- [x] 複数のJSONファイルパスに対応（sample/ディレクトリ全体の読み込み） -- [x] 引数バリデーション機能 -``` - -### 6. 対応アクション - -#### 完全実装済みの場合 - -以下のメッセージと共に次のお勧めコマンドを表示： - -``` -✅ テストケース完全性検証: 合格 -- 予定テストケース: [数]個すべて実装済み -- テスト成功率: 100% -- 品質基準: 達成 - -次のお勧めステップ: `/tsumiki:tdd-cycle` で次のTDDサイクルを開始します。 -``` - -**メモファイル記録**: 検証結果をメモファイルに自動追記する。 -**元タスクファイル更新**: 完了したタスクに✅完了マークを自動追加する。 - -#### 実装不足がある場合 - -以下のメッセージを提供し、状況を記録する： - -``` -⚠️ テストケース実装不足を検出 - -未実装テストケース（[数]個）があります。 -以下の内容をmemoファイルに記録しました： - -[未実装テストケースのリスト] - -【重要】この工程では修正を行いません。 -修正が必要な内容はmemoファイルに記載され、後の工程で対応されます。 - -現状の記録を完了し、次のステップに進みます。 -``` - -**メモファイル記録**: 実装不足の検証結果と修正方針をメモファイルに詳細記録する。 -**元タスクファイル更新**: 実装不足の場合でも、部分完了したタスクがあれば適切にマークする。 -**修正作業禁止**: この工程では一切の修正作業を行わない。 - -## 検証対象ファイル - -### 確認すべきドキュメント - -- **元タスクファイル**: `docs/tasks/{taskファイルのパス}.md` - プロジェクト全体のタスク完了状況（完了マーク更新対象） -- `docs/implements/{要件名}/{{task_id}}/{feature_name}-requirements.md` -- `docs/implements/{要件名}/{{task_id}}/{feature_name}-testcases.md` - -### 確認すべきテストファイル - -- `src/__tests__/*.test.ts` -- `src/__tests__/*.test.js` - -### 確認すべき実装ファイル - -- `src/*.ts` -- `src/*.js` - -### Gitで変更されたファイル - -- `git status` で変更されたファイル -- `git diff --name-only` で変更されたファイル - -## 品質基準 - -### 最低品質基準 - -- **実装率**: 80%以上 -- **成功率**: 100% -- **重要テスト**: すべて実装 -- **要件網羅性**: 要件定義書の主要機能をすべて網羅 -- **コンパイルエラー**: なし - -### 理想品質基準 - -- **実装率**: 100% -- **成功率**: 100% -- **網羅性**: 全ケース対応 -- **要件完全網羅**: 要件定義書の全項目を網羅 - -### 要件定義書の網羅性チェック - -要件定義書（requirements.md）に記載された以下の項目が実装・テストされているかを確認： - -#### 必須チェック項目 - -- **入力パラメータ**: 全ての必須・オプション引数の処理 -- **出力仕様**: 期待される出力形式・構造の実装 -- **制約条件**: パフォーマンス・セキュリティ・互換性要件 -- **基本使用例**: 想定される基本的な使用パターン -- **エッジケース**: 境界値・例外条件の処理 -- **エラーケース**: 異常系の適切な処理 -- **主要アルゴリズム**: 機能の核となる処理ロジック - -#### 網羅性判定基準 - -``` -✅ 完全網羅 (100%): -- 要件定義書の全項目が実装・テストされている -- 入力パラメータの全パターンをテスト -- 出力仕様の全形式を検証 -- エラーケース・エッジケースを全て網羅 - -⚠️ 部分網羅 (80-99%): -- 主要機能は実装されているが一部項目が未実装 -- 基本的な使用例は網羅されている -- 重要でないエラーケースの一部が未実装 - -❌ 不十分 (<80%): -- 要件定義書の重要な項目が未実装 -- 基本的な使用例に漏れがある -- エラーハンドリングが不十分 -``` - -## 自動遷移判定 - -### 品質判定基準 - -``` -✅ 高品質（要件充実度完全達成）: -- 既存テスト状態: すべてグリーン -- 要件網羅率: 100%（要件定義書の全項目に対する完全な実装・テスト） -- テスト成功率: 100% -- 未実装重要要件: 0個 -- 要件充実度: 要件定義に対する完全な充実度を達成 - -⚠️ 要改善（要件充実度不足）: -- 既存テスト状態: 失敗テストあり または -- 要件網羅率: 100%未満（要件定義書の項目に対する実装・テスト不足） -- 重要な要件項目が未実装・未テスト -- 要件充実度: 要件定義に対する充実度が不十分 -- 追加実装による要件充実度向上が必要 -``` - -## 使用例 - -```bash -# refactorフェーズ後に自動実行 -/tsumiki:tdd-refactor -# ↓ 自動実行 -/tsumiki:tdd-verify-complete -# ↓ 実装完全なら自動実行 -/tsumiki:tdd-cycle -``` - -## 出力形式 - -実装状況に応じて以下のいずれかの形式で出力： - -### 完全実装の場合 - -``` + ✅ **テストケース完全性検証: 合格** 📊 今回のタスク要件充実度: @@ -378,22 +332,22 @@ TDD開発でテストケースの実装が完全に完了しているかを検 - 要件充実度: 完全達成 📊 全体のテスト状況: -- 全テストケース総数: [数]個 +- 全テストケース総数: [数]個 - 成功: [数]個 / 失敗: [数]個 - 全体テスト成功率: [数]% 🚀 要件定義に対する完全な充実度を達成しました。 自動で次のTDDサイクルに進みます。 -``` -### 実装不足の場合 +次のお勧めステップ: `/tsumiki:tdd-cycle` で次のTDDサイクルを開始します。 + -``` + ⚠️ **テストケース実装不足を検出** 📊 今回のタスク要件充実度: - 対象要件項目: [数]個 -- 実装・テスト済み: [数]個 / 未実装: [数]個 +- 実装・テスト済み: [数]個 / 未実装: [数]個 - 要件網羅率: [数]% - 要件充実度: [充実度レベル] @@ -407,6 +361,4 @@ TDD開発でテストケースの実装が完全に完了しているかを検 📝 **修正内容をmemoファイルに記録済み** 後の工程で対応予定です。この工程では修正を行いません。 -``` - -この検証により、TDD開発の品質と完全性を確保します。 + diff --git a/package.json b/package.json index ffcd3a1..7bfb341 100644 --- a/package.json +++ b/package.json @@ -1,7 +1,7 @@ { "name": "tsumiki", "private": false, - "version": "0.0.6", + "version": "0.0.7", "description": "AI-driven development framework for Claude Code", "keywords": [ "tsumiki",