Claude Code で作業が中断しても再開できるようにする ── CLAUDE.md と STATE.md の役割分担

AIエージェントに複数日かけて大きな仕事を任せると、必ず何度かセッションが途中で切れる。コンテキストウィンドウが満杯になったり、単純に閉じてしまったり、日をまたいだりするからだ。そこで厄介な問題が起きる。再開すると、AIは「このプロジェクトは何ですか？」と聞き直してくるのだ。こちらが説明し直すまで、作業は進まない。その説明もプロジェクトが大きくなるほど長くなり、やがて「説明するのが面倒で作業を止める」という本末転倒な状況に陥る。この問題の本質は「情報の性質の混同」にある。プロジェクトに関する情報は、実は二つのカテゴリに分かれている。一つは「変わらないもの」、つまりプロジェクトの背景、方針、要件といった永続的な情報だ。もう一つは「変わるもの」、つまり今日やったこと、どこまで進んだか、次は何をするかといった一時的な状態である。従来の開発では、この両者を混ぜてREADMEやドキュメントに書いていた。だから毎回、AIに長々と説明する羽目になる。解決策は、この二つを物理的に分けることだ。CLAUDE.mdには「変わらないもの」だけを書く。プロジェクトの概要、設計原則、既知の制約などで、一度書いたら更新頻度は少ない。それに対してHANDOFF.mdには「変わるもの」だけを書く。昨日までの進行状況、いま何をしているか、次のやることだけだ。セッション再開時にAIが読むのは、この二つのファイルで、毎回の説明は不要になる。これはAIとの作業効率の問題ではなく、そもそも「情報設計」の問題だ。ドキュメント構造を変えるだけで、人間側の生産性も同時に上がる。