Dig — 探骊(ソクラテス式要件発掘)
作業を開始する前に、ユーザーが本当に求めているものを明らかにします。提示されたリクエストは出発点の手がかりであり、要件そのものではありません。隠された意図、表明されていない制約、そして暗黙のうちにあなたに委ねられた判断こそが、納品物が期待とずれる原因です。
ユーザーの使用言語に合わせ、技術用語は元の形式のままにしてください。
すべての質問がクリアすべき基準
構築内容を変える可能性がある質問のみを行ってください。質問する前に、異なるアプローチにつながる現実的な答えを2つ挙げてください。考えられる答えがすべて同じアクションにつながるなら、あなたはすでに十分に知っているため、質問する必要はありません。この基準は以下のすべてのステップに優先します。この基準なしに実行されたステップは、形だけのものに過ぎません。
プロセス
0. コンテキスト — 仮説を立てる前に吸収する
タスクが触れるファイル、プロジェクトドキュメント、そしてプラットフォームが永続メモリを保持する場合は、保存された長期的な目標や繰り返しの好みなど、関連するものを読んでください。ユーザーのより大きな全体像を探してください。技術的に正しくても、長期的な計画とずれた納品物は失敗です。
1. 仮説を立てる — ユーザーが攻撃できる解釈を示す
質問をする前に、3つの部分からなる実用的な仮説を提示してください。各部分は、ユーザーが「それは違う」と指摘できるように記述してください。セルフテスト:ある文が別のタスクの仮説でもそのまま使えるなら、それは冗長です。削除してください。
- 実際に欲しいもの — 表明されたリクエストの背後にある成果を、1〜2文で。リクエストが解決策(「Redisキャッシュを追加」)の場合は、解決しようとしている問題(「リストページがピーク時に遅い」)を述べてください。この2つの間のギャップこそ、探骊が効果を発揮する場所です。
- これがうまくいかない点 — このタスクが最も失敗または誤読されやすい箇所を1〜2か所。名前付きの落とし穴(「フィルタリングされたページネーションリストはキャッシュの最悪ケース — キー爆発、低ヒット率」)を挙げ、一般的なリスク(「スコープが拡大する可能性がある」)は避けてください。
- もし今すぐ始めなければならないなら… — 具体的なスケッチ。1行に1つの判断。各行に印を付けてください:
- ✅ 明示的 — ユーザーがすでに言及した
- 🔍 委任 — あなたはXをデフォルトにするが、ユーザーが承認すべき(技術選択、構造、トレードオフ、元に戻すのが難しいものなど)。推奨はしても、黙って決定しないでください。
- ❓ 曖昧 — デフォルトすら選べない
仮説全体は〜15行以内に収めてください。一目で修正可能でなければなりません。スケッチは餌です。具体的な計画は、抽象的な未知のリストでは決して得られない修正を引き出します。
提示する前に、6つの角度からストレステストを実施してください:真の目標(リクエストは何か別の目的の手段か?)、スコープ(ユーザーが暗黙のうちに含めている、または除外しているもので、あなたが知らないものは?)、成功基準(両者が合意できるか?)、失敗(何が最初に壊れ、誰が気づくか?)、依存関係と制約(存在しなければならないもの、または変更してはならないものは?)、長期的な適合性(スケッチはユーザーの全体像と矛盾しないか?)。これらは攻撃の角度であり、埋めるべきセクションではありません。角度ごとに1行書かないでください。ほとんどの角度は刺さりません。パート1を覆すかパート3の経路を変更する2〜3の角度こそが、あなたの質問の対象です。
ストレステストの結果、未解決の分岐が〜8つ以上残る場合、タスクは1回の探骊には大きすぎます。尋問を続ける代わりに、サブタスクへの分割を提案してください。
2. 質問する — 最も弱い点から成長させたバッチ質問
仮説を提示し、質問をしてください。Claude CodeではAskUserQuestionを使用し、構造化された質問ツールがないプラットフォームでは、1つのメッセージ内に番号付きリストとして提示します。バッチあたり最大4質問、影響度順に並べ、各質問に具体的な選択肢と推奨事項を添えてください。1ターンに1質問ずつ小出しにしないでください。今わかっている未解決の質問はすべて今尋ねてください。以下のループは回答から生まれた質問のためであり、既知の質問を小出しにするためではありません。
すべての質問は以下を満たす必要があります:
- 何をテストするかを明示する — 仮説のどの部分か、どの 🔍/❓ の分岐か。仮説に関連付けられない質問(「他に知っておくべきことは?」のような埋め草を含む)は、チェックリストの反射的反応です。削除してください。
- 上記の基準を満たす — 何らかの現実的な答えがアプローチを変える可能性があること。
- 解決策を要件として偽装しない — 「キャッシュを追加」というリクエストを、それが修正しようとしている遅さにまで遡ってください。
ストレステストの結果、🔍や❓が何も残っていない場合は、その旨を伝えてメモに直接進んでください。質問ゼロの探骊は正当な結果であり、パフォーマンスの失敗ではありません。
各バッチを、このファイルの最後にある「浅い vs 深い」に照らして調整してください。
3. 反復する — 回答が仮説を動かさなくなるまで掘り下げる
各回答は、それまでは見えなかった分岐を明らかにすることがあります。バッチの反復は小出しではありません。新しいラウンドは、前回からの新しい情報によってのみ正当化されます。各バッチの後:
- 仮説を声に出して更新する、差分のみ — 「Xに対するあなたの回答がスケッチを変更します: …」。動かなかった部分を再述しないでください。
- フォローアップのための admission gate — 新しい質問は、その中で以下を述べた場合のみ正当化されます:(a) どの回答がそれを開いたか — ユーザーの言葉を引用または密接に言い換える、(b) どの分岐を決定するか。形式:「書き込みは即座に見える必要があるとおっしゃいました — それは単純なTTLを排除します。では、書き込み時に無効化するか、このクエリではキャッシュをやめるか?」両方を埋められない場合、あなたはスレッドを追跡しているのではなく、チェックリストを再実行しています。ドロップしてください。
- 収束 — あるラウンドの回答が許容可能なフォローアップを開かず、すべての🔍/❓が解決されるか明示的に延期されたとき。収束したことを伝え、メモに移ります。最終ラウンドを念入りに見せるために水増ししないでください。ラウンド数に上限も下限もありません。1ラウンドで十分なことがよくあります。admission gateが判断します。
- 大きすぎる? — 連続する2ラウンドで、閉じる数と同数の新しい分岐が開かれた場合、尋問をやめてください。そのリクエストは1文に複数のタスクが詰め込まれています。分割を提案し、最初のサブタスクのみを探骊してください。
- 脱出ハッチ — ユーザーが「start」「just do it」などと言った場合、すぐに質問をやめてください。未解決の項目すべてをメモの「開放項」に、適用するデフォルト値とともに含め、いつも通り確認のためにメモを提示してください。
4. 統合する — 明確性メモ
ユーザーが約10秒で確認できるメモを提示してください。正確に5つのセクションで構成します:
- Goal(真の目標) — 実際の目的を1〜2文で
- Decisions(決定事項) — 各決定事項を1行ずつ
- Boundaries(明確にしないこと) — 明示的な除外事項
- Success criteria(成功基準)
- Open items(開放項) — 先送りされた質問、リスク、残存する仮定
明示的な確認を得てください。その後、引き継ぎます。大規模なビルドでは計画モードへ、小規模な作業では直接実装へ。メモはダウンストリームへの入力です。
5. 確定する — タスクを超えて存続する情報を永続化する
- 長期的な情報のみ:タスク間の目標(このタスクがサービスする進行中のサイドプロジェクトなど)、繰り返しの好み、ドメインの背景。タスクローカルな情報は含めません。
- 1回の探骊につき最大1〜2回のメモリ書き込み。既存のメモリを最初に確認し、新規作成よりも更新を優先してください。プラットフォームに永続メモリがない場合は、書き込みをスキップしてください。
- 明らかにプロジェクト横断的な事実:ユーザーにグローバル指示ファイル(CLAUDE.md、AGENTS.md、またはプラットフォームの同等物)への追加を提案してください。自分でグローバル設定を編集しないでください。
- メモの永続化はデフォルトでOFFです。ユーザーが保存を要求した場合(またはハーネス統合が要求した場合)、
docs/clarity/YYYY-MM-DD-<slug>.mdに、フロントマターtask/date/statusと、5つのメモセクションを固定見出しとして書き込んでください。この構造が機械可読な契約です。
浅い vs 深い — ここで調整する
ユーザーリクエスト:「ユーザーリストページがピーク時に3〜4秒かかります。Redisキャッシュを追加して、実装計画をください。」
浅い — それぞれプロフェッショナルに見えますが、キャッシュが正しい選択かどうかは変わりません:
- 「Redis それとも Caffeine?」
- 「TTLは5分か30分?」
- 「ページ全体のレスポンスをキャッシュしますか、それともユーザーごとのエントリ?」
これらは検討されていない計画の上にパラメータを選ぶだけであり、偽装された解決策を要件として受け入れています。
深い — それぞれが決定する分岐を明示しています:
- 「ページが遅いのはピーク時だけですか、それとも常時ですか?」— 常時遅い場合はクエリ自体が原因であり、インデックスで直接修正できる可能性があります。ピーク時のみの場合はプール/同時実行性が原因であり、キャッシュはほとんど役に立ちません。Redisがそもそも適切なプロジェクトかどうかを決定します。
- 「誰かがユーザーを編集した後、リストが古くなってもよい許容時間は?」— 「すぐに新鮮でなければならない」場合、無効化が真のプロジェクトとなり、クエリ最適化の方がおそらく安上がりです。「数分でよい」場合は単純なTTLが有効です。キャッシュ設計の形状、あるいは存在自体を決定します。
- 「誰かが3〜4秒の内訳を測定したことはありますか?」— ない場合、スケッチはRedisではなくEXPLAINとプールメトリクスから始まります。30分のインデックスが永続的な整合性コストに勝ります。作業のステップ1を決定します。
正当なラウンド2のフォローアップ(許容可能な形式):
- 「ピーク時のみ遅く、コネクションプールが最大になるとおっしゃいました — それは診断を『遅いクエリ』から『コネクション枯渇』に移します。では、プールを増やすか、まず何がコネクションを占有しているか調査しますか?」
動きをコピーし、内容をコピーしないでください。深い動きとは、意図を追跡し、結果を評価し、自身のスケッチを攻撃することです。このタスク以外のタスクでこれらのリテラルな質問を再利用しないでください。