Gitlab Efficiency Metrics

gitlab-efficiency-metrics — GitLab 効率性メトリクス

GitLab のイシュー・MR の活動量を収集し、エージェントを使ったことで人のコストをどれだけ削減できたか を推定する。 リポジトリ別・ユーザー別・AI/人別 の軸で内訳を出し、状態ファイルで増分集計・差分・再解析ができる。

中核は決定論的な収集・算出スクリプト scripts/efficiency.py。収集と計算はスクリプトが行い、 エージェントは前提値の確認・結果の解釈・レポート提示を担う。

前提条件

• Python 3.8+（stdlib のみ）
• GitLab パーソナルアクセストークン（read_api で十分）→ GITLAB_TOKEN 環境変数 または connections.yaml
• 同じ skills ディレクトリに gitlab-idd スキルが必要（GitLab 接続・認証の gl.py を再利用する）
• 対象は git remote origin / connections.yaml から解決する。複数リポジトリも指定可能

接続が未設定の場合は gitlab-idd スキルの configure で設定する。

何を測るか（生メトリクス）

3 つの軸と AI/人 の判定

各メトリクスは (リポジトリ, ユーザー, 種別=ai/human) のセルに割り当てられ、以下に集計される:

• totals: 全体。by_kind（ai / human）の内訳付き。コスト削減推定は ai 種別 に対して計算する
• by_repo: リポジトリ別（--axis に repo）
• by_user: ユーザー別（--axis に user）。差し戻しはユーザー帰属しないため by_user の推定には含めない
  • 成果物バイト数は MR 作成者（実装者）に帰属。推定レビューコストは既定で MR が closes する元イシューの作成者（リクエスター）に帰属する（--review-credit、紐付け不可なら MR 作成者へフォールバック）。mr-author で実装者帰属に切替可。帰属先を変えても totals・純削減額は不変

AI / 人の判定は投稿・MR ごとに行う（アカウントを共有していても判別できる）:

1. 本文に AI マーカー が含まれれば ai（既定: gitlab-idd の worker-node-id 等のマーカー、Co-Authored-By: Claude、🤖 Generated with など）
2. または作成者が --agent-users 集合（既定は認証ユーザー）に含まれれば ai
3. それ以外は human

マーカーは --ai-markers（|| 区切りの正規表現）で置換、対象ユーザーは --agent-users（カンマ区切り、空文字でマーカー判定のみ）で変更する。

ワークフロー

Step 1: 前提を確認する

コスト推定は前提値に強く依存する。実行前に最低限これらをユーザーに確認するか、既定値で進めてよいか合意する:

• 対象期間（既定: 直近 30 日。状態ファイルがあれば前回の続きから増分）
• エージェント判定（AI マーカー＋--agent-users。アカウント共有なら特に重要）
• 対象リポジトリ（単一 / --projects / --conn-labels）
• 人件費（既定 6,000 JPY/h）と実装スループット（LOC/人日）

前提の意味は references/cost-model.md を参照する。

Step 2: 収集・算出を実行する

# 直近 30 日・既定前提・Markdown レポート（サブコマンド collect は省略可）
python scripts/efficiency.py collect --days 30 --format markdown

# 複数リポジトリ（同一接続のホスト上）／軸を限定
python scripts/efficiency.py collect --projects ns/a,ns/b --axis repo,user

# 複数インスタンス（connections.yaml のラベル）
python scripts/efficiency.py collect --conn-labels default,work --format markdown

# AI 判定ユーザーを明示（アカウント共有時）
python scripts/efficiency.py collect --days 30 --agent-users bot-node-a,bot-node-b

# 前提を組織値で上書き
python scripts/efficiency.py collect --days 30 --params-file my_params.json

# 機械処理用に単一フィールドだけ取り出す
python scripts/efficiency.py collect --days 30 --get totals.estimate.savings.mid

python は環境に応じて python3 / py に読み替える。収集の内訳は --verbose（stderr）。

Step 3: 状態を記録して増分・差分・再解析する

--state-file でリポジトリ毎の処理済み時刻（カーソル）とラン履歴を記録する。呼び出し側が状態を持つことで、 範囲を柔軟に指定して増分集計・差分・再解析ができる。

# 増分: --since 未指定かつカーソルがあれば前回の続きから集計し、状態を更新
python scripts/efficiency.py collect --state-file s.json --save-state --format markdown

