task-quality-kpi

任务质量 KPI 框架

概述

任务质量 KPI 框架提供用于评估任务实现质量的客观、量化指标。

关键架构：KPI 由钩子自动生成——你只需读取结果，无需运行脚本。

┌─────────────────────────────────────────────────────────────┐
│  HOOK (auto-executes)                                       │
│  Trigger: PostToolUse on TASK-*.md                          │
│  Script: task-kpi-analyzer.py                               │
│  Output: TASK-XXX--kpi.json                                 │
├─────────────────────────────────────────────────────────────┤
│  SKILL / AGENT (reads output)                               │
│  Input: TASK-XXX--kpi.json                                  │
│  Action: Make evaluation decisions                          │
└─────────────────────────────────────────────────────────────┘

为什么采用这种架构？

问题	解决方案
技能无法执行脚本	钩子会在文件保存时自动运行
主观的 review_status	量化的 0-10 分
“我觉得不错”	基于证据的评估
二元的通过/失败	分级的质量水平

KPI 文件位置

修改任何任务文件后，可在以下位置找到 KPI 数据：

docs/specs/[ID]/tasks/TASK-XXX--kpi.json

KPI 类别

┌─────────────────────────────────────────────────────────────┐
│                    OVERALL SCORE (0-10)                     │
├─────────────────────────────────────────────────────────────┤
│  Spec Compliance (30%)                                      │
│  ├── Acceptance Criteria Met (0-10)                         │
│  ├── Requirements Coverage (0-10)                           │
│  └── No Scope Creep (0-10)                                  │
├─────────────────────────────────────────────────────────────┤
│  Code Quality (25%)                                         │
│  ├── Static Analysis (0-10)                                 │
│  ├── Complexity (0-10)                                      │
│  └── Patterns Alignment (0-10)                              │
├─────────────────────────────────────────────────────────────┤
│  Test Coverage (25%)                                        │
│  ├── Unit Tests Present (0-10)                              │
│  ├── Test/Code Ratio (0-10)                                 │
│  └── Coverage Percentage (0-10)                             │
├─────────────────────────────────────────────────────────────┤
│  Contract Fulfillment (20%)                                 │
│  ├── Provides Verified (0-10)                               │
│  └── Expects Satisfied (0-10)                               │
└─────────────────────────────────────────────────────────────┘

类别权重

类别	权重	原因
规格符合度	30%	最重要——是否按要求构建？
代码质量	25%	技术卓越性
测试覆盖率	25%	验证与可信度
契约履行度	20%	与其他任务的集成

适用场景

• 读取 KPI 数据以评估任务质量
• 了解质量指标和评分明细
• 根据量化数据决定是继续迭代还是批准
• 将 KPI 检查集成到自动化循环中（agents_loop.py）
• 生成基于证据的评估报告

说明

1. 读取 KPI 数据（主要用途）

不要运行脚本——读取自动生成的文件：

Read the KPI file:
  docs/specs/001-feature/tasks/TASK-001--kpi.json

2. 了解数据

KPI 文件包含：

{
  "task_id": "TASK-001",
  "evaluated_at": "2026-01-15T10:30:00Z",
  "overall_score": 8.2,
  "passed_threshold": true,
  "threshold": 7.5,
  "kpi_scores": [
    {
      "category": "Spec Compliance",
      "weight": 30,
      "score": 8.5,
      "weighted_score": 2.55,
      "metrics": {
        "acceptance_criteria_met": 9.0,
        "requirements_coverage": 8.0,
        "no_scope_creep": 8.5
      },
      "evidence": [
        "Acceptance criteria: 9/10 checked",
        "Requirements coverage: 8/10"
      ]
    }
  ],
  "recommendations": [
    "Code Quality: Moderate improvements possible"
  ],
  "summary": "Score: 8.2/10 - PASSED"
}

3. 做出决策

使用 overall_score 和 passed_threshold：

IF passed_threshold == true:
  → Task meets quality standards
  → Approve and proceed

IF passed_threshold == false:
  → Task needs improvement
  → Check recommendations for specific targets
  → Create fix specification

与工作流集成

在任务审查中（evaluator-agent）

## Review Process

1. Read KPI file: TASK-XXX--kpi.json
2. Extract overall_score and kpi_scores
3. Read task file to validate
4. Generate evaluation report
5. Decision based on passed_threshold

在 agents_loop 中

# Check KPI file exists
kpi_path = spec_path / "tasks" / f"{task_id}--kpi.json"

if kpi_path.exists():
    kpi_data = json.loads(kpi_path.read_text())
    
    if kpi_data["passed_threshold"]:
        # Quality threshold met
        advance_state("update_done")
    else:
        # Need more work
        fix_targets = kpi_data["recommendations"]
        create_fix_task(fix_targets)
        advance_state("fix")
else:
    # KPI not generated yet - task may not be implemented
    log_warning("No KPI data found")

多轮迭代循环

不再最多重试 3 次，而是持续迭代，直到达到质量阈值：

Iteration 1: Score 6.2 → FAILED → Fix: Improve test coverage
Iteration 2: Score 7.1 → FAILED → Fix: Refactor complex functions  
Iteration 3: Score 7.8 → PASSED → Proceed

每次迭代都会在保存任务时自动更新 KPI 文件。

阈值指南

分数	质量等级	操作
9.0-10.0	卓越	批准并记录最佳实践
8.0-8.9	良好	批准，可附上简要说明
7.0-7.9	可接受	批准（如果阈值为 7.5）
6.0-6.9	未达标准	要求进行具体改进
< 6.0	较差	需要进行大幅返工

推荐阈值

