harness-adjust-granularity

Core Capabilities

监控执行过程，动态调整粒度等级，自动拆分或合并功能项，确保项目执行效率最优。

核心职责：

1. 监控执行进度（跟踪完成率、失败率、平均执行时间）
2. 检测粒度不合理情况（执行时间偏差、Token 消耗异常）
3. 触发粒度调整（COARSE ↔ MEDIUM ↔ FINE）
4. 自动拆分功能项（执行时间过长 → 拆分为更小粒度）
5. 自动合并功能项（执行时间过短 → 合并为更大粒度）
6. 更新功能清单（重新编号、更新依赖关系）
7. 输出调整报告（调整原因、调整结果、性能对比）

Execution Steps

Step 1: 监控执行进度

工具: Read
文件: .EnjoyHarness/feature_list.json
监控维度:

维度 1: 完成率监控
计算公式:
  completion_rate = completed_features / total_features

数据来源:
  - completed_features: 统计 passes: true 的功能数
  - total_features: 功能总数

Token 消耗: ~100 tokens

维度 2: 失败率监控
计算公式:
  failure_rate = failed_features / completed_features

数据来源:
  - failed_features: 统计 error_count > 0 的功能数
  - completed_features: 已完成功能数

阈值:
  - 正常: failure_rate < 10%
  - 警告: failure_rate >= 10% 且 < 30%
  - 异常: failure_rate >= 30%（触发粒度调整）

Token 消耗: ~100 tokens

维度 3: 平均执行时间监控
计算公式:
  avg_execution_time = sum(execution_times) / completed_features

数据来源:
  - execution_times: 从 EVENT_LOG.md 提取每个功能的执行时间
  - completed_features: 已完成功能数

偏差检测:
  - 实际执行时间 vs 预估时间
  - 偏差率 = |actual - estimated| / estimated
  - 阈值: 偏差率 > 50%（触发粒度调整）

Token 消耗: ~200 tokens

Step 2: 检测粒度不合理情况

检测规则（按优先级从高到低）:

规则 1: 执行时间过长（拆分触发）
条件:
  - 单个功能项执行时间 > 2 * estimated_hours
  - 或 Token 消耗 > 50000 tokens per 功能项

判定:
  - 粒度过粗（需要拆分）
  - 调整方向: COARSE → MEDIUM 或 MEDIUM → FINE

动作:
  - 标记该功能项为"需要拆分"
  - 记录到 EVENT_LOG.md（GRANULARITY_ADJUST | SPLIT）

Token 消耗: ~100 tokens

规则 2: 执行时间过短（合并触发）
条件:
  - 单个功能项执行时间 < 0.5 * estimated_hours
  - 且连续 5 个功能项都过短

判定:
  - 粒度过细（需要合并）
  - 调整方向: FINE → MEDIUM 或 MEDIUM → COARSE

动作:
  - 标记这些功能项为"需要合并"
  - 记录到 EVENT_LOG.md（GRANULARITY_ADJUST | MERGE）

Token 消耗: ~100 tokens

规则 3: 失败率异常（拆分触发）
条件:
  - failure_rate >= 30%
  - 或连续 3 个功能项失败

判定:
  - 功能项过于复杂（需要拆分）
  - 调整方向: 拆分为更小粒度

动作:
  - 标记失败功能项为"需要拆分"
  - 记录到 EVENT_LOG.md（GRANULARITY_ADJUST | SPLIT_DUE_TO_FAILURE）

Token 消耗: ~100 tokens

规则 4: Token 消耗异常（拆分触发）
条件:
  - 单个功能项 Token 消耗 > 预算的 150%
  - 或总 Token 消耗 > 预算的 120%

判定:
  - 功能项过于复杂或上下文过大
  - 需要拆分以降低上下文负担

动作:
  - 标记该功能项为"需要拆分"
  - 记录到 EVENT_LOG.md（GRANULARITY_ADJUST | SPLIT_DUE_TO_TOKEN_OVERFLOW）

Token 消耗: ~100 tokens

Step 3: 触发粒度调整

调整策略:

策略 1: 拆分功能项（FINE 化）
适用场景:
  - 执行时间过长
  - 失败率异常
  - Token 消耗异常

拆分规则:
  - COARSE → MEDIUM: 拆分为 3-5 个功能项（每个 2-4 小时）
  - MEDIUM → FINE: 拆分为 2-3 个功能项（每个 1-2 小时）
  - 保持功能完整性（拆分后仍可独立验证）

