公众号地址 https://mp.weixin.qq.com/s/zn_H8Gp2wMLUFj6CadQR4A

SPEC 别再装了：把需求拆成"专业废纸"，实现全是屎，还不如随手撸

一、先把结论摊开

• SPEC 踩错了油门。它把"写得更细"当"做得更好"，把需求碾成碎末，工程实现最后只能做昂贵的"再缝合"。
• "一句话生成"是伪确定性。模糊被默认值填满，看似一键出活，实则把不确定性推迟到联调和上线前，代价最大。
• **Kiro spec 的本质是"把一句话粉饰成专业废纸"**。格式漂亮、术语响亮，但缺"怎么改、改哪里、以何为准"。最后落地肉眼下坠，甚至不如工程师"随手撸"的原型顺滑。

二、SPEC 为啥错在方向

1) 过度细化，撕裂上下文

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

2) 串行慢反馈，返工巨大

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

3) 文档完备≠可执行

看着满满当当，却没有"文件路径、函数签名、请求/响应、错误码、迁移/回滚、监控点"。执行器只能猜：猜路径、猜接口、猜错误码。猜错一次，返工一次。

4) 质量肉眼下降，不如 vibe

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

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

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

四、Kiro spec = 一句话的精装修

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

五、替代路径：先确认，再实现（ requirements-pilot ）

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

两道门禁

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

  四个维度必须过线：

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

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

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

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

短闭环链路

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

六、细节对比：把争议点掰开揉碎

七、实践：把一件小事做到底（"邀请码有效期"）

确认阶段要问清的硬问题

• 起算口径：创建起算还是首次使用起算？
• 时区精度：统一 UTC 存储，边界秒怎么判？
• 错误码：沿用还是新增？编号、语义、HTTP 状态码映射？
• 配置与灰度：配置中心键名、动态生效机制、灰度与回滚路径？
• 存量兼容：历史邀请码无有效期如何处置？
• 观测：日志字段、指标（命中过期次数、拒绝率）、告警阈值。

规格里必须出现

• 数据层：表字段/索引、迁移脚本与回滚脚本。
• 领域逻辑：校验函数签名、边界与失败路径的预期返回。
• API：请求/响应样例、错误码与语义。
• 配置：键名、加载流程、缓存更新、灰度开关。
• 监控：指标与仪表盘字段，报警建议。

测试优先覆盖

• 单元：过期/未过期/临界秒、历史无有效期兼容、配置变更生效路径。
• 集成：接口联调、鉴权链路、错误码一致性、监控打点。
• 端到端（必要时）：后台配置调整→前台创建→过期命中→指标可见。

八、落地：把工具装好，用起来

克隆仓库

git clone https://github.com/cexll/myclaude 

仅复制命令与代理

mkdir -p ~/.claude/{commands,agents} cp -R myclaude/commands/* ~/.claude/commands/ cp -R myclaude/agents/* ~/.claude/agents/ 

开跑

/requirements-pilot "你的功能描述" 

流程：回答澄清，拿到 requirements-confirm.md（≥90 ）→ 批准 → 自动生成 requirements-spec.md → 实现 → 评审 → 测试。

九、常见坑与防守要点

• 把确认回路走成模板题：形式对了，信息没用。

  对策：问题直指"动哪个文件、加什么字段、返回啥错误码、失败怎么回滚"。

• 把规格写回宏大叙事：看起来专业，落地全靠猜。

  对策：没有路径/签名/示例/迁移/监控，就不算规格。

• 评审只看代码风格：偏题。

  对策：以口径对齐、集成可行、观测齐全为主轴评分。

• 测试只跑 happy path：脆。

  对策：先边界与失败，再补常态。

十、收口

• SPEC 输在方向：用"完整性"替代"可执行性"，把系统撕碎，再让工程师用命去缝。
• "一句话生成"输在诚实：它把不确定性藏起来，最后集中爆雷。
• 正确的路：先确认，把歧义一条条打光；再实现，用短闭环把实现、评审、测试跑顺。做到这一步，速度自然快，质量也自然上去。

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