最近は Claude Code や Codex などのAIエージェントを利用して開発する機会が増えてきました。AIによって実装速度は大きく向上しましたが、その一方で別の課題も感じています。
それは、コードが増える速度に対して構造レビューが追いつかない、ということです。
そこで、コードベース全体の構造的な偏りを可視化するツールとして Structure Heatmap を作成しました。
Structure Heatmapとは
Structure Heatmap は、コードベース内のファイルやディレクトリのサイズを集計し、構造上のホットスポットを発見するためのツールです。例えば次のような情報を確認できます。
- ディレクトリごとのコード量
- ファイルごとのコード量
- 同一ディレクトリ内で突出して大きいファイル
- コードベース全体のサイズ分布
このツールは静的解析ツールではありません。コード品質を評価したり、設計の正しさを判定したりするものではなく「どこをレビューすべきか」を発見するためのツールです。
既存ツールはたくさんある
実は、似たような問題を解決するツールは昔から存在します。
例えば PHP であれば、
- PHPMD
- PDepend
があります。JavaScript / TypeScript でも、
- ESLint
- SonarQube
- Code Climate
などが利用できます。これらのツールは非常に優秀です。巨大なクラスや関数、複雑度の高いコード、設計上の問題を検出してくれます。しかし、私が欲しかったものは少し違いました。
私が見たかったのは「コードベースの地形」
例えば次のような構造があったとします。
src/
├── domain 1,200 lines
├── application 1,500 lines
├── infrastructure 2,000 lines
└── ui 18,000 lines
あるいは、
src/pages
├── UserList.tsx 120 lines
├── UserCreate.tsx 140 lines
├── UserEdit.tsx 842 lines
├── UserDelete.tsx 110 lines
こういう状況を見たとき、
- UI層に責務が集中していないか
- 特定の画面だけ肥大化していないか
- Utilityディレクトリが便利屋になっていないか
といったことが気になります。もちろん、大きいから悪いわけではありません。
しかし、「なぜここだけ大きいのか？」という問いは設計レビューの良い出発点になります。
Structure Heatmap は、そのためのツールです。
AIコーディングとの相性
このツールを作ろうと思った最大の理由はAIコーディングです。
最近は AIにコードレビューやリファクタリングの相談をする機会が増えています。
しかし、巨大なコードベース全体を毎回読み込ませるのは現実的ではありません。
一方で、Structure Heatmap の出力は非常にコンパクトです。
例えば、
src/pages
files: 12
lines: 8420
src/pages/UserEdit.tsx
lines: 842
directory median: 176
ratio: 4.8x
という情報だけでも、AIは様々な仮説を立てられます。実際に試してみると、
- UI層への責務集中
- 業務ロジックの混在
- コンポーネント分割候補
- UseCaseへの移譲候補
といった観点から分析を始めてくれます。
Structure Heatmap を実行し、その結果をAIに渡すだけで、
「このファイルだけ極端に大きいため、UI・状態管理・業務ロジックが混在している可能性があります」
といった指摘が返ってきます。
私が面白いと思ったのは、AIがコードを読む前の段階でも、構造情報だけでかなり有益なレビューができることです。
Structure Heatmap は静的解析ツールというより、AIがコードベースの全体像を素早く把握するための要約情報として機能するのではないかと考えています。
言い換えると、数万〜数十万行のコードベースを、数KBの構造情報に圧縮するためのツールです。
なぜ依存解析を入れなかったのか
制作中にも考えたのですが、依存解析機能は意図的に実装していません。
理由は単純です。依存関係やアーキテクチャルールを検査する優れたツールは既に存在します。
Structure Heatmap がやりたいのは、設計を判定することではなく、どこを見るべきかを示すことです。
そのため、行数とディレクトリ構造というシンプルな情報に絞りました。
まとめ
既存の静的解析ツールは、
- コード品質
- 複雑度
- 設計ルール違反
を検出してくれます。一方で Structure Heatmap が見ているのは、コードベース全体の地形です。AIによって実装コストが下がった今、構造レビューの重要性は以前より高くなっていると感じています。
もし同じような課題を感じている方がいれば、試してみてください。