clear vs spec workflow

SPEC 工作流与 Requirements-First 方法的深度对比分析

核心要点（30秒看完）

观察：SPEC 工作流通过简单输入生成 requirements → design → tasks，在某些场景下可能存在需求理解偏差。

挑战：单向输入模式容易产生假设性理解，缺少关键的需求澄清环节，可能影响最终实现效果。

建议方案：Requirements-first 方法——通过交互式对话先确认需求细节，再生成精确的可执行规格。

实践建议：根据项目特点选择合适的工作流，复杂需求建议采用交互式确认方法。

一、SPEC 工作流的常见挑战

在实际项目中，我们经常看到这样的场景：

1. 输入：“为邀请码增加有效期功能”
2. SPEC 工作流自动生成：
   • ✅ Requirements 文档（10页）
   • ✅ Design 文档（15页）
   • ✅ Tasks 列表（30个）
3. 文档结构完整，看起来很专业

然而，执行阶段往往会遇到意外的挑战。

二、SPEC 工作流面临的关键问题

问题1：需求理解的歧义性

以”为邀请码增加有效期功能”为例，这句简单的描述实际包含多个决策点：

• 有效期计算起点：创建时 vs 激活时 vs 首次使用时
• 时区处理：UTC vs 本地时区 vs 用户时区
• 过期处理：HTTP状态码选择和错误信息设计
• 历史数据：兼容性策略和迁移方案

当这些关键细节缺失时，自动生成的文档往往基于默认假设，与实际需求存在偏差。

问题2：模块化文档与整体理解的矛盾

规范化流程通常将系统分解为独立的模块文档：接口定义、数据结构、异常处理、时序图等。虽然结构清晰，但可能导致：

• 上下文分离：相关功能被拆分到不同文档，整体逻辑不够连贯
• 集成复杂度：实现时需要重新整合各个模块的边界条件
• 理解成本：开发者需要在多个文档间切换才能获得完整视图

影响：文档的模块化结构有时与代码的整体性需求产生冲突。

问题3：线性流程的反馈延迟

传统的”规格→实现→验证”流程存在反馈延迟问题：

• 晚期发现：设计假设的问题往往在实现或测试阶段才暴露
• 返工成本：此时修改需要同步更新文档、代码和测试，成本较高
• 风险累积：多个小问题可能在后期集中爆发

问题4：理论与实践的适配挑战

在某些情况下，严格按照SPEC执行可能面临：

• 现有系统约束：生成的规格与既有架构或技术栈不完全匹配
• 实际环境差异：理论设计与生产环境的实际限制存在gap
• 维护复杂度：为了符合规格而增加的适配层可能带来额外复杂度

三、简化输入模式的潜在陷阱

单句描述驱动的自动化流程可能面临以下挑战：

• 隐式假设：简单描述往往隐藏了关键决策点（时区策略、错误处理、兼容方案、发布策略等），系统会基于默认假设进行补充，可能与实际需求不符。
• 验证困难：缺少明确的成功标准和验证方法，导致问题发现较晚，修复成本较高。

四、SPEC 工作流的适用场景

尽管存在挑战，SPEC 工作流在以下场景中仍然具有价值：

适合使用 SPEC 的情况

• 标准化需求：功能相对标准，行业实践成熟，假设偏差风险较低
• 大型项目：需要多团队协作，文档化规格有助于沟通和分工
• 合规要求：某些行业或项目要求完整的设计文档和可追溯性
• 新团队：团队成员经验不足，需要结构化的指导流程
• 维护项目：需要保持与现有文档体系的一致性

不太适合 SPEC 的情况

• 探索性功能：需求不明确，需要大量试错和迭代
• 创新项目：缺少成熟参考，假设风险高
• 紧急修复：时间紧迫，文档化成本过高
• 小规模功能：复杂度低，文档化收益不明显

五、Requirements-First 方法：交互式需求确认

针对SPEC工作流的挑战，Requirements-First 方法提供了一种替代思路：通过交互式对话先澄清需求细节，再生成精确的实现规格。

核心区别

工作原理

主动澄清代替被动假设：

你："为邀请码增加有效期功能"

AI："有效期从什么时候开始计算？
    A) 邀请码创建时
    B) 用户首次使用时
    C) 用户激活账号时"

你："B，首次使用时"

AI："过期的邀请码应该返回什么错误？
    A) HTTP 401 Unauthorized  
    B) HTTP 403 Forbidden
    C) 自定义错误码（请指定）"

你："C，错误码 INVITATION_EXPIRED = 4001"

通过这种方式，最终生成的规格基于明确确认的决策，而非系统假设。

质量门控机制

