第1章 なぜ「メモを書いても Claude が読まない」のか

第1節 会話セッションは状態を持てないという構造的な制約

Claude Code を毎日使っていると、ある時期から同じ違和感に突き当たる。前回のセッションで散々説明した設計方針を、 次のセッションではもう一度最初から説明する羽目になる。プロジェクトの命名規則、避けてほしい実装パターン、 過去に試して失敗したアプローチ——どれも一度は言語化して伝えたはずなのに、次に会う Claude はそれを知らない。

これは Claude が「学習していない」からではない。会話セッションという仕組みそのものが、セッションをまたいだ 記憶を前提にしていないからだ。一般的には、会話モデルは「そのセッションのコンテキストウィンドウに載っている情報」 だけを参照して応答を組み立てる。セッションが終了すれば、そのウィンドウの中身は失われる。次に開いたセッションは、 別のプロセスとして、白紙の状態から始まる。

これは欠陥ではなく仕様だと捉えたほうが実務上は正しい。もし会話モデルが全ユーザーの全セッションを横断して 記憶を保持していたら、それ自体がプライバシーとセキュリティの重大な問題になる。セッションが独立していることは 安全設計の一部であり、この前提は覆らない。したがって、記憶を持たせたいなら、モデルの内部に期待するのではなく、 モデルの外側にファイルとして状態を置くしかない。

Claude Code には、この外側の置き場所として CLAUDE.md という仕組みが用意されている。 プロジェクトのルートに置いた CLAUDE.md は、セッション開始時に自動的に読み込まれ、 コンテキストに含められる——というのが一般的に知られている仕様である。この仕組み自体は単純で、 特別な設定もほとんど要らない。だからこそ多くの人が「とりあえず書いておけば覚えてくれるはずだ」と考えて使い始める。

ここで見落とされがちなのは、「読み込まれる」ことと「記憶が引き継がれる」ことは、似ているようで別の話だという点である。 ファイルは確かに毎回読み込まれる。だが読み込まれた情報をモデルがどう扱うかは、書いてある内容の量・質・ 整理のされ方に強く左右される。人間同士のコミュニケーションに置き換えると分かりやすい。新しく入ったメンバーに 分厚いドキュメントを一度渡しただけで、細部まで完璧に把握してもらえるとは誰も期待しない。要点が整理されていなければ、 渡した情報の大半は読み飛ばされるか、記憶の片隅に追いやられる。CLAUDE.md も同じで、「置いてあること」と 「機能していること」の間には運用の工夫が必要になる。

ところが、しばらく運用すると分かってくる。ファイルに書くことと、Claude がそれを実際に活用できる形で 読み取ることの間には、大きな距離があるということだ。ファイルは確かに読み込まれている。だが、 そこに書かれている情報が多すぎたり、古かったり、矛盾していたりすると、読み込まれてはいても実質的に 「読まれていない」のと同じ結果になる。次節では、この距離がどういう形で事故として表面化するかを見ていく。

第2節 CLAUDE.md に何でも詰め込んだときに起きる3つの事故（読まれない・矛盾する・膨張して埋もれる）

「セッションをまたぐと文脈が消える」という問題に気づいた人の多くが、最初に取る対策は同じだ。 CLAUDE.md に気づいたことをとにかく書き足していく。プロジェクトのルール、過去のバグの原因、 今後のタスク、雑多な気づき——分類せずに、時系列に、思いついた順に追記していく。

この運用は、最初の数週間はうまくいく。だが規模が大きくなるにつれて、次の3つの事故がほぼ確実に起きる。

事故1: 読まれない

ファイルが数百行、数千行に膨れ上がると、コンテキストウィンドウの中でその情報が占める割合が大きくなる。 すべての情報が同じ重みで並んでいると、モデルにとって「今の作業に関係が深い情報」と「関係が薄い情報」の 区別がつきにくくなる。書いてあるのに、実際の応答には反映されない——という現象が起き始める。

事故2: 矛盾する

同じ論点について、3週間前に書いた結論と、先週書いた結論が食い違っていることがある。状況が変わって 方針を変えたのに、古い記述を消し忘れる。一つのファイルに時系列で追記し続けると、この矛盾は自然に蓄積する。 厄介なのは、矛盾していること自体に、書いている本人もなかなか気づけない点だ。ファイルの前半と後半を 見比べる作業を、誰も日常的にはやらないからである。

事故3: 膨張して埋もれる

