claude-md-managementプラグインでCLAUDE.mdを監査・更新する手順
claude-md-managementプラグインの導入方法と、claude-md-improverスキル・/revise-claude-mdコマンドの流れを整理。/doctor prompt-auditや自動メモリとの使い分けも比べます。
claude-md-managementは、CLAUDE.mdの点検と更新を2つの道具に分けたプラグインです。コードベースとのずれを探すスキル claude-md-improver と、セッションで得た学びを書き足すコマンド /revise-claude-md が入ります。どちらも変更案を見せ、承認したものだけを書き込む作りです。
claude-md-managementプラグインは何を追加するか
claude-md-managementは、Anthropicの公式プラグインリポジトリ(claude-plugins-official)の plugins/ 配下にあるプラグインです。plugin.json の説明は「CLAUDE.mdの品質を監査し、セッションの学びを取り込み、プロジェクトの記憶を最新に保つ」旨で、バージョンは1.0.0、作者表記はAnthropicです。
READMEでは、2つの道具を用途で分けています。
| claude-md-improver(スキル) | /revise-claude-md(コマンド) | |
|---|---|---|
| 目的 | claude-md-improver(スキル)CLAUDE.mdをコードベースの現状に合わせる | /revise-claude-md(コマンド)セッションの学びを残す |
| 使う場面 | claude-md-improver(スキル)定期的な点検 | /revise-claude-md(コマンド)作業の終わり |
| 向く状況 | claude-md-improver(スキル)コードが変わってCLAUDE.mdが古びた | /revise-claude-md(コマンド)作業中に足りなかった文脈が見えた |
前者は棚卸し、後者は追記です。CLAUDE.mdを書く場面そのものはClaude CodeのCLAUDE.mdを実用に引き上げる10のパターンが扱っているので、ここでは「保つ」側に絞ります。
インストールして呼び出す
導入は通常のプラグインと同じです。公式マーケットプレイスはインタラクティブなセッションを最初に起動したときに自動で登録されるため、追加の手順は要りません。
/plugin install claude-md-management@claude-plugins-officialセッション内でこのコマンドを打つと、すぐには入らず /plugin パネルの詳細画面が開きます。追加される内容とスコープを確かめてから選ぶ流れです。シェルからは次の形になります。
claude plugin install claude-md-management@claude-plugins-officialスコープは3つあります。
インストールスコープの違い
ユーザー
自分だけが全プロジェクトで使えます。個人の点検用ならここが素直です。
プロジェクト
.claude/settings.jsonに記録され、チームで有効になります。ただし各メンバーが--scope projectで入れる作業は別に必要です。ローカル
自分だけ、そのリポジトリだけで有効です。
呼び出し方はREADMEに沿うと次のとおりです。スキルは「CLAUDE.mdを監査して」「CLAUDE.mdは最新か確認して」といった依頼で動き、コマンドは /revise-claude-md と打つだけです。プラグインの部品は名前空間付きで登録されるため、他のプラグインと名前が重なるときは claude-md-management: を前に付けた形で区別します。プラグイン全体の探し方は公式マーケットプレイスのプラグイン一覧にまとめています。
claude-md-improverは5つの段階で監査する
スキルの本体は SKILL.md に書かれた5段階のワークフローです。
claude-md-improverの流れ
- 1
探す
CLAUDE.md、.claude.md、.claude.local.mdをfindで洗い出します。プロジェクト直下、個人用、ホーム、モノレポのパッケージ別、サブディレクトリの5種類を想定しています。 - 2
採点する
6つの基準で各ファイルを100点満点で評価します。
- 3
報告する
更新の前に必ず品質レポートを出します。
- 4
提案する
ファイルごとに差分と理由を示し、承認を求めます。
- 5
反映する
承認後にEditツールで書き込み、既存の構成は保ちます。
採点の配点は次のとおりです。
| 基準 | 配点 | 見ているもの |
|---|---|---|
| コマンド・ワークフロー | 配点20 | 見ているものビルド、テスト、デプロイの手順があるか |
| アーキテクチャの明快さ | 配点20 | 見ているものディレクトリの役割やエントリポイントが分かるか |
| 自明でないパターン | 配点15 | 見ているもの落とし穴や「なぜそうするか」が書かれているか |
| 簡潔さ | 配点15 | 見ているもの冗長な説明やコードを読めば分かる情報がないか |
| 最新性 | 配点15 | 見ているものコマンドや参照ファイルが今も有効か |
| 実行可能性 | 配点15 | 見ているものコピペで動く指示か |
合計はA(90〜100)、B(70〜89)、C(50〜69)、D(30〜49)、F(0〜29)の5段階に換算されます。参照資料には「失敗するコマンド」「消えたファイルへの参照」「テンプレートのコピペ」「完了しないTODO」「複数ファイルでの重複」といった赤信号の一覧もあります。
スキルが想定するレポートの形は、おおむね次のとおりです。これはSKILL.mdが示す書式で、実際の出力ではありません。
## CLAUDE.md Quality Report
### Summary
- Files found: 3
- Average score: 68/100
- Files needing update: 2
#### 1. ./CLAUDE.md (Project Root)
**Score: 72/100 (Grade: B)**数字が先に出るので、どのファイルから直すかを決めやすくなります。
モノレポでは、サブディレクトリのCLAUDE.mdが一覧に混ざります。標準の仕様では、サブディレクトリのファイルは起動時でなく、その配下のファイルをClaudeが読み書きした時点で読み込まれます。パッケージ別のファイルは、そのパッケージだけに効く内容を書く場所です。逆に、点数は目安にとどめるのが無難です。配点は一般的な基準で、自分のプロジェクトの重みとは限りません。
/revise-claude-mdでセッションの学びを残す
コマンドのほうは5ステップで進みます。
- 振り返る: 使った、または見つけたBashコマンド、守ったコードスタイル、効いたテスト方法、環境の癖、遭遇した落とし穴を拾う
- 置き場所を決める: チーム共有なら
CLAUDE.md、個人用なら.claude.local.md - 下書きする: 1概念1行、「コマンドまたはパターン + 短い説明」の形にする
- 変更案を見せる: ファイルごとに理由1行と差分を出す
- 承認を得て反映する: ユーザーが認めたファイルだけを編集する
allowed-tools は Read, Edit, Glob で、書き込みはEditに限られます。避けるものとして、冗長な説明、自明な情報、再発しそうにない一度きりの修正が挙げられています。
コマンドが変更案を出す書式は、次のように決まっています。以下は書式の例で、実際の出力ではありません。
### Update: ./CLAUDE.md
**Why:** テストが共有DBで落ちる原因を毎回調べ直していたため
+ - テストは `--runInBand` で実行する(共有DBの状態に依存)ファイル単位で理由が1行付くので、どの行が何のための追記かを後から追えます。承認しなかった案は書き込まれません。
使いどころは、同じ指摘を2回しそうなセッションの終わりです。たとえば「テストは --runInBand でないと共有DBで落ちる」と気づいた日は、これを1行で残す価値があります。
公式ドキュメントと食い違う点
READMEとSKILL.mdを標準ドキュメントと照らすと、2つ気になる箇所があります。
プラグインの記述と標準ドキュメント
個人用ファイルの名前
プラグインは .claude.local.md を使います。標準のメモリ解説は ./CLAUDE.local.md を個人用の置き場にしており、.gitignore への追加を勧めています。
#キーのショートカット
SKILL.mdは「# を押すとClaudeが学びをCLAUDE.mdに取り込む」と案内します。標準のメモリ解説にこの操作の説明はありません。
.claude.local.md を採用する提案が出たら、読み込まれるファイル名かどうかを確かめてください。標準ドキュメントが読み込み対象として挙げているのは CLAUDE.local.md です。/context を開き、Memory filesの一覧に出るかどうかで判定できます。
標準機能との使い分け
CLAUDE.mdの点検や更新は、プラグインなしでもある程度できます。
| やりたいこと | 標準の手段 | プラグインとの違い |
|---|---|---|
| 初版を作る | 標準の手段/init | プラグインとの違いプラグインは作成より点検と追記が中心 |
| 古い参照や矛盾を見つける | 標準の手段/doctor prompt-audit(v2.1.283以降) | プラグインとの違い対象はCLAUDE.mdに加え、rules・skills・commandsなど |
| 導出可能な内容を削る | 標準の手段/doctor(v2.1.206以降) | プラグインとの違い削減側。プラグインは追記側に寄る |
| 学びを自動で残す | 標準の手段自動メモリ | プラグインとの違いClaude自身がMEMORY.mdに書く |
| 学びを人が選んで残す | 標準の手段/revise-claude-md | プラグインとの違い承認した行だけCLAUDE.mdに入る |
自動メモリは MEMORY.md の先頭200行または25KBまでを毎回読み込み、CLAUDE.mdとは別の領域です。保存先やオフ設定は自動メモリの保存先変更とオフ設定で扱っています。
プラグインの強みは採点という形で「どこが弱いか」が見える点と、学びを追記に変える入口があることです。標準の /doctor prompt-audit は点数を出さず、指摘と修正案を返します。役割は重なる部分もあるため、どちらを先に回すかは好みで決められます。
何を残して何を残さないか
参照資料の更新ガイドラインは、追加する価値のあるものを5種類に分けています。コマンドとワークフロー、落とし穴、モジュール間の依存、効いたテスト方法、設定の癖です。避けるのは、クラス名から自明な説明、一般論、一度きりの修正、長い解説です。
標準ドキュメントの立場も近く、CLAUDE.mdは200行未満を目安に、複数手順の手続きや一部のコードにしか効かない内容はスキルやパス指定のルールへ移す方針です。プラグインが「足す」側に寄るぶん、続けるほど肥大します。足した後にCLAUDE.mdをSkillsに移行してコストを減らす方法で見直す運用が合います。
良い追記の形は、次のような1行です。
## Gotchas
- テストは `--runInBand` で実行する(共有DBの状態に依存するため)
- `NEXT_PUBLIC_*` はビルド時に設定する。実行時では反映されないどちらもコードを読んでも分からない事実で、再発もしやすい内容です。逆に「UserServiceはユーザー操作を担当する」は名前から分かるので、追記案に出てきたら却下して構いません。
運用のコツ
- 点検は月次か、依存や構成を大きく変えた後に回す。毎セッションは多すぎる
/revise-claude-mdは作業が一区切りしたタイミングで1回だけ使い、出た案から本当に再発しそうな行だけ残す- スキルは「承認してから書く」前提なので、報告を読んで不要な提案は断る。採点が高くても行数が増えるなら見送る
- 点検後は
/contextで、読み込まれるファイルと合計の大きさを確かめる
初版づくりは /init が担当し、その挙動はClaude Code initコマンドの挙動にあります。プラグインはその後、育てる局面で効きます。
まとめ
claude-md-managementは新しい仕組みではなく、点検と追記の手順をパッケージにしたものです。点数付きの棚卸しが欲しいなら claude-md-improver、セッションの終わりに学びを拾いたいなら /revise-claude-md が向きます。ファイル名の食い違いに注意し、追記は1概念1行に絞る。この2点を押さえれば、CLAUDE.mdを肥大させずに最新へ保てます。