AI Vibe Coding 实战（三）：把 SMS 开发方案落成 Spec 文档

前两篇中，我记录了为 CabloyJS 开发 SMS 套件时，与 Claude Code 讨论架构和产品决策的过程。

第一轮先划分短信底座、验证码、认证和 Mock 的职责；第二轮继续明确显式注册、国际号码、真实供应商，以及 Web/Admin 共用身份但不自动获得管理权限的边界。

方案已经有了，接下来是否应该直接让 AI 开始写代码？这一轮，我先让它把讨论结果整理成 spec 文档。

提示词很短：

/cabloy-spec-generation 同意你的方案，请整理到spec文档中

这条指令的重点不在于多生成几份 Markdown，而在于把分散在对话中的共识，落成后续可以核对、拆分和验收的规划基线。

一、先确认生成范围，而不是直接开始实现

Claude Code 没有收到"同意"就创建业务模块，而是先核对仓库中的规划规范、已有账号规划、Web/Admin 站点和登录路由，然后给出本轮范围：

我将按 Cabloy Basic 的完整新套件基线 ，整理到 repo-specs/cabloy-sms/，使用中文正文。范围如下：

• 六份核心文档：README、PRD、SRS、PDP/WBS、测试计划、进度；
• 一份边界 ADR，以及真实短信供应商接入/验收 runbook；
• 甘特图和燃尽图，由完整 WBS 输入生成，不代表工期承诺或已完成进度；
• 固化已同意的方案：显式短信注册、国际号码、共享现有 Web/Admin、Mock + 阿里云 + 腾讯云 + Twilio 首期交付，Vonage 延后；
• 清楚区分现有源码与计划新增能力。ADR 暂记 Proposed，交付状态初始化为 not-started，不把这次同意扩展为代码执行、真实发信或发布授权。

它还补充了两个与现有系统有关的约束：

现有 home-user 规划将用户名等登录标识排除在自由资料编辑范围之外，新 spec 会保留这一边界，明确所需的用户名一致性检查，不顺带扩大改名权限。供应商账号、目标国家开通、真实测试号码等只阻塞对应渠道验收，不阻塞 Mock 闭环。

这里不是简单复述上一轮方案。前一篇讨论了用户名与展示名称的关系，这一轮又对照已有账号规划，确认不能借短信接入顺带扩大资料编辑权限。对话中的建议，需要与仓库里已经存在的边界对齐。

在范围确认中，我选择：

按完整基线生成（推荐），使用英文正文。

Claude Code 随后明确调整：

收到，改用 英文正文 生成完整基线；后续汇报仍使用中文。只写 repo-specs/cabloy-sms/ 下的规划文件，不执行脚手架、数据库操作或真实发信。

因此，下面讨论的是英文 spec 基线的生成过程，不是 SMS 功能已经实现后的总结。

二、六份核心文档，分别回答什么问题？

"把方案整理成文档"很容易变成把同一段架构介绍复制到多个文件。更有用的做法，是让每份文档承担不同的职责。

这一轮生成的核心文档是：

文档	主要回答的问题
README	整套规划从哪里读起？当前范围、状态和下一步是什么？
PRD	为什么做？面向谁？首期交付哪些业务能力，哪些暂不做？
SRS	如何约束实现？模块、接口、安全、身份、并发和前端集成应遵守什么契约？
PDP/WBS	按什么顺序交付？任务依赖和完成条件是什么？
测试计划	如何证明符合要求？需要哪些场景和证据？
进度记录	哪些尚未开始，哪些已有证据，哪些决策或外部条件仍待关闭？

例如，"短信登录不能自动创建账号"不应只在聊天中出现一次。它需要成为产品行为，在系统契约里落实到已有身份检查和认证链边界，在任务中安排实现，并在验收场景中证明不存在身份时不会静默开户。

不同文件不是六套平行说法，而是同一目标的不同层次。

从产品要求到验收证据

这套规划采用明确编号关联需求和交付：

PRD → SRS → WBS → ATP
产品需求 → 系统要求 → 交付任务 → 验收场景

编号的价值不在于形式整齐，而在于能回答：

• 这个交付任务服务哪个需求？
• 某个安全要求由哪个任务落实？
• 任务声称完成时，应该拿出什么证据？
• 某项验收失败，会影响哪一部分交付？

同时，并不是每个规划活动都要编造一个运行时测试。例如，首个边界决策任务可以用文档审查证明完成，但不能因此声称短信发送已经验证成功。

三、ADR 和供应商操作手册，把决策与操作分开

除了六份核心文档，本轮还生成了边界 ADR 和供应商操作手册。

ADR：记录技术边界，但保留待批准状态

ADR 是架构决策记录。本轮的 ADR 0001 保持 Proposed，承接短信传输、验证码、身份和现有框架之间的职责边界。

"我同意整理文档"与"我批准所有技术细节并允许实施"不是同一件事。把状态写清楚，可以避免后续执行者把一份内容完整的规划误读成无限范围的执行授权。

供应商操作手册：代码接好之后，还要验收什么？

真实短信接入不仅涉及 SDK 和参数转换，还涉及：

• 供应商账号与凭据的安全配置。
• 已批准的签名、模板或发送身份。
• 可发送的国家和地区。
• 获得同意的测试号码、允许范围与费用上限。
• 明确拒绝、超时结果不确定时的处理。
• 渠道停用、切换和回滚。

这些内容放在操作手册中，而不是把真实凭据、完整手机号或验证码填进 spec。