恒久的なルール（「このプロジェクトでは○○という命名規則を使う」）と、一時的な進行状況（「今このタスクの 途中まで終わっている」）と、過去の学び（「以前この方法を試して失敗した」）が、すべて同じファイルの 同じ階層に並ぶと、本当に重要な恒久ルールが、日々増えていく進行状況のログに埋もれていく。結果として、 一番参照してほしい情報ほど見つけにくくなるという逆転が起きる。

この3つに共通する原因は一つだ。「何でも1つのファイルに書けば記憶になる」という発想そのものが、 情報の性質の違いを無視していることである。恒久的に変わらない情報と、日々更新される進行状況と、 過去の失敗から得た教訓は、更新される頻度も、参照されるべきタイミングも、扱われ方も本来まったく異なる。 それらを1つのファイルに混在させたまま量だけ増やしていけば、遅かれ早かれこの3つの事故のどれかに行き着く。

さらに厄介なのは、この3つの事故が独立して起きるのではなく、互いを悪化させる方向に作用することだ。 矛盾した記述（事故2）を消さずに残すと、ファイルはその分だけ膨張する（事故3）。膨張したファイルの中では、 個々の記述が相対的に読まれにくくなる（事故1）。一度この悪循環に入ると、「とりあえず書き足す」という 対症療法では収まらなくなり、ファイルを開くこと自体が億劫になっていく。運用が破綻するプロジェクトの多くは、 この悪循環に気づかないまま、書く量だけを増やし続けた結果として起きている。

本書が扱うのは、この3つの事故を避けるための分割設計と、書き方・読み方の手順そのものである。とはいえ、 それは「1つのファイルではなく複数のファイルに分ければ解決する」という単純な話でもない。分割の軸を どこに置くか、どのファイルを何のタイミングで更新するか、更新した情報同士の矛盾をどう検出するかまで 含めて設計しないと、ファイルが増えただけで同じ事故が形を変えて再発する。

第3節 本書が扱う範囲と扱わない範囲（単一プロジェクトの知識管理。マルチユーザーの共有知識ベースは対象外）

期待値を先にそろえておく。「求めていたものと違った」という結果は、書き手と読み手の双方にとって 一番の損失だからだ。

扱うこと

• CLAUDE.md を分割する設計。 恒久ルール・プロジェクト固有事実・進行中タスク・過去の学びという性質の違う情報を、どういう軸で分け、どのファイルに置くか（第2章）。
• Ingest プロトコル。 セッションやタスクの区切りで「その場で覚えておいてほしいこと」をどこに・どの粒度で書き残すかという、書き込み側の手順（第3章）。
• Lint プロトコル。 書き溜めた記述同士が矛盾していないかを、機械的に近い手順で検出する考え方（第4章）。
• 記憶を腐らせない運用。 情報の鮮度の扱い方、古い記述の扱い、短周期のふり返りを長周期のまとめへ集約する階層設計（第5章）。
• hooks やサブエージェントによる自動化の考え方。 手動だと忘れる作業をどこまで仕組みに載せ、どこから先は人が確認すべきかの線引き（第6章）。
• そのまま使えるテンプレート集。 CLAUDE.md 分割構成の雛形、Ingest / Lint のチェックリスト（第7章・付録）。

扱わないこと

• モデルの選び方やプロンプトエンジニアリングの技法。 本書の設計は特定のモデルの性能や言い回しの巧拙には依存しない。
• マルチユーザーで共有する組織的なナレッジベースの構築。 本書が対象にするのは、一人の開発者が単一のプロジェクト（またはごく少数のプロジェクト）で運用する知識管理であり、チームで共有するナレッジベースの権限設計や更新フローは範囲外である。
• Claude Code の内部実装や将来の仕様変更の予測。 本書は公開されている一般的な挙動と、実際に運用して確認できた事実だけを書く。断定できない技術的な詳細については、断定せずに「一般的には」「推測」と明記する。
• 「これで生産性が劇的に上がった」という類の実績訴求。 本書の執筆時点で、この知識管理の仕組みを使っている個人開発の収益は0円である。本書が提供するのは成果の実績ではなく、実際に運用しているファイル構成と手順そのものであり、この点は隠さずに書く。

前提とする読者

Claude Code（または類似の CLI 型 AI コーディングツール）を日常的に使っていて、Markdown を読み書きでき、 セッションをまたぐと文脈が消えることに不便さを感じている個人開発者・副業エンジニアを想定する。 チーム運用や大規模な組織導入は想定しない。

次章では、この3つの事故を避けるために、CLAUDE.md をどういう軸で分割するかという設計そのものに入っていく。