update-claudemd

CLAUDE.md を更新して最適化する

プロジェクトの CLAUDE.md とトピックファイルを、各ファイルの最終コミット以降のコードベースの実態および Git 履歴と照らし合わせて整合させます。段階的開示を徹底します。CLAUDE.md は、プロジェクトの概要、全体に適用される不変条件、.claude/rules/*.md にあるトピックファイルへの参照を示す最上位のインデックスです。.claude/rules/ のファイルは、paths: フロントマターで対象範囲を指定しない限り、SessionStart で自動的に読み込まれます。このスキルが作成するすべてのトピックファイルには、そのファイルが毎回のセッションではなく、担当するサブシステムのファイルが対象になったときにのみ読み込まれるよう、フロントマターを付ける必要があります。

整合性確認の対象には、.claude/rules/ 内のすべてのファイルが含まれます。トピックファイルは独立した重要なコンテンツです。CLAUDE.md 自体と同じく、陳腐化、正確性、重複のリスクがあるため、毎回の実行時に監査し、コードベースと照合し、必要に応じて編集する必要があります。付録として扱ってはいけません。

対象範囲の境界：対象はプロジェクトの CLAUDE.md（L1）とそのトピックファイルのみです。ユーザー共通の ~/.claude/CLAUDE.md（L0）は、ユーザーから明示的に依頼されない限り対象外です。

基本原則

CLAUDE.md の内容が妥当なのは、次のセッションで Claude の行動を変え、かつほとんどのタスクで必要となる場合に限ります。サブシステム固有の内容は重要ですが、必要に応じて読み込むトピックファイルに記載します。

トピックファイルの内容が妥当なのは、そのサブシステム内で Claude の行動を変え、かつ現在のコードベースの実態に照らして正確な場合に限ります。陳腐化したトピックファイルは、Claude がその内容を信頼するため、ファイルがない場合よりも有害です。

フェーズ 3 では、この原則を運用に落とし込むための 7 つのアクションを定めます。これにより、内容を下位へ移す（CLAUDE.md からトピックファイルへ移動する）ことも、上位へ戻す（詳細が全体に適用されるようになった場合に、トピックファイルから CLAUDE.md へ昇格させる）こともできます。目標は一方向の保管場所ではなく、常に更新される段階的開示の階層です。

予算

CLAUDE.md：目安は約 120 行、上限の目安は 150 行です。予算を超えたファイルにはフラグを立てますが、強制的に変更してはいけません。手作業で管理されている CLAUDE.md は尊重します。行数は wc -l で測定します。

トピックファイル：情報提供を目的とした目安の上限は、それぞれ約 300 行です。サブシステムの成長に伴ってトピックファイルが大きくなるのは妥当です。約 300 行を超えた場合は、フェーズ 7 で超過にフラグを立て、サブトピックごとに分割することを提案します。処理を妨げてはいけません。厳格な制約は CLAUDE.md の予算のみです。

ファンアウトルール

コードベースの調査規模は、プロジェクトの規模と変更頻度に応じて調整します。フェーズ 1 で一度だけ計算し、フェーズ 2 で適用します。

指標：

• churn — CLAUDE.md の最終更新以降のコミット数：git log --since="<date>" --oneline --no-merges | wc -l
• files — トラッキング対象のファイル数：git ls-files | wc -l

N（コードベーススキャンの分割数）：

churn	files	N
< 20	< 100	1
20 – 59	100 – 499	2
60 – 149	500 – 1999	3
≥ 150	≥ 2000	4

各列について個別に N を計算し、その最大値を採用します。上限は 4 です。N > 1 の場合は、最上位ディレクトリのまとまりごとに分割します（例：plugins/ → シャード 1、scripts/ + tests/ → シャード 2）。

フェーズ 1 — 方針を確認し、並列数を算出する

プロジェクトルートで CLAUDE.md を Glob 検索します。存在しない場合は、このスキルの範囲外のため作成できないことをユーザーに伝え、停止します。

現在の CLAUDE.md の行数を wc -l で記録します。ディレクトリが存在する場合は .claude/rules/*.md を一覧表示し、各トピックファイルの行数と最終コミット日を git log -1 --format="%ai" -- <path> で記録します。各ファイルの日付は、エージェント B が各ファイルの古さの期間を個別に設定するためにフェーズ 2 で必要です。すべてのファイルに CLAUDE.md の日付を使うと、更新頻度が異なる場合に期間を誤って設定してしまいます。

負荷の低い Git の調査を 2 段階で実行します。

まず、直近の CLAUDE.md のコミット日を解決します（後続の調査がこれに依存するため、順次実行します）。

• git log -1 --format="%ai" -- CLAUDE.md → <last_claudemd_date> として記録します。CLAUDE.md に履歴がない場合は、git log --reverse --format="%ai" | head -1 にフォールバックします。

次に、残りの調査を並列の Bash 呼び出しとして実行します。

• git log --since="<last_claudemd_date>" --oneline --no-merges | wc -l — 変更量
• git ls-files | wc -l — 追跡対象ファイル数
• git ls-files | awk -F/ 'NF>1{print $1}' | sort -u | wc -l — トップレベルディレクトリ数

並列数のルールを使って N を算出します。シャード計画を決定します。各コードベーススキャンエージェントが担当するトップレベルディレクトリを決めます。

終了条件：CLAUDE.md が存在し、基準となる行数、トピックファイルごとの行数と最終コミット日が記録され、N が算出され、シャード計画が決定されていること。

フェーズ 2 — 並行調査

3 + N 個の Explore エージェントを、1 つのメッセージで起動します。すべて subagent_type: Explore を使用します。

エージェント A — CLAUDE.md とトピックファイルの監査（subagent_type: Explore）

プロジェクトの CLAUDE.md と、存在する場合は .claude/rules/ 内のすべてのファイルを読みます。CLAUDE.md と各トピックファイルの両方に、同じ H1/H2/H3 分類を適用します。トピックファイルも目録にとどまらず、第一級のコンテンツです。

どちらのソースでも、各 H1/H2/H3 セクションについて、source（CLAUDE.md のパスまたはトピックファイルのパス）、name、line_count、classification_hint（プロジェクトの概要、普遍的な不変条件、サブシステムに限定された詳細、条件付きのガイダンス、またはファイルの調査から導出可能）を記録します。トピックファイルのセクションについては、普遍的な不変条件となったもの（1 つのサブシステム内だけでなく、プロジェクトのほぼすべてのタスクで Claude の行動に影響を与える内容）があれば、それらもフラグを付けます。これらは CLAUDE.md への再昇格候補です。

古くなった内容（バージョン番号、パス、コマンド、誤りと思われる機能）にフラグを付けます。ファイル間の重複（CLAUDE.md と重複するトピックファイルの内容、または互いに重複するトピックファイル）にもフラグを付けます。

また、CLAUDE.md とトピックファイルのディレクトリ間で、インデックスのずれがないかスキャンします。

• dangling_references — CLAUDE.md の ## Topic Files セクションから参照されているが、ディスク上に存在しないトピックファイル
• unreferenced_topic_files — ディスク上にあるが、CLAUDE.md から参照されていないトピックファイル

以下を返します：sections[{source, name, line_count, classification_hint, promote_back_candidate}]、stale_items[{source, item, reason}]、duplications[{items, locations}]、existing_topic_files[{path, line_count, last_touched, subject, section_count, has_paths_frontmatter}]、dangling_references[]、unreferenced_topic_files[]。

エージェント B — ファイルごとの Git 履歴（subagent_type: Explore）

各指示ファイルについて、そのファイル自体の最終更新日を基準に、Git 履歴を 1 回ずつ調べます。フェーズ 1 で取得した日付を使用します。

1. CLAUDE.md について、リポジトリ全体を対象に git log --since="<claudemd_last_touched>" --format="%s%n%b" --no-merges を実行します。
2. 各トピックファイルについて、トピックファイルの対象ディレクトリを指定して git log --since="<topic_file_last_touched>" --format="%s%n%b" --no-merges -- <directories the topic file covers> を実行します。対象ディレクトリは、トピックファイルの主題と読み込み条件から推定します（例：フックに関するトピックファイルなら plugins/*/hooks/ が対象です）。主題がリポジトリ全体に及ぶ場合は、リポジトリのルートを使用します。