• 阶段一：需求完整性评估

  从四个维度评估需求清晰度：

  • 功能层面：明确输入、输出和成功标准
  • 技术层面：具体到接口、字段、状态码、时序
  • 实现层面：涵盖边界条件和异常处理
  • 业务层面：阐明实现目标和价值

  输出：需求确认文档，包含原始请求、澄清过程和最终决策。

• 阶段二：利益相关方确认

  确保所有相关方对需求理解一致，获得明确的实施授权。

自动化执行流程

需求确认完成后，可以启动自动化执行流程：

• 规格生成：基于确认的需求生成详细技术规格，包含具体的实现细节：文件结构、函数签名、API示例、错误处理、部署方案等。
• 代码实现：按照规格进行代码开发，优先保证功能完整性和可测试性。
• 质量审查：从功能性、集成性、代码质量、性能等维度进行评估，不符合标准的返回修正。
• 测试开发：围绕核心功能路径、边界条件和异常场景创建测试用例。

该流程在需求确认后可以相对独立运行，减少人工干预需求。

六、实战对比：两种方法的输出差异

传统 SPEC 工作流的典型输出

## Requirements
- The system shall implement invitation code expiration
- Codes shall have configurable validity periods
- Expired codes shall be handled gracefully

## Design  
- Add expiration_date field to invitation table
- Implement ExpiredInvitationException
- Create InvitationValidator service

## Tasks
1. Update database schema
2. Implement validation logic
3. Add API endpoints
4. Write unit tests
...（还有26个任务）

特点：结构规范，覆盖全面，但细节层面需要开发者进一步解读和决策。

Requirements-First 方法的典型输出

## 已确认规格

数据库变更：
- ALTER TABLE invitations ADD expires_at TIMESTAMP NULL;
- UPDATE invitations SET expires_at = created_at + INTERVAL '7 days' WHERE expires_at IS NULL;

验证函数：
- validateInvitation(code: string): ValidationResult
- 首次使用时设置 first_used_at，计算 expires_at = first_used_at + validity_days
- 过期返回：{ valid: false, error: 'INVITATION_EXPIRED', code: 4001 }

API 变更：
- POST /invitations/validate 增加错误码 4001
- 响应示例：{ "error": "INVITATION_EXPIRED", "message": "邀请码已过期" }

特点：具体明确，包含可直接执行的SQL、函数签名和API规范。

七、工具选择和实践建议

技术工具的选择原则

选择适合的开发工具时，建议考虑以下因素：

• 集成性：工具与现有开发环境的兼容程度
• 上下文保持：能否维持项目上下文的连续性
• 扩展性：是否支持与其他工具的组合使用

实践建议

对于希望尝试 Requirements-First 方法的团队，可以考虑：

1. 评估现有流程：分析当前工作流的痛点和改进空间
2. 小范围试验：在小功能或子模块上先行验证
3. 逐步推广：根据试验效果决定是否扩大应用范围

2. 在 Claude Code 中的使用体验

# 传统 spec-workflow（问题多）
/spec-workflow "为邀请码增加有效期"  
# → 自动生成 requirements → design → tasks → code
# → 但基于错误假设，执行结果是垃圾

# requirements-pilot（推荐）
/requirements-pilot "为邀请码增加有效期"
# → AI 总结需求评分并询问是否开始 → 用户确认 → auto pilot 执行：generate → code → review → testing

3. 两种工作流对比

传统 spec-workflow 链条：

一句话 → 自动生成规格 → 自动实现 → 自动测试
问题：全程都是基于错误假设，看起来自动化，实际是自动制造垃圾

requirements-pilot 智能链条：

一句话 → AI 总结需求评分并询问 → 用户确认开始 → auto pilot 执行：generate → code → review → testing
优势：基于确认事实的 auto pilot，既快速又可控

4. requirements-pilot 的 Auto Pilot 优势

相比需要手动触发每个步骤的传统方法，requirements-pilot 实现了：

• 智能评分确认：AI 自动总结需求、评分并询问用户是否开始执行
• Auto Pilot 链式执行：用户确认后通过 auto pilot sub-agents 自动完成整个流程
• 质量门控：review 阶段评分<90自动返回重做，≥90才进入测试
• 一键式体验：只需回复确认，整个实现过程完全自动化

# 简单确认即可完成全流程
/requirements-pilot "为邀请码增加有效期功能"
# AI: "需求已理解，评分92分，是否开始执行？"
# 用户: "确认"
# → auto pilot 自动执行：generate → code → review → testing

5. 关键差异总结

八、记住这个教训

一句话生成的”专业文档”都是包装精美的垃圾。真正的需求理解来自于对话和确认。

别被 Spec 的表面功夫骗了。需求不确认清楚，生成再多文档也是浪费时间。

别把工具当银弹，把确认当形式。真正的效率来自”先把话说清楚，再让工具把重复劳动做干净”。