162 lines
6.4 KiB
Markdown
162 lines
6.4 KiB
Markdown
---
|
||
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の開発原則との一致
|
||
|
||
問題がある場合のみユーザーに修正を促す。準拠している場合は何も出力しない。
|
||
|
||
### 矛盾チェック（内部処理）
|
||
|
||
明確化後、内部的に仕様書間の矛盾を確認：
|
||
- 明確化による変更が他のドキュメントと整合しているか
|
||
- 依存関係のあるドキュメント間で矛盾が生じていないか
|
||
|
||
矛盾がある場合のみユーザーに警告を表示。問題がなければ何も出力しない。
|