履歴のないファイルについては、代わりに git log --reverse --format="%ai" | head -1 を使って初回コミットの日付を取得します。

各ファイルのコミットを分類します：new_subsystems（新たに追加されたコード領域）、architecture_changes（コードの記述方法に影響する決定やリファクタリング）、convention_changes（新たなパターン）、removed_features（コードベースから削除された機能）、other。CI、フォーマット、バージョン更新は除外します。

以下を返します：per_file[{path, last_touched, changes_since{new_subsystems, architecture_changes, convention_changes, removed_features, other}}]。指示ファイルごとに 1 つのエントリを返します。

エージェント C1..CN — コードベースの分割スキャン（subagent_type: Explore）

各エージェントは 1 つの分割領域を担当します。各分割領域は、分割計画で割り当てられたトップレベルディレクトリを対象とします。以下を抽出します：技術スタックとフレームワーク、確立されたパターン（テストのスタイル、エラー処理、モジュール構成）、新しいコントリビューターが見落としやすい明白でない規約、設定ファイルやスクリプトに記載された主要なコマンド、コメントやサブディレクトリの README に記載された注意点、独立したトピックファイルにする価値があるほど特定のサブシステムに限定された内容のまとまり。以下を返します：tech_stack、patterns、conventions、commands、gotchas、topic_file_candidates[{filename, subject}]。

