heal: AIが書いたコードの健全性を保つためのCLI

https://github.com/kechol/heal
https://kechol.github.io/heal/ja/quick-start/

Transcript

1. AI が書いたコードの健全性を 保つためのCLI heal Turn codebase health into agent triggers AI が書いたコードを、AI に直してもらう。そのためのCLI です。
2. AI エージェントとコードの劣化 AI エージェントでコードを書くのが、当たり前になりました。機能追加のループは、 これまでにないスピードで回っています。 一方で、AI は目の前のタスクをこなすのは得意でも、コードベース全体への配慮は不 得意です。 似たコードを量産しがちで、重複 が静かに増えていきます 局所的な動作を優先するため、全体設計の整合性 が崩れていきます その帰結として、コードベース全体は次のような道をたどります。 機能追加 → 複雑性が増す → 不具合の温床に ↺ 放置すると、ずっと繰り返されます heal — Turn codebase health into agent triggers 2
3. コードの健全性を測る指標は、昔から存在します 「複雑な関数」 「変更が集中するファイル」 「重複したコード」 「凝集度の低いクラ ス」… こうしたコードの傷んだ箇所を測る指標は、何十年も前から研究されてきました。経 験のあるエンジニアがリファクタの判断に使ってきた指標です。 人の開発で機能してきた指標は、AI が書いたコードベースにもそのまま使えるはずで す。 heal — Turn codebase health into agent triggers 3
4. そこで heal を作りました コードの劣化を、シグナルに。 シグナルを、AI のタスクに。 HEAL = Hook-driven Evaluation & Autonomous Loop heal — Turn codebase health into agent triggers 4
5. コミットを起点に、改善が回り出す heal は git リポジトリで動く CLI です。heal init で1 度セットアップすれば、コミ ットのたびに観測が走り、優先度つきの分析結果がキャッシュされます。 その分析結果を読んで実際に修正するのは、同梱の Claude Skill です。/heal-code- review がアーキテクチャを読み解き、/heal-code-patch が1 コミット1 修正で消化し ていきます。 ＋ 増やすループ コード量 ↑ 要望 ↓ AI 実装 − 減らすループ 複雑性 ↓ heal シグナル ↓ Skill で修正 ↺ コミットのたびに、両方のループが回り続けます heal — Turn codebase health into agent triggers 5
6. Hotspot: もっとも重要な健全性指標 Hotspot とは、複雑 で、かつ 頻繁に変更されている ファイルのことです。 Hotspot = 複雑度 × 変更頻度 複雑だけど、誰も触らないファイル → 気にはなりますが、急ぎません シンプルで、よく変更されるファイル → 問題ありません 複雑で、よく触られているファイル → ここが次のバグの発生源です 開発者が変更のたびに「ここ、どうなってるんだっけ」と迷う場所ほど、ミスが入り 込みやすくなります。Hotspot は、その「迷いやすい場所」をデータで特定する指標 です。 直すなら、まずここから。コードベース全体の健全化への近道です。 heal — Turn codebase health into agent triggers 6
7. heal の内部アーキテクチャ ①〜④ はコミットごとに自動で動き、⑤ はユーザーが呼んだ時に動きます。 ① Hook — git の post-commit フックが heal を起動する ↓ ② Observe — tree-sitter で AST を解析、git2 で履歴を解析 ↓ ③ Classify — Severity と Hotspot を判定する ↓ ④ Cache — 分析結果をキャッシュに保存する — ここまでが自動 / ここから手動 — ⑤ Use — CLI が改善箇所を表示、Skill がレビューや修正を実行 heal — Turn codebase health into agent triggers 7
8. CLI: 指標の分析結果を、優先度つきで出力 $ heal status HEAD bd75d4a (2179 findings) Drain queue: T0 9 findings · T1 34 findings Critical [T0 Must drain] (9) crates/cli/src/commands/status.rs CCN=32 crates/cli/src/core/config.rs coupled LCOM=4 crates/cli/src/commands/hook.rs coupled coupled ... Next: `claude /heal-code-patch` drains the T0 queue 各指標 (CCN 、Coupling 、LCOM 等) の分析結果は、Severity と Hotspot で並べ替えら れて出力されます。コミットのたびに、自動で更新されていきます。 優先度の閾値は、そのコードベース自身の分布で calibration されます。プロジェクト の規模に依らず、相対的に妥当な優先度が付きます。 heal — Turn codebase health into agent triggers 8
9. Skill: アーキテクチャの改善案まで提示 $ claude /heal-code-review status.rs (CCN=32, Hotspot) → render() に分岐が集中しています。Severity ごとに SectionRenderer を分けると、複雑度が下がります。 config.rs (LCOM=4, coupled) → load / validate / merge が同じ struct に同居しています。 責務を分離すると、依存関係も解消できます。 指標から問題箇所を読み解き、 「どこを」 「どう分割・整理すれば」健全になるか を、 具体的なリファクタ案として提示してくれます。 そのうち 機械的に修正できるもの （関数の抽出、責務分離、重複の統合など）は /heal-code-patch が引き取り、1 コミット1 修正で実際にコードを書き換えていきま す。アーキテクチャ判断が必要なもの は人の手元に残ります。 heal — Turn codebase health into agent triggers 9
10. ぜひ使ってみてください brew install kechol/tap/heal-cli https://github.com/kechol/heal https://kechol.github.io/heal/ja/ heal — Turn codebase health into agent triggers 10
11. Appendix 1: 計測している指標 指標 対象 意味 LOC 言語ごとのコード行数 コードベースの規模 CCN 関数の分岐数 (McCabe) テストの難しさ Cognitive 関数の認知的複雑度 (Sonar) コードの読みにくさ Churn ファイルの変更頻度 変更の集中度 Change Coupling 一緒に変更されるファイル ファイル間の暗黙の依存度 Duplication コピペされたブロック 重複コードの多さ LCOM クラスの凝集度の欠如 クラスの責務の分散度 Hotspot 複雑度 × Churn バグが生まれやすい場所 heal — Turn codebase health into agent triggers 11
12. Appendix 2: 対応言語と構成 指標 対応言語 LOC すべての言語に対応 Churn / Change Coupling / Hotspot すべての言語に対応 CCN / Cognitive / Duplication TypeScript / JavaScript / Python / Go / Scala / Rust LCOM TypeScript / JavaScript / Python / Rust (Go / Scala は未対応) 対応言語: TypeScript / JavaScript / Python / Go / Scala / Rust の6 言語をデフォルトで サポートしています。リリースバイナリにすべてバンドル済みです。 モノレポ対応: [[project.workspaces]] で workspace を宣言すれば、各 workspace を独立した分布でキャリブレーションできます。5kloc の CLI と 50kloc の API を、 別々のしきい値で評価できます。 heal — Turn codebase health into agent triggers 12