Find Your Knowns
このルーティングワークフローを使用して、リスクの高い実装の判断を下す前に、ユーザーの「マップ」と実際の「テリトリー」のギャップを埋めてください。マップとは、ユーザーが与えたプロンプト、チケット、計画、またはリファレンスです。テリトリーとは、実際のリポジトリ、製品動作、デザインシステム、データ、API、本番環境の制約、そして暗黙のユーザー期待です。
帰属:これはThariq Shihiparの記事「A Field Guide to Fable: Finding Your Unknowns」と、そのコンパニオンである「Know your unknowns」の例に触発された、オリジナルのエージェントワークフローです。再利用可能な成果物を作成する際はフレームワークをクレジットしてください。ただし、ソーステキストをコピーしないでください。
トリガーポリシー
次の場合にこのワークフローを使用してください:タスクが曖昧、審美的、戦略的、高リスク、不慣れ、長時間実行、未調査のコードベース領域を含む、または製品、デザイン、API、セキュリティ、データ、移行、運用上の制約が隠れている可能性がある場合。
強いトリガーフレーズには、「better」、「cleaner」、「nice」、「intuitive」、「production-ready」、「you decide」、「like X」などがあります。また、大規模な実装計画を作成する前、実装の現実が計画と矛盾する場合、またはレビュアー/ステークホルダーの承認、マージ前の説明、変更の理解ワークフローのために実装後にも使用します。
通常のコードレビュー、バグレビュー、セキュリティレビュー、またはPRの欠陥発見リクエストにはこのワークフローを使用しないでください。それらのタスクには、未知の発見ルーティングではなく、レビュー固有のメソッドが必要です。変更が小さく、明白で、直接指定され、影響が低く、調査するよりも修正する方が安価な場合は、このワークフローを軽量に保つか、完全にスキップしてください。
運用ルール
- 小さく明白な作業には儀式を避けてください。変更が直接的で、低リスクで、明確に指定されている場合は、未知の影響は低いと述べて続行してください。
- 推測する前に、テリトリーを調査することを優先してください。リスクを事実として提示する前に、関連するファイル、テスト、ドキュメント、設定、スキーマ、ログ、製品リファレンスを読んでください。
- 不可逆的な実装の前に、安価な調査を優先してください。大規模なアーキテクチャにコミットする前に、モック、grepパス、小さなテスト、使い捨てスクリプト、リファレンスマップを使用してください。
- ユーザーの入力が必要な場合は、一度に1つの高インパクトな質問をしてください。アーキテクチャ、データモデル、UX、セキュリティ体制、移行戦略、公開API、リリースリスクを変える可能性のある質問を優先してください。
- 具体的な成果物を作成してください。有用な成果物は、リスクテーブル、意味マップ、モック、決定記録、実装ノートファイル、承認ドキュメント、クイズなどです。次のアクションのない一般的な「Xを検討する」リストは避けてください。
- ブロックされない限り作業を続けてください。ユーザーが不在で、リスクがアーキテクチャ/API/セキュリティ/データに重大でない場合は、最も保守的で元に戻せるデフォルトを選択し、その前提を記録して続行してください。
クイックトリアージ
プレイブックを選択する前にタスクを分類してください:
- 既知の既知事項(Known knowns):ユーザーが明示的に与えた要件。
- 既知の未知事項(Known unknowns):ユーザーが既に名前を付けている、または明確に暗示している未解決の質問。
- 未知の既知事項(Unknown knowns):ユーザーが見せられれば認識するであろう、テイスト、慣習、品質基準、ドメインの期待。
- 未知の未知事項(Unknown unknowns):どちらの側もまだ表面化していない、隠れた制約、動作、リスク、または不足しているドメイン知識。
次に不確実性を分類します:
- 低不確実性、低影響:直接実装します。オプションで使用した1つの前提をメモします。
- 中程度の不確実性:1つの焦点を絞ったプレイブックを実行し、続行します。
- 高不確実性または高影響範囲:リポジトリを調査し、ブラインドスポットパスを実行してから、インタビュー、リファレンスハント、モック、調整可能な計画にルーティングします。
- 作業中に計画が現実と矛盾する:実装ノートを使用し、影響を受ける部分を再計画します。
- 作業は完了したが、理解や承認が不足している:承認ドキュメントまたは変更クイズを使用します。
ルーティングテーブル
現在のタスクに必要なプレイブックのみをロードしてください:
- 不慣れなコードベースモジュール、隠れた制約、または高リスク領域:
references/blindspot-pass.mdを読んでください。 - ユーザーにドメイン語彙や専門家レベルの品質基準が不足している:
references/teach-me-my-unknowns.mdを読んでください。 - 曖昧なデザイン、UXのテイスト、「make it nicer」、「intuitive」、「like X」:
references/design-directions.mdを読んでください。 - バックエンド、API、または状態の作業の前にUX/製品の形状が不明確:
references/mock-before-wire.mdを読んでください。 - ソリューション空間が開いており、コスト/リスクのトレードオフが重要:
references/effort-axis-brainstorm.mdを読んでください。 - 既知の曖昧さにユーザーの決定が必要:
references/interview.mdを読んでください。 - 既存の実装、製品、または競合の動作を仕様とする必要がある:
references/reference-hunt.mdを読んでください。 - 大規模な計画が作成されようとしている:
references/tweakable-plan.mdを読んでください。 - 実装が驚きを明らかにしたり、計画を無効にしたりする:
references/implementation-notes.mdを読んでください。 - 完了した作業にレビュアーやステークホルダーの承認が必要:
references/buy-in-doc.mdを読んでください。 - ユーザーがマージ前に大規模な変更を理解したい:
references/change-quiz.mdを読んでください。
デフォルトワークフロー
- マップを簡潔に再述する:ユーザーが何を求め、何が既に分かっているか。
- テリトリーを調査する:リスクをランク付けする前に、関連するリポジトリ/製品の表面から証拠を収集する。
- 最も影響の大きい未知を特定する:ユーザーが調査を求めた場合を除き、簡潔に保つ。
- ルーティングする:テーブルから1つ以上のリファレンスプレイブックを選択する。
- 実行する:要求された成果物を作成する、1つの高インパクトな質問をする、または記録された前提で実装する。
専門のプレイブックが不要な場合は、このコンパクトな出力を使用してください:
Unknowns check:
- Known knowns: ...
- Highest-risk unknown: ...
- Cheap probe performed: ...
- Assumption or question: ...
- Next action: ...
ルーティング例
- 不慣れなコードベースモジュール:「この認証パッケージにSSOを追加してください。以前に触ったことがありません」 ->
blindspot-pass.md、その後リスクが高ければtweakable-plan.md。 - 曖昧なデザインリクエスト:「レビューダッシュボードをよりすっきりとプレミアムにしてください」 ->
design-directions.md、オプションでmock-before-wire.md。 - 既知のアーキテクチャの曖昧さ:「これはAPIゲートウェイとワーカーのどちらに置くべきですか?」 ->
interview.md、その後tweakable-plan.md。 - リファレンスベースの実装:「このRustクレートのリトライ動作をTypeScriptクライアントに移植してください」 ->
reference-hunt.md。 - 実装途中の逸脱:「スキーマが計画された移行をサポートしていません」 ->
implementation-notes.md、その後、新しいパスがデータ/API契約を変更する場合のみ質問する。 - マージ前のクイズ:「マージする前にこのブランチを理解していることを確認してください」 ->
change-quiz.md。