# ラン履歴を一覧
python scripts/efficiency.py history --state-file s.json

# 直近 2 ランの差分（AI メトリクス・削減額の delta）
python scripts/efficiency.py diff --state-file s.json
# 任意のランを比較
python scripts/efficiency.py diff --state-file s.json --a 0 --b -1

# 再解析: 範囲を明示すればカーソルを無視して任意期間を再計算（--save-state を付けなければ状態は不変）
python scripts/efficiency.py collect --since 2026-05-01 --until 2026-06-01 --state-file s.json

--since を明示した場合はカーソルより優先される（＝再解析）。--save-state を付けたときだけ状態を更新する。

Step 4: 結果を提示・解釈する

--format markdown がそのままレポートになる（全体サマリ＋AI/人の生メトリクス＋リポジトリ別＋ユーザー別）。提示時は必ず:

• 削減はレンジで示す（楽観／最頻／悲観）。単一値を断定しない
• 前提を明記する（人件費・スループット・レビュー速度・AI 判定方法）
• 削減率の母数は「人手のみで作った場合の総コスト」、推定は ai 種別 に対するもの
• 異常値（成果物バイト数が極端に大きい等）は原因を指摘する（生成物・vendor・大量自動生成の混入など）

出力形式（JSON, collect）

{
  "window": { "since": "...", "until": "..." },
  "repos": ["ns/a", "ns/b"],
  "classification": { "agent_users": ["..."], "ai_markers": ["..."] },
  "totals": {
    "raw_metrics": { "deliverable_bytes": 0, "...": 0 },
    "by_kind": { "ai": { "...": 0 }, "human": { "...": 0 } },
    "estimate": {
      "currency": "JPY",
      "savings": { "low": 0, "mid": 0, "high": 0 },
      "savings_pct": { "low": 0, "mid": 0, "high": 0 },
      "human_hours_saved": { "low": 0, "mid": 0, "high": 0 },
      "scenarios": { "optimistic": {}, "most_likely": {}, "pessimistic": {} }
    },
    "time": {
      "ai_actual": { "cycle_time_days": 0, "active_time_days": 0, "active_counted": 0,
                     "closed_issue_count": 0, "avg_cycle_time_hours": 0, "avg_active_time_hours": 0 },
      "human_actual": { "cycle_time_hours": 0, "active_time_hours": 0, "closed_issue_count": 0 },
      "human_estimate_for_ai_work_days": { "low": 0, "mid": 0, "high": 0 },
      "time_saved_days": { "low": 0, "mid": 0, "high": 0 },
      "time_saved_net_days": { "low": 0, "mid": 0, "high": 0 }
    }
  },
  "by_repo": { "ns/a": { "raw_metrics": {}, "by_kind": {}, "estimate": {}, "time": {} } },
  "by_user": { "alice": { "kinds": ["ai"], "raw_metrics": {}, "by_kind": {}, "estimate": {} } }
}

savings.low（楽観）は人の生産性が高い前提＝削減が小さい側、savings.high（悲観）は削減が大きい側。 時間軸の time_saved_days（総）/ time_saved_net_days（正味=滞留除く）も同様（low＝人が速い前提で削減小）。人の見積もりは実働日なので、比較は正味の方が同次元に近い。time は totals / by_repo に付き、イシュー単位のため by_user には付かない。

ガードレール

行動指針

1. 収集はスクリプトに任せる — 生メトリクスの算出は efficiency.py が決定論的に行う。手作業で API を叩き直さない
2. 前提を先に握る — 期間・AI 判定・対象リポジトリ・人件費を確認し、合意した前提を結果に明記する
3. 削減の母数を明確に — 削減率は「人手のみ delivery の総コスト」に対する比率で、推定は ai 種別が対象
4. レビューは共通費 — 人手シナリオでもエージェントシナリオでも人のレビューは必要。削減は主に「実装工数の置き換え」から生じる（references/cost-model.md）
5. 状態で増分・再解析 — 継続運用では --state-file --save-state で増分集計し、diff で期間比較する。再解析は --since/--until を明示する
6. 異常値を疑う — 桁外れの成果物バイト数や削減率は生成物混入や前提のズレを示唆する。鵜呑みにせず原因を添える