Claude.md は長ければよいわけではない：AI コーディング用のグローバルメモリファイルの書き方

最近、AI コーディング用のグローバルメモリファイルについての議論を見かけました。プロジェクトに Claude.md や AGENTS.md のようなファイルを追加しても、必ずしも結果がよくなるとは限らず、場合によっては成功率が下がり、推論コストも上がるという話です。

一見すると直感に反します。AI にプロジェクト背景、ルール、説明を多く渡せば、より正確にコードを書けるはずだと思いがちです。
しかし本当の問題は、Claude.md が普通のドキュメントではないことにあります。これは毎回の会話でコンテキストに挿入されるグローバルメモリです。内容が多ければ、モデルは毎回それだけ多く読む必要があります。内容が曖昧なら、毎回余計な判断が増えます。本来入れるべきではない手順を書いてしまうと、関係のないタスクでも不要な動作が発火する可能性があります。

つまり、Claude.md を書く難しさは、内容をすべて書き切ることではありません。どの情報が長期的にコンテキストを占有する価値があるかを判断することです。

Claude.md とは何か

AI コーディングツールにおいて、Claude.md や AGENTS.md のようなファイルは、本質的にはグローバルメモリファイルです。

通常の会話もコンテキストに入りますが、コンテキスト長には上限があります。会話が長くなると、履歴は圧縮され、一部の細部は失われます。グローバルメモリファイルの役割は、重要なルールを固定し、モデルが毎回のタスク開始時に参照できるようにすることです。

これは二つの意味を持ちます。

書いた内容は忘れられにくい
書いた内容は毎回のタスクでコストになる

これは必要なときだけ読まれる README とは違います。長期的に有効な作業制約に近いものです。一度入れると、デフォルトで毎回モデルの判断に影響します。

そのため、Claude.md はプロジェクト紹介でも、経験メモでも、すべての開発手順を詰め込む場所でもありません。モデルが知らないと同じミスを繰り返しやすいルールだけを置くべきです。

なぜ逆効果になることがあるのか

グローバルメモリファイルの書き方が悪いと、主に三つの問題が起きます。

一つ目は、コンテキストを消費することです。

Claude.md が一千行ある場合、その一千行は長期的にモデルのコンテキストに入ります。現在のタスクに本当に関係するコード、エラーメッセージ、要求仕様が圧迫されるかもしれません。コンテキストは無料の空間ではありません。グローバルルールが大きいほど、現在のタスクの焦点は薄まりやすくなります。

二つ目は、余計な行動を誘発することです。

たとえば、グローバルファイルに次のように書いたとします。

1
2


毎回タスクを始める前に、プロジェクトディレクトリを完全に読む。
毎回変更後に、完全なエンドツーエンドテストを実行する。

これらは責任ある指示に見えますが、グローバルメモリに置くと「すべてのタスクで実行する」という意味になります。たとえ一行の文言修正であっても、モデルはこのルールに従って不要な探索やテストを行うかもしれません。結果として、作業は遅くなり、コストは上がり、ときには新しい干渉も生まれます。

三つ目は、判断負荷を増やすことです。

「コードをエレガント、簡潔、保守しやすく、拡張しやすく保つ」のような文は正しく聞こえますが、実際の制約としては弱いです。モデルはコードを生成するたびに、何がエレガントで何が拡張しやすいのかを判断しなければなりません。しかし明確な境界は与えられていません。

よりよい書き方は、抽象的な美徳を並べることではなく、具体的な禁止事項や反例を書くことです。たとえば：

1
2
3


単一の呼び出し箇所のために汎用抽象を追加しない。
テストカバレッジなしで共有パース処理を変更しない。
一時スクリプトをアプリケーションのソースディレクトリに置かない。

これらのルールは具体的で、実行しやすいものです。

何を書くべきか

ある内容を Claude.md に書くべきかどうかは、単純な基準で判断できます。

それを書かないと AI が同じ種類のミスを繰り返すなら、書く価値があります。

グローバルメモリファイルに向いている内容には、だいたい次の特徴があります。

長期的に有効である
現在のリポジトリと強く関係している
コード構造から自然には推測できない
モデルの行動を明確に変える
制約、禁止事項、パス規則、固定コマンドであることが望ましい

たとえば：

1
2
3
4


すべての Hugo 記事では index.zh-cn.md だけを編集し、他言語版を自動生成しない。
記事の front matter には title/date/draft/tags/categories/slug/description が必須。
public/ 配下の生成物を変更しない。
PowerShell でデプロイするときは scripts/deploy.ps1 を使う。

これらは曖昧な助言ではありません。リポジトリの実際の作業方法に結びついています。モデルが知らなければ間違える可能性があり、知っていれば実際に誤操作を減らせます。

書くべきではないもの

多くの人は Claude.md をプロジェクト説明書にしてしまいがちですが、通常それは不要です。

