# Harness Determine Granularity

> Harness Determine Granularity

- Skill: `konglong87/harness-determine-granularity` (Agent Skill)
- Install (CLI): `npx skillmds@latest add konglong87/harness-determine-granularity`
- Raw SKILL.md: https://api.skillmd.com/api/skills/konglong87/harness-determine-granularity/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: konglong87 (https://skillmd.com/u/konglong87)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/konglong87/harness-determine-granularity

---


# harness-determine-granularity

## Core Capabilities

基于项目规模分析，自动选择粒度等级（COARSE/MEDIUM/FINE），更新全局状态，推荐执行模式。

**核心职责**：
1. 读取项目规模分析报告（PROJECT_SCALE_REPORT.md）
2. 根据判定规则确定粒度等级
3. 推荐执行模式（快速/单会话/子代理并行）
4. 更新 GLOBAL_STATE.md（granularity_level 字段）
5. 更新 feature_list.json（granularity_level 字段）
6. 输出粒度决策报告

## Execution Steps

### Step 1: 读取项目规模分析报告

```yaml
工具: Read
文件: .EnjoyHarness/PROJECT_SCALE_REPORT.md
Token 消耗: ~300 tokens
失败处理:
- 如果文件不存在 → 提示"请先运行 harness-analyze-project-scale"
- 如果文件损坏 → 尝试重新分析项目规模
```

### Step 2: 提取关键数据

```yaml
提取字段:
- total_features: 功能总数
- total_apis: 接口总数
- estimated_hours: 预计执行时间
- complexity_level: 复杂度等级

Token 消耗: ~100 tokens
```

### Step 3: 应用判定规则

```yaml
判定规则（优先级从高到低）:

规则 1: FINE（细粒度）
条件:
  - 功能数 > 50 OR
  - 接口数 > 10 OR
  - 执行时间 > 100 小时
动作:
  - granularity_level = FINE
  - recommended_mode = 子代理并行
  - max_parallel_agents = 3

规则 2: MEDIUM（中粒度）
条件:
  - 功能数 >= 10 OR
  - 接口数 >= 5 OR
  - 执行时间 >= 20 小时
动作:
  - granularity_level = MEDIUM
  - recommended_mode = 单会话模式
  - max_features_per_session = 1

规则 3: COARSE（粗粒度）
条件:
  - 功能数 < 10 AND
  - 接口数 < 5 AND
  - 执行时间 < 20 小时
动作:
  - granularity_level = COARSE
  - recommended_mode = 快速模式
  - one_shot_execution = true

Token 消耗: ~100 tokens
```

### Step 4: 更新 GLOBAL_STATE.md

```yaml
工具: Edit
文件: .EnjoyHarness/GLOBAL_STATE.md
修改字段:
  granularity_level: COARSE/MEDIUM/FINE
  recommended_mode: 快速模式/单会话模式/子代理并行
  max_parallel_agents: 0/1/3
  estimated_hours: {从分析报告中读取}

Token 消耗: ~50 tokens
```

### Step 5: 更新 feature_list.json

```yaml
工具: Read + Edit
文件: .EnjoyHarness/feature_list.json
修改字段:
  granularity_level: COARSE/MEDIUM/FINE
  estimated_features_per_session: {基于粒度计算}

计算公式:
- COARSE: 所有功能（一次性完成）
- MEDIUM: 1 功能/会话
- FINE: 3 功能/批次（子代理并行）

Token 消耗: ~100 tokens
验证:
- 使用 Python jsonschema 验证 JSON 格式
```

### Step 6: 输出粒度决策报告

```yaml
报告格式:
🎯 粒度等级决策报告

项目规模数据:
- 功能总数: {total_features}
- 接口总数: {total_apis}
- 预计执行时间: {estimated_hours} 小时
- 复杂度等级: {complexity_level}

粒度等级: {granularity_level}
判定依据:
- 功能数: {total_features} ({criteria_features})
- 接口数: {total_apis} ({criteria_apis})
- 执行时间: {estimated_hours} 小时 ({criteria_time})

推荐执行模式: {recommended_mode}
配置参数:
- max_parallel_agents: {max_parallel_agents}
- max_features_per_session: {max_features_per_session}

下一步建议:
- 如果 FINE → 使用子代理并行模式，每批 3 个功能
- 如果 MEDIUM → 使用单会话模式，每次 1 个功能
- 如果 COARSE → 使用快速模式，一次性完成所有功能

Token 消耗: ~200 tokens
```

## Prerequisites

**必须满足**：
- ✅ 已执行 `harness-analyze-project-scale`（项目规模分析完成）
- ✅ 存在 PROJECT_SCALE_REPORT.md 文件

**如果前置条件不满足**：
- 如果缺少分析报告 → 自动调用 harness-analyze-project-scale

## Success Criteria

**成功标准**：
1. ✅ 成功读取项目规模分析报告
2. ✅ 正确应用判定规则
3. ✅ 成功更新 GLOBAL_STATE.md
4. ✅ 成功更新 feature_list.json
5. ✅ 输出详细的粒度决策报告

**失败情况**：
- ❌ 缺少分析报告 → 自动触发分析
- ❌ JSON 格式验证失败 → 记录错误，拒绝写入

## Failure Recovery

### 错误场景 1: 缺少分析报告

```yaml
检测: PROJECT_SCALE_REPORT.md 不存在
处理:
1. 自动调用 harness-analyze-project-scale
2. 等待分析完成
3. 继续执行粒度判定
```

### 错误场景 2: 数据提取失败

