| name | dig |
| description | 既存の設計ドキュメント・RFC・計画書を読み込み、AskUserQuestion による構造化された質問を
通じて、曖昧さ・矛盾・未定義事項を洗い出し、決定事項と残課題を整理するスキル。
「深掘りして」「曖昧な点を洗い出して」「設計の穴を突いて」「challenge my assumptions」
「ドキュメントを読んで質問して」のような依頼でトリガーすること。
仕様書(spec)の生成が目的の場合は design-to-spec を使うこと。
|
| argument-hint | <doc-path> [output-path] |
dig
既存の設計ドキュメントを読み込み、構造化された質問で曖昧さを洗い出し、
決定事項と残課題を整理する。Spec は生成しない。
引数
- 第1引数(必須): 設計ドキュメントのパス(例:
docs/design.md)
- 第2引数(任意): 出力先パス。省略時は
<doc-basename>-decisions.md
Workflow
Step 1: ドキュメント読み込みと分析
- 指定されたパスのドキュメントを読み込む
- ドキュメントの内容を分類する:
- 明示的記述: ドキュメントに書かれている事実
- 暗黙の前提: 明記されていないが設計が依存している前提条件
- 欠落: 書かれるべきだが存在しない情報
- ユーザーの使用言語を判定し、以降のやり取りはその言語で行う
Step 2: 曖昧さ分析と質問計画
以下の7カテゴリでドキュメントを分析し、質問項目を洗い出す。
各質問には2〜4個の具体的な選択肢を準備し、各選択肢に pros/cons を付記する。
分析カテゴリ:
- 矛盾・曖昧さ: ドキュメント内で矛盾する記述、複数の解釈が可能な箇所
- 暗黙の前提: 明記されていないが設計が依存している前提条件
- エッジケース・障害時: 正常系以外の振る舞い(入力の境界値、同時実行、障害時など)
- セキュリティ・データ: 認証・認可、データの扱い、攻撃ベクトル、データライフサイクル
- スケーラビリティ・運用: データ量の増加、デプロイ、監視、ログ、ロールバック
- トレードオフ・代替案: 採用した設計のメリット・デメリット、検討した代替案
- スコープ・依存関係: 外部サービス、ライブラリ、チーム間の依存、移行計画
すべてを網羅する必要はなく、ドキュメントの内容に応じて重要度の高いものから優先する。
Step 3: 構造化インタビュー
AskUserQuestion を使って、1ターンにつき1〜3問ずつ質問する。
質問のルール:
- ドキュメントの具体的な記述を引用して質問する
- 悪い例: 「セキュリティはどう考えていますか?」
- 良い例: 「認証にJWTを採用とありますが、トークンの失効管理はどうしますか?」
- 各選択肢に pros/cons を必ず含める(description フィールドに記載)
- 例:
description: "Pros: シンプルな実装。Cons: スケール時にボトルネックになる可能性"
- ドキュメントを読めばわかる自明な質問は禁止
- 「まだ決めていない」「よくわからない」も有効な回答として受け入れ、Open Questions として記録
- ユーザーの回答から新たな疑問が生まれたら、計画にない質問も追加する
インタビューの進め方:
- 最も重要度が高い(設計への影響が大きい)質問から始める
- 各カテゴリについて十分な深さに達したら次に移る
- すべての主要カテゴリをカバーし、重要な曖昧さが解消されたと判断したら Step 4 へ
完了の判断基準:
- 全主要カテゴリについて深掘りが完了している
- 重大な矛盾・曖昧さが解消されている(または Open Questions として明示されている)
完了と判断したら、その旨をユーザーに伝えて確認を取る。
Step 4: 再分析ループ
全カテゴリの質問完了後、以下を実施する:
- ドキュメントを再度読み込む
- ユーザーの回答を踏まえて、新たな矛盾・曖昧さがないか確認する
- 新たな問題が見つかった場合は Step 3 に戻って追加質問する
再分析は最大2回まで。 2回目の再分析で新たな問題がなければ Step 5 へ進む。
Step 5: Decisions ドキュメント出力
以下の構造で決定事項ドキュメントを生成する:
# Decisions: <ドキュメントタイトル>
## Decision Records
| # | カテゴリ | 質問 | 決定事項 | 根拠 |
|---|---------|------|---------|------|
| 1 | ... | ... | ... | ... |
## Open Questions
- [ ] <未解決の質問1>
- [ ] <未解決の質問2>
## Next Steps
- <次にやるべきこと>
出力ルール:
- デフォルト出力先:
<doc-basename>-decisions.md(第2引数で上書き可能)
- 元のドキュメントは絶対に上書きしない
- 書き込み前に出力先をユーザーに確認する
Step 6: レビュー
- 決定事項の数、Open Questions の数のサマリーを簡潔に伝える
- 修正要望があれば対応する
- 仕様書が必要な場合は
design-to-spec の利用を提案する