Efficiency Metrics

Triggers

• metrics-agent 启动 / /report 命令

Baseline 双口径（必须同时产生）

管道 A：历史同类项目工时

• 从最近 6 个月的真实项目里选 3–5 个可比案例
• 按阶段（需求 / 架构 / 前端 / 后端 / 联调 / 测试 / 文档）拆解实际工时
• 存入 baseline/historical-projects.csv（见模板格式）

管道 B：专家独立估算

• 架构师 + 项目经理各自独立估算（禁止在 PRD 之后参考任何实际产物）
• 两人估算差 > 20% → 开一次对齐会，消除差异
• 存入 baseline/estimation-rules.md

最终 baseline = 两者均值

• 封盘时机：/prd + /wbs 产出后、/impl 启动前
• 封盘命令：先解析 DDT_PLUGIN_ROOT；若 baseline/baseline.locked.json 不存在，再执行 node "$DDT_PLUGIN_ROOT/bin/baseline.mjs" --lock --hist baseline/historical-projects.csv --expert baseline/estimation-rules.md --out baseline/baseline.locked.json
• 封盘后禁止修改（防止后视偏差污染对比数据）
• baseline/baseline.locked.json 属于被交付项目目录，不属于插件源码目录

质量守门阈值（任一劣化即在报告首行标红 ⚠️）

• 覆盖率（branch）≥ 70%
• Review 阻塞级问题 = 0
• 验收标准通过率 = 100%
• 返工次数（相对基线）不上升
• 缺陷密度不上升

Report Structure（硬性，不可省略任一章节）

1. 摘要：一句话结论 + ⚠️ 劣化告警（若有，必须是报告第一行）
2. 阶段级对比表： | 阶段 | 基线（h） | 实际（h） | 节省（h） | 提效% | （按"提效%"降序排，负值表示劣化）
3. 质量守门表：覆盖率 / 阻塞级 / 验收通过率 / 返工次数 / 缺陷密度
4. 三个分析问题的回答：
   • 哪个阶段提效最多？为什么？
   • 哪个阶段提效最少或劣化？根因是什么？
   • 下次怎么优化？给出 ≤ 3 条可执行建议
5. Top 3 优化建议（必须可执行，不能是"加强 XX"）
6. 原始数据链接：events.jsonl 路径 + metrics.db dump 命令

数据链路（hooks → 脚本 → 报告）

hooks → ~/.claude/delivery-metrics/events.jsonl → bin/aggregate.mjs → metrics.db ┐
                                                                                  ├→ bin/report.mjs → docs/efficiency-report.raw.md
baseline/historical-projects.csv + baseline/estimation-rules.md                  │
      → bin/baseline.mjs → baseline/baseline.locked.json ────────────────────────┘
docs/efficiency-report.raw.md → metrics-agent → docs/efficiency-report.md

events.jsonl 字段结构：

{"event":"session_start","ts":"2026-01-01T00:00:00Z","project_id":"<id>","data":{"session_id":"<uuid>","cwd":"<path>"}}
{"event":"session_end","ts":"2026-01-01T01:00:00Z","project_id":"<id>","data":{"session_id":"<uuid>","tokens_input":1000,"tokens_output":500}}
{"event":"pre_tool_use","ts":"2026-01-01T00:10:00Z","project_id":"<id>","data":{"session_id":"<uuid>","tool_name":"Write","file_path":"docs/prd.md"}}
{"event":"post_tool_use","ts":"2026-01-01T00:10:02Z","project_id":"<id>","data":{"session_id":"<uuid>","tool_name":"Write","success":true,"output_size":2048}}
{"event":"subagent_stop","ts":"2026-01-01T00:30:00Z","project_id":"<id>","data":{"session_id":"<uuid>","subagent_name":"product-agent","duration_ms":120000,"tokens_input":1000,"tokens_output":500}}
{"event":"quality_metrics","ts":"2026-01-01T00:40:00Z","project_id":"<id>","data":{"defects_critical":0,"defects_major":1,"defects_minor":2,"coverage_pct":72.5,"rework_count":0,"acceptance_pass_pct":100}}

Do

• 所有百分比保留 1 位小数（如 42.3%）
• 对比表按"提效%"降序排列
• 优化建议必须可执行（"下次 /design 前先跑一次 lint" ✅ 而不是"加强设计" ❌）
• baseline 封盘后每次新项目开始都重新 lock

Don't

• 不修改 raw 数据（docs/efficiency-report.raw.md 由脚本生成，禁止手改）
• 不在 baseline 封盘后调整基线（即使实际工时严重偏差）
• 不隐藏劣化指标（所有指标必须如实上报，包括负向结果）
• 不用"相对上次提升了"代替"相对基线提升了"（基线是封盘值，不是上次报告）

Templates & References

• templates/efficiency-report.template.md
• bin/aggregate.mjs（事件聚合）
• bin/baseline.mjs（基线封盘与读取）
• bin/report.mjs（原始报告生成）
• baseline/historical-projects.csv（历史项目数据格式）