Articles
CLAUDE.md、下から見るか？横から見るか？
TL;DR
https://code.claude.com/docs/ja/memory を読め。
序文：CLAUDE.mdはコンテキスト設計である
Claudeは CLAUDE.md と Memory を参照します。
CLAUDE.md はプロジェクトメモリとしてセッション開始時に読み込まれます。
つまり、CLAUDE.mdは単なるドキュメントというより、
Claudeに渡す「前提コンテキスト」の一部です。
そしてコンテキストには限りがあります。
会話が長くなると圧縮（chat compaction）が起こり、古い情報は要約され、場合によっては忘却されます。
だからこそ、
CLAUDE.mdをどう管理するかは、コンテキストをどう管理するかの問題
になります。
ここでは、CLAUDE.mdを
- 下から見る（前提を固める）
- 横から見る（作業単位で絞る）
という二つの視点で整理してみます。
CLAUDE.mdの二層構造：ホームとリポジトリ
CLAUDE.mdの置き方には、実際にはいろいろなバリエーションがあります。
- サブディレクトリごとに置く
- モジュール単位で分ける
- .claude/ 配下にまとめる
- 複数階層で管理する
どれも仕様上は可能です。
ただ、本稿では話をシンプルにするために、あえて二層に絞って説明します。
~/.claude/CLAUDE.md（ユーザーレベル）- リポジトリ直下の
CLAUDE.md（プロジェクトレベル）
どちらもセッション開始時に読み込まれますが、役割はかなり違います。
この二層に分けて考えると、
- 個人の作業スタイル
- チームの前提コンテキスト
が自然に分離できます。
下から見る：前提を固める
ホーム直下（ユーザーレベル）
ホーム直下は、個人の作業スタイルを決める場所です。
例えば、
- 回答言語
- 出力フォーマット
- plan提示の有無
- 個人の開発スタイル
といったものです。
設計制約やアーキテクチャの前提は、ここには置かないほうがよいでしょう。
プロジェクトをまたいだときに混ざってしまうからです。
リポジトリ直下（プロジェクトレベル）
リポジトリ直下の CLAUDE.md は、プロジェクトの前提になります。
例えば、
- アーキテクチャ制約
- レイヤーの責務
- 実装上の禁止事項
- 優先順位
- スキルの利用方針
などです。
同じブランチを扱えば、同じ前提がClaudeに渡る。
この状態を作るのが目的です。
肥大化が問題
CLAUDE.mdは毎回読み込まれます。
コンテキストには限りがあります。
会話は圧縮されます。
CLAUDE.mdが大きくなりすぎると、
- 重要な情報の密度が下がる
- 圧縮時に本質が埋もれやすくなる
- 不要な前提が常に残る
といった状態になります。
これはコンテキストの質の問題です。
だからこそ、CLAUDE.mdはできるだけ軽くしておくほうが扱いやすいと考えています。
CLAUDE.mdは索引にする
CLAUDE.mdを、すべてを説明するドキュメントにしない。
代わりに、
- 前提を短く固定する
- 詳細への参照を示す
という役割にとどめます。
例：
# 前提
- バックエンドはGo
- DBはPostgreSQL
- マイグレーションは必ずskillを使用
# 参照
- docs/architecture.md
- docs/business-requirements.md
前提はここに置く。
理由や背景は別に置く。
横から見る：作業単位で絞る
Claudeはタスクに関連する情報を参照します。
作業単位でコンテキストを絞れる構造があると安定します。
docs：理由を置く
例えば、
- docs/business-requirements.md
- docs/architecture.md
- docs/adr/
これらは重要です。
ただ、毎回の実装タスクで常に読む必要はありません。
設計を見直すときや、大きな判断をするときに参照すれば十分です。
skills：作業の入口にする
.claude/skills/ にMarkdownでスキルを置く構成は扱いやすいです。
.claude/
skills/
bugfix.md
migration.md
refactor.md
ClaudeはMarkdownをそのまま読めます。
スキルの作り方そのものに強い再現性を求める必要はありません。
ただし、リポジトリに置いたスキルは必ず使う、という運用にすると安定します。
スキルは、
- 参照範囲を限定する
- 手順を固定する
- 成果物の揺れを減らす
ための装置です。
MEMORY.mdはキャッシュとして扱う
Auto Memory (MEMORY.md)はClaudeが参照します。
エージェント間の情報受け渡しにも使われます。
そのため、MEMORY.mdは作業中のキャッシュとして使うのが自然です。
ただし、MEMORY.mdは永続保証ではありません。
だからこそ、
- コミット前にMEMORY.mdを見直す
- 重要な内容はdocsやCLAUDE.mdに反映する
という運用を入れておくと安心です。
MEMORY.mdは揮発します。
リポジトリは忘れません。
まとめ
ClaudeはCLAUDE.mdとAuto Memoryを参照します。
コンテキストは有限で、圧縮され、忘却されます。
その前提に立つと、
- ホーム直下は個人スタイル
- リポジトリ直下は前提の固定
- CLAUDE.mdは軽量な索引
- docsは理由の保管庫
- skillsは横から読む装置
- MEMORY.mdはキャッシュ
という構造が自然に見えてきます。
さらに、これらのルールを「守る」だけでなく「守られる」状態にするために、
git worktree の活用も有効です。
ブランチごとに物理的に作業ディレクトリを分離すれば、
- ブランチごとのCLAUDE.md
- ブランチごとのdocs
- ブランチごとのskills
が自然に分離されます。
これはコンテキストの強制分離です。
下から固め、横から絞り、
物理的にも分離する。
そこまでやって初めて、
Claudeを安定して最大限活用できる状態になります。