Claude Codeが賢くない原因はCLAUDE.md肥大化──/checkupで直す

「最近、Claude Codeの動きが鈍くなった気がする」「プロジェクトが育つほど、指示を無視されることが増えた」。そう感じているなら、原因はモデルではなく、リポジトリに積み上がったCLAUDE.mdの肥大化かもしれません。

2026年7月8日、Claude Code開発者のBoris Cherny氏が新コマンド/checkupを発表しました。使っていないSkills・MCP・プラグインの整理、CLAUDE.mdの重複排除と分割、遅いHooksの無効化などを、確認つきで提案してくれる、いわばClaude Codeの健康診断です。X上でも「ボトルネックはモデルではなくリポジトリ構成」という指摘が日本語圏でバズり、コンテキスト設計への関心が一気に高まっています。

この記事では、Claude Codeを日常的に使っている現役エンジニアに向けて、CLAUDE.mdが肥大化する典型パターンと、/checkupを起点にコンテキストを4つの階層（CLAUDE.md・rules・Skills・Subagents/Hooks）へ振り分け直す手順を解説します。読み終える頃には、自分のリポジトリのどこを削り、どこへ移すべきかが判断できるようになるはずです。

なぜCLAUDE.mdの肥大化がClaude Codeの精度を下げるのか

まず前提を整理します。CLAUDE.mdは、Claude Codeがセッション開始時に毎回読み込むプロジェクトメモリです。便利なので、運用しているとつい何でも書きたくなります。コーディング規約、デプロイ手順、過去の失敗から学んだルール、レビュー観点、ディレクトリ構成の説明。1つ1つは正しい判断でも、数ヶ月続けるとCLAUDE.mdは数百行に育ちます。

問題は、コンテキストウィンドウが有限の資源だということです。CLAUDE.mdに書いた内容は、タスクに関係あるかどうかに関わらず毎セッション消費されます。今日の作業がフロントエンドの小さな修正でも、データベース移行の手順書やCI設定の注意書きまで全部読み込まれる。本来タスクの理解に使えたはずの容量が、無関係な指示で埋まっていくわけです。しかも指示が増えるほど1つあたりの重みは薄まり、「絶対守ってほしいルール」が数十個の細かい注意書きに埋もれて無視されやすくなります。

2026年7月8日のBoris Cherny氏の/checkup発表は、まさにこの問題への公式の回答でした。投稿は1.1万を超えるいいねを集めています。/checkupが提案してくれる内容は、使っていないSkills・MCP・プラグインを整理してコンテキストを節約する、CLAUDE.mdの重複を排除して分割する、起動を遅くしているHooksを無効化する、といったものです。どれも「書き足す」ではなく「削って移す」方向の整理である点が象徴的です。

日本語圏でも直前の2026年7月7日、「ボトルネックはモデルではなくリポジトリの構成だ」という趣旨の投稿が話題になりました。そこで使われていた整理が示唆的で、指示には「ASKED」（Markdownに書いて守ってくれるようお願いするもの）と「FORCED」（HooksやSettingsで機械的に強制するもの）の2種類があり、CLAUDE.mdに書けるのは前者だけ、という考え方です。お願いはコンテキストが混雑するほど守られなくなる。だから何をどの階層に置くかの設計、いわばContext Ladder（コンテキストの梯子）を意識的に組む必要がある、という話です。

自分のリポジトリが肥大化しているかは、次のサインで判断できます。

  • CLAUDE.mdが300行を超えている
  • ほぼ同じ内容のルールが複数箇所に書かれている
  • ここ1ヶ月呼び出していないSkillsやMCPサーバーが接続されたままになっている
  • セッション開始やツール実行のたびにHooksで待たされる
  • 「CLAUDE.mdに書いてあるのに守られない」と感じる頻度が増えた

2つ以上当てはまるなら、棚卸しのタイミングです。

月$100で使い倒す立場から見た、無駄なコンテキストの実費

僕はClaude CodeにMAXプランの月$100を払っていて、2026年の今も継続課金中です。コスパは非常に良いと感じているし、本当はもっと使いたいくらいなんだけど、この立場になると無駄なコンテキストの見え方が変わってきます。CLAUDE.mdに積もった読まれないルールは、毎セッション使用枠を削り、同時に出力の精度も削る。つまり金額と品質の両方に効いてくる実費なんですよね。

