Initial commit

2025-11-30 08:39:29 +08:00
commit f2613ae15b
26 changed files with 5240 additions and 0 deletions
--- a/commands/clarify-spec.md
+++ b/commands/clarify-spec.md
@@ -0,0 +1,161 @@
+---
+argument-hint: <タスク名>
+allowed-tools: ["Read", "Edit", "Task", "AskUserQuestion", "TodoWrite"]
+---
+
+# specs内の不明箇所をユーザーに質問して明確化します
+
+このコマンドは `specs/[taskname]/` ディレクトリ内の全ドキュメントから「**不明**」と記載された箇所を抽出し、ユーザーに質問して明確化します。
+
+## コマンドの役割
+
+**`/sdd:clarify-spec`（このコマンド）の役割**:
+- **ビジネス要件やユーザーの意思決定**が必要な不明箇所をユーザーに質問
+- AIだけでは判断できず、ユーザー（プロダクトオーナー、ステークホルダー）の意思決定が必要な項目
+- 例：
+  - 機能の優先順位や範囲
+  - UIの具体的な仕様（表示項目、レイアウトなど）
+  - ビジネスルール（承認フロー、権限設定など）
+  - ユーザー体験に関する選択（エラー時の挙動など）
+
+**`/sdd:conduct-research` との違い**:
+- **clarify-spec**: ビジネス要件やユーザーの意思決定が必要な項目をユーザーに質問
+- **conduct-research**: 技術的な調査が必要な項目をAIが調査・検証
+- clarify-specは「ユーザーに聞く」、conduct-researchは「AIが調べる」
+
+**使い分けの例**:
+- ✅ clarify: 「ログイン時にメールアドレスとユーザー名のどちらを使うか」（ビジネス要件）
+- ✅ research: 「JWT vs セッション認証のパフォーマンス比較」（技術的検証）
+- ✅ clarify: 「管理者画面の公開範囲（社内のみ or 顧客も使用）」（ビジネス要件）
+- ✅ research: 「PostgreSQL vs MySQL のベンチマーク」（技術的検証）
+
+【対象タスク名】
+$ARGUMENTS
+
+## 実行手順
+
+### 1. タスクディレクトリの確認
+
+タスク名が指定されている場合:
+- `specs/[taskname]/` ディレクトリの存在を確認
+- ディレクトリ内の全マークダウンファイルを取得
+
+タスク名が指定されていない場合:
+- `specs/` ディレクトリ内の利用可能なタスクをリスト表示
+- ユーザーに選択を求める
+
+### 2. ステアリングドキュメントの読み込み
+
+以下のステアリングドキュメントを読み込み、プロジェクトのコンテキストを把握：
+
+- `specs/_steering/product.md` - プロダクト方針
+- `specs/_steering/tech.md` - 技術スタック
+- `specs/_steering/structure.md` - プロジェクト構造
+- `specs/_steering/principles.md` - 開発原則
+
+ステアリングドキュメントが存在しない場合は警告を表示し、処理を続行。
+
+### 3. 不明箇所の抽出
+
+`specs/[taskname]/` および `specs/[taskname]/tasks/` 内の全マークダウンファイルを検索し、以下のパターンを抽出:
+
+- 「**不明**」または「不明」と記載された箇所
+- その周辺のコンテキスト（前後数行）
+- 記載されている複数の案（案A、案B、案Cなど）
+
+各不明箇所について以下の情報を収集:
+- **ファイル名**: どのファイルに記載されているか
+- **セクション名**: どのセクションの内容か
+- **不明な内容**: 何が不明なのか
+- **提示されている案**: 案A、案B、案Cなど
+
+### 4. 不明箇所の整理とタスク化
+
+抽出した不明箇所をTodoWriteツールでタスク化:
+
+```
+TodoWrite:
+- [不明箇所1: 認証方式を決定] - pending
+- [不明箇所2: データベースを選択] - pending
+- [不明箇所3: デプロイ環境を選択] - pending
+```
+
+不明箇所をユーザーに提示:
+- ファイル名、セクション名、不明な内容、提示されている案を表示
+
+### 5. ユーザーへの質問
+
+各不明箇所について、AskUserQuestionツールを使用してユーザーに質問:
+
+- 質問は明確で具体的にすること
+- 提示されている案をそのまま選択肢として提示
+- 1つずつ順番に質問するのではなく、可能な限り複数の質問をまとめて提示
+- ユーザーが「その他」を選択した場合は自由記述で詳細を取得
+
+例:
+```
+質問: Phase 1で使用する認証方式を選択してください
+選択肢:
+- 案A: JWT認証
+- 案B: セッションベース認証
+- 案C: OAuth2.0
+```
+
+### 6. 回答の反映
+
+各不明箇所について：
+
+1. TodoWriteで該当タスクを`in_progress`に更新
+2. ユーザーの回答を元に該当ファイルの「**不明**」箇所を更新
+3. TodoWriteで該当タスクを`completed`に更新
+
+**更新例**:
+```markdown
+# 更新前
+**不明**: JWT認証 or セッションベース認証
+
+# 更新後
+JWT認証を使用する
+```
+
+### 7. 完了報告
+
+```
+✅ 不明箇所を明確化しました
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+📍 対象: specs/[taskname]/
+📝 明確化: [N]箇所
+
+💡 次のアクション:
+   - 仕様書の内容を確認
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+## 注意事項
+
+- 不明箇所が見つからない場合は、その旨を報告してコマンドを終了
+- ユーザーが「その他」を選択した場合は、その内容をそのまま反映
+- 更新時は「**不明**」の記述と案のリストを全て削除し、選択された内容のみを記載
+- 複数ファイルにまたがる不明箇所も漏れなく更新すること
+- 更新前に必ずファイルの内容を読み込み、正確な位置を特定すること
+
+## 内部品質チェック
+
+**重要**: 以下のチェックはコマンド内部で実施し、**生成されるspecファイルには結果を記載しません**。
+
+### ステアリングドキュメントレビュー（内部処理）
+
+明確化後、内部的にステアリングドキュメントとの整合性を確認：
+- product.mdのビジネス目標との整合性
+- tech.mdの技術方針との整合性
+- principles.mdの開発原則との一致
+
+問題がある場合のみユーザーに修正を促す。準拠している場合は何も出力しない。
+
+### 矛盾チェック（内部処理）
+
+明確化後、内部的に仕様書間の矛盾を確認：
+- 明確化による変更が他のドキュメントと整合しているか
+- 依存関係のあるドキュメント間で矛盾が生じていないか
+
+矛盾がある場合のみユーザーに警告を表示。問題がなければ何も出力しない。