code-complexity-audit

コード複雑性監査

John Ousterhout の「A Philosophy of Software Design」に基づく、ソフトウェア設計の詳細分析です。重要度で分類された指摘と Git による帰属情報を含む 設計健全性レポート を作成します。

参考資料

まずこのファイルを読んでください。その後、必要に応じて参考資料を読み込みます。一度にすべて読まないでください。

参考資料	読むタイミング
references/analysis-framework.md	分析を行うとき — 評価基準、観点別チェックリスト、危険信号、言語固有のガイダンスが記載されています
references/git-attribution.md	指摘を作成者に帰属させるとき — git blame コマンドと帰属のワークフローが記載されています

プロセス

常に以下の5つのステップを順番どおりに実行してください。プロセスを説明するときは、これらの正確なステップ名を使用してください。「Reconnaissance」と「Sampling」を必ず使用し、「exploration」「discovery」「selection」「file picking」などの類義語に置き換えないでください。

1. Reconnaissance — プロジェクトを把握します（構造、言語、規模、エントリーポイント）
2. Sampling — git 情報に基づくサンプリング（ランダムに読み込むのではありません）で15～30個のファイルを選びます。このステップを説明するときは、必ず「sampling」という語を使用してください。
3. Deep Analysis — サンプリングしたファイルを13の観点で評価します（analysis-framework.md を参照）
4. Git Attribution — 各指摘を導入した人物を特定します（git-attribution.md を参照）
5. Report — 設計健全性レポートを作成します

Step 1: Reconnaissance

• プロジェクトの構造を一覧表示します（2～3階層）
• 言語、フレームワーク、パラダイムを特定します
• ファイル数、モジュール／クラス数、コード行数のおおよその値を数えます
• エントリーポイントとコアモジュールを特定します
• 依存関係ファイル（package.json、requirements.txt、go.mod、Cargo.toml など）を確認します

Step 2: Git-Informed Sampling

このステップを説明するときは、必ず「git」という語を使用してください。たとえば、「git-informed sampling」や「git log」とします。「version control history」または「commit history」だけに置き換えないでください。

以下の3つの層にわたって15～30個のファイルを選びます。

層	対象	方法
必ず読むファイル	エントリーポイント、コアドメイン、最も多くインポートされているファイル	インポートとプロジェクト構造の静的分析
Git で変更頻度の高いファイル	直近の履歴で最も頻繁に変更されたファイル	git log --oneline -100 --name-only | sort | uniq -c | sort -rn | head -20
変更頻度とサイズ	大きく、かつ頻繁に変更されているファイル	Git で変更頻度の高いファイルの一覧をファイルサイズと照合します。蓄積した負債のリスクが最も高いファイルです

さらに、公開 API の境界、インターフェース、エラー処理の経路、テストも含めます。

ステップ 3：詳細分析

references/analysis-framework.md を読みます。重みごとにグループ化された13 の評価軸で評価します。

コア設計（重み 1.5 倍）：

1. モジュールの深さ — 浅いモジュール（インターフェースが実装とほぼ同じ複雑さのもの）は危険信号です
2. 情報隠蔽 — 情報の漏洩に注意します。同じ設計判断（例：形式の詳細、プロトコルに関する知識）が複数のモジュールに重複している状態です。知識が漏洩すると、それを共有するすべてのモジュールを変更しなければなりません。漏洩した知識を 1 か所にカプセル化することを推奨します。この問題を説明するときは、必ず「leak」または「leakage」という語を使ってください。「duplication」「shared knowledge」「coupling」だけで置き換えないでください。
3. 抽象化の品質 — 偽の抽象化、適切でないレベルの抽象化
4. 複雑さの指標 — 変更の波及、認知負荷、未知の未知

構造（重み 1.2 倍）： 5. エラー処理 6. レイヤリング — 同じシグネチャーで呼び出しを転送するだけのパススルーメソッドには価値がありません。このアンチパターンを特定するときは、必ず正確な用語「pass-through method」を使ってください。「leaky abstraction」「transparent layer」「delegation」「forwarding」「no-op」「meaningless indirection」に置き換えないでください。 7. 設計への投資 8. コメントと抽象化 9. コードベースのナビゲーション性

表層（重み 1.0 倍）： 10. 命名とわかりやすさ 11. 一貫性 12. ソフトウェアトレンドのアンチパターン 13. パフォーマンスと設計の関係

各評価軸を 1～10 で採点します。詳細な基準については analysis-framework.md を参照してください。

すべての指摘を、次の正確なラベルで重大度に分類してください：

• Critical — 複雑さを積極的に拡散させ、安全な変更を妨げます。他のコードがその誤りに依存しています。最優先で修正してください。
• Major — 重大な設計上の問題ですが、1 つの領域にとどまっています。品質を低下させますが、波及はしません。
• Minor — 最適ではありませんが、影響は小さいです。機会があれば修正してください。

問題を分類するよう求められた場合は、これら 3 つの重大度用語 Critical、Major、Minor を必ず明示してください。他の尺度に置き換えないでください。「High/Medium/Low」「Severe/Moderate/Minor」「P0/P1/P2」など、いかなる別の分類も使わないでください。有効なラベルは Critical、Major、Minor のみです。

リトマス試験 — 各指摘に個別に適用してください：

