Skip to content

Latest commit

 

History

History
127 lines (96 loc) · 3.01 KB

value-observability-guide.md

File metadata and controls

127 lines (96 loc) · 3.01 KB

Value 可观测指南

使用 sce value metrics 将 Spec 交付变成可量化、可审计的周度结果。

为什么这很重要

很多 AI 开发流程可以“产出代码”，但难以回答：

  • 本周是否比上周交付更快？
  • 质量是在改善还是恶化？
  • Day30/Day60 是否应该放行？

sce 通过机器可读 KPI 快照、基线生成、趋势分析和门禁摘要，解决以上问题。

四条命令跑通 KPI 流程

# 0) 首次使用先生成输入样例
sce value metrics sample --out ./kpi-input.json --period 2026-W10 --json

# 1) 生成当周快照
sce value metrics snapshot --input ./kpi-input.json --period 2026-W10 --checkpoint day-60 --json

# 2) 从最早历史快照生成 baseline
sce value metrics baseline --from-history 3 --period 2026-W10 --json

# 3) 基于最近窗口输出趋势与风险
sce value metrics trend --window 6 --json

最小输入示例

如果不使用 sample 命令，也可以手工创建 kpi-input.json：

{
  "period": "2026-W10",
  "metrics": {
    "ttfv_minutes": 25,
    "batch_success_rate": 0.86,
    "cycle_reduction_rate": 0.34,
    "manual_takeover_rate": 0.16
  },
  "notes": "weekly review snapshot"
}

预期 JSON 输出示例

snapshot --json 会返回可机器读取的摘要结果：

{
  "success": true,
  "period": "2026-W10",
  "risk_level": "medium",
  "triggered_metrics": [
    "manual_takeover_rate"
  ],
  "snapshot_path": ".sce/specs/114-00-kpi-automation-and-observability/custom/weekly-metrics/2026-W10.json",
  "gate_summary_path": ".sce/specs/114-00-kpi-automation-and-observability/custom/weekly-metrics/gate-summary.2026-W10.day-60.json",
  "contract_path": "metric-definition.yaml"
}

trend --json 会返回时间窗口、风险和指标方向信息：

{
  "success": true,
  "period": "2026-W10",
  "window_size": 3,
  "range": {
    "from": "2026-W08",
    "to": "2026-W10"
  },
  "risk_level": "high",
  "triggered_metrics": [
    "ttfv_minutes"
  ],
  "metrics": [
    {
      "metric_id": "ttfv_minutes",
      "delta": 3,
      "trend": "up",
      "better_direction": "lower",
      "status": "degraded",
      "target_passed": true
    }
  ],
  "trend_path": ".sce/specs/114-00-kpi-automation-and-observability/custom/weekly-metrics/trend.latest.json"
}

周度运行节奏（建议）

  1. 每周主要交付批次完成后执行一次 snapshot。
  2. 当流程或范围发生明显变化时重建 baseline。
  3. Day30/Day60 决策前执行 trend。
  4. 将输出 JSON 作为评审证据附在周报/门禁记录中。

你将获得

  • 可审计：每次计算都有输入输出可追溯。
  • 可比较：跨周、跨 Agent 使用统一指标口径。
  • 可门禁复用：直接生成 Day30/Day60 可消费的决策输入。
  • 可行动：风险触发原因清晰，不再依赖主观判断。

相关文档