「さっき修正したファイル、もうClaude が忘れてる」

そう感じたことはないでしょうか。10ファイルを横断するリファクタリング中に、完了済みのモジュールへ重複修正を提案してきたり。セッションが長くなったタイミングで自動コンパクションが走って、それまでの決定事項がまるごと消えたり。

実は、この失敗の原因はClaudeの性能ではありません。使う側の「コンテキスト設計」が抜けていることが大半です。

競技データサイエンスで国内7位まで上り詰めた経験から言うと、ツールの限界より先に設計の限界が来ます。Claude Codeも例外ではありません。3原則と具体的なテクニックで、「なんとなく使うAI」から「設計して使うAI」に切り替えましょう。

AIが「忘れる」のは、物理的な制約です

ひとつ確認しておきたい前提があります。Claude Codeが「前の話を忘れた」ように見える現象は、AIの理解力の問題ではありません。コンテキストウィンドウという物理的な制約が原因です。

Claude Codeが「見ている」情報を整理すると、以下になります。

• 会話履歴（メッセージのやり取り全体）

• ツールで読み込んだファイルの内容

• 実行したコマンドの出力結果

• CLAUDE.md の内容

これらがすべて、200,000トークン（約150万文字相当）という上限の中に収まります。使用率が約83.5%に達すると、自動コンパクションが走ります。会話の古い部分が圧縮・削除されるため、セッション序盤に確認した設計方針やファイルパスが消えてしまう。

Claude Code はセッションをまたいで記憶を持ちません。前の会話を自動で引き継ぐ仕組みは存在せず、CLAUDE.md だけが唯一の「持続する記憶」です。

CADDi Tech Blogによると、CLAUDE.md と設計書の読み込みだけで35,000〜38,000トークンを消費する事例もあります。コンテキストウィンドウは、想像より早く埋まります。

なぜマルチファイルで特に壊れやすいのか

単一ファイルの作業なら、コンテキストの消費は限定的です。しかし、複数ファイルをまたぐ実装は構造的に3つのリスクを抱えています。

1. ファイルを読むたびにトークンが消費される

1ファイルを読み込むだけで数千〜数万トークンが消費されます。CADDi Tech Blogによると、単一デバッグセッションやコードベース探索だけで数万トークンを消費する事例も報告されています。「全体を調査して」という一言が、コンテキストを一気に枯渇させます。

2. 自動コンパクションが「初期決定」を消す

セッション序盤に確認したはずの設計方針・禁止事項・ファイルパスは、コンパクション後には消えています。Claude が同じ質問を繰り返してくるのは、文脈が物理的に失われているからです。

3. ファイル間の依存関係が暗黙のまま

「ファイルAを変えたらファイルBも影響を受ける」という情報は、コードを読めば推測できますが、明示されなければ見落とされます。これが、変更の整合性が取れなくなる直接原因です。

品質低下の目安として、CADDi Tech Blog（2026/03）の実務報告によると、コンテキスト使用率60%を超えると指示の見落としが頻発します。ファイル数が多い実装ほど、設計なしには早い段階でこの閾値を超えます。

コンテキスト設計の3原則

原則1: CLAUDE.md を「ナビゲーション指示書」として設計する

CLAUDE.md は「設定ファイル」ではなく、セッション全体の航路を示す指示書です。コンテキストが枯渇しても消えない、唯一の永続情報です。

書くべき内容のフィルター基準は、一つに絞れます。「これがなければ Claude が間違いを犯すか？」— YES のものだけ書く。それ以外は書かない。

# プロジェクト: [名前]

## 必須コマンド
- ビルド: npm run build
- テスト: npm test
- リント: npm run lint

## コードスタイル
- import は ES modules（require 禁止）
- 命名: camelCase（変数・関数）/ PascalCase（クラス）

## アーキテクチャ
- src/api/     : APIレイヤー（外部通信のみ）
- src/domain/  : ビジネスロジック（APIに依存しない）
- src/ui/      : UIコンポーネント

## 禁止
- lodash は使わない（移行中）
- IMPORTANT: 破壊的 git 操作は必ず確認してから実行

