harness-generate-feature-list

Core Capabilities

Initializer Agent 的核心技能：分析需求文档，自动生成功能清单（feature_list.json），支持动态粒度调整。

核心职责：

1. 读取需求文档（README.md、docs/requirements.md、用户故事等）
2. 分析需求内容（提取功能点、识别依赖关系）
3. 拆分功能项（基于粒度等级：COARSE/MEDIUM/FINE）
4. 生成功能清单（符合 JSON Schema 强约束）
5. 验证清单完整性（所有需求已覆盖）
6. 输出生成报告（功能统计、粒度分布）

Execution Steps

Step 1: 读取需求文档

工具: Read
文件列表（优先级从高到低）:
1. docs/requirements.md（需求文档）
2. docs/user-stories.md（用户故事）
3. docs/specifications.md（技术规范）
4. README.md（项目概述）

Token 消耗: ~5000 tokens（中型项目）或 ~20000 tokens（大型项目）

失败处理:
- 如果所有文件不存在 → 提示"缺少需求文档，请提供以下任一文件:"
  - docs/requirements.md
  - docs/user-stories.md
  - README.md（至少包含功能列表）

Step 2: 分析需求内容

分析维度:

维度 1: 功能点提取
方法:
  - 识别功能描述关键词: "实现"、"开发"、"添加"、"支持"
  - 解析用户故事格式: "作为...我想要...以便..."
  - 提取技术规范中的功能列表

示例:
  需求: "用户可以注册账号，填写用户名、密码和邮箱"
  提取功能点:
    - FEAT-001: 用户注册接口（API）
    - FEAT-002: 用户注册页面（UI）
    - FEAT-003: 注册表单验证（Core）

Token 消耗: ~1000 tokens

维度 2: 依赖关系识别
方法:
  - 识别功能前置条件: "注册前需要验证邮箱唯一性"
  - 构建依赖图: FEAT-001（注册）← FEAT-002（验证）
  - 记录到功能清单的 dependencies 字段

Token 消耗: ~500 tokens

维度 3: 复杂度评估
方法:
  - 简单: 单一功能点，无外部依赖（复杂度系数 1.0）
  - 中等: 多个子功能，有外部依赖（复杂度系数 1.5）
  - 复杂: 跨模块集成，涉及多个系统（复杂度系数 2.0）

Token 消耗: ~300 tokens

Step 3: 基于粒度等级拆分功能

拆分策略:

策略 1: COARSE（粗粒度）
适用场景: 功能数 <10，执行时间 <20 小时
拆分规则:
  - 保持功能完整性（不拆分）
  - 合并相关功能（如"用户注册"合并 UI + API）
  - 减少功能总数（优先级低的功能可延后）

示例:
  原始需求: 8 个功能点
  COARSE 拆分: 合并为 5 个功能项
    - FEAT-001: 用户注册（合并注册接口 + 注册页面）
    - FEAT-002: 用户登录（合并登录接口 + 登录页面）
    - FEAT-003: 用户资料管理
    - FEAT-004: 密码重置
    - FEAT-005: 用户注销

Token 消耗: ~500 tokens

策略 2: MEDIUM（中粒度）
适用场景: 功能数 10-50，执行时间 20-100 小时
拆分规则:
  - 按功能边界拆分（一个功能项 = 一个独立特性）
  - 保持模块内聚（同一模块的功能尽量集中）
  - 控制功能项粒度（单个功能项 ≤ 4 小时）

示例:
  原始需求: 35 个功能点
  MEDIUM 拆分: 35 个功能项（保持原样，按优先级排序）

Token 消耗: ~800 tokens

策略 3: FINE（细粒度）
适用场景: 功能数 >50，执行时间 >100 小时
拆分规则:
  - 细化到最小可验证单元（单个功能项 ≤ 2 小时）
  - 按技术层次拆分（UI/API/Core/Test 分离）
  - 支持并行开发（功能项之间无强依赖）

