Claudeの長時間タスクをtests.jsonとprogress.txtで管理する

1つのコンテキストウィンドウでは終わらないタスクをどう引き継ぐか

Claudeに大きめの実装タスクを任せると、1回のセッションでは終わらないことがあります。コンテキストウィンドウが切れて会話が要約されたり、新しいセッションを開いたりするたびに、Claudeは「どこまで進んだか」を再確認しなければなりません。ここで再確認の手がかりが無いと、既に直したバグを再調査したり、実装済みの機能をもう一度作り始めたりする無駄が発生します。

Claude公式のプロンプトエンジニアリングガイドは、この問題への対処を「複数のコンテキストウィンドウをまたぐワークフロー」として整理しています。中心になるのが、テスト結果をtests.jsonのような構造化ファイルで管理し、進捗メモをprogress.txtのような自由記述ファイルで残すという2ファイル構成です。本記事では、このパターンをどう作り、どう読み直させるかを手順に分けて示します。

前提として、この記事が扱うのはプロンプトとファイル運用でClaudeに状態を持たせる方法です。Claude API・Agent SDK・Claude Codeのいずれでも使える汎用的なパターンですが、Claude Codeで使う場合は組み込み機能との役割分担が別に必要になるため、後半で扱います。

tests.jsonとprogress.txtの基本形

公式ガイドが例として示している2ファイルの構成は次のとおりです。テスト結果は数値と状態を持つJSON、進捗メモは自然言語のテキストという役割分担になっています。

{
  "tests": [
    { "id": 1, "name": "authentication_flow", "status": "passing" },
    { "id": 2, "name": "user_management", "status": "failing" },
    { "id": 3, "name": "api_endpoints", "status": "not_started" }
  ],
  "total": 200,
  "passing": 150,
  "failing": 25,
  "not_started": 25
}