## 参照
- 詳細設計: @docs/architecture.md
- API仕様:  @docs/api-spec.md

目安は60行以内です。HumanLayer Blogの調査では、80行を超えると Claude が重要ルールを部分的に無視し始めるとされています。長い説明は `@path/to/file` 構文で外部ファイルへの参照に置き換え、CLAUDE.md 本体は薄く保つのが鉄則です。

絶対に守らせたいルールには `IMPORTANT:` や `YOU MUST:` を付けると遵守率が上がります。個人的には、コンパクション時に保持させたい情報を「When compacting, always preserve the full list of modified files」のように一行明示するだけでも、かなり効きます。

原則2: ファイル間の依存関係を指示に明示する

暗黙の依存関係を可視化することが、マルチファイル実装の核心です。

指示の中で影響範囲を明記する

# 悪い例
「UserService を修正して」

# 良い例
「UserService を修正して。変更が AuthMiddleware と UserController に
 波及するので、3ファイルを同時に確認して整合性を保ちながら変更して」

さらに強力なのが、`@ファイルパス` 構文による明示的な参照です。「@src/api/user.ts を読んでから @src/domain/user.ts を修正して」と書くだけで、Claude は指定の順序でファイルを読み込みます。

Plan Mode（Shift+Tab）を実装前に必ず使う

Plan Mode はコードを一切変更せずに、変更計画だけを立てるモードです。「まずファイル構造を把握して、変更が必要なファイルをリストアップして。コードは触らないで」という指示で探索フェーズを分離できます。

計画を確認してから実装に入ることで、途中で方向ミスに気づいて全部やり直す、という最悪のパターンを防げます。

30分超えるタスクには Dev Docs 戦略を使う

複数セッションにまたがる長期タスクでは、3つのファイルを事前に作っておくと効果的です。

• `plan.md` : 承認済みの実装計画と設計上の決定事項

• `context.md`: 重要ファイルパス・現在の状態・完了済みタスク

• `tasks.md` : 作業チェックリスト（完了/未完了）

各ファイルの先頭はこのような形にします。

# plan.md
## 実装方針（承認済み）
- 認証にはJWTを使う（セッション管理は使わない）
- エラーは全てカスタム例外クラスに統一する

# context.md
## 重要ファイルパス
- 認証ロジック: src/auth/token.ts
- ユーザーモデル: src/domain/user.ts
## 完了済みタスク
- [x] token.ts のリフレッシュ処理を修正

# tasks.md
- [x] token.ts 修正
- [ ] user.ts に新フィールド追加
- [ ] テスト更新

コンパクションが走っても、ファイル自体は消えません。再開時に「continue」と入力するだけで、Claude が Dev Docs を読んで続きから始められます。

原則3: 変更スコープを絞り込んだ指示をする

「全体を調査して」という指示は、コンテキストを最速で枯渇させます。スコープを限定するのが、マルチファイル実装で最も効く習慣です。

調査と実装を分離する

# 調査はサブエージェントに委託
「use a subagent to investigate how authentication works in src/auth/」

# 実装はメイン会話で
「調査結果を踏まえて、refresh_token 関数のみを修正して」

サブエージェントは独立したコンテキストウィンドウで動くため、コードを大量に読む探索作業をここに分離することで、メインの会話をクリーンに保てます。

コンテキスト管理コマンドを積極活用する

$$
\small
\def\arraystretch{1.5}
\begin{array}{|l|l|}
\hline
\textbf{\textsf{コマンド}} & \textbf{\textsf{使いどき}} \\\\
\hline
\textsf{/compact focus on <焦点>} & \textsf{コンテキスト60\%到達時に意図的に実行} \\\\
\hline
\textsf{/clear} & \textsf{無関係なタスクの間でリセット} \\\\
\hline
\textsf{/rewind} & \textsf{誤った方向に進んだとき以前の状態に戻る} \\\\
\hline
\end{array}
$$

同じ間違いを2回繰り返したら、修正を続けるより `/clear` してリセットした方が早いです。失敗から学んだ内容を「今回の失敗の原因は〇〇だった。それを踏まえて改めて実装して」という形で新しいプロンプトに組み込んで再開します。

