exhaustive-systems-analysis

網羅的なシステム分析

システム全体の正確性を確認する作業では、このスキルを使用します。システムを把握し、最もリスクの高い動作を特定し、具体的な障害仮説を検証または反証して、別のエンジニアがコードベース全体を読み直さなくても対応できるレポートを残すことが目的です。

防止すべき失敗

1. ファイルを調べるだけで、動作をエンドツーエンドで追跡しない表面的な監査
2. 十分な証拠がないまま疑いをバグとして報告する、根拠のない断定
3. 多数のサブシステムにまたがる大規模な監査での、文脈の逸脱
4. 実際の正確性やリリース準備に関するリスクを見逃す、表面的なレビュー

作業モード

• デフォルトではchat-first形式で出力します。ユーザーがドキュメントを求める場合、または監査に複数セッションで扱う成果物が明らかに必要な場合を除き、所見をインラインで返します。
• 大規模な監査や中断後に再開する監査では、artifact modeに切り替えます。リポジトリ内の既存の慣例に合わせて、docs/audit/または.claude/docs/audit/を使用します。
• ユーザーが修正を明示的に求めない限り、監査中にコードの修正を始めないでください。このスキルの目的は、診断、検証、優先順位付けです。

ワークフロー

0. 監査範囲を調整する

詳しく読み始める前に、references/templates.mdのテンプレートを使って、1画面に収まる範囲の概要を作成します。

以下を記録します。

• レビュー対象のシステムまたは領域
• 最も重要な、ユーザーに見えるワークフローまたは契約
• 状態、副作用、並行処理、認証、永続化、外部連携など、リスクが高い可能性のある領域
• 対象外の領域
• 出力モード：chat-firstまたはartifact mode

依頼の範囲が広い場合は、ユーザーの成果やリリース準備に実際に影響し得るモジュールに絞り込みます。

1. コードを読む前に意図を把握する

意図された動作を明らかにする資料だけを読みます。

• README、CLAUDE.md、アーキテクチャドキュメント、ADR
• ユーザーに見える動作や契約を説明するテスト
• 対象領域に関連する最近のコミット
• TODO、FIXME、HACK、既知の問題
• 入手可能な場合は、インシデント記録、バグ報告、課題トラッカーの項目

以下を抽出します。

• 重要なワークフロー
• 外部向けのインターフェース
• ホットスポットと最近変更が多い箇所
• コードだけでは完全に検証できない、手動確認のみの領域

2. 対象範囲の台帳を作成する

詳細な分析に入る前に、対象範囲の台帳テンプレート（references/templates.md）を使って、システムをサブシステムに分けます。

各サブシステムについて、以下を記録します。

• 名前
• エントリーポイント
• 対象範囲に含めるファイルまたはディレクトリ
• 不変条件または保証される動作
• 副作用
• リスクレベル
• 状態：planned | in_progress | done | follow_up

優先順位は、まずユーザーへの影響で決め、その後に副作用、並行処理、権限、最近の変更の多さを考慮します。フォルダー構成だけで優先順位を決めてはいけません。

3. 詳細な調査の前に仮説を立てる

リスクが高いまたは中程度の各サブシステムについて、調査に入る前に具体的な仮説を2～3個書き出します。適切な仮説は、反証可能で、動作の境界に結び付いています。

例：

• 「書き込みAと書き込みBの間で失敗すると、永続化された状態に一貫性がなくなる可能性がある。」
• 「冪等性が保証されていないため、再試行の経路で副作用が重複する。」
• 「ドキュメントでは動作Xが約束されているが、無効な入力では実装がYにフォールスルーする。」

証拠が得られたら、仮説を更新するか破棄します。この手順により、目的のない調査を防げます。

4. サブシステムを一つずつ監査する

サブシステムをエンドツーエンドで読みます。

• エントリーポイントから開始し、正常系の経路を追跡する
• エラー処理、クリーンアップ、キャンセルまたはシャットダウン、再試行の経路を追跡する
• 実装をテスト、ドキュメント、型、公開契約と比較する
• 証拠の補強に役立つ場合は、対象を絞った検索、コマンド、テストを実行する
• 所見の根拠となる場合は、正確なコマンド、検索内容、対象範囲を記録する

references/checklists.mdから関連するチェックリストのセクションだけを選びます。サブシステムに必要なチェックリストが1つか2つだけなら、すべてのチェックリストを読み込まないでください。

サブエージェントを利用できる場合は、ファイルの重複がないよう、範囲を限定したサブシステムをそれぞれ1つずつ割り当て、以下を確認するよう依頼します。

• 検証した仮説
• 正確な引用箇所を含む所見
• 対象範囲の抜け
• 次に推奨する検証手順

