asking-clarifying-questions

明確化のための質問

概要

ユーザーが実際に何を意味しているのかを理解し、言葉どおりに受け取るだけで終わらせず、曖昧な入力と構造化されたブレインストーミングの間をつなぎます。

基本原則： まず矛盾を解消し、その後に曖昧さを明確にします。技術的な確認に進む前に、相反する目標をすり合わせる必要があります。そうしなければ、まさに間違ったものを正確に定義してしまいます。

開始時に伝えること： 「要件を正しく理解するため、明確化の質問を行うスキルを使用します。」

使用するタイミング

このスキルを使用するのは、次の場合です。

• ユーザーから最初のコンテキストを集めた後
• ブレインストーミングや設計の検討を始める前
• ユーザーが複数の意味に解釈できる技術用語に言及したとき
• スコープの境界が不明確なとき
• 前提を確認する必要があるとき

次の場合は使用しないでください。

• 設計の代替案を検討するとき（それはブレインストーミングです）
• アーキテクチャを提案するとき（それはブレインストーミングです）
• 完了した設計を検証するとき（それはブレインストーミングのフェーズ 3 です）
• 初期要件を尋ねるとき（それは設計計画の開始フェーズ 1 です）

明確化の前に

まず、自分で質問に答えられないか、作業ディレクトリのコンテキストから曖昧さを解消できないか試してください。codebase-investigator などの利用可能なサブエージェントを使い、確認対象を説明するうえで役立つ既存の作業を調べてください。一般的な技術や固有名詞などの要素に気づいた場合は、代わりに combined-researcher を使って、コードベースとインターネットの検索結果を統合してください。

製品管理に使用されるリモートデータストアへの接続など、有用な情報を含むほかのスキルや MCP が利用できる場合もあります。該当する場合は、調査のために haiku-general-purpose サブエージェントを起動してください。

サブエージェントの入れ子は禁止です： これらの調査用サブエージェントを起動できるのは、現在の呼び出し元だけです。各サブエージェントには、追加のサブエージェントを起動せず、自身で直接作業するよう指示してください。

明確化する内容

0. 矛盾（最初の確認）

技術的な詳細の曖昧さを解消する前に、要件に論理的な矛盾がないか確認してください。ユーザーが両立しない目標を述べている場合は、まずそれらを解決してください。土台が変わるなら、技術的な確認に時間をかけても無駄です。

確認する点：

明示的な矛盾（ユーザーが両方を述べている場合）：

• 「リアルタイム更新」＋「バッチ処理でも問題ない」→ 実際に必要なのはどちらですか？
• 「シンプルに保つ」＋「あらゆるエッジケースに対応する」→ トレードオフが認識されていません
• 「既存のパターンを使う」＋「全面的に書き直す」→ 相互に両立しないアプローチです
• 「外部依存関係なし」＋「Stripe と統合する」→ 暗黙の矛盾です

実現不可能な組み合わせ：

• 「オフライン優先」＋「常に最新のデータ」→ 物理的に両立しません
• 「すばやく構築」＋「無限に拡張可能」→ 典型的な両立不可能の三つ巴です
• 「レイテンシーゼロ」＋「同期的な検証」→ 両方は実現できません
• 「破壊的変更なし」＋「根本的な再設計」→ どちらかを選ぶ必要があります

認識されていないトレードオフ：

• 「シンプル」はしばしば「柔軟」と相反します
• 「速い」はしばしば「徹底的」と相反します
• 「安い」はしばしば「カスタム」と相反します
• 「安全」はしばしば「便利」と相反します

表面化させる方法：

非難するのではなく、相反する点を明らかにしてください。

• 「X と Y に言及されていましたが、両者は異なる方向に働くことがあります。どちらを優先しますか？」
• 「ここには A と B のトレードオフがあります。このプロジェクトではどちらが重要ですか？」
• 「この 2 つの目標は、ときに相反します。その場合、どのようにバランスを取ればよいですか？」

最初に行う理由：

• 矛盾から、認識されていないトレードオフが明らかになります
• その解決によって、「正しい」の意味が変わります
• これを行わずに技術的な曖昧さを解消すると、間違ったものを正確に構築することになります

矛盾を解消した後で、技術的な明確化に進んでください。

1. 技術用語

ユーザーが技術用語を挙げた場合、実際に何を意味しているのかを明確にします。

例：

ユーザーが「OAuth2」と言った場合 -> 質問します：どのフローですか？

• 認可コードフロー（ブラウザーへのリダイレクトを使う人間のユーザー向け）
• クライアントクレデンシャルフロー（サービス間認証向け）
• ユースケースに応じて両方

ユーザーが「データベース」と言った場合 -> 質問します：どの種類ですか？

• 構造化データ向けの SQL（PostgreSQL、MySQL）
• 柔軟なスキーマ向けの NoSQL（MongoDB、DynamoDB）
• 既存のインフラですでに決まっている