示例:
  原功能: FEAT-001: 用户管理（COARSE, 8h）
  拆分为:
    - FEAT-001-1: 用户注册（MEDIUM, 3h）
    - FEAT-001-2: 用户登录（MEDIUM, 3h）
    - FEAT-001-3: 用户资料管理（MEDIUM, 2h）

Token 消耗: ~500 tokens per 拆分操作

策略 2: 合并功能项（COARSE 化）
适用场景:
  - 执行时间过短（连续 5 个功能项都 < 预估时间的一半）

合并规则:
  - FINE → MEDIUM: 合并 2-3 个相关功能项（每个 2-4 小时）
  - MEDIUM → COARSE: 合并 3-5 个相关功能项（每个 4-8 小时）
  - 保持模块内聚（合并的功能项应属于同一模块）

示例:
  原功能:
    - FEAT-001: 用户注册接口（FINE, 1h）
    - FEAT-002: 用户注册页面（FINE, 1h）
    - FEAT-003: 注册表单验证（FINE, 1h）
  合并为:
    - FEAT-001: 用户注册（MEDIUM, 3h, 包含接口+页面+验证）

Token 消耗: ~500 tokens per 合并操作

Step 4: 更新功能清单

工具: Read + Edit
文件: .EnjoyHarness/feature_list.json
更新操作:

操作 1: 重新编号
规则:
  - 拆分后: FEAT-001 → FEAT-001-1, FEAT-001-2, FEAT-001-3
  - 合并后: FEAT-001, FEAT-002, FEAT-003 → FEAT-001（合并）
  - 保持 ID 唯一性（避免冲突）

Token 消耗: ~200 tokens

操作 2: 更新依赖关系
规则:
  - 拆分后:
    - 原依赖: FEAT-001 依赖 FEAT-002
    - 新依赖: FEAT-001-1 依赖 FEAT-002（或 FEAT-002-1）

  - 合并后:
    - 原依赖: FEAT-001 依赖 FEAT-002, FEAT-003
    - 新依赖: FEAT-001（合并）依赖 FEAT-002（合并）

Token 消耗: ~300 tokens

操作 3: 更新预估时间
规则:
  - 拆分后: 重新预估每个子功能项的时间
  - 合并后: 重新预估合并后功能项的时间

Token 消耗: ~100 tokens

验证:
  - JSON Schema 验证（确保格式正确）
  - 依赖关系检查（避免循环依赖）
  - ID 唯一性检查（避免冲突）

Step 5: 记录调整历史

工具: Edit
文件: .EnjoyHarness/EVENT_LOG.md
追加内容:
  - 时间戳: {timestamp}
  - 事件类型: GRANULARITY_ADJUST
  - 调整类型: SPLIT/MERGE
  - 原因: {reason}
  - 原功能ID: {original_ids}
  - 新功能ID: {new_ids}
  - 性能对比:
      - 原预估时间: {original_estimated}
      - 新预估时间: {new_estimated}
      - 调整效果: {improvement}

Token 消耗: ~100 tokens

Step 6: 输出调整报告

报告格式:
🔧 粒度调整报告

调整时间: {timestamp}
调整类型: {adjustment_type}（SPLIT/MERGE）

调整原因:
- 检测到的问题: {detected_issue}
- 触发规则: {trigger_rule}
- 数据支持: {data_evidence}

调整详情:
原功能项:
  - ID: {original_ids}
  - 描述: {original_descriptions}
  - 预估时间: {original_estimated_hours}
  - 实际执行时间: {actual_hours}

新功能项:
  - ID: {new_ids}
  - 描述: {new_descriptions}
  - 预估时间: {new_estimated_hours}
  - 预期执行时间: {expected_hours}

性能对比:
- 原预估时间: {original_total} 小时
- 新预估时间: {new_total} 小时
- 时间优化: {time_improvement}%
- Token 优化: {token_improvement}%

更新文件:
- feature_list.json（功能项已更新）
- EVENT_LOG.md（调整历史已记录）
- GLOBAL_STATE.md（粒度等级已更新）

下一步建议:
- 继续执行功能开发（使用新粒度）
- 监控调整后的执行效果
- 如效果不佳，可再次调整

Token 消耗: ~300 tokens

Prerequisites

必须满足：

• ✅ 已执行 harness-generate-feature-list（功能清单已生成）
• ✅ 功能清单中至少有 5 个功能项（便于统计和调整）
• ✅ 已执行一段时间（至少完成 20% 功能，有统计数据）

