Blindspot Audit
目的
ユーザーのプロジェクトに関する「地図」と、プロジェクトの実際の「領土」との間にあるギャップを見つける。未知の未知を、ユーザーが調査、回答、テスト、または意図的に延期できる具体的な既知の未知へと変換する。
プロジェクトのコンテキストは自己選択的です。所有者は自分がすでに知っていることしか書き留めることができないため、すべてのREADME、TODO、計画は、所有者が頭の中に持っている地図をエンコードしています。そして、それらのファイルから作業するAIは同じ盲点を受け継ぎます。この監査は、意図的にプロジェクトの外部から参照フレームをインポートして、そのギャップを測定します。
このスキルは、単なる汎用的な品質チェックリストではありません。この特定のプロジェクトにとって、この特定の段階において、リポジトリまたは提供されたアーティファクトからの証拠に基づいて、何が異常に重要かを特定する必要があります。この監査は、所有者が「それについて考える必要があるとは知らなかった」と少なくとも一度は感じ、かつその後、何を安全に無視できるかを知ったことで落ち着きを取り戻したときに成功したと言えます。
中核モデル
発見事項を4つの未知のフレームで分類します。
- 既知の既知: プロンプト、ドキュメント、コード、または計画ですでに述べられているもの。
- 既知の未知: ドキュメント、TODO、計画、コメント、またはユーザーの文言ですでに見えている未解決の質問。
- 未知の既知: ユーザーが見せられれば認識できるが、まだ言葉にしたり書き留めたりしていないもの。
- 未知の未知: プロジェクトの形状が暗示する、欠落している概念、隠れた制約、または未質問の問い。
このフレームが重要なのは、処方箋が異なるからです。未知の既知には講義ではなくチェックリストの一行が必要です。未知の未知には短い説明と最も安価な最初のステップが必要です。良い出力は確実性を主張しません。候補を明らかにし、最も安価な次の確認方法を提供します。
基本ルール
これらのルールは、このスキルの失敗モードが「ギャップを見逃すこと」ではなく、「無視される汎用チェックリストのネタになること」であるために存在します。
- プロジェクト自身の追跡ドキュメントは、発見事項のソースではなく、フィルターです。 README / TODO / ロードマップ / チェックリスト / 課題リストにすでにあるものはすべて既知の未知です。それを発見として報告してはいけません。(現場データ:このフィルターにより、候補リストは通常半分以上削減され、これが所有者がレポートを信頼する主な理由です。)
- トップの発見事項は3~7件に制限し、影響 × 所有者が本当に気づいていない可能性でランク付けします。あふれたものは短い「シグナルの弱いウォッチリスト」または台帳に移動します。メインリストには決して入れないでください。
- 欠如だけでは発見事項になりません。 「あなたにはXがない」は、このプロジェクトに対する具体的な結果と、それを埋めるための最も安価な最初のステップを述べることができる場合にのみカウントされます。
- 常に2つの信頼セクションを含めます:「確認済み、十分にカバーされている」と「今はスキップ可能」 (各スキップには明示的な再確認トリガーを付けます)。これらは不安と再スキャンを防ぎ、所有者がレポートを信頼できることを学ぶ方法です。
- 規制対象ドメインについては控えめに扱います。 法律、税務、または規制に関する発見事項については、見つけた内容とそのソースを述べ、その後、専門家が確認する必要があると明確に述べます。あなたは偵察兵であり、弁護士や会計士ではありません。
モード
quick: ドキュメントとプロジェクトインベントリを読み、トップの盲点を返します。deep: 発見事項をランク付けする前に、代表的なコードパス、テスト、設定、ドキュメントを検査します。interview: 回答がアーキテクチャ、ワークフロー、スコープ、またはリスクを変更する場合に、一度に1つの質問をします。post-implementation: 完了した変更、メモ、差分、テストを比較して、残っている未知のものを見つけます。planning: 実装前に、データモデル、インターフェース、UXフロー、運用、または検証を変更する可能性が高い意思決定を表面化します。
ユーザーの文言からモードを推測します。ユーザーが今すぐ実行するように依頼した場合、監査の境界を推測できない場合を除き、モードについて質問しないでください。
クイックスタート
- プロジェクトルートと監査境界を特定します。
- ファイルシステムのプロジェクトが利用可能な場合、インベントリヘルパーを実行します。スクリプトはこのスキル自身のフォルダにあります。このSKILL.mdからの相対パスで解決します。
python <this-skill-folder>/scripts/project_inventory.py <project-root> --format md
監査の質問の一部として、ランタイム出力、生成されたレポート、ログ、またはキャッシュされたアーティファクトがある場合にのみ、--include-generatedを使用します。
- 関連するリファレンスのみを読みます。
references/archetypes.md: プロジェクトタイプと予想される盲点を選択します。references/lenses.md: 監査レンズを導出して適用します。references/host-surfaces.md: Claude Code、Codex、OpenCode、CLI、またはチャットのみのサーフェスに質問と出力を適応させます。references/ledger-lifecycle.md: 耐久性のある盲点台帳を発見、作成、ルーティング、または更新します。references/report-template.md: 結果をフォーマットします。
- 盲点台帳を発見または初期化します。
- 以前の台帳が存在する場合、検索前にそれを読みます(差分実行ルールが適用されます – 「台帳と差分実行」を参照)。
- 台帳が存在せず、ホストがファイルを書き込める場合、ユーザーが読み取り専用/チャット専用出力を要求していない限り、最適なプロジェクトローカルなドキュメント場所に
BLINDSPOT_LEDGER.mdを作成します。 - 台帳が存在せず、ホストがファイルを書き込めない場合、レポートに提案されたパスと最初の台帳エントリを含めます。
- インベントリから最も強力な証拠ファイルを検査します:README/AGENTS、計画、パッケージ設定、アプリエントリポイント、テスト設定、CI、環境変数例、スキーマ、プロンプト、エージェント/スキルファイル、ランタイムドキュメント。
- ホストがWebアクセスを持っている場合、新鮮な目による外部スキャンを実行します(ワークフローステップ5を参照)。
- 発見事項をランク付け、可能な場合は所有者にインタビューし、レポートを作成し、台帳を更新します。
ホストサーフェスポリシー
監査の中核は、Claude Code、Codex、OpenCode、CLI、およびプレーンチャットで同じように動作する必要があります。インタラクションスタイルのみが変更されます。ホストごとの詳細についてはreferences/host-surfaces.mdを参照してください。
- 選択可能なホスト(Claude Code
AskUserQuestion、OpenCodequestion):意思決定がアーキテクチャ、ワークフロー、スコープ、またはリスクを変更する場合、および所有者認識インタビューのために、2~3の選択肢からなる短い質問を1つし、レポートまたは台帳で選択されたオプションを記録します。 - Codexまたはチャット専用ホスト:重要でない質問でブロックしないでください。最も安全な可逆的な仮定で続行し、それを仮定としてマークし、ユーザーが後で選択すべきオプションを含む「意思決定パケット」を含めます。
- Webアクセスがないホスト:新鮮な目による外部スキャンをスキップし、レポートで明示的にそのように述べ、時間に敏感なドメイン(規制、プラットフォームポリシー、価格設定)を、トレーニング知識から断言するのではなく、未確認としてフラグします。
- ファイル書き込み可能なホスト:プロジェクト監査の場合、ユーザーが読み取り専用/チャット専用出力を要求していない限り、デフォルトで台帳を作成または更新します。レポートにパスとルーティング編集を記載します。
- 読み取り専用または公開共有ホスト:ユーザーが実行できるコマンド/チェックを含むポータブルなレポートを返します。
続行することがリスクが高い、破壊的である、高価である、または誤解を招く結果を生み出す可能性が高い場合にのみ、即座に質問します。
台帳と差分実行
初回実行:
references/ledger-lifecycle.mdを使用して、BLINDSPOT_LEDGER.mdの最適な耐久性のある場所を選択します。- ファイル書き込みが適切な場合、
templates/BLINDSPOT_LEDGER.mdから台帳を作成します。 - 台帳を最も近いルーティングサーフェス(例:運用README、ドキュメントインデックス、またはハンドオフポインター)に追加します(そのルーティングファイルがすでに存在する場合)。
- 監査スコープ、モード、証拠範囲、および最初の発見事項を記録します。
プロジェクトにすでに盲点台帳が存在する場合:
- 台帳を入力として扱いますが、真実として扱わないでください。影響が大きい、または古い発見事項を現在のコード/ドキュメントと照らし合わせて再確認します。
- 出力を
new、changed、confirmed、downgraded、resolved、またはneeds-decisionとして分類します。 - 現在の目標をブロックしない限り、変更されていない未解決の項目を繰り返さないでください。これにより、繰り返し実行がネタのように感じられるのではなく、進歩のように感じられるようになります。
- 台帳が新しいが、インデックス、ハンドオフ、または運用READMEからルーティングされていない場合、それを発見可能性の盲点としてフラグします。
- 台帳を更新する際、ローカルのステータス言語とIDを維持します。
良い台帳は将来の監査を安くします。悪い台帳は別の隠しドキュメントになるため、常に発見可能性を確認します。
検索衛生
範囲を限定した検索を使用します。盲点監査は広範なリポジトリに触れることが多く、ノイズの多い生成ファイルは誤った自信を与えたり、コンテキストを浪費したりする可能性があります。
rgおよび類似のツールのデフォルト除外(監査が明示的にそれらの領域を対象としない限り):
!.git/**
!node_modules/**
!.venv/**
!dist/**
!build/**
!runtime/**
!external_repos/**
!vendor/**
!docs/archive/**
!docs/research/**
!docs/sources/**
!data/external/raw/**
リポジトリ全体のスキャンよりも、対象パスと--glob除外を優先します。広範なスキャンが巨大な生成ファイルを返した場合、結果を使用する前に停止し、より厳密な境界で再実行します。
ワークフロー
1. 地図を定義する
ユーザーの明らかな目標、プロジェクトタイプ、成熟度、および監査境界を2~4行で述べます。仮定は明示的にマークします。所有者プロファイルを含めます。
- 個人またはチーム?所有者が明確に得意とする分野は何か、そしてより有用なのは、得意でない分野は何か?盲点は所有者の非専門分野に集中するため、それらのレンズの重みを上げます。
- 趣味または商用?プライベートまたはパブリック?商用またはパブリックの意図は、プライベートな趣味のプロジェクトにはまったくノイズとなる法律、税務、市場のレンズをアクティブにします。意図がファイルから読み取れない場合、スキャン前に質問します(短い質問1つ) – 意図を誤って推測すると、監査全体が無駄になります。
2. 証拠を収集する
インベントリヘルパーと対象を絞った読み取りを使用します。プロジェクトの自己認識サーフェス(README、TODO、ロードマップ、チェックリスト、設計ドキュメント、概要/アウトライン)を最初に読みます – これらは最良のプロファイルソースであると同時に、ノイズフィルターでもあります(基本ルール1)。広範な推測よりも証拠を優先します。証拠に次のようにタグを付けます。
observed: ファイルまたは出力に直接存在する。absent: 調査範囲内で期待されるアーティファクトが見つからない。inferred: 構造、命名、または慣習から可能性が高い。question: ユーザーまたはドメイン所有者の確認が必要。
3. 領域を分類する
references/archetypes.mdから1つ以上のアーキタイプを選択します。プロジェクトがハイブリッドである場合、1つのカテゴリに無理やり分類しないでください。
4. レンズを実行する
プロジェクトの段階に適合するレンズのみを適用します。プロトタイプにエンタープライズコンプライアンスは必要ありませんが、データ損失の境界、シークレット処理、または回復可能性は依然として必要になる場合があります。
5. 新鮮な目による外部スキャン
ホストがWebアクセスを持っている場合、次の2つの質問について時間制限付きのリサーチを行います。
- このカテゴリの健全なプロジェクトは、現在、どのようなものを標準装備として扱っているか?
- このプロジェクトのドキュメントには絶対に含まれ得ない、規制、プラットフォームポリシー、市場やジャンルの慣習、ツールなど、過去6~12か月で何が変わったか?
質問2は不釣り合いに価値があります。時間に依存する変化は、リポジトリと所有者の記憶の両方に対して構造的に見えません。(現場データ:初期の実行では、最も影響の大きい発見事項 – 翌月発効のAIコンテンツラベル表示法、文書化された計画を無効化した決済プロバイダーの買収 – はすべてこのステップから得られました。)ここで見つけたものについてはソースを引用します。Webアクセスがない場合はスキップし、開示します(ホストサーフェスポリシーを参照)。
6. 盲点をチェックに変換する
すべての発見事項について、以下を含めます。
- 何が欠けている可能性があるか。
- このプロジェクトにとってなぜ重要か。
- 証拠。
- 最も安価な次の確認方法。
- 可能性の高い所有者または意思決定サーフェス。
- 優先度:今すぐ、次回、後で、またはウォッチ。
- 確信度:高、中、低。
プロジェクト自身の追跡ドキュメントに出現する候補は削除し(基本ルール1)、上位3~7件を保持し、残りはウォッチリストまたは台帳に移動します。
7. 所有者にインタビューする
発見事項を提示し、所有者がすでに知っていたものはどれかを尋ねます(選択可能なホストでは単一の複数選択質問が適しています)。各発見事項を次のように分類します。
| 認識 | 意味 | 処方箋 |
|---|---|---|
unknown_unknown | 所有者は知らなかった | ここでなぜ重要かを説明 + 最も安価な最初のステップ |
unknown_known | 所有者は知っていたが、どこにも書かれていない | 修正は実装ではなく文書化 – エージェントや将来のセッションがそれを確認できるように、追跡ドキュメントに追加する |
deliberate_skip | 所有者は検討し、選択しなかった | 理由と再確認トリガーを付けてスキップリストに移動する |
(現場データ:初期の実行では、トップの発見事項の約半数がunknown_knownであることが判明しました – リポジトリには実際のギャップがありますが、所有者の頭の中にはありません。この区別により、フォローアップが完全に変わります。)
質問できないホストでは、すべての認識値をunconfirmedとマークし、インタビュー質問をレポートに埋め込み、未決定の意思決定を「意思決定パケット」に入れます。
8. 出力を使いやすく保つ
最もシグナルの強い盲点から始めます。常に2つの信頼セクションを含めます(基本ルール4)。レポートと台帳の散文は、所有者が会話で使用している言語で記述します。ID、ステータス、認識値は、セッションや言語をまたいで差分が取れるように英語のままにします。references/report-template.mdに従ってフォーマットします。
ガードレール
- プロジェクトの証拠が関連性を示さない限り、一般的なベストプラクティスを発見事項として提示しないでください。
- 台帳またはプロジェクト自身の追跡ドキュメントにすでに存在する項目を再報告しないでください。
- 個人の実験や初期のプロトタイプに重いプロセスを要求しないでください。
- ユーザーが明示的に修正を要求しない限り、コード変更を行わないでください。
- ファイルがないという理由だけで何かが壊れていると主張しないでください。欠如が示唆することと、確認方法を述べてください。
- CI、テスト、リリースドキュメント、またはデプロイファイルの欠如は、プロジェクトが再現可能な納品、共有ハンドオフ、またはプロダクションのような信頼性を主張する場合にのみ盲点として扱います。個人のメモや初期のプロトタイプはそれらを必要としない場合があります。
- ユーザーをすべての可能なリスクで埋め尽くさないでください。プロジェクトへの適合性、影響範囲、可逆性、可能性でランク付けします。
- ユーザーがドメインの非専門家である場合、なじみのない盲点について短い教訓的なメモを含めます。
- 現在の外部プラットフォームの動作に依存する発見事項については、事実として扱う前に、公式ドキュメントまたは現在のリサーチで検証します。Webアクセスがない場合は、トレーニングデータの日付に基づいて発見事項を提示し、制限を明確に述べます。
- 監査台帳の更新をファイルシステムに書き込める場合は、必ず書き込みます。書き込めない場合は、ユーザーが手動で適用できるパッチを出力として提供します。