終了条件：3 + N 個すべてのエージェントから、構造化されたメモが返されること。エージェントが空の結果または途中で切れた結果を返した場合は、利用可能な結果で進め、その不足をフェーズ 5 の提案に記載します。

フェーズ 3 — 分類

Agent A の各セクション（CLAUDE.md のセクションおよびトピックファイルのセクション）と、Agents B および C1..CN による新しい各発見に、アクションをちょうど 1 つ割り当てます。アクションは双方向で、内容は下方向（降格）にも上方向（昇格）にも移動します。

• keep — 内容は変更せず、そのまま残します
• update — 内容はその場所に残し、正確さを保てるよう書き換えます（古くなった事実、変更されたパス、新しい規約など）
• delete — package.json、ls、または 1 つのソースファイルを読めば導出できる内容、または機能がすでに存在しない場合
• demote → <topic-file> — CLAUDE.md のうち、サブシステムに限定された内容をトピックファイルに移動します
• promote → CLAUDE.md — トピックファイルの内容のうち、普遍的な不変条件となったものを CLAUDE.md に戻します。Agent A が promote_back_candidate としてマークしたセクションに限定します。これは、読み込み条件が 1 つのサブシステムだけでなく、ほぼすべてのタスクに当てはまるようになった内容です。これは demote の逆であり、慎重に使用する必要があります。CLAUDE.md の予算には余裕がありません
• move → <other-topic-file> — トピックファイルの内容のうち、主題のまとまりが変わり、別のトピックファイルに属するようになったものを移動します
• add — 調査で明らかになった新しい内容を CLAUDE.md またはトピックファイルに追加します
• add-paths-frontmatter → <glob> — 既存のトピックファイルに paths: フロントマターがない場合、そのファイルの主題に合わせて追加します。Agent A が has_paths_frontmatter: false と報告したすべてのファイルに適用します

Agent A の未解決の参照に関する項目には、以下の調整アクションで対処します。

• dangling_references — 参照先の主題が現在も有効であれば、欠落しているトピックファイルを作成します。そうでなければ、CLAUDE.md から無効な参照を削除します
• unreferenced_topic_files — CLAUDE.md の ## Topic Files セクションから参照を追加するか、参照のないファイルを削除します（フェーズ 5 でユーザーが決定します）