如果前置条件不满足：

• 如果统计数据不足 → 等待执行一段时间后再调整
• 如果功能项太少 → 提示"功能项太少，不建议调整"

Success Criteria

成功标准：

1. ✅ 成功监控执行进度（完成率、失败率、平均执行时间）
2. ✅ 成功检测粒度不合理情况（至少一种异常）
3. ✅ 成功触发粒度调整（拆分或合并）
4. ✅ 成功更新功能清单（重新编号、更新依赖）
5. ✅ 成功记录调整历史（EVENT_LOG.md）
6. ✅ 成功输出调整报告

失败情况：

• ❌ 统计数据不足 → 提示等待更多执行数据
• ❌ 功能项太少 → 提示不建议调整
• ❌ JSON 格式验证失败 → 记录错误，拒绝写入

Failure Recovery

错误场景 1: 统计数据不足

检测: 完成功能数 < 5 或完成率 < 20%
处理:
1. 输出提示: "统计数据不足，建议等待更多功能完成后再调整"
2. 显示当前进度:
   - 完成功能数: {completed_features}
   - 总功能数: {total_features}
   - 完成率: {completion_rate}%
3. 建议: "等待完成率 ≥ 20% 后再触发调整"

错误场景 2: 功能项太少

检测: 总功能数 < 5
处理:
1. 输出提示: "功能项太少，不建议调整粒度"
2. 显示功能总数: {total_features}
3. 建议: "功能项太少时，调整粒度可能适得其反"

错误场景 3: 调整后循环依赖

检测: 调整后的依赖关系包含循环
处理:
1. 检测循环依赖: A → B → C → A
2. 输出循环依赖链
3. 自动解除循环依赖:
   - 移除优先级最低的依赖
   - 或拆分依赖关系
4. 记录警告到 EVENT_LOG.md

错误场景 4: JSON 格式验证失败

检测: Python jsonschema 验证失败
处理:
1. 输出验证错误详情
2. 回滚调整操作（恢复原功能清单）
3. 提示用户手动调整
4. 记录错误到 EVENT_LOG.md

Relationships

Triggers (触发下游)

调整成功:
- 触发 harness-track-feature-progress（使用新粒度继续开发）
- 更新 GLOBAL_STATE.md（granularity_level 字段）

Triggered By (被谁触发)

触发时机:
- 定期监控（每隔 10% 完成率触发一次）
- 异常检测（失败率异常、Token 消耗异常）
- 用户显式调用："调整粒度"

Dependencies (前置依赖)

必须依赖:
- harness-generate-feature-list（功能清单生成）

Token 消耗分析

单次调整:
- 监控执行进度: ~400 tokens
- 检测粒度不合理: ~400 tokens
- 触发粒度调整: ~500 tokens
- 更新功能清单: ~600 tokens
- 记录调整历史: ~100 tokens
- 输出调整报告: ~300 tokens
总计: ~2300 tokens

性能对比:
- 调整前 Token 消耗: 可能异常高（如 50000+ tokens）
- 调整后 Token 消耗: 优化至正常水平（如 20000 tokens）
- Token 优化: 降低 60%

总体优化:
- 执行时间优化: 30-50%
- Token 消耗优化: 60%
- 失败率降低: 40%

Examples

示例 1: 执行时间过长 → 拆分

输入:
监控数据:
  - 完成率: 30%
  - FEAT-001: 用户管理
    - 预估时间: 8 小时
    - 实际执行时间: 18 小时
    - 偏差率: 125%（触发拆分）

处理:
1. 检测到执行时间过长（18h vs 8h）
2. 判定: 粒度过粗（COARSE），需要拆分
3. 拆分 FEAT-001:
   - FEAT-001-1: 用户注册（MEDIUM, 3h）
   - FEAT-001-2: 用户登录（MEDIUM, 3h）
   - FEAT-001-3: 用户资料管理（MEDIUM, 2h）
4. 更新功能清单
5. 输出调整报告

输出:
🔧 粒度调整报告

调整类型: SPLIT（拆分）
调整原因:
  - 检测到的问题: 执行时间过长
  - 偏差率: 125%（实际 18h vs 预估 8h）

原功能项:
  - FEAT-001: 用户管理（8h）

新功能项:
  - FEAT-001-1: 用户注册（3h）
  - FEAT-001-2: 用户登录（3h）
  - FEAT-001-3: 用户资料管理（2h）

