exhaustive-systems-analysis について
exhaustive-systems-analysisは、潜在的な問題を見つけるための体系的なコードベース監査手法です。特にエージェントが書いたコードを対象とし、サブシステムごとに根拠と重大度を示して報告する手順を定めています。
主な機能
- 01サブシステムの把握と分離
- 02データフローと副作用の追跡
- 03チェックリストによる個別分析
- 04場所を示した重大度別の指摘
- 05監査レポートの統合
活用シーン
- 01本番投入前のエージェント生成コードの監査
- 02状態管理やネットワーク機能の検査
- 03大規模コードベースの問題の優先順位付け
- 04修正順序の記録と共有
インストール
コマンドをコピーしてターミナルで実行します。
$
npx skills add https:/インストール後、Claude Code で/exhaustive-systems-analysisを入力して読み込まれたか確認します。
詳細
網羅的なシステム分析
コードベースに潜む問題を洗い出すための体系的な監査手法です。特に、本番環境で使用する前に検証が必要な、エージェントが作成したコードを対象とします。
基本原則
- サブシステムの分離 — コンテキストの汚染を防ぐため、各サブシステムを個別に分析します
- 証拠に基づく指摘 — 各問題について、具体的なコードの場所を示します
- 重大度に基づく優先順位付け — 重大な問題を先に、表面的な問題を最後に扱います
- すべての問題が修正される前提で進める — 曖昧な言い方はせず、問題点を率直に指摘します
ワークフロー
フェーズ 1：システムの分解
分析の前に、システムをサブシステムに分割します。次の手順で自動的に洗い出します。
- プロジェクト構成を確認する — 主要なモジュール、パッケージ、ディレクトリを特定します
- データフローを追跡する — データの入力、変換、出力の流れを追います
- 副作用を特定する — ファイル I/O、ネットワーク、データベース、IPC、状態の変更を確認します
- 依存関係を把握する — 各サブシステムがどのサブシステムに依存しているかを確認します
サブシステムの表を出力します。
| # | Subsystem | Files | Side Effects | Priority |
|---|-----------|-------|--------------|----------|
| 1 | Lock System | lock.rs | FS: mkdir, rm | High |
| 2 | API Layer | api/*.rs | Network, DB | High |
| 3 | Config Parser | config.rs | FS: read | Medium |
優先順位の目安：
- 高：副作用、状態管理、セキュリティ、並行処理
- 中：ビジネスロジック、データ変換、検証
- 低：純粋なユーティリティ、書式設定、ロギング
フェーズ 2：順次分析
優先順位に従ってサブシステムを分析します。大規模なコードベース（サブシステムが 5 個を超える場合、または各サブシステムが 3000 LOC を超える場合）は、分析のずれを防ぐため、サブシステムごとにコンテキストをクリアすることを推奨します。
各サブシステムには、その種類に応じた適切なチェックリストを適用します。
フェーズ 3：統合
すべてのサブシステムを分析した後、次の作業を行います。
- 分野横断的な指摘の重複を取り除きます
- すべての問題を重大度順に並べます
- 推奨する対応順を含む最終レポートを作成します
分析チェックリスト
サブシステムの特性に応じてチェックリストを選択します。該当する場合は複数を適用します。
状態を持つシステム（ファイル、データベース、キャッシュ、ロック）
| チェック項目 | 質問 |
|---|---|
| 正確性 | コードはドキュメントに記載されたとおりに動作しますか？ |
| アトミック性 | 部分的な書き込みによって状態が破損する可能性はありますか？ |
| 競合状態 | 同時アクセスによって不整合が発生する可能性はありますか？ |
| クリーンアップ | すべての終了経路（成功、エラー、パニック）でリソースが解放されますか？ |
| エラーからの復旧 | 失敗したとき、システムは有効な状態を維持しますか？ |
| 古いドキュメント | コメントの内容は実際の動作と一致していますか？ |
| デッドコード | 保守担当者を混乱させる可能性がある、使用されていないコードパスはありますか？ |
API とネットワーク（HTTP、gRPC、WebSocket、IPC）
| チェック項目 | 質問 |
|---|---|
| 入力検証 | すべての入力は使用前に検証されますか？ |
| エラーレスポンス | エラーによって内部の詳細が漏えいしませんか？ |
| タイムアウト処理 | ネットワーク操作に上限時間は設定されていますか？ |
| 再試行の安全性 | 操作は冪等ですか、それとも適切に制御されていますか？ |
| 認証 | 認証チェックは一貫して適用されていますか？ |
| レート制限 | API が悪用される可能性はありますか？ |
| シリアライズ | 不正なペイロードによってパニックが発生する可能性はありますか？ |
並行処理（スレッド、非同期処理、チャネル、ロック）
| チェック項目 | 質問 |
|---|---|
| デッドロックの可能性 | ロックを取得する順序によってデッドロックが発生する可能性はありますか？ |
| データ競合 | 共有された可変状態は適切に同期されていますか？ |
| 飢餓状態 | タスクが無期限にブロックされる可能性はありますか？ |
| キャンセル | キャンセルやシャットダウンの処理は適切ですか？ |
| リソースリーク | 起動したタスクやスレッドは適切に結合されるか、切り離されていますか？ |
| パニックの伝播 | タスク内のパニックによってシステム全体がクラッシュしますか？ |
UI とプレゼンテーション（ビュー、コンポーネント、テンプレート）
| チェック項目 | 質問 |
|---|---|
| 状態の整合性 | UI に古い状態や不整合な状態が表示される可能性はありますか？ |
| エラー状態 | すべてのエラー条件が適切に表示されますか？ |
| 読み込み状態 | 非同期操作が適切に示されますか？ |
| アクセシビリティ | 操作はキーボードやスクリーンリーダーで利用できますか？ |
| メモリリーク | サブスクリプションやオブザーバーは適切にクリーンアップされますか？ |
| 再レンダリングの効率 | 不要な再レンダリングは回避されていますか？ |
データ処理（パーサー、トランスフォーマー、バリデーター）
| 確認項目 | 質問 |
|---|---|
| エッジケース | 空の値、null、境界値は適切に処理されていますか？ |
| 型変換 | 暗黙的な変換は安全ですか？ |
| オーバーフロー／アンダーフロー | 数値演算の範囲は適切に制限されていますか？ |
| エンコーディング | テキストのエンコーディング（UTF-8）は一貫して処理されていますか？ |
| インジェクション | 信頼できない入力がコンテキストから抜け出す可能性はありますか？ |
| 不変条件 | データの不変条件は強制され、文書化されていますか？ |
設定とセットアップ（設定ファイル、環境、初期化）
| 確認項目 | 質問 |
|---|---|
| デフォルト値 | デフォルト値は安全で、文書化されていますか？ |
| 検証 | 無効な設定は、明確なエラーとともに早期に拒否されますか？ |
| シークレット | シークレットは安全に扱われていますか（ログに記録されず、VCS に含まれないなど）？ |
| ホットリロード | サポートされている場合、リロードはアトミックかつ安全ですか？ |
| 互換性 | 破壊的変更にはバージョンが付与されているか、移行手段が用意されていますか？ |
重大度の分類
すべての指摘事項を分類してください。ユーザーがすべての問題をすぐに修正することを前提としてください。
| 重大度 | 基準 | 例 |
|---|---|---|
| 重大 | データ損失、セキュリティ脆弱性、本番環境でのクラッシュ | 未処理の panic、SQL インジェクション、ファイル破損 |
| 高 | ユーザーが気づく誤動作 | 計算ミス、誤った UI 状態を引き起こす競合、短すぎるタイムアウト |
| 中 | 混乱や将来のバグにつながる技術的負債 | 古いドキュメント、誤解を招く名前、冗長なコードパス |
| 低 | 見た目や軽微な改善 | 未使用のパラメーター、最適ではないアルゴリズム（正しく動作する） |
指摘事項の形式
すべての指摘事項は、次の形式に従う必要があります。
### [SUBSYSTEM] Finding N: Brief Title
**Severity:** Critical | High | Medium | Low
**Type:** Bug | Race condition | Security | Stale docs | Dead code | Design flaw
**Location:** `file.rs:line_range` or `file.rs:function_name`
**Problem:**
What's wrong and why it matters. Be specific.
**Evidence:**
Code snippet or reasoning demonstrating the issue.
**Recommendation:**
Specific fix. Include code if helpful.
出力構成
プロジェクトの構成に合わせて出力してください。一般的なパターンは次のとおりです。
パターン A：監査ディレクトリ（サブシステムが5つ以上の場合に推奨）
.claude/docs/audit/
├── 00-analysis-plan.md # Subsystem table, priorities, methodology
├── 01-subsystem-name.md # Individual analysis
├── 02-another-subsystem.md
└── SUMMARY.md # Consolidated findings, action items
パターン B：単一ドキュメント（小規模なシステム向け）
.claude/docs/audit/system-name-audit.md
# Contains: plan, all findings, summary
パターン C：既存ドキュメント内に記載
プロジェクトに既存の docs/ ディレクトリなどがある場合は、監査成果物をそこに配置してください。
必ず要約を作成してください。以下を含めます。
- 重大度別の指摘事項の合計
- 最も重大な問題のトップ5
- 推奨する修正順序
セッション管理
徹底的に分析するには、次のようにしてください。
- 小規模システム（1000 LOC 未満、サブシステム3つ未満）：1回のセッションで問題ありません
- 中規模システム（1000～5000 LOC、サブシステム3～7つ）：フェーズ間でコンテキストを明確にしてください
- 大規模システム（5000 LOC 超、サブシステム7つ超）：サブシステムごとにセッションを分けてください
コンテキストをクリアする場合は、次のセッションで作業を再開できるよう、分析計画ファイルに進捗を記録してください。
分析前：既知の問題の確認
詳細な分析を始める前に、文書化された問題を確認してください。
- CLAUDE.md / README を確認し、「gotchas」や「known issues」を探す
- TODO/FIXME/HACK コメントを検索する
- 最近のコミットを確認してバグ修正を探す（脆弱な領域を示している可能性があります）
- アクセス可能であれば、イシュートラッカーを確認する
これらを初期仮説として追加し、分析中に検証または反証してください。
避けるべきアンチパターン
| アンチパターン | 問題点 | 代わりに |
|---|---|---|
| コードをざっと読む | 微妙なバグを見落とす | 対象範囲内のすべての行を読む |
| 正しいと思い込む | エージェントのコードにはエッジケースのバグが多い | 各コードパスを検証する |
| 曖昧な指摘 | 「ここはおかしそう」では対応できない | 該当行を示し、その理由を説明する |
| 対象範囲を広げすぎる | 分析が行き詰まる | サブシステムの境界を厳守する |
| テストを無視する | テストから前提が明らかになる | 意図を理解するためにテストを読む |
完了条件
以下を満たした時点で分析は完了です。
- ✅ 優先度の高いサブシステムをすべて分析した
- ✅ すべての指摘事項に重大度、場所、推奨事項が含まれている
- ✅ 優先順位付きの対応項目を含む要約ドキュメントがある
- ✅ 「TBD」または「要調査」の項目が残っていない
- ✅ 関連する指摘事項間の相互参照が追加されている
コメント
Markdown 対応