⏱ 预计阅读：12 分钟
图注：从产品定义到发布交付，关键在于让每次交接可验证。
[!summary] 本文速览
SDD（Specification-Driven Development，规范驱动开发）要解决的，是让每一次决策都有可交接、可验证的下一步，而非把文档写得更厚。
17 个 Skill 把产品、设计、代码、测试和发布之间最容易丢失的契约接了起来。
对独立开发者来说，这条线必须能按风险裁剪、允许并行，也能把验证证据收回来。
前两天，我连续分享了两个自己做的产品。产品文章展示的是最后能看见、能运行的结果，但我更想补上中间那段通常不会出现在截图里的过程：一个模糊想法怎样被拆成需求，页面、接口和 Agent 怎样对齐，代码写完后又凭什么敢发布。
接下来的四篇，我会把这套过程完整拆开。今天先从总览开始，讲清楚我为什么给 Codex 做了 17 个 Skill，以及它们怎样组成一条可以裁剪、也可以验证的研发流水线。
很多人第一次用 Codex 做产品，都会经历一个很熟悉的循环：先让它写一个页面，再补接口；发现权限没有想清楚，再改数据库；功能终于跑起来，测试、部署和文档全留到“以后再说”。
模型写代码通常很快。真正麻烦的是，代码已经生成，权限、状态、接口和验收条件还散在几轮聊天里。下一次打开 Codex，它只能把这些空白重新猜一遍。
我把这套做法叫作 SDD。这里的规格是一份会跟着研发向前走的共享契约：现在依据什么判断，这一步交付什么，下一步拿什么验证。
这 17 个 Skill 就是沿着这份契约组织起来的一条研发线路，从想法一直走到可交付产品。
1、先把 SDD 说清楚：规格要能连续交接
SDD 最容易被误解成“需求文档驱动开发”。如果只有一份 PRD（产品需求文档），那仍然很容易失控：产品说的是用户目标，开发要的是接口和状态，测试要的是可观察行为，运维关心的是回滚和告警。
所以我更愿意把规格理解为一组连续的交接物：
| 阶段 | 需要回答的问题 | 交接物 |
|---|---|---|
| 产品定义 | 为谁解决什么问题，哪些不做？ | 目标、范围、验收标准 |
| 体验与架构 | 用户如何完成任务，系统如何承接？ | 原型、状态、边界、NFR（非功能需求） |
| 详细设计 | 数据、接口、Agent、前端如何对齐？ | Schema、API、状态机、权限与错误契约 |
| 实施与验证 | 谁先做、怎么验证、失败如何回滚？ | 任务 DAG（有向无环依赖图）、测试证据、发布门禁 |
这套 Skill 里还有一个很重要的约束：每个关键事实都要区分 EXPLICIT、INFERRED 和 UNKNOWN。
EXPLICIT：用户、代码或文档已经明确给出。INFERRED：根据已有证据推导出来，需要写明依据。UNKNOWN：不知道，而且会影响后续选择。
这个区分很朴素，却能拦住 AI 最危险的一种行为：把猜测写成事实。
交付状态也需要更精确，至少区分 PLANNED、CREATED、OBSERVED、VERIFIED、BLOCKED。设计稿写出来只是 CREATED；真正跑过测试、看过日志，才有资格叫 VERIFIED。
2、17 个 Skill 到底怎么分工
下面这张表是整套流程的总览，用法就是缺什么补什么，并不要求每个项目都走完 17 步。
| 阶段 | Skill | 它解决什么问题 | 典型输出 |
|---|---|---|---|
| 入口 | S000 项目编排 | 当前到底处于什么阶段？最短路径是什么？ | 路由、依赖、风险、下一步 |
| 开发前 | S001 产品战略 | 这件事值得做吗？谁愿意为它付费？ | 目标用户、假设、实验、继续/调整建议 |
| 开发前 | S002 PRD | 需求怎样才算说清楚？ | FR（功能需求）、AC（验收标准）、状态、权限、范围 |
| 开发前 | S003 原型 | 用户从哪里进入、如何完成、失败后怎么办？ | 页面地图、流程、状态、原型规格 |
| 开发前 | S003-2 UI | 视觉系统、页面状态和资产如何一致？ | 高保真 UI、Token、资产清单、审计 |
| 开发前 | S004 HLD | 系统边界、数据流和技术取舍是什么？ | HLD、ADR（架构决策记录）、NFR、风险 |
| 开发中 | S005-1 数据 LLD | 数据从哪来、怎么存、怎么追溯和删除？ | 数据模型、管道、检索/RAG 契约 |
| 开发中 | S005-2 后端 LLD | API、事务、异步任务和权限怎样定义？ | DTO、错误模型、幂等、接口契约 |
| 开发中 | S005-3 Agent LLD | Agent 能做什么、何时停止、谁来审批？ | 工具权限、预算、状态机、Evals |
| 开发中 | S005-4 前端 LLD | 页面状态、路由、流式交互如何落地？ | 组件边界、状态、前端契约 |
| 评审 | S006 技术评审 | 各层设计真的能接上吗？ | 冲突清单、P0/P1 风险、Go/No-Go |
| 实施 | S007 实施拆解 | 大需求如何拆成可独立交付的任务？ | 任务 DAG、DoD（完成定义）、回滚点 |
| 实施 | S008 代码实现 | 如何在现有仓库做最小且可验证的改动？ | 代码、测试、真实验证证据 |
| 开发后 | S009 测试与 Evals | 功能、接口、AI 输出如何被重复验证？ | 测试矩阵、数据集、运行报告 |
| 开发后 | S010 安全工程 | 威胁、权限、提示注入和数据边界怎么审？ | 威胁模型、安全发现、修复计划 |
| 开发后 | S011 DevOps | 怎么部署、监控、迁移和回滚？ | CI/CD、环境、Runbook、Smoke Test |
| 开发后 | S012 文档交付 | 代码、接口、运维和发布说明怎样不漂移？ | API 文档、运维手册、发布说明 |
这里有三个容易忽略的设计。
第一，S001、S003-2 不是必经关卡。已有成熟产品做一个小功能，不必重新做战略，也不一定需要高保真视觉重构。
第二，S005 的四个分支可以并行。并行前先确认字段、权限、错误和状态是否对齐。
第三，测试和安全要提前介入。S009 可以从 PRD 阶段开始设计测试资产，S010 可以从 HLD 阶段开始做威胁建模。
3、这条流水线怎样跑起来
整个生命周期可以简化成下面这条线：
S000 → [S001] → S002 → S003 → [S003-2] → S004
→ S005-1/2/3/4 → S006 设计评审 → S007 → S008
→ S009 + S010 → S006 发布门禁 → S011 → S012
方括号代表“按需使用”。整条线实际在回答几个很现实的问题：
- 需求变化时，影响哪些资产？
- 前端拿到的状态枚举，和后端实际返回的是不是同一套？
- Agent 调用工具时，权限、超时和成本上限有没有被系统约束？
- 发布前说“测试通过”，到底对应哪一批实际运行结果？
如果这些问题没有留下可追溯的答案，研发就会变成“每次都从聊天记录里找上下文”。
4、独立开发者不必拿走全部 17 个
一个人做产品，最怕把流程做成额外负担。所以我的建议很简单：按项目风险裁剪。
场景一：一个小功能或 Bug
从 S000 判断范围，直接进入 S007 拆任务和 S008 实现；涉及接口时补 S005-2，最后用 S009 做回归。修一个筛选条件，没有必要先写一整套“企业级架构”。
场景二：准备做一个新产品
至少把 S001、S002、S003、S004、S007、S008、S009 跑一遍。这样在写第一行代码前，就已经明确了用户、范围、关键流程、架构边界和验收标准。
场景三：有 AI Agent 或敏感数据
把 S005-3、S010 提前。Agent 要被拆成可调用工具、权限、预算、终止条件和人工审批规则，不能只留下一段 Prompt。涉及用户数据时，安全也要从数据流和信任边界开始设计，不能等发布前才扫一次漏洞。
场景四：准备对外发布或交付客户
最后一定不要跳过 S006、S011、S012。在自己电脑上跑通，只是发布的起点；用户能否稳定使用、出了问题能否定位和回滚，才是交付要回答的事。
5、我在 SDD 里最看重的十个经验
先说明案例边界：下面十个案例都是把常见研发冲突压缩后的示意场景，用来说明方法怎么落地，不对应某一个真实客户或已交付项目。
经验一：先写“不可猜”的部分
不要急着让 AI 生成页面。先把这些写下来：谁能做什么、做完后状态如何变化、错误怎么提示、数据是否能删除、什么情况下需要人工确认。这些内容一旦靠猜，返工会沿着接口、数据库、前端和测试同时扩散。
一个最容易踩坑的场景是“管理员可以删除文档”。后端可能把它理解为删除文件，检索层仍保留旧索引，前端则立即隐藏条目。先在 S002 写清“删除请求—处理中—删除生效—历史引用不可再访问”四个状态，S005-1、S005-2、S005-4 才能交付同一个行为。
经验二：把事实、推断和未知项拆开
S000 的 EXPLICIT、INFERRED、UNKNOWN 三分类看起来简单，却能阻止最常见的“规格漂移”。AI 很擅长把空白补得流畅；研发真正需要的是知道哪些结论有证据，哪些只是当前最合理的假设。
举个简化例子。用户只说“希望员工用公司的知识库提问”，并没有说明是否支持跨部门检索。把“需要租户隔离”直接写成既定需求，会增加不必要的复杂度。先标记为 UNKNOWN，再让 S001 设计访谈问题、S002 将权限范围列为未决项，团队可以继续推进原型，也不会把一条猜测固化为数据库结构。
经验三：先选最短路径，不要每次都跑完整流水线
SDD 从来不以文档数量论成败。S000 要为当前目标挑出最少且足够的 Skill：改一个明确的表单校验，可以从 S007/S008/S009 开始；做一个新产品方向，才需要 S001 到 S004。流程是否合理，要看风险有没有门禁，而不是编号有没有走全。
什么时候可以直接跳过前面的 Skill？比如某个已上线页面只需新增“撤销上传”按钮，而且删除 API、权限规则和测试夹具都已存在。这时让 S007 把需求拆成前端状态、接口调用和回归测试三项就够了；强行重写 S001 战略和整份 HLD，只会把一小时的改动拖成一次无价值的重设计。
经验四：验收标准要在实现前就能失败
S002 最重要的产物是 AC（验收标准）。如果无法写出“给定什么、发生什么、应该看到什么”，那就还没有定义好完成。把验收前置，才能让 S003 的页面状态、S005 的接口、S009 的测试都指向同一件事。
拿 PDF 上传来说，“支持导入 PDF”还无法验收。更可用的 AC 是：给定一个权限合法但内容为空的 PDF，当管理员上传后，系统显示“无法提取文本”，不创建可检索文档，并允许管理员下载错误详情。这样 S003 会画错误与恢复路径，S005-2 会定义错误码，S009 也有了一条稳定的回归用例。
经验五：并行前先冻结握手面
四个 S005 分支可以并行，但不能各写各的。并行前要把字段、状态、错误、权限、事件顺序和数据所有权写成握手清单；S006 再检查它们是否一致。并行能省等待时间，写契约的时间省不了。
真正麻烦的是这种情况：数据设计将文档片段标识命名为 chunk_id，Agent 工具 Schema 使用 passageId，前端引用组件期待 source_id。三端都能独立跑通，却无法稳定联调。若在 S005 开始前由 HLD 指定“引用对象 ID、版本、权限过滤字段与删除语义”，名称差异会在编码前暴露，也就不用上线后靠兼容层堆补丁。
经验六：原型要覆盖恢复路径，不只展示成功路径
S003 用最低成本暴露交互缺口。加载、空、错误、权限不足、离线、超时、取消、重复提交和危险操作确认，都属于产品行为，不能留成“以后由开发补一下”的边角料。
比如用户点击“生成答案”后网络中断。原型若没有交代已生成部分如何处理、能否重试、是否会重复扣费或重复调用，前端只能临时猜。把断线、取消和恢复写入原型后，S005-4 会定义事件续传和按钮状态，S005-3 会定义 Agent 取消边界，用户也不会面对一个无限转圈的输入框。
经验七：视觉系统也是端侧契约
S003-2 的价值不止于做出高保真稿。Token（设计变量）、组件状态、响应式规则和资产清单会成为 S005-4 实现与 S006 审核的共同事实。只交一张首页图，等于把所有边缘状态留给工程师临场发挥。
我会先检查一个细节：一个“需要管理员审批”的高风险操作，在视觉稿里是否仍是一枚普通按钮？如果是，前端很可能把它做成一次点击即执行。设计阶段明确警示层级、确认弹窗、禁用状态和审批中反馈后，前端实现才能保留产品意图，安全设计也能追溯到具体交互。
经验八：评审要放在代码之前，也要放在发布之前
S006 有两个不同角色：设计评审用来抓“各层规格看似都对、合起来对不上”的错位；发布门禁用来确认测试、安全、迁移和回滚证据是否真的存在。它关注的是资产之间能否正确交接，不负责检查代码风格。
这里看一个具体冲突。前端叫 job_id，后端返回 taskId 还只是轻微问题；更严重的是，后端将“删除任务已受理”当成功，前端却显示“资料已彻底删除”，检索索引此时仍在异步清理。设计评审可以要求补齐状态枚举、轮询或事件以及删除完成证据；发布门禁再确认相关回归测试和回滚方案是否真正执行过。
经验九：工单按可交付纵向切片拆，不按技术部门拆
S007 的任务单位应是可观察的用户价值、契约或风险。若只拆成“数据库任务”“后端任务”“前端任务”三张清单，它们很快就会彼此等待。每张工单还应带范围、依赖、禁止项、DoD（完成定义）、测试、安全、迁移和回滚。
把“完成知识问答模块”拆开看，可以先交付“用户只能检索自己有权访问的资料，并看到可点击引用”这一纵向切片。它会触及最小权限过滤、检索工具、答案引用、前端展示和一组回归测试，但可以独立验收、独立回滚，也能更早验证真正的产品风险。
经验十：让“未完成”也有准确表达
很多团队做了不少事，却把状态说得太满：计划被写成完成，设计被写成已验证，预计结果被写成实际指标。S008、S009、S010、S011、S012 都要求区分 PLANNED、CREATED、OBSERVED、VERIFIED、BLOCKED，并附上可追溯证据。
这一区分落到发布里很直观：CI 配置已经提交，只能说明部署链路被 CREATED；在 staging 环境跑过健康检查，才有 OBSERVED；真正触发一次小流量发布、监控到核心路径并验证回滚可用后，相关门禁才可写为 VERIFIED。这种表达不会拖慢项目，反而能让独立开发者准确知道下一步该补运行、补证据，还是补设计。
6、写在最后
这 17 个 Skill 最终只想解决一个问题：让 Codex 在更少猜测的情况下，持续交付可验证的产品增量。
我现在判断一份规格是否有用，只看一件事：下一阶段敢不敢拿它直接做判断。敢，就说明这里留下了足够的证据。
如果你正在独立开发一个产品，可以先问自己一个具体问题：下一次需求改动发生时，你能不能在 10 分钟内说清它会影响哪些需求、接口、状态、测试和发布步骤？
能说清，你已经在做 SDD；说不清，就从 S000 和 S002 开始补第一张地图。
明日预告｜第 2 篇：开发前，怎样把想法变成可评审规格
17 个 Skill 的地图有了，下一步先不急着写代码。我会从“做一个团队资料问答工作台”这句模糊想法出发，具体拆解 S000 到 S004：如何判断值不值得做，怎样写出可验收的 PRD，原型为什么必须覆盖失败路径，以及 HLD 到底要把哪些系统边界钉住。