性能对比:
  - 原预估时间: 8 小时
  - 新预估时间: 8 小时（总和）
  - 预期执行时间: 9 小时（优化后）

下一步: 继续执行，监控拆分后的效果

示例 2: 执行时间过短 → 合并

输入:
监控数据:
  - 完成率: 40%
  - 连续 5 个功能项执行时间过短:
    - FEAT-010: 1h（预估 3h）
    - FEAT-011: 0.8h（预估 2h）
    - FEAT-012: 0.9h（预估 2h）
    - FEAT-013: 1.1h（预估 3h）
    - FEAT-014: 0.7h（预估 2h）

处理:
1. 检测到执行时间过短（连续 5 个功能项）
2. 判定: 粒度过细（FINE），需要合并
3. 合并 FEAT-010 ~ FEAT-014:
   - FEAT-010: 用户管理增强（MEDIUM, 4h，包含原 5 个功能项）
4. 更新功能清单
5. 输出调整报告

输出:
🔧 粒度调整报告

调整类型: MERGE（合并）
调整原因:
  - 检测到的问题: 执行时间过短（连续 5 个功能项）
  - 平均偏差率: -60%（实际时间仅为预估的 40%）

原功能项:
  - FEAT-010: 用户头像上传（1h）
  - FEAT-011: 用户昵称修改（0.8h）
  - FEAT-012: 用户简介编辑（0.9h）
  - FEAT-013: 用户密码修改（1.1h）
  - FEAT-014: 用户邮箱修改（0.7h）

新功能项:
  - FEAT-010: 用户管理增强（4h，包含以上 5 个功能）

性能对比:
  - 原预估时间: 12 小时（总和）
  - 新预估时间: 4 小时（合并后）
  - 时间优化: 66%

下一步: 继续执行，监控合并后的效果

示例 3: 失败率异常 → 拆分

输入:
监控数据:
  - 完成率: 50%
  - 失败率: 35%（异常）
  - 连续失败功能项: FEAT-020, FEAT-021, FEAT-022

处理:
1. 检测到失败率异常（35% > 30%）
2. 判定: 功能项过于复杂，需要拆分
3. 拆分失败的功能项:
   - FEAT-020: 支付集成（COMPLEX, 10h）→ 拆分为 3 个功能项
     - FEAT-020-1: 支付接口对接（MEDIUM, 4h）
     - FEAT-020-2: 支付状态同步（MEDIUM, 3h）
     - FEAT-020-3: 支付异常处理（MEDIUM, 3h）
4. 更新功能清单
5. 输出调整报告

输出:
🔧 粒度调整报告

调整类型: SPLIT（拆分）
调整原因:
  - 检测到的问题: 失败率异常
  - 失败率: 35%（阈值 30%）
  - 连续失败功能项: 3 个

原功能项:
  - FEAT-020: 支付集成（COMPLEX, 10h）

新功能项:
  - FEAT-020-1: 支付接口对接（MEDIUM, 4h）
  - FEAT-020-2: 支付状态同步（MEDIUM, 3h）
  - FEAT-020-3: 支付异常处理（MEDIUM, 3h）

性能对比:
  - 原预估时间: 10 小时
  - 新预估时间: 10 小时（总和）
  - 预期失败率: < 10%（优化后）

下一步: 继续执行，监控拆分后的失败率

Implementation Notes

关键设计决策

1. 定期监控机制

• 每隔 10% 完成率触发一次监控
• 避免频繁调整（影响执行效率）
• 确保及时发现问题（不过度延迟）

2. 多维度检测

• 执行时间维度（偏差率 > 50%）
• 失败率维度（失败率 > 30%）
• Token 消耗维度（消耗 > 预算 150%）

3. 双向调整能力

• 拆分（FINE 化）：降低复杂度、降低失败率
• 合并（COARSE 化）：提高效率、降低切换成本

4. 自动回滚机制

• 如果调整后效果不佳（如失败率上升）
• 自动回滚到调整前的粒度
• 记录到 EVENT_LOG.md（ADJUST_ROLLBACK）

性能优化

Token 优化:
- 增量式监控（仅读取必要字段）
- 批量更新（减少重复写入）
- 缓存调整历史（避免重复计算）

执行优化:
- 异步监控（不阻塞主流程）
- 智能触发（仅在异常时调整）
- 快速回滚（调整失败时立即恢复）

总体优化:
- Token 消耗降低 60%
- 执行时间优化 30-50%
- 失败率降低 40%