もうひとつ、日々のSaaS開発で実感しているのが、Claude Codeはゴールが明確なほど正しく動くということです。ゴールが曖昧なときは先にClaudeと壁打ちして整理してから実装に入るとうまくいくし、違和感を頑張って言語化するほど出力の精度が上がる。人に説明して伝わらないことはClaudeにも伝わらない。この経験から言えるのは、Claudeに何を読ませるかが出力品質をほぼ決めるということで、肥大化したCLAUDE.mdは「説明が下手なまま大量に喋っている状態」に近いと思っています。

/checkupの実行手順とコンテキスト4階層の整理術

ここからは実践です。/checkupによる自動診断と、4階層への手動振り分けの2本立てで進めます。

/checkupを実行する

/checkupはClaude Codeのセッション内で実行するスラッシュコマンドです。手順は次の3ステップです。

  1. Claude Codeを最新版に更新する（npm install -g @anthropic-ai/claude-code またはインストール時の手段で更新）
  2. 対象リポジトリでClaude Codeを起動し、/checkup と入力する
  3. 提示された提案を1つずつ確認し、採用するものだけ適用する

重要なのは3番目です。/checkupは勝手にファイルを書き換えるのではなく、変更前に確認を挟む提案ベースの設計になっています。診断対象は大きく分けて、使っていないSkills・MCP・プラグインの整理、CLAUDE.mdの重複排除と分割、遅いHooksの無効化です。最初は全部適用しようとせず、「明らかに使っていないMCPの削除」のような低リスクの提案から採用するのがおすすめです。

コンテキストの置き場所は4階層で決める

/checkupが削る場所を教えてくれても、「では今後どこに何を書くか」は自分で設計する必要があります。判断基準は「何を書くか」ではなく「いつ読ませるか」です。Claude Codeには読み込みタイミングの異なる置き場所が4階層あります。

| 階層 | 読み込みタイミング | 向いている内容 | アンチパターン | |---|---|---|---| | CLAUDE.md | 毎セッション必ず | プロジェクトの一言説明、ビルド・テストの基本コマンド、全タスク共通の最重要ルール数個 | 手順書・特定ディレクトリ専用の規約・滅多に使わない情報を書く | | rules（サブディレクトリのCLAUDE.md等） | 該当パスの作業時のみ | ディレクトリ固有のコーディング規約、モジュール別の注意点 | 全体ルールとの重複、他ディレクトリの話を書く | | Skills | 呼び出されたときのみ | 繰り返す定型手順（リリース作業、レポート生成など）の詳細 | 使わないSkillsを溜め込み一覧だけでコンテキストを消費する | | Subagents / Hooks | 独立コンテキストで実行 / イベント時に強制実行 | 大きな調査・検証の委譲（Subagents）、必ず守らせたい機械的チェック（Hooks） | 何でもHooks化して起動やツール実行が遅くなる |

この表で一番効くのは、FORCEDの発想をHooksに寄せることです。「コミット前にlintを必ず通す」「特定ファイルは編集禁止」のような絶対条件をCLAUDE.mdにお願いとして書くのは筋が悪い。Hooksやpermissions設定（.claude/settings.json）で機械的に強制すれば、Markdownから消せてコンテキストも空きます。詳細はAnthropic公式のメモリ管理ドキュメントとClaude Codeベストプラクティスが一次情報です。

手動棚卸しの手順

/checkupの提案を眺めたあと、僕がおすすめしたい棚卸しの順序はこうです。

  1. CLAUDE.mdの行数を数える。300行を超えていたら「毎セッション必要か」を各項目に問い、Noなら移動候補にする
  2. ディレクトリ固有のルールを、該当ディレクトリ配下のCLAUDE.mdやルールファイルに移す
  3. 3回以上繰り返した定型手順をSkillに切り出す。呼ばれるまで詳細が読み込まれないので、本体は説明1行で済む
  4. 「必ず守らせたい」系の記述をHooks・permissionsに置き換え、元の文章をCLAUDE.mdから削除する
  5. 使っていないMCPサーバー・Skills・プラグインを外す。ツール定義だけで毎回コンテキストを消費しているため、削除効果が大きい
  6. 月1回、/checkupを定期実行して再点検する

