無人エージェントの夜間作業を KPI 化する（「完走しました」を成果の証明にしない）

残タスクを無人エージェントに夜間消化させる構成では、朝に届く報告が **「N/N セッション完走・失敗0」**になりやすい。これは成果の証明になっていない。 実測すると、38セッション完走のうち 25本が「既に修正済み・差分ゼロ」で何も生んでいなかった （＝空回り）という状態が、失敗0のまま何日も続く。

この指示書は、無人作業の成果を数字にするための 指標の設計 を与える。 特に 空回り分をコスト削減効果から差し引くという一点が要で、これを外すと 「無駄に多く回すほど削減効果が増える」という逆向きの指標になる。

読み替えて使う前提:

• <残タスク台帳>: 残タスクが書かれたファイル。完了は打ち消し線＋チェック印などで印が付く
• <実行記録>: 1セッション＝1ファイルの JSON。開始/終了時刻・終了ステータス・要約・ モデル別トークン・実コストを持つ
• <バッチログ>: 夜間バッチの1行1ステップのログ

---

1. 主KPIは3つに絞る

KPI	式	意味
消化率 closeRate	夜間に完了した残タスク ÷ 夜間開始時点の未消化数	どれだけ進んだか
空回り率 noOpRate	実質何もしなかったセッション ÷ 全セッション	どれだけ無駄に回したか
コスト削減効果 netSaving	(同トークンを高価モデルで処理した換算 − 実コスト) − 空回り分	差引でいくら得したか

補助として、残数・純減・成果率（夜間に作られた PR 数 ÷ セッション数）・ バッチが実際に動いたか・完了1件あたりの削減額を出す。

夜間の窓を先に固定する

「前日18:00 〜 当日09:00（ローカル時刻）」のように両端を含む窓を決め、 セッションは開始時刻がこの窓に入るものだけを対象にする。境界はテストで固定する （17:59は対象外 / 18:00は対象 / 09:00は対象 / 09:01は対象外）。

消化数は「後ろ向きに逆算」する

夜間開始時点のスナップショットは普通残っていない。取りに行かずに逆算する。

backlogAtEnd    = 現時点で完了印が無い残タスク数（重複除去後）
closedOvernight = 完了日が対象日（または前日で夜間窓内）の残タスク数
backlogAtStart  = backlogAtEnd + closedOvernight
netBurnDown     = backlogAtStart - backlogAtEnd

<残タスク台帳> が過去ブロックを積み上げる構造なら、同じタスクが文言違いで複数回書き写されている。 これを畳まないと分母が水増しされ closeRate が歪む。完全一致で畳んだうえで、 近似一致（日本語は文字bi-gram、英数字は語単位の Jaccard、閾値0.7程度）でもう一段畳む。 クラスタ内に1つでも完了印があれば完了として数える。

---

2. 空回り率 — これが改善の駆動輪

「実質何もしなかった」の判定は、セッションの要約と最終応答を結合したテキストに対する 定型句マッチで足りる。判定語は名前付き定数にまとめて1か所で足せるようにしておく。

コード変更(は)?不要 / 差分ゼロ / 既に修正済み / 変更ゼロ / 実装は不要 /
再実装は行わなかった / already (fixed|resolved|merged) / no (new )?code

空回りが起きる典型は 完了済みタスクが台帳に残り続け、毎晩再配布されること。 だから空回り率が閾値（30%程度）を超えたら、 「台帳の完了済みブロックを刈る」という改善タスクを自動で起票する。 実測では、この起票を1回入れただけで次の測定で空回り率が 65.8% → 0% に落ちた。

---

3. コスト削減効果 — 空回り分を必ず差し引く

nightCost        = 実行記録の実コスト合計（欠けていればモデル別トークン×単価で算出）
supervisorEquiv  = 同じトークン量を「高価な監督モデル」の単価で再計算した反実仮想
modelSaving      = supervisorEquiv - nightCost
wasted           = 空回りセッションのコスト合計
netSaving        = modelSaving - wasted          ← これを主KPIにする
savingPerTask    = netSaving / closedOvernight

