Claude Code の利用上限対策として育てている自作のAIエージェント(Python の CLI)に、作業の「計画」と「中断したタスクの再開」を足しました。以前このエージェント自身に「汎用エージェントに必要なもの」を挙げさせたとき、後回しにしていた2つです。再開は会話の履歴を保存せず、記録から「続きをやって」という依頼文を組み立てる方式にしました。
今日やったこと
- 計画ツールを追加。モデルが手順の一覧を「未着手・作業中・完了・省略」付きで書き、着手・完了のたびに更新する。更新のたびに画面に一覧を出す
- タスクの開始時とツールを呼ぶたびに、元の依頼・計画・呼んだツール(入力の要約と成否)を記録に書き、最後まで終わったら消すようにした。残っているものが中断したタスクになる
- 起動時に中断したタスクの件数を知らせ、コマンド1つで続きから再開できるようにした
- 実行中に Ctrl+C を押すと CLI ごと落ちていたのを、そのタスクだけ止めて入力待ちに戻るようにした
- テストは 415 件から 445 件に増えて、すべて通過
詰まったところと、どう解いたか
再開の方式。最初に考えたのは、会話の履歴(モデルとのやり取り全部)をそのまま保存して積み直す方法です。ただ、このエージェントは Claude と OpenAI のモデルを切り替えて使っていて、両者でメッセージの形が違います。履歴を保存すると、再開するときにモデルを変えられません。読んだファイルの中身がディスクに残り、再開のたびに元の会話を全部入力し直すのでトークンもかさみます。
そこで、元の依頼・中断の理由・中断時点の計画・呼んだツールの一覧・途中経過の要約から依頼文を組み立てて、新しい実行として始めることにしました。代わりに前回のツールの出力は渡らないので、「必要なファイルは読み直す」「作業中だった手順は結果が反映されているかを先に確かめる」「書き込みや作成は二重にしない」と依頼文で指示しています。ツールの出力は依頼文に入れていません。Web ページなど外部の内容に書かれた指示が、自分の依頼と同じ立場でモデルに渡ってしまうのを避けるためです。
中断と再開のしくみはこうなっています。

実行中は記録を書き足し、最後まで終わったら消す。上限・ガードの停止・Ctrl+C・エラー・ウィンドウを閉じたときは記録が残り、再開では元の依頼・計画・呼んだツール・途中経過の要約だけを渡し、会話の履歴とツールの出力は渡さない。
計画の更新だけで1周を使ってしまう。実際のモデル(gpt-6-luna)で、順番に意味がある4手順の読み取りの依頼を、ツール実行の上限を3周に下げて流しました。わざと途中で止めるためです。結果は「計画を作る → 1つ目のファイルを読む」で上限に達し、4手順のうち1つしか進みませんでした。おもしろかったのは、実行後の反省フェーズで、エージェント自身が「計画作成で1周を使わず、最初の周から読み込みを進める」と教訓の候補を出してきたことです。
モデルは1回の応答で複数のツールを呼べます。そこで「計画の更新は、作業のツール呼び出しと同じ応答で一緒に呼ぶ」とシステムプロンプトとツールの説明に書き足しました。この後の再開では、計画の更新とファイルの読み込みが同じ応答で呼ばれていました。
同じ1秒に保存した記録の順番が決まらない。「いちばん新しい中断タスク」を選ぶのに記録の更新時刻(秒単位)を使っていたら、テストで同じ1秒の中に2件を保存したとき、どちらが新しいか決まらずに失敗しました。ファイルの更新時刻(ナノ秒)で並べるように変えて直しました。
実際のモデルで試した3回の結果です。

3ファイルを読む依頼は計画を作らずツール3回で完了。4手順の依頼は上限3周で計画0/4・ツール2回の時点で打ち切られて記録が残り、それを再開すると計画4/4・ツール9回で完了して記録が消えた。
1回目の「3ファイルを読んでまとめる」依頼では、手順が3つあってもモデルは計画を作らず、3回の読み込みで終えました。並べて読むだけの作業だと判断したようです。計画を作るかどうかはモデルに任せています。
気づき
再開したエージェントは、最後の報告で「README に新しいサブコマンドの記載がない」と指摘してきました。実装したばかりで、まだドキュメントを直していなかった部分です。動作確認のつもりで流した依頼が、そのままドキュメントの漏れを見つけてくれました。
もう一つは、ツールを呼べる回数に上限があるエージェントでは、「計画を立てる」こと自体がその回数を食うという点です。人間なら計画はタダですが、モデルにとっては1回の応答です。計画を独立した手順にせず、作業と同じ応答に相乗りさせる書き方が要りました。反省フェーズが自分でそこに気づいたのは、仕組みを入れておいてよかったと思えた点です。
次にやること
- Ctrl+C とウィンドウを閉じた場合の記録の残り方を、単体テストだけでなく実機で確かめる
- 実際の雑務をこのエージェントに任せて、Claude Code の消費が減るかを測る
