公众号地址 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：围绕规格的关键路径、边界与失败场景写"真能用"的测试。

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

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

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

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