クイックスタート

heal は、コードベースの劣化をエージェントの仕事に変えます。 コミットのたびに複雑度、Hotspot、重複を測り直し、その結果の TODO リストを Claude に渡します。Claude は修正を提案し、承認されたものを 1 件 1 コミットで適用します。人が様子を見に行く必要はなくなります。このページでは、その流れを 5 分ほどで最後まで組み立てます。

必要環境

始める前に、次のものを用意してください。

• macOS または Linux
• 試す git リポジトリ
• （任意）heal プラグインの /heal:setup、/heal:refactor、/heal:docs、/heal:tests スキルを使うための Claude Code

1. インストール

どの方法を選んでも、同じ heal バイナリが入ります。

Homebrew

brew install kechol/tap/heal-cli

Cargo

cargo install heal-cli

Shell

curl --proto '=https' --tlsv1.2 -LsSf \
  https://github.com/kechol/heal/releases/latest/download/heal-cli-installer.sh | sh

heal --version

方法ごとの詳細は インストール を参照してください。

2. リポジトリを準備する

.heal/ の作成と git フックの設置を、1 つのコマンドで済ませます。

heal init

.heal/（設定と calibration）を作り、コミットのたびに新しい Critical / High を知らせる post-commit フックを設置します。何度実行しても安全で、既存の設定と calibration は --force を付けない限りそのまま残ります。何が済んでいて何が残っているかは、heal doctor で確認できます。

3. プラグインを入れて /heal:setup を実行する

スキルは Claude Code プラグインとして配布しています。Claude Code で次を実行します。

/plugin marketplace add kechol/heal
/plugin install heal@heal

続けて、セットアップ用のスキルを実行します。必須ではありませんが、初回は実行をおすすめします。

/heal:setup

このスキルは heal doctor の結果を起点にするので、足りない作業だけを行います。まず Strict / Default / Lenient のどれにするかを尋ねて、.heal/config.toml を更新します。次に、オプトインの Test / Docs / Semantic を有効にするかを尋ねます。有効にしたものには、必要な準備も整えます。Docs ならドキュメントのペア、Test ならカバレッジのリポータ、Semantic なら概念の一覧です。calibration のやり直しは、同意したときだけ行います。何度実行しても構いません。準備がすべて済んだプロジェクトでは、その旨を報告するだけです。

4. TODO リストを見る

TODO リストは、Tier（T0、T1 といった解消の優先段階）と Severity ごとにまとまり、同じファミリの中では Hotspot スコアの高い順に並びます。

heal status

ファイルごとの TODO リストを、Tier、Severity、スコアの順に表示します。絞り込みや JSON 出力については CLI › heal status を参照してください。

5. Claude と Finding を片付ける

どのスキルも、heal が見つけたものを読んで変更を提案し、承認されたものだけを適用します。適用は 1 提案 1 コミットで、コミットの前には毎回テストを実行します。push や pull request の作成は、どのスキルもしません。

/heal:refactor          # コードの Finding を全体として読み、構造的な変更も含めてリファクタを提案する
/heal:refactor plan     # 提案だけを行い、適用はあとで
/heal:docs              # [features.docs]: Diátaxis の観点でドキュメントを直す・書き直す・移す・分ける
/heal:docs scaffold     # [features.docs]: ドキュメントがまだないプロジェクトで、コードベースから文書ツリーを作る
/heal:tests             # [features.test]: テストピラミッドの観点でテストを書く・揃える・再び有効にする・消す

スキルの詳細は Code › スキル、Docs › スキル、Test › スキル を参照してください。

続けて読む

• コンセプト — heal がこの形をしている理由
• 機能 — Code（常時オン）、Test（[features.test]）、Docs（[features.docs]）
• CLI — すべてのサブコマンド
• Code › メトリクス — 7 つの Code メトリクス
• Code › 設定 — .heal/config.toml のリファレンス

常時オンの Code ファミリの先に進むときは、次のページへ。

• Test › 設定 — lcov.info の取り込みと、それで有効になるカバレッジ・skip 比率のレポート
• Docs › 設定 — ペアになったドキュメントのずれとリンク切れのチェック

書いてあるとおりに動かない手順があれば、issue で知らせてください。