こんにちは、白々さじきです。
今回は CLAUDE.md の最適化について書きます。
プロジェクトを進める中で CLAUDE.md にいろいろ書き足していくと、気づいたら膨大なファイルになっていました。「CLAUDE.md は短いほうがコンテキストを圧迫しなくて良い」というアドバイスを受けて自分のを確認したら 358行ありました。しかも中身を見ると、指示書と設計書がほぼ半々で混在していました。
そこで設計書部分を別ファイルに切り出し、CLAUDE.md を 145行まで削ぎ落とした話をします。
CLAUDE.md に何が入っていたか
自分の CLAUDE.md を眺めてみると、2種類のコンテンツが混在していることに気づきました。
指示書パート（Claude Code の行動を変えるもの）
- 命名規則（ファイル名・コンポーネント・DB カラムの記法）
- 実装ルール（localhost 禁止、Workers 制約、DB アクセス方針）
- 発注方針（大きな変更は計画を先に提示すること、など）
- ブログ記事の成果物ルール（ファイルセット・フォルダ命名）
- DB 操作のルール
設計書パート（プロジェクトの背景・仕様）
- プロジェクト概要・検証の目的
- 技術スタック（React + Vite + Hono + Cloudflare Workers + D1）
- ディレクトリ構成
- 機能スコープ（実装済みの機能一覧）
- データモデル（テーブル定義）
- セキュリティ前提
- 検証の成否指標
2種類がほぼ半々で入っていました。行数でいうと、指示書パート約180行・設計書パート約178行。
分離の判断軸：「Claude Code が毎回読む必要があるか」
CLAUDE.md は Claude Code が会話のたびに自動で読む特別なファイルです。
「Claude Code がこの情報を毎回読む必要があるか？」と問い直してみると、設計書パートの答えは「No」でした。
- 技術スタックや機能スコープは、コードや README を見れば分かる
- データモデルは
schema.tsが正 - ディレクトリ構成はファイルシステムを見れば分かる
一方、指示書パートは「Yes」です。
- 命名規則を知らないと間違ったファイル名で実装する
- 実装ルールを知らないと localhost を書いたり Node.js API を使ったりする
- 発注方針を知らないと事前相談なしにライブラリを追加する
この区別が分離の判断軸になりました。「Claude Code の行動を変えるもの」だけを CLAUDE.md に残す。
分離後の構成
| ファイル | 行数 | 役割 |
|---|---|---|
CLAUDE.md |
145行 | 指示書のみ |
docs/DESIGN.md |
220行 | 設計・仕様の記録 |
CLAUDE.md の冒頭には1行だけ参照を追加しました。
> 設計・仕様・機能スコープ・データモデルの詳細は `docs/DESIGN.md` を参照すること。これで Claude Code が必要なときに「docs/DESIGN.md を読んで」と明示的に指示できます。
ブログルールは CLAUDE.md に残した
分離作業の途中で「ブログ記事の成果物ルールも別ファイルに移してもいいか？」と自問しました。
答えは No です。
ブログ記事ルールは「記事を作るときに Claude Code がどう動くか」を定義しています。Claude Code の行動を変えるルールである以上、CLAUDE.md に置く必要があります。
別ファイルに移してしまうと、Claude Code が自動ではそのファイルを読みません。毎回「読んで」と指示する手間が増えるだけで、メリットがありません。
CLAUDE.md に書く基準は「Claude Code の行動を変えるか」であって、「内容の種類」ではない。
docs/DESIGN.md の正しい理解
分離後に「docs/DESIGN.md って Claude Code にとって何のファイル？」と改めて整理しました。
docs/DESIGN.md は 人間が読む仕様書 です。
- Claude Code は自動では読まない
- 必要なときに「
docs/DESIGN.mdを読んで」と明示的に渡す - CLAUDE.md に書いていないことをここに書いても、Claude Code には届かない
つまり「CLAUDE.md に書けないほど量が多い設計情報を、人間が参照するために置いておくファイル」というポジションです。
新しい会話でプロジェクトの背景を共有したいときや、振り返り材料として使うのが主な用途になります。
docs/DESIGN.md のメンテナンスはどうするか
分離したはいいものの、時間が経つと docs/DESIGN.md とコードが乖離してきます。どうメンテナンスするかを考えました。
案1: 初期設計の記録として固定する
作成時点で書き切り、以後は更新しない。変化した部分はコードが正とする。
メリット：メンテコストゼロ。「最初にどう設計したか」の記録として価値が残る。
デメリット：ディレクトリ構成やデータモデルがコードと乖離する。
案2: マイルストーン毎に手動更新する
実装完了のタイミングで見直して更新する。
メリット：常に最新の仕様書になる。
デメリット：忘れやすい。コードとの二重管理が発生する。
案3: Claude Code に更新を提案させる
CLAUDE.md にルールを追加し、実装完了時に更新候補を提案させる。
メリット：自動化できる。
デメリット：提案がノイズになることがある。「本ファイルの変更は人間のみ」というポリシーと相性が悪い。
今回のような2週間の検証プロジェクトには案1が最適だと判断しました。揮発しやすいセクションには一言添えておくと混乱を防げます。
## データモデル（初期設計。最新は `src/server/db/schema.ts` を参照）検証終了後に一度だけ見直して、「実際どうなったか」を書き足す程度が現実的です。コスパを考えると、それが案1の範囲内でできる最大限だと思います。
まとめ
CLAUDE.md= Claude Code の行動を変えるルール集docs/DESIGN.md= 人間が読む背景ドキュメント（Claude Code は自動では読まない）
この2つの役割を明確にしておくと、CLAUDE.md に何を書くべきかの判断がシンプルになります。
教訓：CLAUDE.md に入れるのは「Claude Code の行動を変えるもの」だけ。設計背景は別ファイルに切り出してコンテキストを節約しよう。
サポートのお願い
下記リンクからお買い物いただけると、ブログ運営のための費用が増え、有料サービスを利用した記事作成が可能になります。ご協力よろしくお願いします！
コメント