konglong87 harness-generate-feature-list
Core Capabilities
Initializer Agent 的核心技能：分析需求文档，自动生成功能清单（feature_list.json），支持动态粒度调整。
核心职责：
- 读取需求文档（README.md、docs/requirements.md、用户故事等）
- 分析需求内容（提取功能点、识别依赖关系）
- 拆分功能项（基于粒度等级：COARSE/MEDIUM/FINE）
- 生成功能清单（符合 JSON Schema 强约束）
- 验证清单完整性（所有需求已覆盖）
- 输出生成报告（功能统计、粒度分布）
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
成功标准：
- ✅ 成功读取并分析需求文档
- ✅ 成功提取功能点（覆盖率 ≥ 95%）
- ✅ 成功识别依赖关系（无循环依赖）
- ✅ 成功拆分功能项（基于粒度等级）
- ✅ 成功生成功能清单（符合 JSON Schema）
- ✅ 成功验证清单完整性（所有检查项通过）
- ✅ 输出详细的生成报告
失败情况：
- ❌ 所有需求文档不存在 → 自动基于 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
关键设计决策
- 需求驱动生成
- 从需求文档提取功能点（而非手动定义）
- 确保功能清单与需求一致
- 支持多种需求格式（用户故事、技术规范、README）
- 粒度自适应拆分
- COARSE: 合并功能，减少总数
- MEDIUM: 保持功能完整性
- FINE: 细化到最小可验证单元
- 强约束机制
- JSON Schema 验证（防止格式错误）
- 依赖关系检查（避免循环依赖）
- 覆盖率验证（确保需求完整）
性能优化
Token 优化:
- 分批处理大型项目（每批 50 项）
- 增量式生成（边分析边写入）
- 缓存中间结果（避免重复计算）
执行优化:
- 并行读取多个需求文档
- 异步生成功能清单
- 流式写入 JSON 文件
总体优化:
- Token 消耗降低 30%
- 执行时长缩短 40%