3つの原則を実際の開発フローに統合すると、次のワークフローになります。

実践: マルチファイル実装の4フェーズワークフロー

公式ドキュメントが推奨する流れを、実際の指示文とあわせてまとめます。

Phase 1: Explore（探索）

Plan Mode（Shift+Tab）で:
「src/auth/ の全ファイルを読んで、認証フローを図示して。
 どのファイルがどのファイルに依存しているか整理して。
 コードは一切変更しないで」

Phase 2: Plan（計画）

「変更が必要なファイルをリストアップして、変更内容を具体的に説明して。
 変更の順序（依存関係的に先に変えるべきファイル）も提示して。
 承認するまでコードを変更しないで」

Phase 3: Implement（実装）

Normal Mode に戻して:
「承認した計画に従って実装して。各ファイルの変更後に
 npm test を実行して、次のファイルに進む前に必ず確認して」

Phase 4: Commit（コミット）

「変更したファイルをファイル単位でコミットして。
 コミットメッセージには変更理由も含めて」

このフローの核心は「探索→計画→承認→実装」の順序を崩さないことです。実装を先に始めると、方向ミスに気づいたときにやり直すコストが大きくなります。

このフローを徹底した事例として、Firebase SDK v9のモジュラーAPI移行があります。39ファイルを3グループに分割してサブエージェント3体が並列実行した結果、従来なら数日かかる作業が約1時間で完了しました（StartLink社ブログ）。「設計して使う」と「なんとなく使う」の差はここまで出ます。

よくある失敗パターンと対処法

修正ループの沼にはまった

間違い→修正→別の間違い→修正……と繰り返すうち、コンテキストが失敗事例だらけになり、Claude がそれに引きずられます。同じ間違いが2回続いたら `/clear` してリセット。「今回の原因は〇〇だった。それを踏まえて」と書いた新しいプロンプトで再スタートする方が、修正を続けるより圧倒的に早いです。

計画なしに実装を始めた

タスクを与えた瞬間に Claude がコードを書き始め、途中で方向ミスが発覚するパターンです。Plan Mode を先に使って変更ファイルリストと変更内容を確認してから実行に移る。これだけで防げます。

サブエージェントに調査させたら結果が消えた

GitHub Issue #23821 で報告されているパターンです。サブエージェントの出力は必ずファイルに書き出させましょう（「調査結果を research-result.md に保存して」）。コンパクション後もファイルは消えません。

CLAUDE.md が100行を超えて重要ルールが埋もれた

思いつくまま追記した結果、Claude が部分的に無視し始めます。定期的に棚卸しして「Claude がデフォルトでやっていること」は削除する。長い説明は `@path/to/doc.md` の外部参照に置き換えて、本体は60行以内を維持します。

まとめ: 設計するか、溺れるか

マルチファイル実装でのコンテキスト設計を3原則でまとめます。

1. CLAUDE.md を60行以内のナビゲーション指示書に整理する（重要ルールには IMPORTANT: を付ける）

2. Plan Mode + Dev Docs でファイル間依存を可視化する（計画なしに実装を始めない）

3. スコープを絞った指示とサブエージェント分離でコンテキストを温存する（60%で意図的にコンパクション）

「AIは手、人間は頭」が私の考えるAI活用の基本姿勢です。コンテキストを設計するのは人間の仕事で、その設計の質がAIのアウトプットの質をそのまま決めます。Firebase移行で数日→1時間という差が生まれたのも、ツールではなく設計力の違いです。

まず手元の CLAUDE.md を開いて、60行を超えていたら棚卸しするところから始めてみてください。次のマルチファイル実装では、Plan Mode を一度だけ使ってみる。小さな一歩で、体感できる変化が出るはずです。

関連記事

Claude Codeをもっと体系的に学びたい方はこちらもどうぞ。

私のことが気になった方は、自己紹介もあわせてどうぞ。

生成AIの活用術の全記事をマガジンにまとめています。

生成AI関連の全記事はマガジンにまとめています。

今後も生成AIについてや生成AIの活用術についても発信しています。ご興味ある方はフォローお願いします🙇🏻

https://note.com/horizon_it00