示例:
  原始需求: 用户注册（复杂功能）
  FINE 拆分:
    - FEAT-001: 用户注册接口（API）
    - FEAT-002: 用户注册页面（UI）
    - FEAT-003: 注册表单验证（Core）
    - FEAT-004: 邮箱唯一性验证（Core）
    - FEAT-005: 密码加密存储（Security）
    - FEAT-006: 注册单元测试（Test）

Token 消耗: ~1500 tokens

Step 4: 生成功能清单

工具: Write
文件: .EnjoyHarness/feature_list.json
格式: JSON（符合 JSON Schema）

功能项字段:
  - id: 功能ID（格式：FEAT-{数字}，如 FEAT-001）
  - category: 功能分类（core/api/ui/security/performance/test）
  - description: 功能描述（简洁清晰，可执行）
  - priority: 优先级（HIGH/MEDIUM/LOW）
  - steps: 验证步骤（端到端测试步骤）
  - passes: 是否通过（初始值：false）
  - dependencies: 依赖功能ID列表（可选）
  - estimated_hours: 预计开发时间（小时）
  - complexity: 复杂度等级（SIMPLE/MEDIUM/COMPLEX）

Token 消耗: ~2000 tokens（小型）或 ~10000 tokens（大型）

验证:
  - 使用 Python jsonschema 验证 JSON 格式
  - 检查功能ID唯一性
  - 检查依赖关系有效性（无循环依赖）

Step 5: 验证清单完整性

验证维度:

维度 1: 需求覆盖率
方法:
  - 对比需求文档与功能清单
  - 计算覆盖率: 覆盖功能数 / 总需求数
  - 阈值: 覆盖率 ≥ 95%（允许少量非功能性需求未覆盖）

Token 消耗: ~300 tokens

维度 2: 功能项合理性
检查项:
  - 功能描述是否清晰（可执行）
  - 验证步骤是否完整（端到端可测试）
  - 优先级是否合理（符合业务价值）
  - 依赖关系是否正确（无循环依赖）

Token 消耗: ~500 tokens

维度 3: 粒度一致性
检查项:
  - 所有功能项粒度是否一致（基于粒度等级）
  - 单个功能项预估时间是否合理（COARSE: 4-8h, MEDIUM: 2-4h, FINE: 1-2h）
  - 功能项总数是否符合粒度等级预期

Token 消耗: ~200 tokens

Step 6: 输出生成报告

报告格式:
📋 功能清单生成报告

项目名称: {project_name}
生成时间: {timestamp}
粒度等级: {granularity_level}

功能统计:
- 功能总数: {total_features}
  - 核心功能: {core_features}
  - API 功能: {api_features}
  - UI 功能: {ui_features}
  - 安全功能: {security_features}
  - 性能功能: {performance_features}
  - 测试功能: {test_features}

优先级分布:
- HIGH: {high_priority_features} ({high_percentage}%)
- MEDIUM: {medium_priority_features} ({medium_percentage}%)
- LOW: {low_priority_features} ({low_percentage}%)

复杂度分布:
- SIMPLE: {simple_features} (复杂度系数 1.0)
- MEDIUM: {medium_features} (复杂度系数 1.5)
- COMPLEX: {complex_features} (复杂度系数 2.0)

预计总工时: {total_estimated_hours} 小时

需求覆盖率: {coverage_percentage}%
验证结果: {validation_result}

下一步建议:
- 确认功能清单无误后，运行 harness-track-feature-progress 开始开发
- 如果需要调整粒度，可手动编辑 feature_list.json

Token 消耗: ~500 tokens

Prerequisites

必须满足：

• ✅ 已执行 harness-init（系统初始化）
• ✅ 已执行 harness-determine-granularity（粒度等级已确定）
• ✅ 存在至少一个需求文档

如果前置条件不满足：

