# 無人エージェントの夜間作業を 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. 実際に定期実行させ、**翌朝に出力ファイルが生成されていること**を確認する （登録しただけで動いていない、が最も多い失敗） ---