wasted を引かない設計にしてはいけない。 引かないと、無駄なセッションを増やすほど modelSaving が積み上がり、KPI が改善したように見える。実測では modelSaving 41.26 / wasted 19.50 / netSaving 21.76 で、無駄が削減効果のほぼ半分を食っていた。

出力には必ず「これは list 価格換算であり実請求額ではない」と明記する。 定額プランで動かしている場合、この数字は請求額ではない。

---

4. 「動いたか」の検証はログの不在を見る

ここを間違えると、検証しているつもりで何も検証していない状態になる。

• ログファイルが存在しない = 異常。ステップ 0/0 を「正常」と丸めない
• ログはあるが最終サマリ行が無い = 途中で停止
• 取得できなかった値（スケジューラ情報など）は null にする。0 や「正常」に丸めない

結果語の表記ゆれで取りこぼす

1行1ステップのログは、実運用でコロン付きとコロン無しが混在する。 ok: の前方一致だけで数えると、素の ok を1件も数えない。 失敗語も error: だけでなく NG などが実在する。実ログを全行読んで語彙表を作る。

分類	表記例	出力先
成功	ok / ok:...	stepsOk
失敗	error:... / NG / NG:...	failedSteps
警告	warn:...	warnSteps（失敗と分けて数える）

サマリ行はステップ数から除外し、完了判定にだけ使う。 実測では、この取りこぼしで ok=7/24（実際は22件が成功）と誤報していた。

---

5. 測れない指標は載せない

「同じテーマに何本張り付いたか（テーマ集中率）」は、直感的で欲しくなるが実測では作れなかった。 記録として残す（同じ試行を繰り返さないため）。

長文どうしの Jaccard 係数は和集合が支配的になり、人手判定 約74%（29/39） に対して:

キーにした欄	閾値0.3	0.4	0.5
タスク文のみ	7.7%	5.1%	5.1%
要約全文	7.7%	5.1%	5.1%
要約の目的節	5.1%	2.6%	2.6%

代替案の「着手時点で完了済みのタスクを配られた率」も 1/39 で不発だった。 完了印はその夜のセッション自身が事後に付けるので、配布時点の重複は検知できない。

実態74%に対して5%と出す指標は、無いより悪い。 取り下げて、 精確に測れる 成果率（PR数 ÷ セッション数） に差し替えた。判断の基準はこれ:

指標を実データに当て、人手の実測値と桁が合わなければ棄却する。 閾値をいじって数字を合わせにいかない。

---

6. 改善の自動起票（ループを閉じる）

測るだけでは改善しない。閾値割れで <残タスク台帳> の先頭へ改善タスクを重複なしで追記する。

条件	起票
ログ不在	P0: バッチが起動直後に死んでログを1行も書いていない
サマリ行なし	P0: 途中停止。最終ステップ = ...
失敗ステップあり	P1: ステップ失敗: ...
空回り率 > 30%	P1: 完了済みタスクが台帳に残り再配布されている。完了ブロックを刈る
成果率 < 30% かつ セッション数 ≥ 5	P1: N セッションに対し成果 M 件。タスクの粒度と配り方を見直す

毎朝おなじ内容を積まないこと。 未完了の同内容タスクが既にあれば追記しない。

通知の失敗で KPI 算出自体を失敗扱いにしない（通知不達とデータ欠損は別物）。

---

7. 実行時刻は既存タスクとぶつけない

KPI 集計タスクを既存の定期タスクと同じ時刻に置かない。 同時刻起動は、共有リポジトリ・共有ログファイルの奪い合いで 「片方が rc=1・ログ0行で無音死」を起こす。数分ずらし、ランダム遅延を付ける。

---

検証（ここまでやって「できた」と言う）

1. ユニットテスト: 窓の境界 / ログ不在 / サマリ行なし / 表記ゆれ（ok と ok:、NG と NG:）/ 重複タスクの畳み込み / 分母0で null / 壊れた JSON でも落ちない / 同内容タスクの再起票なし
2. 実データで空撃ちし、人手で数えた値と突き合わせる。ずれたら数字を丸めず、ずれた事実を記録する
3. 実際に定期実行させ、翌朝に出力ファイルが生成されていることを確認する （登録しただけで動いていない、が最も多い失敗）