Docs · スキル

オプトインの Docs ファミリでは、heal の Claude Code プラグインの 2 つのスキルを使います。docs のオブザーバが読むドキュメントとソースの対応表を作る /heal:setup の docs の手順と、ページそのものに手を入れる /heal:docs です。プラグインの入れ方は Code › スキル を参照してください。

/heal:setup docs — ファミリの有効化とドキュメントとソースの対応づけ

リポジトリに合わせたドキュメントのグロブで [features.docs] をオンにし、どのドキュメントがどのソースファイルを説明しているかの一覧、.heal/doc_pairs.json を書き出します。heal はこのファイルを読むだけで、作るのはセットアップ用のスキルの役目です。スキルは、頼んだときにだけ実行されます。ファイルがない、またはもう存在しないパスが書かれていると、heal doctor が docs の項目を todo と報告するので、/heal:setup はこの手順をもう一度提案します。

ペアを選ぶ方法は 3 つあります。

方法	ペアの選び方
Mention	ドキュメントの本文が path/to/source.rs に触れているか、バッククォートで囲んだ識別子が 1 つのソースファイルに当たる。
Mirror	ディレクトリの構成が対応している: docs/payments/engine.md ↔ src/payments/engine.ts。
LLM（任意）	最初の 2 つで決まらないとき、Claude がドキュメントと候補のソースを読む。行う前に確認を求める。

どのペアにも、どの方法で見つけたかが記録されます。手で加えたペア（source: "manual"）は、何度作り直してもそのまま残ります。書き出すのは .heal/doc_pairs.json だけです（ファミリを初めて有効にするときは .heal/config.toml も書きます）。

/heal:docs — ドキュメントの見直しと改善

/heal:refactor のドキュメント版です。docs の Finding を読んで変更を提案し、承認されたものだけを適用します。1 提案 1 コミットで、push や pull request の作成はしません。

1. 診断: heal status --all --feature docs --json、ドキュメントのペア、docs の設定を読み、フラグの立った各ページを、それが説明しているソースと一緒に読みます。各ページは Diátaxis の目的で分類します。チュートリアル、ハウツー、リファレンス、解説のどれかです。この分類によって、ずれがどれだけ問題になるかが決まります。リファレンスのページやチュートリアルの手順が古いと読み手を誤らせますが、解説のページが古くても、たいていは誤らせません。
2. 提案: まず、ドキュメントのどこが傷んできているかを短く読み解きます。続けて、優先度の高い Finding から順に、番号付きの提案を並べます。
3. 選択: 適用する提案を、自分で選びます。
4. 適用: 1 提案 1 コミットで適用します。コミットの前には毎回、サイトのビルド（プロジェクトにあれば）とリンクの確認をやり直します。
5. 報告: 何が変わり、何が残っているかを伝えます。

Finding ごとの提案の内容は次のとおりです。

メトリクス	よくある提案
doc_link_health	名前が変わった、または移動したページにリンクを向け直す。候補が複数あるときは質問する。
doc_drift	名前の変わった識別子を置き換える。概念そのものがなくなった、または作り直されたなら、節を書き直す。
doc_freshness	ソースが離れていった節を、今のコードから組み立て直して書き直す。
doc_coverage	コードから事実が分かるなら、足りないページを書く。ページが要らないなら、ペアを外す。
orphan_pages	読み手が探すセクションからリンクを張る、アーカイブへ移す、または廃止する。
todo_density	コードや設定から答えが分かる TODO を片付け、未解決の問いは、利用者が決める判断事項として示す。

根拠がそろえば、個別の修正にとどまらず、構造的な変更も提案します。

• 目的の混ざったページを分ける（リファレンスの中にチュートリアルがある、など）。
• いくつものページで説明している概念を、1 つの正本にまとめる。
• 読み手が探すセクションへページを移す。
• 誰も必要としないページを廃止する。

どのページに説明を残すか、古いページを書き直すか廃止するかのように、本当は編集の判断にあたるものは、具体的な選択肢を付けた質問になります。

しないこと: doc_coverage を黙らせるための空のページは作りません（空のページは、ないよりも悪いからです）。わざと古い名前に触れている変更履歴、移行の手引き、引用を「揃える」こともしません。ずれたドキュメントに合わせてコードを変えることもしません。正しいのはソースで、直すのはドキュメントです。

Semantic (Jev) を有効にしていると、スキルは次の情報も使います。

• Jev が付けたページの種類。
• 複数の文書が同居していたり、目的が混ざっていたりするページ（doc_structure）。
• 置き場所の違うページ（doc_placement）。
• コードがもう裏付けていない記述（doc_drift.semantic）。
• 2 回説明されている、食い違っている、どこにも説明がない概念（doc_concept）。

引数: パスを渡すとその下の Finding に、Finding の id を渡すとその Finding に絞ります。plan を渡すと、提案までで止まります。

呼び出しに使える言い方の例: 「ドキュメントの状態を見直して」「ドキュメントの Finding を直して」「ドキュメントが古くなってる」「/heal:docs」。

/heal:docs scaffold — 何もないところから文書ツリーを作る

ドキュメントがほとんど、あるいはまったくないプロジェクト向けです。コードベースから読み取れるシグナルだけで文書ツリーを組み立てます。何度実行しても安全です。出力は [features.docs] scaffold_root（既定は .heal/docs/）の下に Markdown として置かれ、コミットはしません。

• 対話ではなく検出で決める。 どのページを書くかは、検出したシグナルだけで決めます。結果を見直して、要らないページは消してください。
• 書き出す基準は厳しめ。 ページを書き出すのは、コードベースから意味のある中身を埋められるときだけです。基礎になるページ（README、Wiki Index、System Context、Architecture Overview、Glossary、Getting Started）は常に書き出し、条件付きのページは、その条件に当てはまったときに書き出します。組織に関わるページ（Quality Goals、Roadmap、Runbooks、SLOs、Postmortems、Security Posture）は、初回には書き出しません。材料がそろったときに書いてください。
• 実際のシグナルから埋める。 マニフェストからコンテナの一覧を、ドキュメントコメントからモジュールの責務を、公開しているシンボルから用語集のたたき台を、CI の設定から貢献のルールを、マイグレーションから ER の表を埋めます。自信を持って埋められないものは、書かずに残します。担当者の名前や、でっち上げた SLO の数値を書くことはありません。
• TODO(human): は 1 つのファイルだけにある。 ADR のテンプレート（decisions/0000-template.md）です。
• 何度でも実行できる。 既定では、自動で管理している各セクションを今のシグナルから更新し、手で編集した部分は残します。--missing-only は新しいファイルを足すだけ、--force はページを最初から作り直します。

ページの一覧は、次のものを組み合わせています。

• Diátaxis（目的）
• arc42（アーキテクチャの章立て）
• C4 モデル（拡大の段階）
• 戦略的 DDD（境界づけられたコンテキスト）
• ADR（判断の記録）
• SRE（運用のページ）
• DeepWiki（AI が書いた wiki に見られるパターン）

[features.docs] を有効にする前でも使えます。出力は、ファミリを有効にした時点で観測の対象になります。

呼び出しに使える言い方の例: 「ドキュメントのツリーを作って」「wiki を生成して」「ドキュメントを一から組み立てて」「/heal:docs scaffold」。