イメージしやすいように、2番と3番の移動例を挙げます。たとえばCLAUDE.mdにこんな記述が居座っているとします。

## リリース手順
1. release/x.y.z ブランチを作成する
2. CHANGELOG.md を更新してコミットする
3. タグを打って push し、CI の完了を待つ
4. デプロイ後にステージングでヘルスチェックを確認する
（以下、環境変数の注意点などが20行続く）

リリースは週に1回あるかどうかの作業で、毎セッション読ませる必要はまったくありません。これをSkillに切り出せば、CLAUDE.md側は「リリース作業はreleaseスキルの手順に従う」の1行になります。同様に、「src/api/ 配下では必ずエラー型を明示する」のようなパス限定の規約は src/api/ 配下のCLAUDE.mdへ移す。移した分だけルートのCLAUDE.mdは短くなり、残った少数のルールの重みが上がります。

4番のHooks置き換えも一例を挙げると、「コミット前にテストを必ず通す」というお願いは、.claude/settings.json のHooksでコミット操作の前にテストコマンドを走らせる設定に置き換えられます。「マイグレーションファイルは編集禁止」のような絶対条件も、permissionsのdeny設定に書けば仕組みとして強制できる。守られるかどうかがClaudeの調子ではなく設定で決まるようになるので、CLAUDE.mdから該当の文章を消しても不安が残りません。

ポイントは、削った内容を捨てるのではなく階層を下げることです。情報は失わず、読み込みタイミングだけを遅らせる。これがProgressive Disclosure（必要になったときだけ開示する）の考え方で、Skillsの設計思想とも一致しています。

/checkupの限界と注意点

/checkupは便利ですが、銀の弾丸ではありません。現場目線で注意点を挙げておきます。

第一に、自動整理には挙動が変わるリスクがあります。CLAUDE.mdの分割や重複排除の提案を深く確認せず一括適用すると、意図して毎セッション読ませていたルールがパス連動側に移り、「あのルールが効かなくなった」と後から気づくことがあります。提案の採用は1つずつ、適用後は普段のタスクで挙動確認をするのが安全です。

第二に、階層化しすぎの管理コストです。4階層への振り分けは強力ですが、ルールの置き場所が増えるほど「どこに書いたか」を人間側が忘れます。チーム運用ならなおさらで、置き場所の規約そのものを短くCLAUDE.mdに書いておく必要があります。

第三に、ASKEDの限界です。どれだけCLAUDE.mdを痩せさせても、Markdownのお願いが100%守られるようにはなりません。守られないと困るものをHooksへ移す作業をサボると、整理しても同じ不満が残ります。

最後に、切り分けの難しさです。「賢くなくなった」と感じる原因には、モデルやツール側のアップデートに伴う挙動変化も混ざります。新モデル移行期は特にそうで、コンテキスト起因かモデル起因かを見分けるには、CLAUDE.mdを一時的に最小構成へ絞って比較してみるのが手っ取り早い方法です。それでも改善しないなら、原因は別の場所にあります。

まとめ

要点を整理します。

  • Claude Codeの精度低下は、モデルよりCLAUDE.mdの肥大化が主因になっていることが多い
  • 2026年7月8日リリースの/checkupは、未使用Skills・MCPの整理、CLAUDE.mdの重複排除、遅いHooksの無効化を確認つきで提案してくれる健康診断コマンド
  • コンテキストは「何を書くか」でなく「いつ読ませるか」で置き場所を決める。毎セッションのCLAUDE.md、パス連動のrules、呼び出し時のみのSkills、強制実行のHooksの4階層
  • 必ず守らせたいことはMarkdownに書かず、Hooksやpermissionsで機械的に強制する
  • 整理は捨てるのではなく階層を下げる。情報は残し、読み込みタイミングを遅らせる

今日のアクションは3つです。自分のリポジトリのCLAUDE.mdの行数を数える。/checkupを1回走らせてみる。提案の中から1つだけ採用してみる。それだけで、次のセッションのClaude Codeは少し賢く戻ります。

参考リンク