它也延续了前一篇的重要区别：供应商接受请求，不等于手机已经收到短信。 适配器的请求映射可以先验证；真实渠道的发送与收件证据，要在具备条件并获得明确授权后单独取得。

四、外部条件只阻塞对应分支

生成过程中，Claude Code 对交付拆分作了进一步说明：

文档将把基础发送、验证码安全扩展、显式注册/登录、Web/Admin 接入和真实供应商验收分别列为可追踪的交付项。真实供应商的账号、签名、模板和国家权限只约束对应渠道验收，不会阻塞 Mock 闭环的独立交付。

这个边界很实用。

如果 Twilio 的目标国家权限尚未开通，不能宣称国际渠道已经验收；但也不必让所有开发工作停下来。通过 Mock，仍然可以独立验证发送契约、号码与用途绑定、验证码消费和注册登录链路。

反过来，Mock 流程跑通，也不能把阿里云、腾讯云、Twilio 都标为验收完成。

这让团队既能推进一个有用的增量，也不会在进度表中掩盖尚未完成的真实渠道要求。

五、检查过程也有一次明确的失败

这一轮并不是所有检查第一次就通过。

首次执行规划检查时，工具识别出 45 个正式定义，但由于文档引用的两张派生图表还未生成，报告了链接目标缺失：

complete planning structure failed (45 definitions).
Missing local link target: implementation-gantt.svg.
Missing local link target: implementation-burndown.svg.

随后生成图表，再重新运行规划和图表新鲜度检查：

npm run spec:charts -- cabloy-sms
npm run spec:check -- cabloy-sms
npm run spec:charts:check -- cabloy-sms

最终结果是：

complete planning structure passed (45 definitions).
checked implementation-gantt.svg and implementation-burndown.svg
(en; 0/10 verified).

这里的 0/10 verified 很重要：生成图表没有制造任何实现进度。十个交付任务仍然全部是 not-started。

甘特图表达任务组织与依赖，范围计数燃尽图表达当前状态；它们不是工期承诺，也不是根据真实交付历史计算出的速度预测。

规划检查工具本身也明确提示：它验证的是静态结构，批准状态、语义充分性、实现和证据真实性仍需要人工审查。编号能连起来，不代表方案一定正确；图表能生成，也不代表功能已经可用。

六、找回的生成完成回复

下面是这一轮最终回复的内容，保留当时的结论与状态，文件链接整理为便于阅读的文档名称：

已完成 Cabloy Basic 的英文完整 spec 基线 ，全部位于 repo-specs/cabloy-sms/。

文档入口

README --- 规划总览与阅读顺序。

文档	内容
prd.md	产品目标、用户流程、首期与延期范围
srs.md	provider/clients/scene、验证码安全、身份与并发、Web/Admin 集成
pdp-wbs.md	分阶段交付、依赖和完成条件
test-plan.md	12 个验收场景及证据要求
progress.md	初始状态、待决事项及后续入口
ADR 0001	Proposed 技术边界与决策门槛
供应商 runbook	渠道配置、真实发送验收、故障与停用流程

另已生成两张英文图表：实施路线图、范围计数燃尽图。

已固化的方案重点

• 显式注册：手机号 + 用户选择的 username + 注册验证码；短信登录不自动注册。
• 支持国际号码，统一 E.164；Web/Admin 复用现有身份、Passport 和共享站点。
• 首期包含 Mock、阿里云、腾讯云、Twilio；Vonage 延后。
• 复用并安全扩展 a-captcha，不另建 OTP 系统；覆盖绑定、原子消费、限流及通用接口绕过风险。
• Mock 自动回填仅限实际 Mock、非生产、显式开启的场景；真实渠道不向前端返回验证码。
• 真实渠道的账号、签名、模板和国家权限分别验收，不阻塞 Mock 分支实施。

检查结果

• spec:check：通过，45 个正式定义及完整追踪链。
• spec:charts、spec:charts:check：通过。
• 本地链接、空白、机器路径隐私检查通过；图表已渲染查看。

当前仅完成规划生成 ：ADR 保持 Proposed，10 个交付任务均为 not-started，没有运行时或真实供应商验收证据。未执行脚手架、依赖安装、数据库操作、真实发送或提交。

下一步候选是 WBS-SMS-10-01：为验证码消费者实现基于 scene 的 Mock 发送，验证租户隔离和生产禁用；通过 cabloy-spec-execution 完成对应决策与执行 dossier 审批后再进入实现。

这里的"45 个正式定义""12 个验收场景""10 个交付任务"分别是不同的规划计数，不能混为一组通过的测试。上述状态记录的是这次生成结束时的快照，不代表后续开发进展。

七、这一步真正留下了什么？

回看这次很短的提示词，我希望 AI 完成的其实是一次工作状态转换：从"已经讨论过的方案"，转到"可以交接和逐项验证的规划"。

这个转换需要保留几条清楚的边界：

• 方案共识：明确首期要做什么、不做什么。
• 技术决策：识别哪些细节还处于 Proposed，不能默认为已批准。
• 交付任务：给每个有用增量定义依赖与退出条件。
• 验收证据：区分计划中的场景和真正执行后取得的结果。
• 操作授权：不把生成文档的同意扩展成写代码、重置数据库、付费发信或发布。

这不是要求把每个细节都规划到没有任何未知，而是让未知有归属、让下一步有边界。

当 spec 已经指出一个可独立验证的 Mock 发送切片后，后续就可以围绕这个切片进入实施，而不是反复重写整套宏大方案。至于验证码、身份与前端如何真正接起来，那是下一阶段需要用代码和运行结果回答的问题。