efficiency-metrics

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}}