Communitygithub.com

aiswarya797/find-your-knowns

AIコーディングエージェントスキル。実装前に隠れた未知の要素を、実行可能な既知の要素に変換します。

find-your-knowns とは?

このスキルは、AIコードエージェントが実装のリスクを冒す前に、ユーザーの「マップ」(プロンプト、チケット、計画)と実際の「テリトリー」(リポジトリ、製品動作、デザインシステム、API、データ、運用制約、暗黙のユーザー期待)のギャップを埋めるためのルーティングワークフローを提供します。主にClaude Code、Cursor、CodexなどのAIエージェント向けに設計されており、タスクが曖昧だったり、戦略的・高リスクな場合、またはコードベースの未調査領域を含む場合に起動します。ワークフローは、既知・未知の分類と不確実性の評価から始まり、必要に応じて「ブラインドスポット調査」「デザイン方向性」「インタビュー」などの参照プレイブック(playbook)にルーティングします。これにより、エージェントは安価な調査プローブを優先し、アーキテクチャやデータモデルに影響する高インパクトな質問を1つずつユーザーに投げかけ、リスクテーブルや意味マップなどの具体的なアーティファクトを生成します。結果として、推測に基づく実装を減らし、証拠に基づいた意思決定を促進します。

対応~Claude Code~Codex CLI~Cursor
npx skills add aiswarya797/find-your-knowns

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

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の欠陥発見リクエストにはこのワークフローを使用しないでください。それらのタスクには、未知の発見ルーティングではなく、レビュー固有のメソッドが必要です。変更が小さく、明白で、直接指定され、影響が低く、調査するよりも修正する方が安価な場合は、このワークフローを軽量に保つか、完全にスキップしてください。

運用ルール

  1. 小さく明白な作業には儀式を避けてください。変更が直接的で、低リスクで、明確に指定されている場合は、未知の影響は低いと述べて続行してください。
  2. 推測する前に、テリトリーを調査することを優先してください。リスクを事実として提示する前に、関連するファイル、テスト、ドキュメント、設定、スキーマ、ログ、製品リファレンスを読んでください。
  3. 不可逆的な実装の前に、安価な調査を優先してください。大規模なアーキテクチャにコミットする前に、モック、grepパス、小さなテスト、使い捨てスクリプト、リファレンスマップを使用してください。
  4. ユーザーの入力が必要な場合は、一度に1つの高インパクトな質問をしてください。アーキテクチャ、データモデル、UX、セキュリティ体制、移行戦略、公開API、リリースリスクを変える可能性のある質問を優先してください。
  5. 具体的な成果物を作成してください。有用な成果物は、リスクテーブル、意味マップ、モック、決定記録、実装ノートファイル、承認ドキュメント、クイズなどです。次のアクションのない一般的な「Xを検討する」リストは避けてください。
  6. ブロックされない限り作業を続けてください。ユーザーが不在で、リスクがアーキテクチャ/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. マップを簡潔に再述する:ユーザーが何を求め、何が既に分かっているか。
  2. テリトリーを調査する:リスクをランク付けする前に、関連するリポジトリ/製品の表面から証拠を収集する。
  3. 最も影響の大きい未知を特定する:ユーザーが調査を求めた場合を除き、簡潔に保つ。
  4. ルーティングする:テーブルから1つ以上のリファレンスプレイブックを選択する。
  5. 実行する:要求された成果物を作成する、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。

関連スキル