コードベーススキャンのシャードから得られた降格候補とトピックファイル候補は、主題ごとにまとめます。新しいトピックファイルを作成する前に、既存のトピックファイルがその主題をすでに扱っているか確認してください。該当する場合は、既存のファイルに追加します。

CLAUDE.md の普遍的な不変条件の上位 3～5 件は、降格しません。反対に、トピックファイルのセクションを再昇格させるのは、「ほぼすべてのタスクで Claude の動作を変える」という基準を明確に満たす場合に限ります。

終了条件：すべてのソースの各セクションと新しい各発見に、アクションがちょうど 1 つ割り当てられていること。降格候補が名前付きのトピックファイルのまとまりに分類されていること。未解決の参照と孤立したトピックファイルに、解決計画があること。

フェーズ 4 — 予算の確認

調整後の CLAUDE.md の行数を見積もります。計算式は current + added + promoted_in − demoted − deleted です。promoted_in は、トピックファイルのセクションを CLAUDE.md に戻す分を考慮します。他のアクションが差し引きゼロでも、再昇格の数が多ければ CLAUDE.md の予算を超える可能性があります。

見積もりが 150 以下の場合は、降格を停止します。トピックファイルがあるからといって、過剰に降格する理由にはなりません。

見積もりが 150 を超える場合は、まず昇格を厳しく検証します。再昇格のアクションには高い基準を設けます。普遍性がわずかしかない再昇格は除外します。その後、上位の不変条件を対象外としたうえで、150 未満になるまで、優先度が最も低い keep 項目をまとまりごとに追加で降格します。妥当な範囲で降格し、再昇格を絞り込んでもファイルが 150 行を超える場合（意図的に密度を高くして手動で管理されている場合など）は、超過をフェーズ 5 で示し、受け入れるかどうかはユーザーに判断してもらいます。

変更を加えた各トピックファイルについても、情報提供用の上限である約 300 行と照らして確認します。超過があればフェーズ 5 で提示しますが、降格や分割を強制しないでください。トピックファイルは正当な理由で密度が高い場合があります。厳格な制約は CLAUDE.md の予算のみです。

終了条件：実行前後の行数見積もり、CLAUDE.md の予算ステータス（under、over (user override)）、および情報提供用の上限を超えるトピックファイルの一覧を含む最終アクションリストが作成されていること。

フェーズ 5 — 提案

計画を構造化された要約として提示します。すべての指示ファイル（CLAUDE.md と、変更対象となる各トピックファイル）について、ファイル名だけでなく、同じ詳しさで示します。

CLAUDE.md

• 行数：<current> → <estimated>（予算：<status>）
• 維持：セクション数
• 更新：各項目に1行の理由を添えたリスト（古くなっている内容、修正する内容）
• 削除：各項目に1行の理由を添えたリスト（例：「package.json から導出可能」）
• 移管：移管先のトピックファイルごとにまとめ、各ファイルに移すセクションを表示
• 再昇格：トピックファイルから戻すセクションのリスト（普遍的な不変条件となったため）
• 追加：新しい内容と出典（どの調査エージェントが見つけたか）のリスト

トピックファイル

新規作成する各トピックファイルについて：

• ファイル名、推定行数、取り込むセクション（移管または調査結果から）

更新する各トピックファイルについて：

• パス、行数：<current> → <estimated>
• 維持／更新／削除／再昇格による削除／移管による追加 — CLAUDE.md と同じ構造化された内訳
• paths フロントマター：追加（paths: のないファイルに paths: を追加する場合）
• 予算フラグ：約300行を超える場合

変更しない各トピックファイルについて：パスと、ドリフトが検出されなかった理由を1行で記載します。

インデックスの整合性

• 解決した参照切れ（リスト）
• 解決した孤立トピックファイル（リスト）

AskUserQuestion を使い、次の3つの選択肢を提示します：すべて承認、一部を承認、却下。

終了条件：ユーザーがアクションのセットを明示的に承認していること。

フェーズ 6 — 書き込み

トピックファイルへのポインターを解決できるよう、次の順序で実行します。

