SPEC 别再装了：把需求拆成”专业废纸”，实现全是屎，还不如随手撸
作者： Ben Chen
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：围绕规格的关键路径、边界与失败场景写”真能用”的测试。
六、细节对比：把争议点掰开揉碎
| 对比维度 | SPEC | requirements-pilot |
|---|---|---|
| 输入表达 | 信息量大但密度低，术语飞舞，执行性弱 | 只保留对实施有用的信息，单位是”具体代码动作” |
| 反馈路径 | 串行长闭环，问题暴露晚、返工重 | 先清不确定性，再短闭环做评审与测试，快速收敛 |
| 变更成本 | 大拼图耦合，动一处牵全身，文档同步易漏 | 确认记录+单文档规格，变更点集中、可追踪 |
| 协作方式 | 写文档的人与写代码的人隔空喊话 | 确认回路就是沟通，规格直接服务实施与测试 |
| 质量实效 | 为”完整”牺牲”贴合”，质量甚至不如”随手撸” | 先对齐口径，再动手；实现轻、集成顺 |
七、实践：把一件小事做到底（“邀请码有效期”）
确认阶段要问清的硬问题
- 起算口径：创建起算还是首次使用起算？
- 时区精度：统一 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 输在方向：用”完整性”替代”可执行性”，把系统撕碎，再让工程师用命去缝。
- “一句话生成”输在诚实：它把不确定性藏起来，最后集中爆雷。
- 正确的路：先确认，把歧义一条条打光；再实现，用短闭环把实现、评审、测试跑顺。做到这一步，速度自然快，质量也自然上去。
💡 关键提醒：别把工具当银弹，把确认当形式。真正的效率来自”先把话说清楚，再让工具把重复劳动做干净”。