CLAUDE.mdは書いた瞬間から劣化する｜「計測OK ✅」の一行が翌日の判断を狂わせた

Claude Codeは、プロジェクトのフォルダに CLAUDE.md を置いておくと毎回それを読んでから作業します。「毎回同じ説明をしなくて済む」ので、真っ先に整えたくなるところです。

ただ、運用してみて分かった一番の問題は「書き方」ではありませんでした。書いた内容が古くなることです。毎回読まれるということは、間違った一行が毎回そのまま次のセッションに引き継がれるということでした。

この記事は運営者が実際に運用して得たものです。仕様は変わるため、細かい挙動は公式のドキュメントで確認してください。

結論：CLAUDE.mdの最大のリスクは「肥大化」ではなく「嘘の固定化」

📌 先に結論 CLAUDE.md は毎回ロードされる。だから古い一行は「たまに誤解される」のではなく、毎回必ず前提として採用されます。定期的に実態と突き合わせないと、AIは壊れた前提の上で改善判断を始めます。

実際に混入していた嘘

このサイトのCLAUDE.mdを実態と突き合わせたときに見つかったものを、正直に並べます。

書いてあったこと	実際	何が起きるか
本番URLが旧アドレスのまま	独自ドメインへ移行済み	古いURLを前提に確認作業をする
「記事20本」	実際は30本	進捗の判断を誤る
スクリプトが「未実装」	すでに実装済み	同じものをもう一度作らせる
「計測OK ✅」	イベントが届いていないと認識していた時期があった	壊れたデータを前提に改善方針を決める

上3つは手戻りで済みます。危険なのは4行目です。

「計測OK」と書いてあれば、次のセッションのAIは数値を疑いません。届いていないデータを見て「このCTAは効いていないので差し替えましょう」と提案してきます。そしてその提案は、書いてある前提の上では完全に筋が通っています。

⚠ いちばん怖い壊れ方 間違った指示は「守られない」だけですが、間違った前提は「正しく守られてしまう」。だから気づくのが遅れます。

ちなみに、この「計測OK」の裏側にあった誤診（Googleタグの503を見て「サイト側の障害」と断定した件）の顛末はClaude Codeとは何かに書きました。AIの断定を一度そのまま指示ファイルに書き込むと、それが次の何日かの前提になります。

対策：突き合わせを「作業」として置く

気合いでは維持できないので、時々まとめて機械的に確認しています。

実際にやって効いたのは参照リンクの到達確認です。CLAUDE.mdから他のドキュメントへ張ったリンクを全部たどってみたところ、破損が2件見つかりました。 ファイルを整理したときに参照だけが取り残されていたものです。

突き合わせるのは、だいたいこの4種類です。

項目	確認方法
URL・ドメイン	実際に開く
件数・本数	ファイル数を数える
「未実装」「未対応」の記述	そのファイルが存在するか見る
参照リンク（`@docs/...` 等）	全部たどって存在を確認する

「◯◯は完了している」と書いてある行が、いちばん危ないと考えてください。完了は変化しないと思い込まれるので、誰も再確認しません。

短く保つ：長い指示ファイルは無視される

もう一つの原則がこれです。書けば書くほど守られる、ということはありません。

Claude Code のベストプラクティスとして紹介されている目安では、CLAUDE.md は60行程度が最適、多くても300行までとされています。それを超えると全体が無視されやすくなる、という考え方です。

運営者の実感も同じで、守られない指示が続いたら、それは書き方の問題ではなく量が多すぎるサインでした。追記して強調するより、周りの行を消して相対的に目立たせるほうが効きます。

判断基準は一行だけです。

「この行を消したら、AIはミスをするか？」

答えが No なら消します。「あったほうが親切」「念のため」で残した行が、本当に効かせたい行の効力を削ります。

消していい行	理由
プロジェクトの一般的な説明	READMEを読ませればいい
ディレクトリ構成の一覧	見れば分かる。しかもすぐ古くなる
過去にやった修正の履歴	変更履歴で追える
コードの整形ルール	整形ツール・Lint・フックの仕事
「丁寧に書いてください」等の心構え	判定できないので効かない

2行目と3行目は、そのまま「劣化する行」でもあります。構成の写しは、構成を変えた瞬間に嘘になります。

良い例と悪い例

悪い例：判定できない

- コードは読みやすく書くこと
- パフォーマンスに配慮する
- 適切にテストを書く

「読みやすい」「適切」の基準が無いので、AIは自分の解釈で進みます。書いていないのとほぼ同じです。

良い例：行動が一意に決まる

- 変更後は必ず `npm run build` を通してから完了とする
- 日本語ファイルの編集は Edit/Write で行う（PowerShellのパイプ経由は文字化けする）
- 「コミットした」と報告する前に `git log` で実体を確認する

2行目と3行目は、実際に事故ってから追加した行です。過去に一度やらかしたことだけを書くと、自然と「消したらミスする行」しか残りません。