ユーザーが「キャッシュ」と言った場合 -> 質問します：どのレイヤーですか？

• アプリケーションレベル（Redis、Memcached）
• HTTP キャッシュ（CDN、ブラウザーキャッシュ）
• データベースクエリキャッシュ

これらには AskUserQuestion を使用し、トレードオフを示す具体的な選択肢を提示します。

2. スコープの境界

ユーザーが広範な概念を挙げた場合、何が含まれ、何が含まれないのかを明確にします。

例：

ユーザーが「ユーザー」と言った場合 -> 質問します：具体的には誰ですか？

• ウェブブラウザーからログインする人間のユーザー
• API アクセス用のサービスアカウント
• 認証フローを分けた両方
• 社内従業員と外部顧客

ユーザーが「X と連携する」と言った場合 -> 質問します：どの部分ですか？

• 認証のみ
• データの完全な同期
• 特定の API エンドポイント
• リアルタイムの Webhook とバッチインポートのどちらか

ユーザーが「レポート」と言った場合 -> 質問します：どの範囲ですか？

• 基本的なデータエクスポート（CSV、Excel）
• インタラクティブなダッシュボード
• スケジュールに基づく自動レポート
• リアルタイム分析

AskUserQuestion を使用し、範囲が明確に異なる選択肢を提示します。

3. 前提条件と制約

ユーザーが要件を提示した場合、その背景にある理由や制約を確認します。

例：

ユーザーが「ライブラリ X を必ず使う必要がある」と言った場合 -> 質問します：なぜですか？

• 規制上の要件（変更不可）
• チームに既存の専門知識がある（必須要件ではなく、希望）
• ほかの箇所ですでに使用している（一貫性のメリット）
• 誤解（より適した選択肢があるかもしれない）

ユーザーが「高速である必要がある」と言った場合 -> 質問します：どの程度の速さですか？

• 100ms 未満の応答時間（厳格な要件）
• 現在の実装より速いこと（相対的な改善）
• 速さの印象（楽観的 UI、読み込み状態）
• 実際のパフォーマンス上のボトルネックが特定されている

ユーザーが「パターン Y に従うべき」と言った場合 -> 質問します：どの側面ですか？

• 実装を完全に一致させる（厳密な一貫性）
• 全般的なアプローチ（柔軟に適用）
• 同じライブラリを使うことだけ（ツールの一貫性）
• 実際には必須ではない（古くなったガイドライン）

「なぜ」なのかを理解するには自由回答形式の質問を使用します。ユーザーが背景を説明できるようになります。

4. バージョンと API の詳細

ユーザーが外部サービスやライブラリを挙げた場合、現状を確認します。

例：

ユーザーが「Stripe と連携する」と言った場合 -> 確認します：

• どの Stripe API バージョンか（最新か、特定のバージョンか）
• Payment Intents API か、旧式の Charges API か
• 必要な機能（一回限り、サブスクリプション、または両方）
• Stripe アカウントの設定はすでに済んでいるか

ユーザーが「React Router を使う」と言った場合 -> 確認します：

• React Router v5 か v6 か（バージョン間で互換性のない変更あり）
• コードベースですでに使用されているか（既存のパターンに従う）
• Browser Router、Hash Router、Memory Router のどれか

事実確認のためのエージェントへの簡単な問い合わせ：

• 「X のどのバージョンが存在しますか？」-> ウェブ検索またはコードベースの確認
• 「現在の API は何ですか？」-> ドキュメントをインターネットで調査
• 「Y はすでに使用されていますか？」-> コードベースの調査

深く調査しないでください。それはブレインストーミングのために取っておきます。基本事項だけを確認します。

5. 完了の定義（最終ステップとして必須）

ブレインストーミングに進む前に、必ず完了の定義を確立してください。

完了の定義では、「成功とはどのような状態か？ 成果物は何か？」に答えます。

矛盾を解消し、要件を明確にした後：

1. これまでに集めた情報から、完了の定義を推定します：

   • 完了時に、何が存在しているでしょうか？
   • ユーザーやシステムは何ができるようになるでしょうか？
   • 具体的な成果物は何でしょうか？

2. 十分に把握できている場合は、内容を提示して確認します：

   Use AskUserQuestion:
   "Based on our discussion, here's what I understand success looks like:
   
   [State the definition of done in 2-4 bullet points]
   
   Does this capture what you're trying to achieve?"
   
   Options:
   - "Yes, that's right" (proceed to brainstorming)
   - "Partially, but..." (user will clarify)
   - "No, let me explain..." (user will reframe)
   

3. 成果物がまだ曖昧な場合は、焦点を絞った質問をします：

   • 「完了時に、何が存在しているべきでしょうか？」
   • 「成功したと、どのように判断できますか？」
   • 「実用最小限の成果物は何でしょうか？」

