Code · スキル

heal のスキルは Claude Code プラグインとして配布しているので、heal が集めた Finding をそのまま Claude のセッションで扱えます。Claude Code で、最初に 1 度だけ入れてください。

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

プラグインはプロジェクトではなく Claude Code の設定の側に入るので、git 管理下のファイルは増えません。プラグインは、一緒に公開された heal のリリースに固定されています。heal CLI を更新したら、プラグインも更新してください（/plugin marketplace update heal を実行してから /plugin update heal@heal）。heal を使っているプロジェクトでセッションを始めると、CLI とプラグインのリリースが違うときにだけ、プラグインがそのことを 1 行で知らせます。

プラグインには 4 つのスキルがあります。

スキル	用途
/heal:setup	heal のセットアップ、またはセットアップの再確認。このページで説明する。
/heal:refactor	コードの Finding を読み、リファクタを提案し、承認されたものを適用する。
/heal:docs	同じことをドキュメントに対して行う。Docs › スキル を参照。
/heal:tests	同じことをテストに対して行う。Test › スキル を参照。

どのスキルも、push や pull request の作成はしません。提案が承認されるまで、ファイルを変えることもありません。

/heal:setup — セットアップと再確認

いつ実行しても安全です。まず heal doctor で何が済んでいるかを確かめ、足りないことや古くなったことだけを行います。

• 初期化: .heal/ がなければ、プロジェクトを初期化します（heal init）。
• 厳しさの調整: Strict / Default / Lenient のどれにするかを尋ね、コードベースを調べた結果（除外するパス、モノレポの workspace、シグナルの出ないメトリクス）から .heal/config.toml を書きます。初回と、調整を頼んだときに提案します。
• calibration のやり直し: コードベースが変わってきたら行います。目安は、calibration の後に 200 を超えるコミットが入った、ファイル数が 20% を超えて増減した、修正を 10 件以上したのに Critical / High が 1 件も残っていない、のどれかです。実行する前に必ず尋ね、heal が自分でやり直すことはありません。
• オプションのファミリの有効化: 有効にしたファミリに必要なものを整えます。Docs ならドキュメントのペア、Test ならカバレッジのリポータ、Semantic (Jev) なら API キーと概念の語彙です。
• 古いスキルのフォルダの削除: heal 0.6 以前がプロジェクトにコピーしたフォルダ（.claude/skills/heal-*、.agents/skills/heal-*）を消します。

セットアップが済んだプロジェクトでは、すべてそろっていることを報告するだけで、何も尋ねません。特定の手順から始めたいときは、/heal:setup docs、/heal:setup tests、/heal:setup semantic、/heal:setup config のように指定します。

呼び出しに使える言い方の例: 「heal をセットアップして」「heal の設定を確認して」「heal を厳しくして」「heal でカバレッジを見られるようにして」「/heal:setup」。

/heal:refactor — リファクタの提案と適用

heal がコードに見つけたものを理解し、手を打つためのスキルです。次の 5 つの手順で進みます。

1. 診断: heal status --all --feature code --json を読み、フラグの立ったファイルを開いて、全体をひとつのまとまりとして読みます。どのファイルに複数の Finding が集まっているか、どのファイルのペアがモジュールの境界をまたいで一緒に変わっているか、どのファイルがハブになっているか、コードベースがどう層に分かれているかを見ます。
2. 提案: まず、アーキテクチャの面から短く読み解きます（中心にある問題が、複雑度、重複、結合、概念の混在のどれか）。続けて、番号付きの提案を、Hotspot のファイルにある Critical の Finding から順に並べます。各提案には、変更の内容、取り除く摩擦、解消する Finding、触るファイル、リスクが書かれます。
3. 選択: 適用する提案を、自分で選びます。
4. 適用: 1 提案 1 コミットで適用します。コミットの前には毎回ビルドとテストを実行し、失敗したらその試みを捨てます。コミットしたら、解消した Finding を記録し（heal mark fix）、heal status で確かめ直します。
5. 報告: 何を適用したか、何をなぜ見送ったか、キューに何が残っているかを伝えます。

構造的な提案。 ファイルを概念に沿って分ける、関数を本来のモジュールへ移す、クラスを抽出する、層の境界にインターフェースを置く。こうした変更も、独立した 2 つ以上のシグナルが同じ切れ目を指していれば、普通の提案として出します。たとえば、LCOM のクラスタが、Semantic (Jev) の見つけた概念と一致している場合です。ある関数の概念が別のファイルにあり、しかもそのファイルと一緒に変更されている場合も当てはまります。シグナルが 1 つしかないときは、提案ではなく質問として投げかけます。

判断が必要なもの。 次の 3 つは、適用する前に、具体的な選択肢を付けた個別の質問になります。公開 API の名前の変更（外部に公開している要素、CLI のフラグ、JSON のフィールド）、どちらにも筋が通るモジュールの切り分け方の選択、ドメインの単位での大きな動きです。

変えずに受け入れる。 Finding の中には、意図してそうなっているものを測っているものがあります。生成されたパーサーの表、閉じた enum に対する網羅的な match、手順が一体であるべきパイプラインなどです。スキルはこうしたものを、短い理由を付けて受け入れとして記録する（heal mark accept）ことを提案し、キューから外します。承認を得ずに受け入れることはありません。

Semantic (Jev) を有効にしていると、提案は表示する前に確かめられ（verify_proposal）、各コミットも入った後で確かめられます（verify_patch）。確認で問題が見つかると、スキルはそのコミットを取り消して次に進みます。問題とみなすのは、複雑さが移っただけのとき、条件を早期リターンにひっくり返しただけのとき、コミットメッセージが変更と合わないとき、リファクタのつもりで振る舞いが変わったときです。この機能を有効にしていないとき、またはキーがないときは、これらの確認を省きます。

引数: パスを渡すと（/heal:refactor src/payments）その下の Finding に、Finding の id を渡すとその Finding に絞ります。plan を渡すと、提案までで止まります。

呼び出しに使える言い方の例: 「heal は何て言ってる?」「どこをリファクタすべき?」「heal の Finding を直して」「/heal:refactor」。

heal 0.6 以前からのアップグレード

以前のバージョンは、CLI に 12 のスキルを同梱し、各プロジェクトにコピーしていました。プラグインのスキルとの対応は次のとおりです。

以前	現在
/heal-setup、/heal-concepts-setup、/heal-doc-pair-setup、/heal-test-reporter-setup	/heal:setup
/heal-code-review、/heal-code-patch	/heal:refactor
/heal-doc-review、/heal-doc-patch、/heal-doc-scaffold	/heal:docs
/heal-test-review、/heal-test-patch	/heal:tests
/heal-cli	（プラグインに組み込み済み）

プラグインを入れたら、各プロジェクトで heal skills uninstall を実行して古いコピーを消し、削除をコミットしてください。消すのは heal が書いたフォルダだけで、自分で作ったスキルは残ります。