前两篇中，我记录了为 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 功能已经实现后的总结。
二、六份核心文档，分别回答什么问题？
“把方案整理成文档”很容易变成把同一段架构介绍复制到多个文件。更有用的做法，是让每份文档承担不同的职责。
这一轮生成的核心文档是：
例如，“短信登录不能自动创建账号”不应只在聊天中出现一次。它需要成为产品行为，在系统契约里落实到已有身份检查和认证链边界，在任务中安排实现，并在验收场景中证明不存在身份时不会静默开户。
不同文件不是六套平行说法，而是同一目标的不同层次。
从产品要求到验收证据
这套规划采用明确编号关联需求和交付：
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 — 规划总览与阅读顺序。
另已生成两张英文图表：实施路线图、范围计数燃尽图。
已固化的方案重点
- 显式注册：手机号 + 用户选择的 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 发送切片后，后续就可以围绕这个切片进入实施，而不是反复重写整套宏大方案。至于验证码、身份与前端如何真正接起来，那是下一阶段需要用代码和运行结果回答的问题。
本文由 AI图鉴自动抓取并翻译，版权归原作者所有；如需查看原文请点下方链接。
In the first two articles, I recorded the process of discussing architecture and product decision-making with Claude Code when developing the SMS package for CabroyJS.
In the first round, the roles of SMS, authentication code, authentication and mock were assigned first; in the second round, the clear and explicit registration, international numbers, real suppliers, and Web/Admin shared identity but did not automatically acquire the borders governing permission.
There's a plan. Should we just let AI start writing the code? On this round, I'll let it organize the discussion into a spec document.
prompt is short:
/cablory-spec-generation agrees with your plan, please sort in the spec document
The focus of this directive is not on generating more than a few Marktowns, but rather on putting the consensus scattered in the dialogue into a planning baseline that can be reconciled with split and acceptance check.
I. Confirmation of the extent of generation rather than a direct start to realization
Claude Code created the business module without “consent” and first checked the planning specifications in the warehouse, the existing account code, Web/Admin site and login route, giving the scope of the round:
I will use the full new package baseline of Cablory Basic to repo-specs/cabloy-sms/ in Chinese. The scope is as follows:
- Six core documents: README, PRD, SRS, PDP/WBS, testing plan, progress;
- A border ADR, as well as access to a genuine text message provider/acceptance check runbook;
- Gantt and burn-out maps, generated by complete WBS input, does not represent time commitments or progress achieved;
- Consolidating agreed options: Visible SMS registration, international numbers, sharing of existing Web/Admin, Mark + Alibaba Cloud + Tencent cloud + Twilio first delivery, delay of Vonage;
- A clear distinction between existing source codes and planned additional capabilities. ADR suspensed, initialised as not-starded, does not extend this consent to code execution, real mail or publish authorization.
It also complements two constraints related to existing systems:
The existing home-user plan excludes login identifiers such as user names from the scope of free data editing, and the new spec will retain this boundary, specify the required user name consistency check and not expand the name permission as appropriate. The supplier account number, the target country's opening, the real test number, etc. only block the corresponding channel acceptance check and not the Mock closed ring.
This is not a brief restatement of the previous round. The previous article discussed the relationship between the user name and the display name, and this round was planned against the existing account number, confirming that SMS could not be used to access permission, an extension of information. The recommendations of the dialogue need to be aligned with the borders that already exist in the warehouse.
In the scope confirmation, I choose:
Generated on a full baseline (recommended) in English.
Claude Code then clearly adjusted:
Copy, change to English text to generate a full baseline; follow-up report remains in Chinese. Write only planning documents under repo-specs/cabloy-sms/ without scaffolding, database operations or real mail.
The process of generating the English spec baseline is therefore discussed below and is not a summary of the SMS functionality that has been achieved.
Two, six core documents, each of which questions?
“Consolidate the programme into a document” can easily be translated into copying the same structural presentation to multiple documents. It would be more useful for each document to have different responsibilities.
The core documents generated in this cycle are:
For example, “SMS login cannot automatically create accounts” should not appear only once in a conversation. It needs to be a product act, implemented in the system compact at the borders of the existing identification and certification chain, arranged in the mission and not opened silently in the acceptance check scene when it proves that no identity exists.
The different documents are not six sets of parallel statements, but different levels of the same objective.
From product requirements to acceptance check evidence
The plan uses a clear numbering of associated needs and delivery:
PRD → SRS → WBS → ATP
Product demand, system requirements, mission delivery, acceptance check scene
The value of the numbering is not in its proper form, but in its ability to answer:
- What's this need for mission delivery?
- Which task should a security requirement be carried out?
- What evidence should be produced when the mission claims to have been completed?
- What part of a acceptance check failure affects?
At the same time, not every planned activity requires a running-time test. For example, the first border decision-making task could be proved by document review, but it could not be claimed that SMS had been validated.
III. ADR and the vendor operations manual, separating decision-making from operations
In addition to the six core documents, the current round produced boundary ADR and supplier operations manuals.
ADR: Record technical boundaries but retain status pending approval
ADR is the institutional decision-making record. The current round of ADR 0001 maintains a Proposed line of responsibility between text messaging, authentication code, identity and the existing framework.
"I agree to sort out the files" is not the same thing as "I approve all technical details and allow implementation". A clear description of the status would avoid the follow-on implementer misreading a complete plan as an unlimited enforcement mandate.
Vendor Operations Manual: What do you need acceptance check once the code is in place?
True SMS access involves not only SDK and parameter conversion, but also:
- Secure configuration of vendor accounts and evidence.
- Approved signatures, templates or sending identities.
- Sendable countries and territories.
- Agreed test number, permissible range and maximum cost.
- Unequivocal rejection, treatment when the outcome of timeout is uncertain.
- Channels are disabled, switched and rolled back.
These are included in the operating manual rather than filling in a genuine certificate, a full cell phone number or a certificate code.
It also perpetuates the important distinction in the previous article: the fact that a supplier accepts a request does not mean that a cell phone has received a text message. The requested map of the adaptor can be validated first; evidence of the transmission and receipt of the true channel must be obtained separately after conditions have been met and clear authorization has been obtained.
iv. External conditions only block counterpart branches
In the process of generation, Claude Code further explained the delivery of split:
The document will include base delivery, authentication code security extension, visible registration/entry, Web/Admin access and real supplier acceptance check as traceable deliverables. The true supplier ' s account numbers, signatures, templates and national permission are bound only to the corresponding channel acceptance check and do not block the independent delivery of the Mock closed ring.
This border is practical.
If Twilio ' s target country, permission, is not operational, international channels cannot be claimed to have reached acceptance check, but there is no need to stop all development work. Through Mock, transmission contracts, number and purpose binding, certification code consumption and registration log-in links can still be independently validated.
On the other hand, the Mock process ran and could not have been completed with Alibaba Cloud, Tencent clouds, Twilio.
This allows the team to move forward with a useful increment and does not cover up the outstanding genuine channel requirements in the schedule.
V. There was also a clear failure in the inspection process
Not all inspections passed for the first time.
At the time of the first planning check, the tool identified 45 formal definitions, but since two derived charts cited in the document had not yet been generated, the missing link targets were reported:
complete planning structure failed (45 definitions).
Missing local link target: implementation-gantt.svg.
Missing local link target: implementation-burndown.svg.
This is followed by the production of graphs and rerun planning and graph freshness checks:
npm run spec:charts -- cabloy-sms
npm run spec:check -- cabloy-sms
npm run spec:charts:check -- cabloy-sms
The final results are:
complete planning structure passed (45 definitions).
checked implementation-gantt.svg and implementation-burndown.svg
(en; 0/10 verified).
The 0/10 verified here is important: the production of graphs does not create any progress towards achievement. Ten of the deliverables are still full.
The Gantt chart expresses mission organization and dependence, and range count-out maps represent the current state; they are not work-time commitments or speed projections based on real delivery history.
The planning inspection tool itself is clear: It validates static structures, and approval status, semantic adequacy, fulfilment and authenticity of evidence still require manual review. The numbering is linked and does not mean that the programme is always correct; charts are generated or the functionality is already available.
VI. RESPONSIBILITY RESPONSIBILATION COMPLETING RESPONSES
The following is the content of the final response for this round, with the conclusion and status at that time, and the document is linked to a reader-friendly document name:
Completed full English spec baseline for Cabloy Basic, all in repo-specs/cabloy-sms/.
Document Entry
README - Planning overview and reading order.
Two additional charts have been produced in English: implementation of the road map, scope count-out.
firmly established programme focus
- Visible registration: mobile phone + user selected username + registration code; SMS login is not automatically registered.
- Support for international numbers, harmonization of E.164; Web/Admin reuse of existing identities, Passport and shared sites.
- The first issue consists of Mark, Alibaba Cloud, Tencent clouds, Twilio; Vonage deferred.
- Reuse and safely expand a-captcha without creating an OTP system; cover binding, atomic consumption, rate limit and general interface bypassing risk.
-Mock automatically returns the actual, non-production, visible opening scene; the real channel does not return the authentication code forward.
- The accounts, signatures, templates and national permission of the true channel, respectively, acceptance check, without blocking the implementation of the Mark branch.
Check results
- Spec:check: adopted, 45 official definitions and complete tracing chains.
- spec:charts, spec:charts:check: adopted.
- Local links, blanks, machine path privacy checks pass; charts are rendered.
Currently, only planned generation is completed: ADR maintains Proposed, and 10 deliveries are not-starded, without running time or evidence from the real supplier acceptance check. No scaffolding, reliance on installation, database operation, real dispatch or submission.
next step's candidacy is WBS-SMS-10-01: Make a scene-based Mock sent to the certification code consumer to verify the segregation of tenants and the prohibition of production; complete the corresponding decision-making and execution of dossier approval through cablory-spec-exclusion.
The “45 official definitions” here, “12 acceptance check scenarios”, “10 deliverables”, are separate planning counts and cannot be confused into a set of passed tests. This status record is a snapshot of the end of the generation and does not represent subsequent development.
VII. What really remains of this step?
Looking back at this very short prompt, I hope AI has actually accomplished a working-level shift from “discussed options” to “programming that can be handed over and validated on a case-by-case basis”.
This conversion requires several clear boundaries:
- Consensus on the programme: clarify what to do and what not to do in the first phase.
- Technical decision-making: identifying which details are still in Proposed and cannot be tacitly approved.
- Delivery of tasks: define each useful incremental condition of dependence and exit.
- Evidence of acceptance check: Distinguishing between the scenes of the plan and the results of its actual implementation.
- Operating authorization: does not extend the consent to generate documents to write codes, reset databases, paid letters or publish.
This is not a request to plan every detail to the point where there is no unknown, but rather to place the unknown at the edge of next step.
When a separately validated Moc sent slice has been identified by spec, it can be followed around the slice into implementation, rather than over and over and over and over again rewrite the package. As to how the authentication code, identity and front end really fit together, that is the question that will need to be answered in the next phase with the code and the results of the operation.
Auto-fetched and translated by AI Atlas. All rights belong to the original author.