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

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

Transcript

1. が書いたコードの健全性を 保つためのCLI heal AI Turn codebase health into agent triggers が書いたコードを、AIに直してもらう。そのためのCLIです。 AI
2. heal — Turn codebase health into agent triggers エージェントとコードの劣化 AI エージェントでコードを書くのが、当たり前になりました。機能追加のループは、 これまでにないスピードで回っています。 一方で、AIは目の前のタスクをこなすのは得意でも、コードベース全体への配慮は不 得意です。 似たコードを量産しがちで、重複 が静かに増えていきます 局所的な動作を優先するため、全体設計の整合性 が崩れていきます その帰結として、コードベース全体は次のような道をたどります。 AI 機能追加 → 複雑性が増す → 不具合の温床に ↺ 放置すると、ずっと繰り返されます 2
3. heal — Turn codebase health into agent triggers コードの健全性を測る指標は、昔から存在します 「複雑な関数」「変更が集中するファイル」「重複したコード」「凝集度の低いクラ ス」… こうしたコードの傷んだ箇所を測る指標は、何十年も前から研究されてきました。経 験のあるエンジニアがリファクタの判断に使ってきた指標です。 人の開発で機能してきた指標は、AIが書いたコードベースにもそのまま使えるはずで す。 3
4. heal — Turn codebase health into agent triggers そこで heal を作りました コードの劣化を、シグナルに。 シグナルを、AIのタスクに。 HEAL = Hook-driven Evaluation & Autonomous Loop 4
5. heal — Turn codebase health into agent triggers コミットを起点に、改善が回り出す は git リポジトリで動く CLI です。 heal init で1度セットアップすれば、コミ ットのたびに観測が走り、Critical / High の項目が git commit の出力に表示されま す。 heal status を実行すると、優先度つきの TODO リストが出ます。 その TODO リストを読んで実際に直すのは、heal プラグインの Claude Skill で す。 /heal:refactor が改善案を出し、承認された提案を1つずつコミットしていきま す。 ＋ 増やすループ − 減らすループ コード量 ↑ 複雑性 ↓ heal 要望 ↓ heal シグナル ↓ 実装 Skill で修正 ↺ コミットのたびに、両方のループが回り続けます AI 5
6. heal — Turn codebase health into agent triggers Hotspot: Hotspot もっとも重要な健全性指標 とは、複雑 で、かつ 頻繁に変更されている ファイルのことです。 Hotspot = 複雑度 × 変更頻度 複雑だけど、誰も触らないファイル → 気にはなりますが、急ぎません シンプルで、よく変更されるファイル → 問題ありません 複雑で、よく触られているファイル → ここが次のバグの発生源です 開発者が変更のたびに「ここ、どうなってるんだっけ」と迷う場所ほど、ミスが入り 込みやすくなります。Hotspot は、その「迷いやすい場所」をデータで特定する指標 です。 直すなら、まずここから。コードベース全体の健全化への近道です。 6
7. heal — Turn codebase health into agent triggers heal の内部アーキテクチャ が動くのは、コミットした時と、自分で呼んだ時の2通りだけです。常駐するデー モンやバックグラウンドプロセスはありません。 heal コミット時 自動 呼んだ時 手動 git commit heal status → → Hook → → Observe Observe → → Classify Classify Cache → → Critical / High Skill を表示 が提案・修正 で AST を、git2 でコミット履歴を解析する Classify — コードベース自身の分布（calibration）から Severity と Hotspot を判定する Cache — TODO リストを .heal/findings/latest.json に保存する。このファイルも git で管理するの で、同じコミットならチーム全員が同じ TODO リストを見る Observe — tree-sitter 7
8. heal — Turn codebase health into agent triggers CLI: 指標の分析結果を、優先度つきで出力 $ heal status HEAD 405a282 (4990 findings) Drain queue: T0 19 findings (9 files) · T1 95 findings (23 files) ═══ Code ═══ Critical [T0 Must drain] (19) crates/cli/src/core/config.rs coupled (sym) crates/cli/src/observers.rs CCN=42 crates/cli/src/cli.rs CCN=27 crates/cli/src/feature.rs LCOM=6 ... Next: `claude /heal:refactor` drains this family's T0 queue 分析結果は、直す順番の段（Tier）→ Severity → Hotspot スコア の順に並びます。 先頭の T0 は「Critical かつ Hotspot」、つまり真っ先に直すべき場所です。 Severity のしきい値は、そのコードベース自身の分布で calibration されます。プロジ ェクトの規模に依らず、相対的に妥当な優先度が付きます。 8
9. heal — Turn codebase health into agent triggers Skill: 改善案を出し、承認したものだけを直す $ claude /heal:refactor Reading 複雑度が2つのファイルに集中し、どちらも Critical かつ Hotspot です。 Proposals (T0: 5 shown of 7) [1] src/payments/engine.ts を pricing と validation に分ける risk: medium Why: 価格計算を変えるたびに、40行の入力チェックを読み直している Pattern: Extract Class Evidence: LCOM 2 clusters · CCN 28 · Hotspot Accept instead - ccn src/parser/table.rs:dispatch — exhaustive_enum_dispatch 診断 → 提案 → 承認 → 1提案1コミットで適用 リスト全体を見渡して、どこを、どう分ければ変えやすくなるか を提案しま す。2つの指標が同じ切れ目を指していれば、ファイルの分割のような構造的な変更に も踏み込みます。適用するのは 承認した提案だけ で、1提案ごとにテストを通してか らコミットします。 TODO 9
10. heal — Turn codebase health into agent triggers Test / Docs: テストとドキュメントにも同じループを で追加できる指標のまとまり（ファミリ）です。Code と同じ く、TODO リストに並んだ項目を専用の Skill が直します。 .heal/config.toml Test [features.test] テストから見えていない本番コードはどこか？ 入力: カバレッジ計測ツールが出す lcov.info 指標: coverage_pct （行カバレッジ）、 skip_ratio （skip されたテスト） 、 change_coupling.drift （ソースに取り残された テスト） 🔥 Test Hotspot: 変更頻度 × 未カバー率 Skill: /heal:tests が足りないテストを書き、ず れたテストを直す /heal:setup tests / /heal:setup docs Docs [features.docs] ドキュメントは実装からずれていないか？ 入力: ドキュメントとソースの対応表 .heal/doc_pairs.json 指標: doc_drift （存在しない識別子の参照）、 doc_freshness （ソースに追いついていない） 、 リンク切れ、孤立ページ、TODO の密度 🔥 Doc Hotspot: ソースの変更頻度 × ドキュメン トの遅れ Skill: /heal:docs がリンク切れや参照切れを直 し、ずれた説明を書き直す で、有効化から準備までを済ませられます。 10
11. heal — Turn codebase health into agent triggers Semantic: 指標では測れない「意味」を問う 指標で分かるのは「どこが変えにくいか」までで、「名前と中身が合っているか」は分 かりません。 [features.semantic] を有効にすると、こうした問いを TypeSafe の分 類モデル Jev に投げ、確率つきの答えを TODO リストに加えます。 問い 項目 名前が中身と合っているか name_mismatch 1つのファイルに概念が混ざっていな concept_mix いか テストが振る舞いを確かめているか test_value ドキュメントの説明がまだ正しいか doc_drift.semantic 答えの使い道 並び順: 同じ Tier・Severity の中で、利用者 への影響・変えにくさ・バグ修正の多さを 使って並べ替える 構造的な変更の根拠: 指標と答えが同じ箇所 を指せば、ファイルの分割などを提案する 自己検証: Skill が自分の提案とコミットを Jev に確かめさせる コードを外部に送るのは heal semantic ask を実行した時だけです。答えは .heal/semantic/verdicts/ に保存し てコミットするので、API キーを持たないメンバーも同じ結果を見られます。 11
12. heal — Turn codebase health into agent triggers ぜひ使ってみてください brew install kechol/tap/heal-cli Claude Code で Skill を入れる /plugin marketplace add kechol/heal /plugin install heal@heal https://github.com/kechol/heal https://kechol.github.io/heal/ja/ 12
13. heal — Turn codebase health into agent triggers Appendix 1: Code 指標 ファミリの指標 対象 意味 LOC 言語ごとのコード行数 コードベースの規模 CCN 関数の分岐数 (McCabe) テストの難しさ Cognitive 関数の認知的複雑度 (Sonar) コードの読みにくさ Churn ファイルの変更頻度 変更の集中度 Change Coupling 一緒に変更されるファイル ファイル間の暗黙の依存度 Duplication コピペされたブロック 重複コードの多さ LCOM クラスの凝集度の欠如 クラスの責務の分散度 Hotspot 複雑度 × Churn バグが生まれやすい場所 13
14. heal — Turn codebase health into agent triggers Appendix 2: 指標 対応言語と構成 対応言語 LOC すべての言語に対応 Churn / Change Coupling / Hotspot すべての言語に対応 CCN / Cognitive / Duplication TypeScript / JavaScript / Python / Go / Scala / Rust LCOM TypeScript / JavaScript / Python / Rust (Go / Scala Test lcov.info ファミリ Docs ファミリ は未対応) を出力できるすべての言語 Markdown / RST のドキュメントと、上記6言語のソース 対応言語: 6言語の解析器はすべてリリースバイナリに同梱されていて、追加のインス トールは要りません。 モノレポ対応: [[project.workspaces]] で workspace を宣言すれば、各 workspace を独立した分布でキャリブレーションできます。5kloc の CLI と 50kloc の API を、 14 別々のしきい値で評価できます。