5. 証拠、ステータス、確信度を示して指摘事項を分類する

すべての指摘事項で、観察と推論を分けて記載する必要があります。

必須フィールド：

• Severity：Critical | High | Medium | Low
• Status：Confirmed | Likely | Needs follow-up
• Confidence：High | Medium | Low
• Type：Bug | Race condition | Security | Stale docs | Dead code | Design flaw | Reliability
• Location：正確なファイルパスと行番号または関数
• Impacted behavior：リスクにさらされている、ユーザーから見えるワークフロー、不変条件、または契約
• Observed evidence：コードの引用、コマンド出力、テスト結果、ログ、または検索結果
• Inference：その証拠から報告された問題が示唆される理由
• What I checked：問題を否定するために確認した検索、テスト、ドキュメント、コミット、または別の説明
• Recommendation：信頼できる最小限の次のアクション
• Next verification step：ステータスが Needs follow-up の場合に必須

Confirmed を使うのは、バグがコード、失敗するテスト、再現手順、または明確な矛盾によって直接示されている場合に限ります。推論は強いものの、直接再現できていない場合は Likely を使います。疑わしい点はあるものの、証拠が不十分な場合は Needs follow-up を使います。

6. 収束パスを実行する

サブシステムのレビュー後：

• サブシステムをまたぐ指摘事項の重複を除く
• 重大度とユーザーへの影響に基づいて優先順位を付け直す
• 古いドキュメント、非推奨の名前、未使用のヘルパー、一時的なフラグ、TODO または FIXME の集中箇所、リスクの高い API を対象に、最後の残存項目スイープを実施する
• 結論に影響する場合は、残存項目を調べた正確な検索クエリと件数を記録する
• 監査を完了していない箇所がある場合は、完了したふりをせず、カバレッジの不足を明示する

証拠の基準

言葉を増やすより、より強い証拠を優先します。証拠の強さは、次の順です。

1. 失敗するテストまたは対象を絞ったテスト
2. 正確な手順で再現できる経路
3. 正確な引用箇所を伴う、コード上の直接的な矛盾
4. ログ、テレメトリ、またはコマンド出力
5. 件数を伴う範囲を限定した検索結果
6. 静的な推論

静的な推論だけでも有用な場合はありますが、通常は Confirmed ではなく Likely とするべきです。

デッドコードまたは古いドキュメントについて指摘する場合は、必ず何を検索したか、そしてコードやドキュメントが古いと判断した理由を示します。利用箇所を検索せずにデッドコードと主張するのは不十分です。

報告ルール

• 方法論の振り返りではなく、指摘事項から始めます。
• スタイルの整理より、ユーザーに影響する正確性の問題を優先します。
• 同じ根本原因を共有しない限り、関連する指摘事項は分けて記載します。
• 深刻な問題がない場合は、その旨を明確に伝え、残存リスクと未検証の領域も報告します。
• 何を確認し、何があれば問題を裏付ける、または否定できるのかを述べずに、「誤っているように見える」「問題かもしれない」とだけ書かないでください。

次の項目には、references/templates.md のテンプレートを使います。

• スコープ概要
• カバレッジ台帳
• 指摘事項の形式
• チャットを優先する要約
• 成果物モードの監査ディレクトリ

セッション管理

小規模な監査では、単一セッションモードを使います。大規模な監査、またはコンテキストが限られている場合は、軽量な制御プレーンを作成します。

• スコープ概要とカバレッジ台帳を記載する 00-plan.md
• 監査の規模から作成する価値がある場合に限り、サブシステムごとに 1 ファイル
• 指摘事項と修正順をまとめる SUMMARY.md
• 後で作業を続ける場合は HANDOFF.md

適切な引き継ぎには、次の内容を含めます。

• 調査した範囲
• 現時点で正しいと考えていること
• 未検証の項目
• 現在のブロッカー
• 正確な次の手順

アンチパターン

• エントリーポイントや不変条件を特定せずにディレクトリをスキャンする
• コードの問題点をすべて指摘事項として報告する
• 利用箇所を検索せずにデッドコードと判断する
• 壊れた動作や違反している契約を示さずに、バグと判断する
• 複数のサブシステムを 1 つの巨大な報告にまとめる
• 不確実性を隠し、Needs follow-up と明記しない

完了基準

監査は、以下を満たした時点で完了です。

1. 高リスクのサブシステムに台帳の項目と最終ステータスがある
2. 報告されたすべての指摘に、根拠、確信度、具体的な場所が示されている
3. 最終レポートに、修正の優先順位と未検証の範囲が含まれている
4. 横断的な指摘と残存する指摘が統合されている
5. 立証できなかった事項について、レポートが正直に記載している