あまり向いていない内容は次のようなものです。

プロジェクトのビジョンや背景紹介
長いディレクトリ構成説明
一時的なタスク計画
一回限りのデバッグ手順
抽象的なコード品質スローガン
一部の状況でしか必要ない長いワークフロー

たとえば「これは商品、注文、ユーザーモジュールを含む EC プロジェクトです」という説明は、具体的なコーディングタスクにはあまり役立ちません。実際の開発では、モデルは現在の要求、仕様書、コード構造、テストに基づいて判断すべきであり、グローバルメモリ内の粗い紹介に頼るべきではありません。

ディレクトリ構成も同じです。「共有コンポーネントはこのディレクトリからのみ参照する」のような特別な約束がある場合を除き、ツリー全体を書く必要はありません。モデルはプロジェクトディレクトリを自分で読めます。静的な構成説明は古くなりやすいだけです。

手順は skills やコマンドに向いている

ある内容が「第一にこれをする、第二にこれをする、第三にこれをする」という手順なら、それは Claude.md に置くべきではないかもしれません。

長期的なワークフローは、skills、スクリプト、コマンドに分離できます。そうすれば、グローバルメモリには名前と発火条件だけを残し、詳細な手順は必要なときだけ読み込めます。

たとえば：

1
2


ユーザーが Hugo 記事の翻訳を依頼したら、post-translate skill を使う。
ユーザーがサイトのデプロイを依頼したら、hugo-rsync-deploy ワークフローを実行する。

完全な翻訳手順やデプロイ手順を Claude.md に書くより軽くなります。グローバルメモリは短く保ち、具体的な流れは起動可能なツールに任せます。

Claude の最近の初期化フローもこの方向に進んでいます。単に Claude.md を生成するだけでなく、再利用可能なワークフローを skills に、固定イベントを hooks に分けようとします。この変化の背景にある考え方は明確です。グローバルメモリは入口だけを担い、詳細は必要に応じて読み込むべきです。

Claude.md は継続的に改善するもの

Claude.md は一度書いて終わりにすべきではありません。

より現実的なのは、最初は短く保ち、実際のタスクの中で問題を露出させることです。あるミスが一度だけ起きたなら、まず人間が処理すれば十分です。同種のミスが二回以上起きたなら、それはグローバルルールとして残す価値があるかもしれません。

最初から大量のルールを書くより、このような反復のほうが効果的です。初期段階では、どのルールが本当に役立つのか、どの内容がノイズになるのか分かりません。プロジェクトが大きくなり、協業が増え、モデルの挙動が安定してきたら、高頻度の問題を少しずつ追加していけばよいのです。

もう一つ重要な傾向があります。モデルが強くなるほど、グローバルメモリファイルは短くあるべきです。

以前はプロンプトに書く必要があった多くの要求を、今のモデルは自然に処理できます。そうした基本要求を Claude.md に入れ続けると、コンテキスト負荷が増えるだけです。グローバルメモリはモデル能力の向上に合わせて縮小し、このリポジトリ固有で、モデルが自動推測できない内容だけを残すべきです。

より実用的な書き方

Claude.md を書くときは、次の順序で考えるとよいです。

このリポジトリにはどんな特別な約束があるか？
モデルがすでに二回以上犯したミスは何か？
誤用してはいけないディレクトリ、ファイル、コマンドは何か？
どの手順は常駐コンテキストではなく、skills、スクリプト、コマンドにすべきか？
どの内容は単なる紹介で、削除できるか？

最終的なファイルは数十行だけかもしれません。プロジェクト全体を説明する必要はありません。行動を正確に制約することが目的です。

よい Claude.md は、たとえば次のようになります。

1
2
3
4
5
6
7


# 作業ルール

- 現在のタスクに関係するファイルだけを編集する。
- public/ や resources/ のような生成物ディレクトリを変更しない。
- Hugo 記事の書き換えでは index.zh-cn.md だけを処理し、他言語版を生成しない。
- デプロイが関係する場合は、先に Hugo ビルドを実行し、その後既存の rsync スクリプトを実行する。
- 既存のユーザー変更がある場合は、巻き戻さず、現在の状態を前提に続ける。

短いですが、どの行も実際の行動に影響します。こういう内容こそ、長期的にコンテキストを占有する価値があります。

最後に

Claude.md の価値は、AI に「もっと多くを知ってもらう」ことではありません。AI に「決まったミスを減らしてもらう」ことです。

これは知識ベースでもプロジェクト百科でもありません。AI コーディングにおける長期的な制約ファイルです。
具体的で、短く、実際のミスに近いほど役に立ちます。逆に、汎用的で、長く、プロジェクト紹介のようになるほど、モデルを遅くし、結果を悪化させる可能性が高くなります。

グローバルメモリは無限のメモ帳ではなく、希少な資源として扱う。これが、よい Claude.md を書くためのもっとも重要な原則かもしれません。