コンテンツにスキップ
heal

クイックスタート

heal はコードベースの劣化をエージェントの仕事に変えます。 コミットのたびに複雑度・Hotspot・重複を再計測し、出てきた TODO リストを Claude に渡して 1 コミット 1 修正で解消します。人間はポーリング役から降りられます。このページではそのループを最後まで、5 分ほどで立ち上げます。

必要環境

Section titled “必要環境”

始める前に揃えておくもの:

  • macOS または Linux
  • 評価対象の git リポジトリ
  • (任意)Claude Code CLI — 同梱の /heal-setup、/heal-code-review、/heal-code-patch などのスキルを使う場合

1. インストール

Section titled “1. インストール”

どの方法でも同じ heal バイナリが入ります。好みのものを選んでください。

brew install kechol/tap/heal-cli
 
heal --version

各方式の詳細は インストール を参照。

2. リポジトリをブートストラップ

Section titled “2. リポジトリをブートストラップ”

.heal/ の作成と git フックの設置を、このコマンド 1 つでまとめて行います。

heal init

.heal/(設定・Calibration・出力)を作り、コミットのたびに次の Critical / High を表示する post-commit フックをインストールします。PATH にある AI エージェント CLI ごとに、同梱スキルを当該エージェントの配置先に展開するかどうかも確認します(Claude Code → .claude/skills/、OpenAI Codex → .agents/skills/)。--yes で全エージェント分を確認なしで展開、--no-skills で全スキップ。

3. /heal-setup で厳しさを調整する

Section titled “3. /heal-setup で厳しさを調整する”

任意ですが、最初は実行を強くおすすめします。同梱のセットアップウィザードがコードベースを調べて、ちょうどよい厳しさを選び、オプションの Test / Docs ファミリを有効化するか確認します。インストールしたエージェントから実行してください:

/heal-setup

Strict / Default / Lenient のどれにするかを聞き、.heal/config.toml を更新します。Test / Docs を有効化するなら、そのまま /heal-doc-pair-setup(.heal/doc_pairs.json を生成)や /heal-test-reporter-setup(lcov リポータの配線を提案)に連携します。コードベースが大きく変わって基準を動かしたくなったら、後から再実行できます。

4. TODO リストを見る

Section titled “4. TODO リストを見る”

Severity ごとにまとまった、すぐ手をつけられる項目の一覧です。

heal status

ファイル単位の TODO リストを Severity 別に表示します。フィルタや JSON 出力は CLI › heal status を参照。

5. エージェントに監査と修正を任せる

Section titled “5. エージェントに監査と修正を任せる”

やりたいことに合わせて同梱スキルを選びます。各機能ファミリには、読み取り専用の review スキル(アーキテクチャ視点の監査、書き込みなし)と、書き込み付きの patch スキル(1 コミット 1 修正、dirty な worktree では起動しない)が揃っています。下の例は claude を使っていますが、Codex を使っているなら codex に置き換えるだけでスラッシュコマンド形式は同じです。

# 常時オン — Code ファミリ:
claude /heal-code-review     # 出力をシステムとして読み解く。問題のあるコードを精読し、優先度付きのリファクタ TODO を返す。コードは触らない。
claude /heal-code-patch      # TODO を機械的に解消。1 コミット 1 修正、Severity 順に進め、push も amend もしない。


# [features.docs] が ON のとき:
claude /heal-doc-review      # Diátaxis レンズでドキュメントを監査。読者がどこで迷うかを見つける。
claude /heal-doc-patch       # 内部リンク切れ・参照切れの識別子・孤立ページを自動で修正。


# [features.test] が ON のとき:
claude /heal-test-review     # テストピラミッドの視点でカバレッジの穴と暗黙の skip を可視化。
claude /heal-test-patch      # review が指摘したテストを書く。カバレッジ未達の hot path 1 つにつき 1 コミット。

特定の場面向けにもう 2 つ:

claude /heal-doc-scaffold    # [features.docs]: コードベースのシグナルだけでドキュメントツリーを新規生成。docs がまだほぼ無いプロジェクト向け。
claude /heal-cli             # heal CLI 自体の使い方をエージェントに聞く。全フラグと JSON 形式を安定した契約として参照できる。

スキルの詳細は Code › スキル、Docs › スキル、Test › スキル を参照。

続けて読む

Section titled “続けて読む”

ドキュメントサイトの各ページへ:

常時オンの Code ファミリ以上を試したくなったら:

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

ドキュメント通りに動かないときは issue を立ててください。