もう一組。

悪い例：ファイルを見れば分かること

このプロジェクトは Next.js 製のブログサイトです。
site/ 配下に記事が入っており、public/images に画像があります。
記事は MDX 形式で、frontmatter に title, description, slug ... があります。

良い例：見ても分からないこと

- 記事の date は「公開予定日」であって作成日ではない
- status: drafting のまま本番デプロイしない
- 画像が無い記事はプレースホルダーが出るので、配線待ちで問題ない

コードやファイルからは導けない約束事——ここにこそ書く価値があります。

「知見の置き場所」を別に作ってはいけない

途中で、学んだことをObsidian（メモアプリ）に貯めようと考えて調べました。結論から言うとやめました。

理由は2つあります。

理由1：Claudeが読まない場所に置いても、次のセッションで効かない

当たり前のようで見落としがちですが、自動的に読み込まれるのは ~/.claude/ 配下だけです。別の場所に立派なvault（メモの保管庫）を作って知見を貯めても、次のセッションのAIはそこを開きません。読まれない知見は、存在しないのと同じです。

理由2：そもそも、すでにvaultだった

調べてみると、Claudeのメモリ用フォルダはObsidianのvaultとして必要な条件をすでに全部満たしていました。

Markdown形式
YAML frontmatter つき
[[wikilink]] 形式の相互リンクが9本
MEMORY.md という索引ファイル

つまり新しく作る必要が無く、既存のフォルダをObsidianで開けばそのまま読めたわけです。

採用した折衷案はこうなりました。

📌 結論：保存先は増やさない。閲覧レイヤーとして被せる Claudeのメモリフォルダを Obsidian の vault として開き、読む専用で使う。書き込みは従来どおりClaudeが行う。

もう一つの理由は運用面です。運営者はすでにNotionを情報ハブにしています。Notion・Obsidian・CLAUDE.mdの3箇所に散らすと、どれが最新か分からなくなって管理が破綻します。 場所を増やすより、既にAIが読む場所に置くほうが確実でした。

その後、置き場所を増やす代わりに役割で4層に分ける形に整理しました。自動メモリ／このファイル／セッション記録／設定とフックの4つで、「毎回自動でやる」を保証できるのは4番目だけです。分け方と、メモリが全プロジェクト同居になっていた話はAIにAIを引き継ぐブリーフとメモリ設計に書きました。

「止める操作」は文章ではなく設定で止める

CLAUDE.md に「勝手にデプロイしないでください」と書くこともできますが、お願いは守られたり守られなかったりします。 戻せない操作は設定で拒否するほうが確実です。

考え方はひとつだけです。

読み取り・検査・テストは無制限に許可して摩擦をゼロにし、戻せないものだけ止める。

実際に使っている形がこれです。

allow:
  Read, Glob, Grep,
  Bash(git status), Bash(git log:*), Bash(git diff:*),
  Bash(ls:*), Bash(pytest:*)

deny:
  Bash(git push:*),
  Bash(rm -rf:*),
  Bash(vercel deploy --prod:*),
  Read(./.env), Read(./.env.*)

ポイントは allow 側を渋らないことです。git status や git diff のたびに確認を求められると、確認そのものが儀式になって中身を読まなくなります。止める回数を減らすほど、止まったときにちゃんと読むようになります。

Read(./.env) を deny に入れているのは、APIキー等がAIの読む範囲に入るのを避けるためです。

何を書くべきか

削っていった結果、残るのはだいたい次の4種類でした。

種類	例
絶対にやってはいけないこと	「本番データベースに接続するコマンドは実行しない」
完了の定義	「検証コマンドが通るまでを1タスクとする。通っていない状態で完了と報告しない」
相談すべき境界	「外部に公開する変更、課金が発生する操作は必ず先に確認を取る」
一度やらかした事故の再発防止	「日本語ファイルはシェルのパイプを通さない」

逆に言うと、この4つに当てはまらない行は、たぶん要りません。

まとめ

CLAUDE.md は設定ファイルではなく、AIが毎回信じる前提です。だから2種類の壊れ方をします。

長すぎて無視される（目安は60行前後・多くても300行）
古くて誤誘導する（こちらのほうが危険。正しく守られてしまうため）

対策は同じ一行です。各行に「消したらミスするか？」を問い、Noなら削る。 そして「完了している」と書いた行こそ、定期的に実物と突き合わせる。

守られない指示が続いたら、増やさず剪定する
知見の置き場所を増やさない。AIが読む場所に置く
戻せない操作は文章ではなく権限設定で止める

指示を具体的に書くという発想自体は、チャット型AIでも同じです → AIへの指示（プロンプト）の書き方

Claude Code自体がどんなツールかはClaude Codeとは何か、並列実行の実測値と検証を嘘にしない型はClaude Codeの実務での使い方にまとめています。