• 如果未确定粒度等级 → 自动调用 harness-determine-granularity
• 如果缺少需求文档 → 自动基于 README、目录结构和默认模板推断需求

Success Criteria

成功标准：

1. ✅ 成功读取并分析需求文档
2. ✅ 成功提取功能点（覆盖率 ≥ 95%）
3. ✅ 成功识别依赖关系（无循环依赖）
4. ✅ 成功拆分功能项（基于粒度等级）
5. ✅ 成功生成功能清单（符合 JSON Schema）
6. ✅ 成功验证清单完整性（所有检查项通过）
7. ✅ 输出详细的生成报告

失败情况：

• ❌ 所有需求文档不存在 → 自动基于 README、目录结构和默认模板生成初始功能清单
• ❌ 功能提取失败 → 自动切换到保守提取策略并生成待验证功能清单
• ❌ JSON 格式验证失败 → 记录错误，拒绝写入

Failure Recovery

错误场景 1: 缺少需求文档

检测: 所有文档文件不存在
处理:
1. 自动回退到仓库现有上下文：
   - README.md
   - docs/ 目录结构
   - 现有源码目录命名
2. 使用内置需求模板生成初始功能清单
3. 记录 WARNING | REQUIREMENT_DOCS_MISSING_AUTOFALLBACK
4. 继续执行，不等待用户上传
5. 提供文档模板作为后续优化参考:
   - docs/requirements.md（需求列表）
   - docs/user-stories.md（用户故事）
6. 提供示例:
   - 示例 1: 电商平台需求文档
   - 示例 2: 博客系统用户故事

错误场景 2: 功能提取失败

检测: 正则表达式匹配失败，覆盖率 < 50%
处理:
1. 尝试多种提取策略:
   策略 1: 关键词搜索（实现、开发、添加）
   策略 2: 标题解析（## 功能列表）
   策略 3: 表格解析（| 功能 | 描述 |）
   策略 4: 自然语言处理（AI 辅助提取）

2. 如果仍然失败 → 自动生成保守功能列表:
   - 按目录和模块命名推断功能
   - 未能确认的条目标记为 `assumption: true`
   - 记录 WARNING | FEATURE_EXTRACTION_DEGRADED

3. 使用保守功能列表继续生成功能清单

错误场景 3: 循环依赖检测

检测: 功能A依赖B，B依赖C，C依赖A（循环依赖）
处理:
1. 输出循环依赖链: A → B → C → A
2. 自动解除循环依赖:
   - 移除优先级最低的依赖
   - 记录警告到 EVENT_LOG.md

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

检测: Python jsonschema 验证失败
处理:
1. 输出验证错误详情:
   - 错误字段: {field_name}
   - 错误类型: {error_type}
   - 错误位置: {json_path}

2. 尝试自动修复:
   - 缺少必填字段 → 使用默认值
   - 字段类型错误 → 转换类型

3. 如果无法修复 → 触发 harness-handle-failure；仅真实阻塞时升级人工介入

Relationships

Triggers (触发下游)

生成成功:
- 触发 harness-track-feature-progress（开始开发第一个功能）
- 写入 GLOBAL_STATE.md（feature_list_generated: true）

Triggered By (被谁触发)

触发时机:
- harness-init 完成后（自动生成功能清单）
- harness-determine-granularity 完成后（确定粒度后生成）
- 用户显式调用："生成功能清单"

Dependencies (前置依赖)

必须依赖:
- harness-init（系统初始化）
- harness-determine-granularity（粒度等级确定）

Token 消耗分析

小型项目（10项）:
- Read 需求文档: ~5000 tokens
- 分析需求内容: ~1800 tokens
- 拆分功能项: ~500 tokens
- 生成功能清单: ~2000 tokens
- 验证完整性: ~1000 tokens
- 输出报告: ~500 tokens
总计: ~10800 tokens

中型项目（50项）:
- Read 需求文档: ~10000 tokens
- 其他步骤按比例增加
总计: ~25000 tokens

