この記事を読むとわかること
- Claude Code の
prompt-auditが何をチェックしてくれるのか（対象ファイル・観点・出てくる成果物） - 個人開発中の Godot 製ゲーム「SLOTS QUEST」の CLAUDE.md に実際にかけてみた結果と、指摘された 3 件
- 「昔のモデル向けに書いた指示」が今のモデルでは逆効果になる、という考え方と、その直し方
- CLAUDE.md を書くときに残すべきもの・消していいものの見分け方
TL;DR
-
prompt-auditは、CLAUDE.md・スキル・サブエージェント定義などの「古くなった指示」を探して、指摘レポートと修正 diff の提案を出してくれる。ファイルは勝手に書き換えない。 - 一番効いた指摘は 「企画は
docs/GDD.mdを必ず参照すること」の「必ず」。今のモデルは指示に素直なので、タイポ修正でも 53KB の企画書を読みにいく原因になりうる。→「仕様に関わる変更では該当の節を参照する」に弱めた。 - 2 つ目は CLAUDE.md の情報が古くなっていたこと。書いた当時はテストが 1 本だけだったのに、今は約 45 本ある。→「どれを回すかは対応表を見る」に書き換えた。
- 3 つ目は 事故の日付のような経緯の記述。ルールの理由として必要なのは「何が起きるか」で、「いつ起きたか」は要らない。
- 逆に、環境の事実・理由・手順は消さないのが原則。全体としては「短くする」監査ではなく「今のモデルと今のリポジトリに合っているか」を見る監査だった。
背景
SLOTS QUEST は、Godot 4（GDScript）で作っている個人開発のクエスト系スロットゲームです。開発はほぼ Claude Code と一緒に進めていて、リポジトリ直下の CLAUDE.md と、全プロジェクト共通の ~/.claude/CLAUDE.md に作業ルールを書いています。
これらのファイルは書いた時点のモデルや状況を前提にしているので、時間が経つと
- 当時のモデルの癖に合わせて書いた強い言い回しが、今のモデルには効きすぎる
- リポジトリが育って、書いてある事実が古くなる
- 複数のファイルで言っていることが食い違う
といったことが起きます。これをまとめて点検してくれるのが prompt-audit です。
prompt-audit とは
Claude Code に同梱されている claude-api スキルのサブコマンドです。今回は Claude Code のデスクトップアプリから /checkup prompt-audit で起動しました。
(/claude-api prompt-audit or /doctor prompt-audit でも同じものが起動するようです）
何を見るか
対象にしたのは、Claude Code のセッションに読み込まれる設定だけです。
- プロジェクトの
CLAUDE.md（親ディレクトリやサブディレクトリにあるもの、CLAUDE.local.md、AGENTS.mdも含む） ~/.claude/CLAUDE.md-
.claude/と~/.claude/の下の rules / skills / commands / agents / output-styles - インストール済みプラグインのスキルなど（報告だけで、修正は提案しない）
settings 系のファイル、.mcp.json、~/.claude.json は、プロンプトではなく秘密情報が入りうるので読まない、という線引きもされていました。
観点は大きく 4 グループ
| グループ | 中身 | 例 |
|---|---|---|
| 1. 古いプロンプト文言 | 昔のモデル向けの強調や手順書き |
CRITICAL: MUST ... の多用、「step by step で考えて」 |
| 2. 設定ファイルの劣化 | 事実が古い、ファイル同士の矛盾、経緯の書きすぎ | 存在しないパス、2 つのファイルで逆のことを言っている |
| 3. ツール定義 | 説明が足りない／誘導しすぎ | API アプリ向け |
| 4. リクエスト設定 | API パラメータの化石など | API アプリ向け |
SLOTS QUEST は Claude API を呼ぶコードを持たないので、グループ 3・4 は「対象外」と判定されました。
出てくるもの
-
指摘レポート:
ファイル:行、該当テキスト、どのパターンか、なぜ古いか、確度（High / Medium / Low）、対応（remove / rewrite / flag など） - 提案 diff: 指摘ごとに 1 hunk。取り込むかどうかは人が決める
確度が Low のものは「flag（報告だけ）」になり、diff には入りません。監査の方針として「何も見つからなければ何も変えない」が明記されているのも好印象でした。
結果
指摘 1: 「必ず参照すること」の「必ず」（Medium）
-企画は `docs/GDD.md` を必ず参照すること。
+ゲームの仕様や企画に関わる変更では `docs/GDD.md` の該当する節を参照する。
条件のない「必ず」は、今のモデルだと文字どおりに効きます。GDD は 53KB あるので、関係ないタスクでも毎回これを読みにいくと、時間もトークンもかかります。
ここで面白かったのは、昔は強く書かないと読んでくれなかった指示が、今は強く書くと読みすぎるという逆転です。強調するなら「どのときに」を添える、が今のモデル向けの書き方でした。
指摘 2: テストコマンドが 1 本だけ（Medium）
-# マップ生成ロジックのテスト
+# テスト（tests/test_*.gd を1本ずつ実行。どれを回すかは docs/tuning.md の対応表に従う）
godot --headless --path . -s tests/test_map_generator.gd
git blame で見ると、この行を書いたのはプロジェクト初期で、当時はテストがマップ生成の 1 本だけでした。今は tests/test_*.gd が約 45 本あり、どのパラメータを触ったらどのテストを回すかは docs/tuning.md にまとめてあります。
書いてあること自体は間違っていないのに、「テスト＝この 1 本」と読まれてしまう。嘘ではないが古い、という一番気づきにくいタイプの劣化でした。
指摘 3: 事故の日付（Medium、全プロジェクトに影響）
共通設定の ~/.claude/CLAUDE.md に、こんなルールを書いていました。
共有の作業ツリーで
git stashを使わない。（中略）git stash -uした stash をdropすると、未追跡ファイルはgit fsck --unreachableからしか復旧できなくなる（20XX-XX-XX に実際に消失事故を起こした）。
指摘は、括弧内の「いつ事故を起こしたか」は経緯の記述なので要らない、というもの。禁止の理由は「復旧が非常に難しくなる」で十分に伝わります。禁止ルールそのものは残して、経緯だけ削る提案になっていました。
ちなみに、このルール自体は同じリポジトリで複数の Claude セッションを並行で走らせる人にはかなりおすすめです。stash は他のセッションの作業中のファイルまで巻き込みます。
報告だけ（Low / flag）
- 「複数ステップの作業では最初にタスクリストを作る」: 今のモデルは言われなくても計画を立てるが、この行は「人が追えるようにする」のが目的で、理由も書いてあるので残してよい、という判定
- プラグインのスキル本文に
MUST/NEVERなどが高密度で入っているもの: 自分では直せないので報告だけ
「問題なし」と判断されたもの
ここが一番参考になりました。
-
ファイル同士の食い違いに見えて、実は上書き: 共通設定では PR 本文に
Closes #123と書くルールで、プロジェクト側ではCloses <owner>/<別リポジトリ>#123と書くルール。一見矛盾ですが、プロジェクト側に「Issue は別リポジトリで管理しているので#123では閉じない」と理由が書いてあるので、正当な上書きとして扱われました。 - 内容が同じ重複は残す: プラグインのスキルと CLAUDE.md の両方に Godot のヘッドレステスト手順が書いてありましたが、内容が一致しているので「動いている重複」としてそのまま。
- CLAUDE.md に出てくるパスやツール名は、実在するかどうかまで確認されていました。
学び: 消していいもの・残すもの
監査の基準を自分なりにまとめると、こうなります。
残すもの（モデルが自分では知り得ないこと）
- 環境の事実（例: 「このPCは Win と Ctrl が入れ替わっている」）
- ルールの理由（「なぜダメか」）
- 手順が 1 つしか安全でない操作の、具体的なコマンド
見直すもの
- 条件のない「必ず」「絶対」（→ どのときに、を添える）
- 書いた当時は正しかったが、リポジトリが育って古くなった事実
- 事故の日付や PR 番号のような経緯（→ ルールと理由だけ残す）
- 今のモデルなら言われなくてもやること
「短くするための監査」ではなく、今のモデルと今のリポジトリに合っているかを見る監査、というのが一番の気づきでした。
まとめ
- CLAUDE.md は書きっぱなしにすると、モデルの世代交代とリポジトリの成長の両方で古くなる
-
prompt-auditは、その劣化を「なぜ古いか」付きで指摘し、diff まで提案してくれる - モデルが新しくなったタイミングで定期的にかけるのがよさそう