docs-update（ドキュメント更新）
ドキュメントは静かに腐ります。何も壊れず、ただ文章が真実でなくなるだけです。このスキルは、最近の変更が触れるべきだったドキュメントを見つけ出し、それを最新の状態にします。
以下のコマンドは ~/.claude/skills/docs-update/scripts/ を完全な形で示しています。記述された通りにそのまま実行してください。先頭の ~ を保持し、展開しないでください。 許可ルールはリテラルのコマンド文字列と一致するため、/home/<ユーザ名>/.claude/...（チルダ展開後）、python3 ~/...、相対パス、または cd を先に実行するものは、それぞれ異なる文字列であり、それぞれが再プロンプトを引き起こします。チルダ付きのパスは「非形式的に書かれた絶対パス」ではありません。許可ルールにとって、それはそのパスそのものです。
ドキュメントは変更と同時にリリースされ、後追いではありません。 フィーチャーブランチで作業している場合は、そのブランチにドキュメントをコミットして、マージが自動的にドキュメントも運ぶようにしてください。ドキュメントのフォローアップPRは、誰も書かないドキュメントPRです。
1. スコープを選択する
優先順位は以下の通りです。
ユーザーが明示的に指示した場合。 「full sweep」「since v2.1」「just this branch」など。その指示を使用します。フルスイープは --full で、すべてのドキュメントを読み込みます。長い期間が空いた後や、このスキルをリポジトリに初めて導入する場合に適切な選択です。
ドキュメントに自身の最終更新ポイントが記録されている場合。
~/.claude/skills/docs-update/scripts/docscheck.py markers
ドキュメントに Last updated: <日付|sha> が含まれている場合、そのドキュメント をその時点からスコープします（--since）。ドキュメントごとに最終更新が異なる場合、それぞれに独自のスコープが設定されます。単一の答えはありません。
それ以外の場合、git からスコープを導出します。
~/.claude/skills/docs-update/scripts/docscheck.py scope
これは、最後にマージされたブランチを優先します（ブランチ単位の作業が人々が意図する単位であるため）、次に最後のコミットを使用します。--since <ref> で上書きできます。
このセッションで行われた作業 は、スクリプトでは認識できないケースです。このセッションで変更を行った場合、変更したファイルは既に把握しているはずです。セッション前のリファレンスを --since として渡すか、自身の編集リストから作業します。
scope は kind=code と kind=doc-already-touched を区別します。2番目のリストは重要です。それらのドキュメントは変更と同時に更新されたものであり、存在の有無ではなく、正確性をチェックする必要があります。
2. 変更が実際に影響するドキュメントを見つける
~/.claude/skills/docs-update/scripts/docscheck.py impacted
変更された各コードファイルについて、その正確なパスを名前として参照しているドキュメントを報告します。変更したファイルを引用しているドキュメントは、もはや真実でなくなっている可能性が最も高く、すべてのドキュメントを読み直すよりもはるかに優れた出発点となります。
これは意図的に完全パスのみを照合します。親ディレクトリも照合するのはより寛大に聞こえますが、実際には無価値です。モノレポで apps/web-nuxt/ が62のドキュメント中55に出現する場合、すべてがすべてに影響することになります。
result=none は正常であり、「何もすることがない」という意味ではありません。つまり、どのドキュメントもこれらのパスを名前として参照していないため、代わりに主題で判断する必要があるということです。それがステップ3です。
3. リポジトリ独自のドキュメント分類を使用して、主題で判断する
impacted はパスの引用を見つけます。ファイル名を挙げずに、変更した動作を説明するドキュメントを見つけることはできません。したがって、変更内容を読み、それが何を意味するのかを問いかけてください。
まず、このリポジトリがドキュメントをどのように整理しているか（brain/、docs/、CONTEXT.md、ADRディレクトリなど）を把握し、新しい構造をでっち上げるのではなく、その構造に従ってください。プロジェクトスキルがドキュメントをカバーしている場合（.claude/skills/*）、それがこのスキルよりも優先されます。
一般的なマッピングは以下の通りです。
| 変更内容 | 該当ドキュメント |
|---|---|
| 新しいユーザー向け機能 | 機能ドキュメント + そのインデックス/カタログ行、READMEの機能リスト |
| 既存の動作の変更 | その機能のドキュメント |
| スキーマ、認証、ビルド、ストレージ、リアルタイム、プロバイダー | 対応するアーキテクチャドキュメント |
| 明白でない、またはレビューで表面化した判断 | 決定事項/ADRログ。その理由と共に |
| 新しい用語 | 用語集 |
| 新規または変更された環境変数、コマンド、スクリプト | README およびセットアップ/運用ドキュメント |
| 新しい依存関係 | スタック/技術リストドキュメント（これらは手動で管理され、常に忘れられがちです。マニフェストとの差分を確認してください） |
| ユーザー向けの変更 | CHANGELOG [Unreleased] |
二つの落とし穴があります。
- 散文に埋め込まれた派生的な事実。「現在のバージョンは 2.16.2 です」やテクノロジースタックを列挙したドキュメントは、他の何かが移動したもののコピーです。散文を信頼するのではなく、真実のソース（マニフェスト、バージョンファイル）の差分を確認してください。
- 歴史的または将来的な目的を持つドキュメント。 CHANGELOG エントリ、TODO、および ROADMAP は、削除されたか、または一度も書かれなかったファイルを引用します。これらを「修正」しないでください。
4. 引用がまだ解決可能か確認する
~/.claude/skills/docs-update/scripts/docscheck.py links
二種類あります。
kind=link- 対象が存在しない相対マークダウンリンク。常に実際の問題です。kind=source- 存在しないインラインコードパス。通常、ファイルが移動または名前変更されたことが原因です。説明文書は除外され、ブレース展開、<プレースホルダー>、グロブ、および gitignored なビルド出力はフィルタリングされるため、残ったものは調査する価値があります。
スコープ内のものを修正してください。リポジトリ内の他の場所で見つかった問題は報告する価値がありますが、黙ってジョブをフルスイープに拡大しないでください。
5. 執筆
書いたものすべてに unslop を適用する
追加または変更したすべての行に unslop スキルを適用してください。 ドキュメントは、スロップが最も害を及ぼす場所です。何かを学ぼうとしている人に読まれ、新参者が最初に触れるものであり、チャットメッセージとは異なり、残り続けます。
特にドキュメントに現れる特徴は以下の通りです。
- 前置きの枕詞。 「このドキュメントは～の概要を提供します...」「このセクションでは～を探求します...」。これらを削除し、事実から始めてください。
- コードを散文で言い換える。 「
getUser関数はユーザーを取得します。」文が識別子を英語に展開しただけなら、それは無価値です。コードが言えない部分、つまり制約、理由、注意点を書いてください。 - 空虚な強調表現：包括的、堅牢、シームレス、強力、柔軟、シンプルに、簡単に、ただ。「シンプルに X を実行する」は、X がシンプルでない場合には常に誤りです。
- 答えが確定している場合の曖昧な表現：「一般的に」「通常」「通常は」。するか、名前を付けられる何かに依存するかのどちらかです。名前を付けてください。
- 注意書きのパディング：「留意すべき重要な点は」「注意してください」「心に留めておいてください」。その後の文が内容です。それをそのまま書いてください。
- ページ上の内容を要約する要約セクション。 ドキュメントに要約が必要なら、それは長すぎます。
- 名前を繰り返す説明列。 テーブル行
| --verbose | 詳細な出力を有効にします |は一行を費やして何も教えません。 - 3つのルールの埋め草 - 最初の2つと異なるからではなく、リズムのために追加された3番目の例。
ファイルに合わせる、スロップに合わせない
ファイルの既存のスタイルに合わせてください。時制、密度、エントリが一行なのか散文なのか。あるセクションが突然異なる文体で書かれているドキュメントは、一貫して簡潔なドキュメントよりも悪質です。
これらの二つのルールは、既存のドキュメント自体がずさんな場合にのみ衝突します。その場合は、その構造と密度に合わせ、パディングは合わせず、それ以外で触れていないセクションは書き換えないでください。 ドキュメント更新でファイル全体のスタイルも変更してしまうと、レビュー不可能な差分となり、実際に重要な変更が埋もれてしまいます。ドキュメント全体に散文のパスが必要な場合は、その旨を伝え、それを独立したジョブとして提案してください。
残りのルール
- コードを言い換えるのではなく、ソースパスにリンクしてください。そうすれば、次の変更がリンクを壊し、静かに散文と矛盾する代わりになります。
- 現在形で、今真実であることを記述してください。ドキュメントは変更履歴ではありません。「私たちはXをYに置き換えました」はCHANGELOGに、「システムはYを使用しています」がドキュメントに属します。
- ドキュメントに最終更新マーカーがある場合は、それを更新してください。
6. 報告
- 使用したスコープと、その理由
- 更新したドキュメントと、それぞれで変更した内容
- 確認したが、意図的に変更しなかったドキュメント
- スコープ外で見つかった壊れたリンクや引用（リストアップするが修正はしない）
- ユーザーなしでは判断できなかった事項