コーディングエージェントのETAを、正直に表示する

最初の記事では、エージェントの作業中に待つか、短い用事を済ませるか、別の仕事を始めるかという時間の使い方を考えました。今回は、次に人の注意が必要になりそうな時間帯を、ローカルに記録して表示します。

この例は作業時間を自動予測しません。自分かエージェントが状態を明示し、根拠がある場合だけおおよその時間帯を報告します。その情報を読みやすくし、古い予測が今も有効に見えるのを防ぐためのものです。

1. 独立したサンプルを動かす

macOSまたはLinuxのターミナルとPython 3が必要です。確認には python3 --versionを使います。次のファイルをダウンロードして内容を確認し、 agent-eta.py一時的な作業ディレクトリに保存してください。以下のコマンドはそこで実行します。パッケージの追加やClaude Codeの設定変更は不要です。

タスクごとに別のローカルJSONファイルを用意します。複数のエージェントでひとつのファイルを共有しないでください。保存先のディレクトリは先に作っておきます。

python3 agent-eta.py --file ./eta-demo.json write --state working --phase verification --min 5 --max 12
python3 agent-eta.py --file ./eta-demo.json show

最初は、おおむね次のように表示されます。

verification | WORKING | rough next-attention window 5-12m | declared, not calibrated

5〜12分は説明用に作った入力値で、ベンチマークでも保証でも、実際のタスクについての根拠でもありません。示しているのは次に注意が必要になりそうな時間帯であり、完成した解決策を受け取れる時刻ではありません。

2. わからない時間は、わからないままに

時間帯を示す根拠がない場合は、状態だけを記録します。

python3 agent-eta.py --file ./eta-demo.json write --state working --phase research

表示は next attention window unknownとなり、未入力の見積もりをゼロにはしません。有効な範囲内では、経過時間を差し引きます。上限を過ぎたら、 declared window expired; refresh needed と表示し、ゼロのまま誤解を招くカウントダウンを残しません。

3. 人の判断が必要になったら伝える

python3 agent-eta.py --file ./eta-demo.json write --state needs-input --phase implementation
python3 agent-eta.py --file ./eta-demo.json write --state waiting --phase external
python3 agent-eta.py --file ./eta-demo.json write --state ready --phase review

実際の状態変化に合わせて、それぞれ個別に実行します。順番どおりに機械的に実行するコマンド列ではありません。 INPUT NEEDED は、時間の見積もりより優先されます。 READY FOR REVIEW は、テスト合格を意味しません。外部の処理待ちでも、時間帯が報告されなければ所要時間は不明のままです。

このスクリプトは、実際の許可ダイアログやテスト結果を観測しません。記録の正確さと新しさは、書き手にかかっています。

4. ワークフローに明示的な更新を加える

最初は、作業段階が変わるたびに自分で記録を更新してみてください。後からエージェントに任せるなら、確認済みのスクリプトと専用ファイルを渡し、入力を求める前と作業を止めた後に更新するよう指示します。根拠のない時間帯は書かせません。

これは作業手順の指示であり、検証済みのClaude Code自動連携ではありません。ネイティブのステータスラインやライフサイクルフックへの対応は別の作業です。 show の呼び出しは、その時点の状態を1回表示するだけです。ライブダッシュボードやバックグラウンドのポーリングは作りません。タスクを確認するときに実行できます。

空き時間に何をするかを決める助けになるか、観察してみてください。数値だけで「離れても大丈夫」と判断しないこと。想定より早く質問が来る可能性は残ります。

5. 限界を確かめ、記録を片付ける

実装は合成した時刻と入力で検証しました。ファイルの欠落・破損、時間帯不明、期限切れ、人の対応待ち、不正な範囲、時計の変更を確認しています。24時間より古い記録は古いと表示します。実際のタスクの予測精度を実証したものではありません。

保存するのは、定義済みの状態・段階名、更新時刻、入力した時間帯だけです。ネットワーク通信、プロンプトの収集、履歴アーカイブはありません。更新時は同じファイルを上書きし、自動では削除しません。 eta-demo.json は、試用後にファイルマネージャーで削除してください。スクリプトとそのファイルを消せば元に戻ります。復元するエージェント設定はありません。

履歴による補正は、比較可能な完了タスクが蓄積してからでよいでしょう。それまでは、根拠のない精密そうな予測より、期限を明示したおおまかな範囲の方が役に立ちます。