```yaml
检测: 无法提取关键字段（功能数、接口数、执行时间）
处理:
1. 尝试重新分析项目规模
2. 如果仍然失败 → 使用默认值:
   - 功能数: 10（MEDIUM）
   - 接口数: 5
   - 执行时间: 50 小时
3. 提示用户: "使用默认值估算"
```

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

```yaml
检测: Python jsonschema 验证失败
处理:
1. 记录到 EVENT_LOG.md（ERROR | JSON_VALIDATION_FAILED）
2. 输出验证错误详情
3. 拒绝写入 feature_list.json
4. 触发 harness-handle-failure；仅真实阻塞时升级人工介入
```

## Relationships

### Triggers (触发下游)

```yaml
粒度确定后:
- 触发 harness-track-feature-progress（使用正确的粒度等级）
- 触发 feature_list.json 更新（granularity_level 字段）
```

### Triggered By (被谁触发)

```yaml
触发时机:
- harness-analyze-project-scale 完成后（自动）
- 用户显式调用："确定粒度等级"
- 功能清单生成前（确保粒度等级正确）
```

### Dependencies (前置依赖)

```yaml
必须依赖:
- harness-analyze-project-scale（项目规模分析）
```

## Token 消耗分析

```yaml
单次执行:
- Read 分析报告: ~300 tokens
- 提取关键数据: ~100 tokens
- 应用判定规则: ~100 tokens
- 更新 GLOBAL_STATE.md: ~50 tokens
- 更新 feature_list.json: ~100 tokens
- 输出决策报告: ~200 tokens
总计: ~850 tokens

性能优化:
- 复用分析报告（避免重复分析）
- 增量式更新（仅修改必要字段）
- Token 消耗降低 30%
```

## Examples

### 示例 1: 大型项目 → FINE

```yaml
输入:
功能总数: 215
接口总数: 25
预计执行时间: 682.5 小时

处理:
1. 应用判定规则:
   - 功能数 215 > 50 ✅ → FINE
2. 推荐执行模式: 子代理并行
3. 配置参数:
   - max_parallel_agents: 3
   - max_features_per_session: 3（每批）

输出:
🎯 粒度等级决策报告

粒度等级: FINE
判定依据:
- 功能数: 215 (>50) ✅
- 接口数: 25 (>10) ✅
- 执行时间: 682.5 小时 (>100) ✅

推荐执行模式: 子代理并行
配置参数:
- max_parallel_agents: 3
- max_features_per_session: 3

下一步建议: 使用子代理并行模式，每批 3 个功能
```

### 示例 2: 中型项目 → MEDIUM

```yaml
输入:
功能总数: 35
接口总数: 8
预计执行时间: 93.6 小时

处理:
1. 应用判定规则:
   - 功能数 35 >= 10 → MEDIUM
   - 执行时间 93.6 < 100 → 不满足 FINE
2. 推荐执行模式: 单会话模式
3. 配置参数:
   - max_parallel_agents: 0
   - max_features_per_session: 1

输出:
🎯 粒度等级决策报告

粒度等级: MEDIUM
判定依据:
- 功能数: 35 (10-50) ✅
- 接口数: 8 (5-10) ✅
- 执行时间: 93.6 小时 (<100) ✅

推荐执行模式: 单会话模式
配置参数:
- max_parallel_agents: 0
- max_features_per_session: 1

下一步建议: 使用单会话模式，每次 1 个功能
```

### 示例 3: 小型项目 → COARSE

```yaml
输入:
功能总数: 5
接口总数: 0
预计执行时间: 10 小时

处理:
1. 应用判定规则:
   - 功能数 5 < 10 → COARSE
2. 推荐执行模式: 快速模式
3. 配置参数:
   - one_shot_execution: true

输出:
🎯 粒度等级决策报告

粒度等级: COARSE
判定依据:
- 功能数: 5 (<10) ✅
- 接口数: 0 (<5) ✅
- 执行时间: 10 小时 (<20) ✅

推荐执行模式: 快速模式
配置参数:
- one_shot_execution: true

下一步建议: 使用快速模式，一次性完成所有功能
```

### 示例 4: 边界条件 → FINE

```yaml
输入:
功能总数: 51
接口总数: 10
预计执行时间: 102 小时

处理:
1. 应用判定规则:
   - 功能数 51 > 50 → FINE（刚好超过阈值）
2. 推荐执行模式: 子代理并行

输出:
🎯 粒度等级决策报告

粒度等级: FINE
判定依据:
- 功能数: 51 (>50) ✅（刚好超过 FINE 阈值）
- 接口数: 10 (=10) ❌（不满足 FINE）
- 执行时间: 102 小时 (>100) ✅

下一步建议: 使用子代理并行模式
```

## Implementation Notes

### 关键设计决策

1. **判定规则优先级**
- 功能数 > 接口数 > 执行时间（优先级递减）
- 任一条件满足 → 触发对应粒度等级
- 避免冲突（高优先级覆盖低优先级）

2. **配置参数联动**
- FINE → max_parallel_agents: 3
- MEDIUM → max_features_per_session: 1
- COARSE → one_shot_execution: true

3. **自动触发机制**
- 缺少分析报告 → 自动调用分析技能
- 确保粒度等级始终正确

### 性能优化

```yaml
Token 优化:
- 复用分析报告（避免重复读取）
- 增量式更新（仅修改必要字段）
- JSON 压缩（降低写入开销）

执行优化:
- 自动触发分析（减少用户干预）
- 快速判定（O(1) 时间复杂度）
- 批量更新（一次写入多个字段）

总体优化:
- Token 消耗降低 30%
- 执行时长缩短 20%
```