大型项目（200项）:
- Read 需求文档: ~20000 tokens
- 其他步骤按比例增加
总计: ~50000 tokens

性能优化:
- 分批处理大型项目（每批 50 项）
- 增量式生成（边分析边写入）
- Token 消耗降低 30%

Examples

示例 1: 电商平台（FINE 粒度）

输入:
需求文档: docs/requirements.md
内容: "电商平台包含用户管理、商品管理、订单管理、支付系统等 215 个功能点..."

处理:
1. Read docs/requirements.md
2. 提取功能点:
   - 用户注册、用户登录、商品浏览、添加购物车、下单支付、订单查询...
   - 总计 215 个功能点
3. 基于FINE 粒度拆分:
   - 用户注册 → 拆分为 6 个功能项（API、UI、Core、Security、Test、Validation）
   - 商品浏览 → 拆分为 4 个功能项（API、UI、Core、Test）
   - ...
4. 生成功能清单:
   - FEAT-001: 用户注册接口（API, HIGH, 2h）
   - FEAT-002: 用户注册页面（UI, HIGH, 3h）
   - FEAT-003: 注册表单验证（Core, HIGH, 1h）
   - ...（共 320 个功能项）

输出:
📋 功能清单生成报告

功能总数: 320
粒度等级: FINE
预计总工时: 680 小时
需求覆盖率: 98%

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

示例 2: 博客系统（MEDIUM 粒度）

输入:
需求文档: docs/user-stories.md
内容: "作为博主，我想要发布文章，以便分享知识..."

处理:
1. Read docs/user-stories.md
2. 提取功能点（用户故事格式）:
   - 发布文章、编辑文章、删除文章、评论管理、用户关注...
   - 总计 35 个功能点
3. 基于MEDIUM 粒度拆分:
   - 保持功能完整性（不拆分）
   - 按优先级排序
4. 生成功能清单:
   - FEAT-001: 文章发布（Core, HIGH, 4h）
   - FEAT-002: 文章编辑（Core, HIGH, 3h）
   - ...（共 35 个功能项）

输出:
📋 功能清单生成报告

功能总数: 35
粒度等级: MEDIUM
预计总工时: 94 小时
需求覆盖率: 100%

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

示例 3: 待办事项（COARSE 粒度）

输入:
需求文档: README.md
内容: "待办事项应用，包含添加任务、删除任务、标记完成..."

处理:
1. Read README.md
2. 提取功能点:
   - 添加任务、删除任务、标记完成、任务列表显示
   - 总计 5 个功能点
3. 基于COARSE 粒度拆分:
   - 合并相关功能
   - 减少功能总数
4. 生成功能清单:
   - FEAT-001: 任务管理（合并添加、删除、标记, Core, HIGH, 6h）
   - FEAT-002: 任务列表显示（UI, MEDIUM, 4h）
   - 共 2 个功能项）

输出:
📋 功能清单生成报告

功能总数: 2
粒度等级: COARSE
预计总工时: 10 小时
需求覆盖率: 100%

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

Implementation Notes

关键设计决策

1. 需求驱动生成

• 从需求文档提取功能点（而非手动定义）
• 确保功能清单与需求一致
• 支持多种需求格式（用户故事、技术规范、README）

2. 粒度自适应拆分

• COARSE: 合并功能，减少总数
• MEDIUM: 保持功能完整性
• FINE: 细化到最小可验证单元

3. 强约束机制

• JSON Schema 验证（防止格式错误）
• 依赖关系检查（避免循环依赖）
• 覆盖率验证（确保需求完整）

性能优化

Token 优化:
- 分批处理大型项目（每批 50 项）
- 增量式生成（边分析边写入）
- 缓存中间结果（避免重复计算）

执行优化:
- 并行读取多个需求文档
- 异步生成功能清单
- 流式写入 JSON 文件

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