项目类型	阈值	原因
生产级 MVP	8.0	需要高质量
内部工具	7.0	满足要求即可
原型	6.0	功能优先，无需完美
关键系统	8.5	不容妥协

指标详情

规格符合度指标

验收标准达成度

• 计算方式：(checked_criteria / total_criteria) * 10
• 来源：任务文件中的复选框计数
• 示例：勾选 9/10 项 = 9.0

需求覆盖率

• 计算方式：计算此任务覆盖的 REQ-ID 数量
• 来源：traceability-matrix.md
• 示例：覆盖 4 项需求 = 8.0

无范围蔓延

• 计算方式：(implemented_files / expected_files) * 10
• 来源：任务中的“要创建的文件”与实际文件对比
• 处罚因素：缺少文件或意外添加文件

代码质量指标

静态分析

• Java：Maven Checkstyle
• TypeScript：ESLint
• Python：ruff
• 评分：通过得 10 分，发现问题得 5 分

复杂度

• 计算方式：长度超过 50 行的函数
• 评分：10 - (long_functions_ratio * 5)
• 处罚因素：庞大、复杂的函数

模式一致性

• 检查：知识图谱中的模式
• 来源：knowledge-graph.json
• 验证：实现是否遵循项目模式

测试覆盖率指标

是否包含单元测试

• 计算方式：min(10, test_files * 5)
• 2 个测试文件 = 最高分
• 处罚因素：缺少测试

测试/代码比

• 计算方式：(test_count / code_count) * 10
• 1:1 比例 = 10/10
• 理想情况：每个代码文件至少对应 1 个测试文件

覆盖率百分比

• 来源：覆盖率报告（JaCoCo、lcov 等）
• 计算方式：coverage_percent / 10
• 覆盖率为 80% = 8.0

合约履行指标

提供项已验证

• 检查：文件存在且导出了预期符号
• 来源：任务 provides frontmatter
• 验证：合约已满足

预期项已满足

• 检查：依赖项提供所需文件/符号
• 来源：任务 expects frontmatter
• 验证：前置条件已满足

KPI 文件缺失时

如果 TASK-XXX--kpi.json 不存在：

1. 任务从未修改过——钩子会在保存文件时运行
2. 钩子运行失败——检查 Claude Code 日志
3. 任务是新建的——先保存文件以触发钩子

不要尝试手动计算 KPI。以下操作会自动运行钩子：

• 保存任务文件（Write 工具）
• 编辑任务文件（Edit 工具）

最佳实践

1. 始终检查 KPI 文件是否存在

评估前：

Check if KPI file exists:
  docs/specs/[ID]/tasks/TASK-XXX--kpi.json

If missing:
  - Task may not be implemented yet
  - Ask user to save the task file first

2. 信任指标

KPI 是客观的。只有在有记录的证据支持时才覆盖：

• 指标中未体现的严重安全问题
• 静态分析未发现的逻辑错误
• 未衡量的卓越质量

3. 针对较低的 KPI 进行迭代

针对具体类别：

❌ "Fix code quality issues"
✅ "Improve Code Quality KPI from 5.2 to 7.0:
    - Complexity: Refactor processData() (5→8)
    - Patterns: Add error handling (6→8)"

4. 跟踪 KPI 趋势

持续监控质量变化：

Sprint 1: Average KPI 6.8
Sprint 2: Average KPI 7.3 (+0.5)
Sprint 3: Average KPI 7.9 (+0.6)

故障排除

未生成 KPI 文件

检查：

1. hooks.json 中的钩子已启用
2. 任务文件名符合模式 TASK-*.md
3. 文件确实已保存（而非仅被查看）

KPI 分数似乎不正确

验证：

1. 检查 evidence 字段中的数据源
2. 确认文件存在于预期路径
3. 某些指标需要构建工具（Maven、npm）

代码质量良好但分数较低

可能的原因：

• 缺少测试文件
• 未生成覆盖率报告
• 未检查验收标准
• Lint 规则过于严格

修复根本原因，而不只是提高分数。

示例

示例 1：读取 KPI 数据

Read the KPI file to evaluate task quality:
  docs/specs/001-feature/tasks/TASK-042--kpi.json

Based on the data:
- Overall score: 6.8/10 (below threshold)
- Lowest KPI: Test Coverage (5.0/10)
- Recommendation: Add unit tests

Decision: REQUEST FIXES - target Test Coverage improvement

示例 2：迭代决策

Iteration 1 KPI: Score 6.2 → FAILED
- Spec Compliance: 7.0 ✓
- Code Quality: 5.5 ✗
- Test Coverage: 6.0 ✗

Fix targets:
1. Refactor complex functions (Code Quality)
2. Add test coverage (Test Coverage)

Iteration 2 KPI: Score 7.8 → PASSED ✓

示例 3：agents_loop 集成

# In agents_loop, after implementation step
kpi_file = spec_dir / "tasks" / f"{task_id}--kpi.json"

if kpi_file.exists():
    kpi = json.loads(kpi_file.read_text())
    
    if kpi["passed_threshold"]:
        print(f"✅ Task passed quality check: {kpi['overall_score']}/10")
        advance_state("update_done")
    else:
        print(f"❌ Task failed quality check: {kpi['overall_score']}/10")
        print("Recommendations:")
        for rec in kpi["recommendations"]:
            print(f"  - {rec}")
        advance_state("fix")

参考资料

• evaluator-agent.md - 使用 KPI 数据进行评估的 Agent
• hooks.json - 自动生成的钩子配置
• task-kpi-analyzer.py - 钩子脚本（请勿直接执行）
• agents_loop.py - 读取 KPI 并据此做出决策的编排器