1. 書き込み前に Bash 経由で cp CLAUDE.md CLAUDE.md.bak を実行し、バックアップを作成します
2. .claude/rules/ が存在しない場合は、mkdir -p で作成します
3. 次の順序でトピックファイルのアクションを適用します。
   • ユーザーが削除を承認した孤立トピックファイルを削除します
   • 新しいトピックファイルを書き込みます。各ファイルには、対象とするグロブに合わせた paths: YAML フロントマターをブロックシーケンス形式で記述します（形式は以下の例全体を参照してください）
   • 既存のトピックファイルを編集します（維持／更新／削除／再昇格による削除／移管による追加のアクションを適用）。再昇格によって削除するセクションはここで削除し、ステップ4で CLAUDE.md に再掲載します
   • Agent A が paths: フロントマターの欠落を報告した既存のトピックファイルに paths: フロントマターを補完します。これがないとファイルは毎回の SessionStart で自動読み込みされ、段階的な開示が損なわれます
4. CLAUDE.md を書き込み、末尾に ## Topic Files セクションを再生成します。削除済みトピックファイルへのポインターは除外します。ステップ3で再昇格したセクションは、## Topic Files インデックスブロック内ではなく、CLAUDE.md 本文の新しい H2 セクションとして記述します

## Topic Files セクションは、ステップ2の後に実際のディスクの状態から再生成し、手動では管理しません。各項目は説明用リンクではなく、読み込みトリガーです。

## Topic Files

Read on demand — do not load preemptively.

- `.claude/rules/testing.md` — before writing or modifying tests
- `.claude/rules/hooks.md` — before editing anything in plugins/*/hooks/

読み込みトリガーのフレーズは、見出しからコピーせず、トピックファイルの内容に基づいて生成します。同じトリガーをトピックファイル自体の paths: フロントマターにも使用します。グロブとポインターのフレーズは一致している必要があります。

---
paths:
  - "plugins/*/hooks/**"
---
# Hooks

paths: フロントマターのないトピックファイルは、CLAUDE.md と同等の優先度で、すべての SessionStart で読み込まれます。これはオンデマンド読み込みとは正反対です。パスのスコープ設定は必須です。

CLAUDE.md の大部分を維持する場合は、変更箇所を絞って Edit を使用します。ファイルの60%を超える部分を変更する場合に限り、Write を使用します。その時点では、文書を更新するのではなく再生成することになります。

終了条件：すべてのファイルが書き込まれ、## Topic Files セクションが実際のディスクの状態を反映していること。

フェーズ 7 — レポート

変更した各指示ファイルについて、ファイルごとの差分の概要を出力します。

CLAUDE.md

• <before> → <after> 行（<budget status>）
• 削除：理由を添えて一覧表示
• 追加：出典を添えて一覧表示
• CLAUDE.md に昇格：トピックファイルから CLAUDE.md に移動したセクションの一覧（該当する場合）
• 維持された不変条件：ユーザーが維持を確認できるよう、上位 3～5 件を原文のまま引用

作成したトピックファイル — ファイルごとに、パス、行数、元にしたソースを記載

更新したトピックファイル — ファイルごとに、パス、<before> → <after> 行、変更内容の概要を 1 行で記載（例：「古いパスを 2 件修正、1 セクションを CLAUDE.md に昇格、Agent C2 の調査結果に基づく新規セクションを 1 件追加」）。約 300 行の情報量の上限を超えるトピックファイルにはフラグを付けます。

変更のないトピックファイル — ドリフトが検出されなかったファイルを一覧表示

インデックスの整合性確認 — 解決した参照先のない項目、解決またはリンクした孤立トピックファイル

バックアップ：フェーズ 6 の手順 1 で CLAUDE.md.bak が作成されています。diff CLAUDE.md.bak CLAUDE.md で差分を確認し、問題がなければご自身で削除できることをユーザーに伝えてください。このスキルではバックアップを削除しません。

終了条件：レポートを提出し、確認後に CLAUDE.md.bak を削除するようユーザーに案内します。