CLAUDE.mdをモデル進化に追従させる：放置を防ぐメンテナンスの考え方
はじめに
突然ですが、あなたのプロジェクトの CLAUDE.md、最後に手を入れたのはいつでしょうか。
Claude Code を本格的に使い始めるとき、多くの人がまず取り組むのが CLAUDE.md（やグローバルの ~/.claude/CLAUDE.md）の整備です。コーディング規約、ディレクトリ構成、使ってほしいコマンド、避けてほしい挙動——Claude に「最初に読んでもらう前提」として、それなりに気合を入れて書いた方も多いはず。
ただ、その後一度も触っていないという方は、想像以上に多いのではないでしょうか。私自身もそうでした。今日はその話をします。
なお本記事は、CLAUDE.md のメンテナンス・改善に焦点を当てています。「そもそも初版をどう書くか」については別記事で扱っているので、まだ何も書いていない方は先に Claude Codeの/insightsコマンドで、自分の使い方のクセを知る を読んでから戻ってきてもらうとスムーズです。
この記事で読み取れるのは、おおむね次の3点です。
- (1) なぜ
CLAUDE.mdのメンテナンスが必要になるのか、その理由の体系的な整理 - (2) モデルの世代交代にどう追従させるかという考え方
- (3) ルールをファイル分割してコンテキスト効率を上げる実装例（このブログでの構成）
想定している読者は、初期の CLAUDE.md は書いたものの、その後ずっと放置している開発者です。まさに少し前までの自分に向けて書いています。
これは技術解説ではなく、注意喚起の意味を込めた話です。「Claudeを使いこなしている人ほど、ここを意識的にメンテナンスしている」と感じることが増えてきたので、自分への戒めも込めて書いています。
CLAUDE.mdは「Claudeとの対話の前段」
要点だけ押さえておくと、CLAUDE.md は Claude Code がセッション開始時に自動で読み込む前提知識の注入ファイルです。あなたが何かを依頼するより前に、Claude は既にこのファイル（プロジェクト構成・規約・使ってほしいコマンド・避けてほしい挙動など）を読んだ状態で会話を始めます。自動読み込みの仕組みや書式の詳細は公式ドキュメントに譲ります。
ここで押さえたいのは、この前提知識が会話の品質を左右するという点だけです。
そして、ここに書くべき内容はそれなりにボリュームがあります。プロジェクトが複雑になるほど書くべきことは増えますし、社内ルール・セキュリティルール・Git運用ルールなども入れると、すぐに数百行になります。
「全部自分で書くのは大変では？」と思うかもしれませんが、ありがたいことに以下のような選択肢があります。
- Claude自身に書かせる — プロジェクトを読み込ませて「CLAUDE.mdの初版を作って」と頼むだけで、それなりに使えるものができます
- OSSテンプレート/まとめリポジトリを参考にする — GitHub上には、
CLAUDE.mdのテンプレートや、Claude Code のベストプラクティスを体系的にまとめたリポジトリが多数公開されています。私は shanraisshan/claude-code-best-practice を参考にしながら、Claude自身に構成提案をさせています。Memory（CLAUDE.md）・Subagents・Commands・Skills・Hooks など、領域ごとにベストプラクティスとリンク集が整理されており、最新の Claude Code 機能にも追従しているのが便利です - /insights のようなコマンドの提案を取り込む — Claude Code には自分の使い方を分析して
CLAUDE.md改善提案を出してくれる機能があります（後述）
つまり、ゼロから書き起こす負担は年々下がっています。問題はその後です。
多くの人が陥る「作って満足」状態
ここからが本題です。
CLAUDE.md を最初にしっかり整備すると、Claude の挙動は目に見えて変わります。指示が通りやすくなり、無駄な質問が減り、規約に沿ったコードが出てくるようになる。これは確かに大きな効果です。
そのため、ここで満足してしまう人が少なくありません。私もそうでした。
しかし、現実には Claude も Claude Code も日々アップデートされ続けています。新しいモデルがリリースされ、機能が追加され、内部の挙動も変わっていく。たとえば最近だと Opus 4.6 から Opus 4.7 への切り替えで、明らかにモデルの賢さや得意分野が変動しました。
ここで重要なのは、モデルが変わると「効く書き方」も変わる、という事実です。
- 賢くなった部分については、冗長な説明を削れる → コンテキストを節約できる
- 苦手になった部分や挙動が変わった部分については、新たに明示が必要になる
- 古い書き方（旧モデル向けのワークアラウンド）が、もはや不要になっていることもある
つまり、CLAUDE.md は書いた時点のモデルに最適化されているもので、モデルが進化したら追従しないと、最適とは言えなくなっていきます。これは少し前まで自分も意識していませんでしたが、改めて考えると当たり前の話です。
「Claudeがバカになった」問題の正体
X（旧Twitter）などで定期的に話題になるのが、「Claudeが急にバカになった」という声です。
実際にモデル側の調整や混雑による品質低下が起きるケースもあるとは思いますが、それを差し引いても、こちら側の CLAUDE.md がモデルに合っていないことが原因の場合は無視できないくらい多いと感じています。
たとえば、以下のような状況です。
- 旧モデルが苦手だったから書いていた「念のための注意書き」が、新モデルでは過剰になり、かえって判断を縛っている
- 量が増えすぎた
CLAUDE.mdがコンテキストを圧迫し、本来読んでほしい部分の優先度が下がっている - プロジェクト構造が変わったのに
CLAUDE.md内のディレクトリ説明が古いまま、Claude が誤った前提で動いている
こうした状態だと、新しいモデルがどれだけ賢くなっても、その賢さを引き出せません。むしろ、バカになったように見えるだけで、実はこちらの設定が古いままということが起きます。
逆に言えば、ここを見直すだけで体感品質が大きく回復することが多いです。「バカになる前」より良くなることすら珍しくありません。
このブログでの実体験：Claude自身に最適化を任せた話
ここまで偉そうに書いてきましたが、私自身もずっと放置していました。
このブログを作るときに最初に書いた CLAUDE.md、その後たまに小さな追記はしていたものの、構造そのものを見直したことはありませんでした。「動いているからいいか」というやつです。
先日、ふと思い立って Claude自身に CLAUDE.md の最適化を依頼してみました。やったことは単純で、現状の CLAUDE.md を提示し、参考リポジトリ（後述の shanraisshan/claude-code-best-practice）の構成も合わせて見せながら「Opus 4.7 時代のベストプラクティスに沿って、コンテキスト消費を抑えつつ意図が伝わる形にリファクタしてほしい」と頼んだだけです。
結果として返ってきた提案は、想定以上に有用でした。代表的なものを挙げると以下のような感じです。
1. mdファイルの遅延読み込み（lazyload）構造への分割
すべてのルールを CLAUDE.md 本体に書き込むのではなく、領域ごとに別ファイルに切り出し、必要なときだけ参照させる構造にする提案がありました。
たとえば「デプロイ手順」「コーディング規約」「記事品質基準」のようなトピックごとに別ファイルに分け、CLAUDE.md 本体からは概要とリンクだけを示しておく。Claude が必要と判断したときだけ詳細ファイルを読みに行くため、毎回の初期コンテキスト消費が抑えられる、というアイデアです。
実際このブログでも .claude/rules/ 配下にトピックごとのルールを分離し、CLAUDE.md 本体は概要とリンクだけを持つ最小構成に変えました。現在の構成はこうなっています。
my-learning-blog/
├── CLAUDE.md # 本体：プロジェクト概要・規約の要点・各ルールへの参照
└── .claude/
└── rules/
├── deploy.md # Cloudflare Pages デプロイ時の注意事項
├── coding-standards.md # 静的エクスポート制約・TSX規約など
├── article-checklist.md # 記事追加時のチェックリスト
└── article-quality.md # 記事の品質基準（AdSense対策）
ポイントは、この4ファイルが常に全部読み込まれるわけではないという点です。デプロイ作業をしているときに article-quality.md の品質基準は不要ですし、記事を書いているときに deploy.md のデプロイ手順は不要です。本体に概要とファイル名だけを書いておけば、Claude は「今このタスクではどのルールを読むべきか」を判断し、必要なものだけを参照できます。
仮にこれらを1つの巨大な CLAUDE.md に全部書き込んでいた場合、デプロイ作業中でも記事品質基準が、記事執筆中でもデプロイ手順が、毎セッションの初期コンテキストに乗り続けることになります。トピックごとに切り出しておくことで、そのタスクに関係する知識だけを必要なときに読み込ませる設計にできる——これが分割の理屈です。
2. 同じ内容の重複削除
複数箇所で似たことを言っていた部分を集約。指示の一貫性が増し、行数も減りました。
3. 古い記述の整理
過去のモデル向けに書いていた回りくどい注意書きや、今や Claude Code 側で標準対応されている内容を削除。
4. 優先度の明示
「これは絶対」「これは推奨」を分かりやすく書き分け、Claude が判断に迷ったときの基準を明確化。
すべて自分でやろうとすると地味に大変な作業ですが、現状の CLAUDE.md を渡して「最適化して」と頼むだけで、ここまでやってくれるのは素直にありがたかったです。もちろんレビューは必要ですが、たたき台としては十分使えます。
コンテキストを抑えることは「パンクまでの余裕」を増やすこと
ここで強調しておきたいのが、コンテキスト消費を抑えることの意味です。
Claude Code を長時間使っていると、いずれコンテキストウィンドウが圧迫されてきて、応答精度が落ちたり、過去のやり取りを忘れ始めたりします。いわゆる「Claudeがバカになる」状態の一つの正体が、これです。
CLAUDE.md を含む初期読み込みコンテキストが軽ければ、そこに到達するまでの余裕が増えます。同じ作業を依頼しても、コンテキストが余っているほど Claude は丁寧に考えられる、ということです。
CLAUDE.md の最適化は、見た目には地味な作業です。コードが速くなるわけでも、機能が増えるわけでもない。でも、Claude を使った開発体験全体の「持久力」が変わるという意味で、効果は意外に大きいと感じています。
どうやってメンテナンス時期を判断するか
「じゃあ、どのタイミングで見直せばいいの？」という疑問への自分なりの答えはこうです。
- モデルがメジャーアップデートしたとき（例：Opus 4.6 → 4.7）
- Claude Code 自体が大きく更新されたとき（新コマンド・新機能の追加時）
- プロジェクトの構造を変えたとき（ディレクトリ移動、技術スタック切り替えなど）
- 「最近Claudeがいまいち」と感じたとき — モデル側のせいにする前にまず疑う
- 定期的に（自分の場合は、目安として2〜3ヶ月に1回は触る）
最後の「定期的に」は地味ですが大事です。Webサーバーや CI も、放置すれば必ず劣化します。Claude Code というシステムも、CLAUDE.md という設定ファイルを抱えている以上、メンテナンス対象であることを意識したいところです。
関連トピック：/insights と参考リポジトリ
実は Claude Code には、自分のセッション履歴を分析して CLAUDE.md の改善提案を出してくれる機能があります。これを組み合わせると、最適化のたたき台がさらに作りやすくなります。
詳しくは以下の記事にまとめています。
「自分のCLAUDE.mdに何が足りないかわからない」という方は、まず /insights を実行して、現状の癖を可視化するところから始めるのがおすすめです。
加えて、Claude Code のベストプラクティスを体系的に追いたい方には、こちらのリポジトリを参考リソースとしておすすめします。
- shanraisshan/claude-code-best-practice — Memory（
CLAUDE.md）、Subagents、Commands、Skills、Hooks、MCP、Settings など、Claude Code の構成要素ごとにベストプラクティスと実装例がまとまっており、最新の機能アップデートにも追従しています。私はこのリポジトリの構成を Claude に見せて「これを参考に、うちのCLAUDE.mdをベストプラクティス寄りに整えて」と頼む使い方をしています
まとめ
CLAUDE.mdは Claude との対話の前段にあたる重要なファイル- 最初にしっかり書くことは大事だが、そこで満足してしまう人が多い
- モデル（Opus 4.6 → 4.7 など）やプロジェクトが進化すれば、最適な書き方も変わる
- 「Claudeがバカになった」と感じたら、まず自分の
CLAUDE.mdを疑う - Claude自身に最適化を依頼するのは有効。私のケースでは lazyload 構造化やコンテキスト削減の提案が得られた
- コンテキストを軽くしておくことは、パンクするまでの余裕を増やすこと
- どんなシステムも投げっぱなしでは劣化する。Claude も例外ではない
派手な機能追加や新ツールに目が行きがちですが、足元の CLAUDE.md のメンテナンスは地味ながら見返りが大きい作業です。久しく触っていない方は、この機会に一度、Claude自身に「最適化して」と頼んでみてはいかがでしょうか。