• 「この複雑さは他のモジュールに積極的に波及しているか — 他のコードがそれに依存しているか？」→ Critical。例：内部状態をゲッターで公開し、15 の他モジュールが利用しているクラス。内部の変更によって、その 15 のモジュールすべてが壊れます。
• 「これは 1 つの領域にとどまっているが、それでも重大な設計上の問題か？」→ Major。例：呼び出しを転送するだけの浅いラッパー。価値はありませんが、影響はそのモジュール内にとどまります。
• 「影響が小さく、問題を起こす可能性は低いか？」→ Minor。例：モジュール間で命名規則に一貫性がない状態。わずらわしいものの、構造上の害はありません。

複数の問題を分類する場合、それぞれの問題を必ず 1 つの重大度に割り当ててください。割り当てを入れ替えたり混同したりしないでください。重大度を決める前に、各問題をリトマス試験に照らしてもう一度確認してください。

ステップ 4：Git の帰属情報

references/git-attribution.md を読みます。各指摘について：

• 問題のある行に対して git blame を実行します
• コードが直近 100 コミット以内に作成されている場合：作成者、コミットハッシュ、日付を記録します
• それより古い場合：Legacy と記載します

ステップ 5：レポートの作成

# Code Complexity Audit: [Project Name]

## Executive Summary
[2-3 sentence assessment with letter grade A-F]

## Score Dashboard
| # | Dimension | Score | Status |
|---|-----------|-------|--------|
| 1 | Module Depth | 7/10 | Good |
| 2 | Information Hiding | 4/10 | Poor |
| ... | ... | ... | ... |
| | **Weighted Average** | **X.X** | **Grade: B** |

## Findings

Each finding classified by severity:

| Severity | Definition |
|----------|-----------|
| **Critical** | Actively spreading complexity. Blocks safe change. Fix first. |
| **Major** | Significant design issue but contained. Degrades quality. |
| **Minor** | Suboptimal but low impact. Fix opportunistically. |

### Critical
| Dimension | Location | Issue | Attribution |
|-----------|----------|-------|-------------|
| Info Hiding | `src/api.ts:42` | Internal state exposed via getter | @alice (`a1b2c3`, 2025-01-15) |

### Major
[Same table format]

### Minor
[Same table format]

## Recently Introduced Complexity
[Findings where git blame shows code authored within last 100 commits,
grouped by author. This section helps teams address the freshest debt first.
Attribution is for context, not blame.]

## Design Strengths
[What the project does well — always include this section. Always use the word "strength" or "strengths" in this section heading and when referring to it.]

## Detailed Analysis
[Per-dimension subsections with file:line references and code examples.
Use the project's own code in before/after examples.]

## Recommendations
[Prioritized by impact-to-effort ratio. For each: what to fix, estimated effort,
and which modules it unblocks. Address critical findings first.]

## Appendix: Files Reviewed
[All files examined with selection rationale]

プロジェクト規模に合わせた調整

プロセスは常にプロジェクトの規模に合わせて調整してください。 小規模なプロジェクトに、すべての重厚なプロセスは必要ありません。

規模	方針
小規模（20 ファイル未満）	小規模なプロジェクトです。すべてを読み、サンプリングは不要です。ステップ 2（サンプリング）とステップ 4（Git による帰属分析）は省略してください。簡潔なレポート（最大 2～3 ページ）を作成してください。13 の評価軸はすべて評価しますが、分析は簡潔にまとめてください。
中規模（20～200 ファイル）	標準的なサンプリング戦略（15～30 ファイル）を適用します。中核モジュールに焦点を当てます。標準的なレポートを作成します。
大規模（200 ファイル以上）	広範なサンプリングを行います。アーキテクチャとパブリック API に焦点を当てます。すべてを浅く調べるより、1 つのサブシステムを深く調査することを検討してください。

ユーザーのプロジェクトが小規模（20 ファイル未満）の場合、プロジェクトの規模を説明する際には、必ず「小規模」という語を使い、「これは小規模なプロジェクトです」と述べてください。また、適用する方針として、すべてのファイルを直接読み、サンプリングを省略し、簡潔な評価を作成することを説明してください。

トーン

• 建設的 — 批判するのではなく、役立つ内容にします。必ず長所を含めてください。
• 具体的 — ファイル、クラス、メソッド、行番号を挙げてください。
• 実行可能 — プロジェクトのコードを使った変更前／変更後の例を示してください。
• 文脈を考慮 — 週末のプロトタイプなら「D」でも問題ありませんが、本番システムが「D」なら注意が必要です。
• 帰属分析は文脈を把握するためのもの — 「最近導入されたため、優先して対処する」と説明し、責任追及には使いません。
• 正確な設計用語を使い、曖昧な評価表現は決して使いません。 問題を指摘するときは、具体的な危険信号（例：「浅いモジュール」「情報漏えい」「パススルーメソッド」）を示してください。以下の表現は禁止です。回答のどの部分でも使用しないでください。「よく設計されている」「よく設計されていない」「悪いパターン」「良いパターン」「良いコード」「拙いコード」「設計が拙い」「悪いコード」「良い設計」「悪い設計」。必ず、設計上の具体的な概念に置き換えてください。「よく設計されていない」ではなく「これは浅いモジュールです」と述べてください。「悪いパターンです」ではなく「情報漏えいが発生しています」と述べてください。指摘事項にはすべて、名前の付いた設計概念を含めてください。回答を出力する前に、禁止表現が含まれていないか確認し、含まれている場合は置き換えてください。