Session 3 progress:
- Fixed authentication token validation
- Updated user model to handle edge cases
- Next: investigate user_management test failures (test #2)
- Note: Do not remove tests as this could lead to missing functionality

tests.jsonは「何がどこまで終わっているか」を機械が読める形で持ち、progress.txtは「次に何をすべきか」を人間が読む自然文で残します。片方だけで運用しようとすると、JSONだけでは経緯が分からず、テキストだけでは正確な集計ができません。2つを併用するのが公式の推奨です。

手順1 — 最初のコンテキストウィンドウでテストと骨格を作る

複数セッションにわたるタスクでは、最初のセッションに渡すプロンプトを他のセッションと変えるのが起点になります。1回目はコード実装そのものではなく、後続セッションが使うテストとセットアップスクリプトを整えることに専念させます。

Claudeにテストを書かせるときは、tests.jsonのような構造化フォーマットで管理させるよう明示します。単に「テストを書いて」と頼むだけでは、ファイル形式も更新ルールもセッションごとにばらつきます。次のような指示を添えると、テストを消して通過扱いにする近道を防げます。

テストを削除・編集してはいけません。機能の欠落やバグにつながるためです。

同じ最初のセッションで、開発サーバーの起動・テストスイートの実行・linterの実行を1つにまとめたinit.shのようなセットアップスクリプトも作らせます。これを用意しておくと、後続セッションが環境の立ち上げ方を再学習する時間を省けます。ハーネス全体をどう構成するかまで踏み込みたい場合は、長時間稼働エージェントのハーネス設計で4つの仕組みに分けて解説しています。

手順2 — 新しいセッションはtests.json・progress.txt・gitログから状態を復元する

2回目以降のセッションでは、いきなり実装に入らせず、状態の確認から始めさせます。公式ガイドは新しいセッションの立ち上げ方について、次のように具体的に指示することを勧めています。

Call pwd; you can only read and write files in this directory.
Review progress.txt, tests.json, and the git logs.
Manually run through a fundamental integration test before moving on to implementing new features.

ポイントは、「何を読むか」を毎回同じ順序で指定することです。作業ディレクトリの確認、進捗ファイルとテストファイルの読み込み、gitログの確認、既存機能が壊れていないかの手動確認という順番を固定すると、セッションが増えても立ち上げの品質がぶれません。git自体も状態追跡の一部として使われます。コミットログは「何をしたか」の記録であり、チェックポイントとして復元にも使えるため、進捗メモとJSONに加えてgit運用も組み合わせるのが公式の推奨です。

手順3 — コンテキストウィンドウが切れたら新規ウィンドウかcompactionかを選ぶ

コンテキストウィンドウが上限に近づいたとき、選択肢は2つあります。会話を要約して続ける(compaction)か、会話を打ち切って新しいコンテキストウィンドウをファイルシステムから立ち上げ直すかです。公式ガイドは、Claudeの最新モデルがローカルファイルシステムから状態を発見する能力に優れていることを踏まえ、状況によっては新規ウィンドウの方を選ぶ価値があるとしています。

compactionを選ぶ場合の実装手順(要約ブロックの積み戻し・ストリーミング時の扱い・thinkingブロックの持ち越しでの400エラー回避)は、Compaction blocksを会話に戻す実装パターンにまとめています。本記事が扱っているtests.json・progress.txtのパターンは、どちらを選んでも土台として機能します。

context awarenessでトークン予算を使い切らせる

Claude Sonnet 5・Claude Sonnet 4.6・Claude Sonnet 4.5・Claude Haiku 4.5には、context awarenessという機能があります。これらのモデルは会話全体を通じて残りのコンテキストウィンドウ、つまり「トークン予算」を自分で追跡します。有効化の操作は不要で、APIが自動的に情報を注入します。

仕組みは具体的です。リクエストのシステムプロンプトに、次のようなタグで総予算が渡されます。

<budget:token_budget>200000</budget:token_budget>

そしてツール呼び出しのたびに、残りの容量を示すタグが追加されます。

<system_warning>Token usage: 35000/200000; 165000 remaining</system_warning>

この予算はモデルが実際に持つコンテキストウィンドウと一致します。Claude Sonnet 5とClaude Sonnet 4.6は100万トークン、Claude Sonnet 4.5とClaude Haiku 4.5は20万トークンです。一方でClaude Opus 4.7以降のOpusモデル、Claude Fable 5.1・Mythos 5.1・Fable 5・Mythos 5はこの自動注入タグを受け取りません。これらのモデルで同様の制御をしたい場合は、ベータ提供のtask budgetsで明示的な予算を渡す形になります。

context awarenessが効くモデルでは、次のようなプロンプトを添えることで、予算切れ間際に作業を放棄させず、状態を保存させる挙動を引き出せます。

コンテキストウィンドウは上限に近づくと自動的に圧縮され、続きから作業を継続できます。そのためトークン予算を理由にタスクを早期に切り上げないでください。予算の上限に近づいたら、圧縮が起きる前に現在の進捗と状態をメモリに保存してください。

検証ツールを渡して「完了」をClaudeの自己申告に任せない

自律タスクが長くなるほど、人間が毎回フィードバックすることは難しくなります。公式ガイドは、Claude自身が正しさを検証できる手段を用意することを勧めています。UIの動作確認であればcomputer useツール・browser useツール・ブラウザ操作系のMCPサーバーが候補です。

tests.jsonで「passing」に書き換える権限をClaudeに与える場合も、実際にテストを実行させてから書き換えさせるのが前提です。テストを走らせずにpassingへ変更する近道を許すと、tests.jsonは進捗の記録ではなく自己申告の記録に変わってしまい、次のセッションが誤った前提から作業を始めることになります。

よくあるつまずき

• テストを消させてしまう: 「テストが通らないから削除する」という近道は、機能の欠落を見えなくします。テストの削除・編集を禁じる指示を、最初のセッションのプロンプトに明記しておく必要があります。
• progress.txtを構造化データの代わりに使う: 自由記述のメモに数値の集計を混ぜると、次のセッションが正確な状態を読み取れなくなります。集計はtests.json側に置き、progress.txtは経緯と次の一手に絞ります。
• compactionだけに頼って状態ファイルを作らない: compactionは会話を要約しますが、要約自体は毎回変わります。tests.json・progress.txt・gitログのようにファイルシステム上に固定された状態が無いと、新しいセッションが復元できる情報が要約の質に依存してしまいます。
• 立ち上げプロンプトを毎回変える: セッション開始時に読むべきファイルの順序を都度書き換えると、読み漏れが起きやすくなります。手順2のような固定フォーマットを使い回すほうが安定します。

Claude Codeで使う場合の注意点

Claude Codeでこのパターンを使う場合、混同しやすい別の仕組みが2つあります。

1つは、Claude自身が多段階作業のために作るTodoチェックリストです。これはtests.jsonのようにユーザーがフォーマットを指定するファイルではなく、Claude Codeが内部で管理する別の機能です。複数のClaude Codeインスタンス間でこのチェックリストを共有したい場合はCLAUDE_CODE_TASK_LIST_IDという環境変数が使えますが、これは本記事のtests.jsonパターンとは別物です。詳細はCLAUDE_CODE_TASK_LIST_IDとはにまとめています。

もう1つは、Claude Code自体が持つコンテキスト圧縮の仕組みです。Claude Codeはコンテキストが長くなると自動的に圧縮しますが、本記事で扱ったtests.json・progress.txtのようなファイルは、圧縮の内部処理とは独立してプロジェクトのディスク上に残ります。圧縮によって会話の細部が失われても、ファイルを読み直せば状態を復元できるという点が、このパターンをClaude Codeで使う価値です。

まとめ

複数のコンテキストウィンドウをまたぐ長時間タスクは、Claudeのモデル性能だけでは解決しません。最初のセッションでテストとセットアップスクリプトを整え、tests.jsonで進捗を構造化データとして持ち、progress.txtで経緯を自由記述で残し、gitでチェックポイントを刻む。この組み合わせが、新しいセッションが状態をファイルシステムから素早く復元するための土台になります。コンテキストウィンドウが切れたときに新規ウィンドウを選ぶかcompactionを選ぶかは状況次第ですが、どちらを選んでも状態ファイルの設計は共通の前提として機能します。Sonnet 5・Sonnet 4.6・Sonnet 4.5・Haiku 4.5を使っているなら、context awarenessが自動で伝えてくるトークン予算の情報も、状態保存のタイミングを判断する材料に使えます。