重要な理由： ブレインストーミングでは、目標を達成する「方法」を探ります。まず目標を確定させる必要があります。そうしなければ、どんな形を作るのか分からないまま、素材の質感だけを探ることになります。

完了の定義は出力バンドルの一部となり、最終設計ドキュメントの冒頭に目立つ形で記載されます。

質問のテクニック

選択肢にはAskUserQuestionを使う

トレードオフのある明確な選択肢が2～4個ある場合：

Question: "Which OAuth2 flow are you targeting?"
Options:
  - "Authorization code flow" (human users with browser redirect)
  - "Client credentials flow" (service-to-service automated auth)
  - "Both flows" (supports human users AND service accounts)

メリット：

• 明確な選択を促します
• トレードオフを分かりやすく示します
• 曖昧な「両方かもしれない」という回答を防ぎます
• 意思決定に適した形式です

理由を尋ねるには自由回答形式の質問を使う

理由や背景を理解する必要がある場合：

「Xはなぜ要件なのでしょうか？」 「Yはどんな問題を解決しますか？」 「Zを含めなかったらどうなりますか？」

メリット：

• 隠れた制約を明らかにします
• ユーザーの思考モデルを把握できます
• 問い直すべき前提を特定できます
• ブレインストーミングの背景情報を得られます

事実の確認には簡単な照会を使う

事実を確認する必要がある場合：

• codebase-investigatorを呼び出す：「ライブラリXはすでに使われていますか？」
• ウェブで簡単に検索する：「API Yの現在のバージョンは何ですか？」
• ファイルを読む：「package.jsonを確認し、既存の認証関連の依存関係を調べてください」

本筋から逸れないでください。これらは簡単な確認であり、調査プロジェクトではありません。

出力：ブレインストーミング用コンテキストバンドル

明確化の後、ブレインストーミングに渡すための明確な要約を作成します：

解決済みのトレードオフ：

• 柔軟性より速度を優先（シンプルな実装を選び、設定可能性が低くなることを受け入れる）
• 利便性よりセキュリティを優先（厳格な検証を選び、手間が増えることを受け入れる）
• 理想より一貫性を優先（既存のパターンを選び、単体では最適でないことを受け入れる）

明確化済みの要件：

• OAuth2クライアントクレデンシャルフロー（サービス間）
• 外部顧客のみ（社内従業員は対象外）
• Stripe Payment Intents API（最新バージョン）
• PCI DSS Level 1への準拠が必須（規制上の制約）
• 「高速」はp99応答時間が200ms未満であることを意味します（測定可能な要件）

検証済みの前提：

• React Router v6はすでに使用中（既存のパターンに従う）
• PostgreSQLデータベース（既存のインフラストラクチャ）
• 既存の認証システムなし（新規構築）

スコープの境界：

• 対象：サービスアカウントの作成、トークンの発行、トークンの検証
• 対象外：人間のユーザーログイン、SSO統合、パスワード管理

このバンドルにより、具体的で曖昧さのない出発点をブレインストーミングに提供できます。

よくある間違い

間違い	修正方法
要件の矛盾を無視する	技術的な明確化に入る前に、目標の衝突を明らかにする
曖昧な用語をそのまま受け入れる	技術用語をすべて明確にする
確認せずにスコープを決めつける	境界について明示的に質問する
「必須」要件に疑問を持たない	制約の背後にある理由を理解する
明確化の最中に深掘り調査をする	簡単な確認にとどめ、調査はブレインストーミングまで保留する
明確化しながら解決策を提案する	理解に集中し、まだ設計しない
「明確そう」だからと明確化を省略する	必ず明確化する。前提は危険です

明確化を終了するタイミング

次の条件を満たしたら、明確化を終了してブレインストーミングに進みます。

• 矛盾が解消されている（トレードオフが明示的に選択されている）
• 技術用語の意味が明確になっている
• スコープの境界が明確になっている
• 制約が理解されている（単に述べられているだけではない）
• 前提条件が検証されている
• 重大な曖昧さが残っていない

完璧な情報は必要ありません。効果的にブレインストーミングを行うのに十分な情報があればよいです。

ブレインストーミングで新たな曖昧さが明らかになった場合は、明確化に戻ることができます。

設計ワークフローとの統合

このスキルは、コンテキストの収集とブレインストーミングの間に位置します。

Context Gathering (starting-a-design-plan Phase 1)
  -> User provides: "Build OAuth2 integration for our API"

Clarification (this skill)
  -> Disambiguate: Which OAuth2 flow? What scope? Why OAuth2?
  -> Output: Service accounts, client credentials, PCI compliance

Brainstorming (starting-a-design-plan Phase 3)
  -> Explore: Architecture options, library choices, implementation phases
  -> Uses clarified requirements as foundation

目的： 間違ったものをうまく作るのではなく、正しいものを作るためにブレインストーミングを行います。