V2EX = way to explore
V2EX 是一个关于分享和探索的地方
现在注册
已注册用户请  登录
• 请不要在回答技术问题时复制粘贴 AI 生成的内容
cexll
V2EX  ›  程序员

Claude Code 别再使用 SPEC 了,把需求拆成"专业废纸",实现全是屎,还不如随手撸

  •  1
     
  •   cexll ·
    cexll · 32 天前 · 1643 次点击
    这是一个创建于 32 天前的主题,其中的信息可能已经有所发展或是发生改变。

    Claude Code 别再使用 SPEC 了,把需求拆成"专业废纸",实现全是屎,还不如随手撸

    核心要点( 30 秒看完)

    问题:Spec 通过一句话生成 requirements → design → tasks ,看起来专业完整,实际执行结果是垃圾。

    原因:一句话输入 → 自动生成一堆"专业文档" → 但缺少最关键的需求确认环节 → 生成的都是错误假设。

    解决方案:requirements-pilot —— 不急着生成文档,先通过对话确认需求(≥90 分),再生成可执行规格。

    行动:抛弃 Spec ,Claude Code 安装 requirements-pilot ,从确认需求开始。


    一、Spec 的美丽谎言

    你肯定见过这样的演示:

    1. 输入:"为邀请码增加有效期功能"
    2. Spec 自动生成:
    • ✅ Requirements 文档( 10 页)
    • ✅ Design 文档( 15 页)
    • ✅ Tasks 列表( 30 个)
    1. 看起来好专业!好完整!

    然后呢?执行时全崩了。

    二、为什么 Spec 生成的是垃圾?

    问题 1:一句话藏着 100 个坑

    "为邀请码增加有效期功能" —— Kiro Spec 会自作主张脑补:

    • 假设有效期从创建时算(实际可能要从激活时算)
    • 假设用 UTC 时区(实际系统用本地时区)
    • 假设过期返回 401 (实际应该返回自定义错误码)
    • 假设老数据不管(实际需要兼容处理)

    这些错误假设被包装成"专业文档",执行时才发现全错了。

    问题 2:过度细化,撕裂上下文

    文档把接口、数据结构、异常、时序拆成孤岛。纸面整齐,代码成渣。到实现阶段,你得把被拆碎的东西一针一线缝回去:接口卡口半毫米对不上,边界条件到处漏,越补越碎,越缝越厚。

    结果:开发者要花更多时间理解这些"垃圾文档",还不如直接写代码。

    问题 3:串行慢反馈,返工巨大

    流程是"规格→实现→验证",结论最晚才出来。一个中等功能,走完整条流水线才发现某个设计假设不成立——这时候改动像推倒重来,代价翻倍。

    问题 4:质量肉眼下降,不如 vibe

    真事:按 SPEC 做,集成和测试阶段崩得更狠;反倒是"随手撸"的原型对齐现状、问题更少。原因明白得很:SPEC 的"默认假设"跟仓库的真实约束错位。为了服务文档,不得不堆适配层,复杂度直线上天。

    三、"一句话生成"的两个致命误导

    • 伪确定性:一句话盖住关键歧义——时区怎么算、起算口径从哪来、失败怎么回退、如何兼容存量、灰度怎么切。生成器会选一个默认,但八成与系统既有约定冲突。你看不到坑,它就在上线前一起炸。
    • 不可验证:没有"通过/失败"的可证伪标准。测试只能临时拼。一旦爆雷,已是最贵时刻。

    四、spec = 一句话的精装修

    把一句话拆成看起来专业的章节、画上好看的表格,但依旧不告诉你"具体怎么改代码"。于是实施全靠猜,补丁贴满身,交付物像缝合怪,和现有系统就是不贴。

    五、替代路径:先确认,再实现( requirements-pilot )

    别把文档写得更厚,先把歧义打光。动作不多,但每一步都往"可执行"走。

    核心区别

    Spec requirements-pilot
    输入 一句话 → 自动脑补 一句话 → 开始对话
    过程 生成一堆文档 通过问答确认细节
    输出 看着专业的废纸 可直接执行的规格
    结果 执行时发现全错 执行时按规格跑通

    工作原理

    不是让 AI 猜,而是让它问:

    你:"为邀请码增加有效期功能"
    
    AI:"有效期从什么时候开始计算?
        A) 邀请码创建时
        B) 用户首次使用时
        C) 用户激活账号时"
    
    你:"B ,首次使用时"
    
    AI:"过期的邀请码应该返回什么错误?
        A) HTTP 401 Unauthorized  
        B) HTTP 403 Forbidden
        C) 自定义错误码(请指定)"
    
    你:"C ,错误码 INVITATION_EXPIRED = 4001"
    

    每个回答都被记录,最终生成的规格是基于确认的事实,不是猜测。

    两道门禁

    • 门禁一:需求确认≥90 分

      四个维度必须过线:

      • 功能讲清输入/输出/成功判据
      • 技术具体到接口/字段/状态码/时序
      • 实现覆盖边界与失败路径
      • 业务说清"为什么要这么做"

      产物:requirements-confirm.md(原始请求、往返澄清、评分与最终口径)。

    • 门禁二:需求方明确批准

      由需求方说"按此实现"。理解对但不是他要的?不准开工。

    Auto Pilot Sub-Agents 链路

    AI 总结需求评分并询问是否开始,用户确认后 auto pilot sub-agents 自动执行:

    • requirements-generate:自动合成单文档规格 requirements-spec.md,只写可落地动作:文件路径、函数签名、请求/响应示例、错误码、迁移/回滚脚本、配置与灰度、监控指标。
    • requirements-code:自动按规格直改代码,少抽象,先跑通。
    • requirements-review:自动按功能/集成/质量/性能四象限打分;<90 退回重来;≥90 进测试。
    • requirements-testing:自动围绕规格的关键路径、边界与失败场景写"真能用"的测试。

    Auto Pilot 全程无需人工干预,用户只需在 AI 询问时确认开始执行。

    六、实战对比:同样的需求,不同的结果

    Kiro 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-pilot 的输出(直接能用)

    ## 已确认规格
    
    数据库变更:
    - 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": "邀请码已过期" }
    

    区别:每一行都是可以直接复制执行的命令。

    七、在 Claude Code 中使用 requirements-pilot

    Claude Code 的革命性优势

    requirements-pilot 不是普通工具,而是 Claude Code 的原生 slash 命令,这意味着:

    • 无缝集成:直接在 Claude Code 中使用,无需切换工具
    • 上下文保持:与你的代码仓库完全联通
    • 专家协作:可以与其他 Claude Code sub-agents 组合使用

    1. 安装 requirements-pilot

    git clone https://github.com/cexll/myclaude
    mkdir -p ~/.claude/{commands,agents}
    cp -R myclaude/commands/* ~/.claude/commands/
    cp -R myclaude/agents/* ~/.claude/agents/
    

    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 自动链 requirements-pilot 智能链
    需求确认 ❌ 自动脑补 ✅ 对话确认
    执行方式 全自动(基于假设) 分段式(确认+Auto Pilot )
    错误处理 最后才发现全错 确认阶段避免错误,review 阶段质量门控
    结果质量 1 分钟垃圾 AI 评分确认 + Auto Pilot 精品实现
    用户参与 无参与,盲目执行 AI 询问时确认开始,Auto Pilot 执行
    Claude Code 集成 ✅ 原生支持 ✅ 原生支持

    八、记住这个教训

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

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

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

    6 条回复    2025-08-13 10:12:42 +08:00
    panda188
        1
    panda188  
       31 天前 via Android
    你这不也是 Spec ?你是不是用了个垃圾 Spec 的工具,所以以为都没有需求确认环节😂?
    cexll
        2
    cexll  
    OP
       31 天前
    @panda188 kiro spec 是垃圾吗? 本身一句话生成 spec 就不合理
    kneo
        3
    kneo  
       31 天前 via Android   ❤️ 1
    ai 发帖,小心给你封了。
    mightofcode
        4
    mightofcode  
       29 天前
    沙比
    qi1
        5
    qi1  
       22 天前
    用了一下,其实挺好的。只不过你说话比较狂放,哈哈。
    cexll
        6
    cexll  
    OP
       21 天前
    @qi1 😂 哈哈 狠狠打脸自己 认识到很多不足
    关于   ·   帮助文档   ·   自助推广系统   ·   博客   ·   API   ·   FAQ   ·   实用小工具   ·   953 人在线   最高记录 6679   ·     Select Language
    创意工作者们的社区
    World is powered by solitude
    VERSION: 3.9.8.5 · 28ms · UTC 21:06 · PVG 05:06 · LAX 14:06 · JFK 17:06
    Developed with CodeLauncher
    ♥ Do have faith in what you're doing.