AI 原生研发范式：从“代码中心”到“文档驱动”的演进

推荐语

AI编程时代如何避免工程失序？SDD开发范式为你提供轻量可落地的人机协作方案。

核心内容：
1. AI编程三大痛点：上下文腐烂、审查瘫痪、维护断层
2. SDD开发范式原理与价值：文档锚定上下文，代码成为可消耗品
3. 两种落地版本选择：个人极速迭代的Lite版与团队长期维护的标准版

杨芳贤

53AI创始人/腾讯云(TVP)最具价值专家

TL;DR (太长不看版)

根据任务复杂度，你可以灵活选择“重”度：

• Lite 版 (Vibe Mode)：

• 适用：个人开发、原型验证、极速迭代。
• 特点：Flow over Friction。

• 零侵入 (Zero Friction)：无需安装 CLI，无需配置环境，新建一个 .md 即可开始。
• 无痛回滚 (No Lock-in)：随时可以停止使用。留下的文档是可读的“资产”，而不是难以维护的“技术债”。
• 操作：仅需一份简要的 Task_Spec 作为上下文锚点，即可开始极速 Reroll。

• 标准版 (Team Mode)：

• 适用：多人协作、复杂业务逻辑、需要长期维护的项目。
• 特点：完整的 Requirements -> Interface -> Implementation 链路，确保 AI 在长周期内不漂移。

目标：30 分钟跑通一次“文档 → 实现 → 复核 → 留痕”，产出 docs/specs/feature-xxx/ 。

• 0–3min（Initialization）：给 AI 一份“家规/约束/口径”，让它复述确认。
• 3–10min（Research）：给大模型足够的上下文和清晰的需求，让他出spec文档（In/Out + AC + 约束），你 Sign-off。
• 10–15min（Plan）：让大模型按照spec文档去规划步骤并且更新到文档中。
• 15–25min（Execute）：按spec文档的描述分步写代码 + 最小单测。
• 25–30min（Review）：New Chat/换模型审查 Spec文档 + Diff，然后人工review此次改动并且上线。

先把闭环跑通，再逐步把门禁、规则库、决策日志升级到团队级（Full 版）。

如果你希望先“照着跑一次完整闭环”（Spec → 实现 → 测试 → 交付留痕），可以先做一个开源项目的小练习：

• 案例：Halo 新增 SystemConfig 分组列表 API（只返回 group name）+ 单测 + AI_CHANGELOG

大模型与 AI 编程工具进入了快速迭代期：IDE、插件、模型能力每天都在刷新上限。表面上看是生产力爆发，但在真实的团队工程里，我们正在同时遭遇三类“隐性成本”，它们会抵消甚至吞噬工具红利。

团队把大量注意力投入在“用哪个模型/哪个 IDE 更强”的选择与配置上。短期看每个人都更快了，但由于缺少统一的输入标准与产出约束：

• 代码风格、工程结构、边界处理各自为政
• 同一需求被不同人用不同工具实现，产物难以合并、难以维护
• 组织层面无法复制经验，只能“个人英雄式提效”

评测往往聚焦“写得快不快、能不能一把梭”，但工程需要回答的是：

• 可维护性是否提升（结构清晰、可读、可扩展）
• 缺陷率是否下降（边界、异常、兼容性是否可靠）
• 需求变更时是否敢改、改得动（是否可追溯、可验证） 如果 AI 只是更快地产生“一次性代码”或“幻觉代码”，组织获得的不是效率，而是技术债累积速度。

不少人仍把 AI 当成“问答框”：

• 报错就贴日志问原因
• 要函数就要片段
• 甚至不理解逻辑就直接接收产出

这种“补丁式/填空式”使用，缺少流程、缺少门禁、缺少协作协议，团队协作时很难形成稳定产能。

工具已经进入 AI 时代，但研发流程与协作方式仍停留在“人肉编码”的惯性里。要让 AI 真正成为可规模化的生产力，需要把个人技巧升级为团队 SOP。

我自己的真实 case：上个月用模型做了一个复杂功能（代码量大，经历多轮优化与 bugfix）并上线。后续出现几个小 bug、产品追加了几个新点；如果不用 SDD，就得翻提交+人工回忆来重建上下文，既慢也不精确；如果用 SDD，只要把“新需求文档 + 旧实施文档/决策留痕”交给模型，通常 10 分钟内就能启动下一轮迭代。

接下来要介绍的 SDD（Spec-Driven Development，规范驱动开发），核心目标很明确：让“文档/规范”成为任务的唯一事实来源，让 AI 围绕规范执行与互审，让人回到设计、决策与验收的位置。

💡极客时刻：重新定义 .md

曾有人提到过一个绝妙的笑话：以前编程语言都是从各种角度设计给人的，什么各种复杂的面向对象、类型系统、语法设计⋯很低效，虽然对于AI来说不在话下。下一个编程语言应该是直接给AI设计的，让AI可以高效创作。我建议命名为Machine Done（机器完成），后缀名都想好了，就叫.md。

这不仅仅是个段子，这正是 SDD 的本质。

在真正的 AI 原生语言出现之前，Markdown 就是我们将意图传递给硅基大脑的最佳中间语言 (Intermediate Representation)。它既是人类的可读文档，更是机器的执行指令。写下 .md 的那一刻，就意味着：Human Designed, Machine Done.

SDD 的关键不在“写更多文档”，而在于把 Spec（Specification） 当作研发过程的“契约”。在 AI 时代，编程的重心从“人直接写代码”转向“人定义规范，AI 按规范实现”。

需要纠正一个常见误区：文档不只是写给人看的，它同样是写给 AI 看的。
在 SDD 模式下，Spec 扮演一种“中间表示（IR）”：

• 人把模糊意图明确成可验证的规范（Spec）
• AI 读取 Spec 生成代码、测试、变更说明
• 另一 AI（或另一轮会话/模型）以 Spec 为准绳进行 Review
• 通过“以 Spec 为准”的闭环，减少口头沟通失真与上下文丢失

换句话说：Spec 是团队里人和 AI 的共同语言，也是跨角色协作的统一输入。

1) 解决上下文丢失：用 Spec 锚定任务（Context Anchoring）

大模型对话天然存在“记忆衰减、注意力丢失、上下文腐烂、重点漂移、换会话丢上下文”等问题。Spec 作为稳定锚点，使得：

• 任务可在任意时间恢复（把 Spec 交给 AI 即可重建上下文）
• 重点更集中（以验收标准/边界条件为中心）
• 沟通更可追溯（争议回到 Spec，而不是回到聊天记录）

2) 不需要人类从零写文档：AI 起草，人类 Review / Sign-off

SDD 的典型操作流不是“人从头写一套文档”，而是：

• 人提供需求/背景/约束（即使是粗糙口述也可以）
• AI 产出或改写 Spec（结构化、可审阅）
• 人作为仲裁者 Review，补齐边界与验收标准，并最终签字确认
• 只有 Spec 通过，才进入编码与交付核心变化是：人把精力放在“正确性与决策”，而不是“打字与搬运”。

3) 角色边界清晰：不同角色对齐在不同层级的 Spec

SDD 不是让所有人都写同一种文档，而是让协作关系“各看各的关键点”：

• PM/业务：Requirement Spec（目标、范围、验收）
• 前后端/客户端：Interface Spec（字段、错误码、示例、契约）
• QA：Test Spec（用例覆盖、边界、回归策略）
• 架构/核心研发：Implementation/Architecture Spec（实现路径、取舍、风险） 大家在各自关心的层面完成对齐，最终通过 Spec 链条咬合成闭环。

4) 真正解耦模型与工具：Spec 让产能可迁移

当 Spec 足够清晰、约束足够明确时：

• 模型/工具可以替换（写草稿、重构、补测试、做 Review 可用不同模型）
• 产出更稳定（弱一些的模型也能按规范交付合格结果）
• 组织资产沉淀在 Spec 与规则里，而不是沉淀在某个工具的“私有用法”里

5) 信心锚点 (Confidence Anchor)：消除“失控感”

AI 编程最大的副作用是“失控感”。当 AI 生成了你读不完的代码时，SDD 文档是你唯一能完全掌控的真理。它让 Review 从“在海量代码中找 Bug”变成了“检查代码是否兑现了文档承诺”。

结论：SDD 的核心不是“文档本身”，而是“以规范为中心的协作协议 + 可验证门禁”，从而把 AI 的能力变成组织可复制的工程能力。

💡 核心辨析：为什么不直接用 OpenSpec 或 Spec-Kit？

市面上已经出现了如 OpenSpec、GitHub Spec Kit 等优秀的 SDD 自动化工具。它们很棒，但对于许多开发者来说，它们可能“太重了”或者“太死板”。

本文提出的 Manual SDD 范式 与这些 工具框架 的核心区别在于：

结论：OpenSpec 是把 SDD 变成了流程，而本文是把 SDD 变成了习惯。在 Vibe Coding 中，我们更倾向于“习惯”，因为习惯没有运行时开销。

"If fixing takes too long, regenerate." (如果修复太慢，就重生成) —— Manifesto for Vibe Coding
但重生成的前提是：Spec 是准确的。否则重生成就是抽奖。

在这个单元，我们将深入“单兵作战”的细节。

很多程序员抱怨 AI 写的代码不能用，本质原因是 跳过了思考，直接进入了执行。为了解决这个问题，我们将传统的编码过程重构为 Initialization + RIPER + LAFR 全链路模型。

这不仅仅是写代码，这是一场精心编排的 人机协作 (Human-AI Symbiosis)。

“在开始干活前，先告诉 AI 它是谁，以及家规和历史信息是什么。”
不要上来就扔需求。大模型就像一个刚入职的天才实习生，你需要先给它做 Onboarding。

• 动作：

1. 装载协议：这是 SDD 的“操作系统”。如果你有没有个人偏好，或者以前没有用过大模型，请先发送以下指令，让 AI 进入“文档驱动模式”：

⚡️ 通用启动指令 (System Prompt)

# RoleYou are a Senior Engineer following the "Spec-Driven Development" protocol.
# Workflow Rules1.  **Context First**: Before coding, ALWAYS check if a relevant Spec file exists in `docs/`.2.  **No Hallucinations**: If the user request contradicts the Spec, STOP and ask for clarification.3.  **Update Loop**: If you change the code logic, suggest updates to the corresponding Spec file immediately.
# File Structure Strategy- Use `01_requirements.md` for User Stories.- Use `02_interface.md` for Tech Stack & Data Structures.- Use `03_implementation.md` for detailed Logic/Prompts.

2. 加载偏好（可选）：发送你的 Prompt_Skill.md 或 .cursorrules 的个性化部分。

• 告诉它你的“私有家规”（如：“禁止使用 Lombok”、“所有金额计算使用 BigDecimal”）。
• 注：如果没有特殊喜好，这一步可跳过，直接复用通用的启动指令即可。

3. 注入记忆：把项目里的 README.md和某些功能的过往的历史信息也提供给大模型。

• 🚪 验收门禁：

• AI 是否确认收到了上下文？（让它简单复述一遍主要约束和对此项目的总结）

Step 1: Research (调研与意图锁定)

“不要急着给方案，先搞清楚到底要解决什么问题。”

很多时候，我们的需求描述是模糊的。这个阶段的核心是 “反向复述”。

• 输入：你模糊的想法、Bug 的现象、或者一段杂乱的聊天记录。
• 动作：

• 让 AI 阅读并复述：指令它 —— “请阅读上述需求，用你自己的话复述一遍，并指出其中不清晰的地方。”
• 澄清边界：让 AI 告诉你，这个需求涉及哪些业务领域？需要参考哪些现有的代码逻辑？

• 产出：清晰的 Requirement Spec (需求意图)。
• 🚪 验收门禁：

• AI 指出的“模糊点”是否都已解答？AI是不是已经完全明白了需求意图和项目结构？

Step 2: Innovate (设计与推演)

“这是体现架构师价值的环节。寻找最优解，而不是第一个想到的解。”
这一步严禁写代码，而是要进行 “审讯游戏 (The Interrogation Game)”。

• 动作：

• 你要问它：“除了这个方案，还有没有更好的？”“这样做的坏处是什么？”
• 逼它问你：指令它 —— “如果你对现有业务逻辑或代码细节有任何不确定的地方，请立刻向我提问，不要自己瞎猜（Hallucinate）。”

• 引入外部智慧：把你同事的建议，或者你在其他项目的经验喂给它作为补充。

• 产出：Design Spec (设计/技术规格书)，包含核心技术选型、Pros/Cons 分析。

• 🚪 验收门禁：

• 你是否对这个设计方案进行了 review和Sign-off（批准）？

Step 3: Plan (规划与契约)

“从战略下沉到战术。不仅要告诉它造什么房子，还要告诉它每一块砖怎么砌。”
文档即协议。我们要把模糊的 Design 变成精确的 Implementation Plan。

• 动作：

• 要修改哪几个文件（File Paths）？
• 要新增哪几个方法和类（Signatures）？
• Mock 数据：在写代码前，先定义好接口的 Request/Response 示例。

• 产出：Implementation Spec (详细实施/接口文档)。
• 🚪 验收门禁：

• 实施计划是否拆解到了“原子级”任务，如果换一个大模型是否可以100%完美实施？

Step 4: Execute (执行与编码)

“你不是在看戏，你是在跟 AI 结对编程 (Pair Programming)。”

• “好的，先完成 Step 1 的数据库 Schema 变更。”
• “现在进行 Step 2，实现 Service 层逻辑。”

• 产出：源代码。

• 🚪 硬性门禁(Hard Gates)：

• Lint Check：生成的代码必须通过 Linter 检查（无语法错误、无未使用的变量）。
• Compile Check：代码必须能编译通过。如果跑不通，严禁进入下一步。

Step 5: Review (验收与对齐)

“让一个 AI 去检查另一个 AI 的作业。”

“这是对抗‘代码通胀’的唯一防线。当 Diff 达到几千行时，不要试图人肉 Review，要相信 Spec 的验证能力。”

• 指令：“请基于这份 Spec 审查这次代码变更。寻找潜在 Bug、逻辑漏洞或不符合规范的地方。”

• 产出：单元测试、Review 报告、最终交付代码。

• 🚪 硬性门禁 (Hard Gates)：

• Automated Tests：自动化测试必须全绿（覆盖门槛按项目等级设定，并在 CI/规则库中固化）。
• Interface Contract：新代码的接口响应必须与 02_interface.md 定义的 JSON Schema 完全一致（使用工具自动比对）。
• 未过门禁 = 0 交付：任何一项失败，直接退回 Step 4，严禁合并代码。

“遇到 Bug 时，不要直接改代码。Bug 的本质是‘代码’与‘文档’的对齐失败。”
当生产环境报错或测试不通过时，请严格执行 L.A.F.R. 流程：

• 如果是代码错 -> 生成补丁。
• 如果是文档错 -> 必须先改文档，再重新生成代码。

• 更新 SKILL.md，防止下次复发。
• 在文档上打补丁：“⚠️ [FIX] 此处逻辑曾导致死锁，已修正为...”

为了让“文档 = 协议”不再停留在概念层，这一章用一个贯穿示例（用户积分系统 - 签到功能）展示：一套最小但完整的 Spec 链条应该长什么样、写到什么粒度算合格、以及这些文档如何直接驱动 AI 产出与团队并行协作。

本章的核心原则：

• Spec 不是“说明书”，而是“可执行指令集”：能直接喂给 AI 生成代码/测试/评审。
• 每份 Spec 都要“可验收”：写清楚验收标准与边界，减少口头解释空间。
• 一份 Spec 对应一个 Owner 与一次 Sign-off：否则文档会快速漂移（Spec Drift）。

docs/├── specs/│   ├── feature-001-checkin/              # 一个 feature 一个目录│   │   ├── 00_context.md                 # 可选：一次性上下文（业务背景/现状/约束）│   │   ├── 01_requirement.md             # 需求意图（PM/业务/Owner）│   │   ├── 02_interface.md               # 接口契约（前后端/客户端共同协议）│   │   ├── 03_implementation.md          # 实施细节（AI Coder 执行指令）│   │   └── 04_test_spec.md               # 测试策略与用例（QA/Test Agent）├── decisions/│   ├── AI_CHANGELOG.md                   # 决策与变更日志（审计/追溯）│   └── ADR-xxxx.md                       # 可选：重大架构决策记录├── skills/│   └── SKILL.md                          # 团队规则库/“家规”（防复发）└── logs/    └── ai-review-reports/                # 可选：每次 Review 报告归档

约定建议（便于团队规模化）：

• 命名稳定：01/02/03/04 固定顺序，降低沟通成本。
• 一个 feature 一套文档：不要把多个需求混在一个 Spec 里，避免上下文污染。
• 文档也要版本意识：重大变更通过 PR 更新 Spec，让“讨论/决策/结果”都可追溯。

下面给出每类 Spec 的三件事：

• 最小模板（团队可直接复制）
• 签到功能示例片段（让你知道该写成什么样）
• 门禁（Definition of Done）（写到什么程度才允许进入下一步/合并代码）

A. Requirement Spec（需求规格）——意图层（写给人，也写给 AI）

定位：把“想要什么”写成可验收的契约，避免实现阶段反复扯皮。主要读者：PM/业务 Owner、研发 TL、QA、AI（用于复述与生成后续文档）。

最小模板：01_requirement.md

• 背景（Context）：为什么要做（1 段即可）
• 目标（Goals）：要达成什么结果（条目化）
• 范围（In Scope / Out of Scope）：明确不做什么
• 验收标准（Acceptance Criteria, AC）：必须可验证
• 约束（Constraints）：性能/安全/兼容/依赖系统/灰度要求
• 风险与灰度（Risks & Rollout）：上线策略、回滚预案（如适用）

示例片段（签到功能）

## Background为了提升 DAU 与留存，引入“每日签到得积分”，积分可用于兑换权益。
## In/Out- In：每日签到、幂等、防重复、查询签到状态、积分发放- Out：积分商城兑换、积分过期策略（本期不做）
## Acceptance Criteria- AC1：同一用户同一天只能签到一次，重复请求返回“已签到”且不重复发放积分- AC2：返回结果需包含：是否签到、签到时间、当次获得积分、当前总积分- AC3：接口 P95 < 200ms（依赖现有积分查询能力）- AC4：出现异常时必须可追溯（含必要审计字段）

门禁（写完才允许进入接口/实施）

• AC 至少覆盖：主流程 + 重复请求/幂等 + 至少 2 个失败场景
• In/Out 明确，避免“做到一半发现还要做 X”
• 关键约束写清楚（性能/安全/灰度/审计），否则后面补救成本更高

B. Interface Spec（接口契约）——协议层（跨角色并行的关键）

定位：这是前后端/客户端/测试并行启动的“唯一真相”。主要读者：前端/客户端（生成 types/mock）、后端（实现约束）、QA（生成用例/自动化）、AI（按契约写代码）。

最小模板：02_interface.md

• 总览：鉴权方式、幂等要求、错误码规范
• Endpoint：路径、方法、说明
• Request：字段表/Schema（含必填、类型、枚举、校验）
• Response：字段表/Schema（明确成功/失败结构）
• Error Codes：错误码、含义、触发条件
• Examples：成功/失败示例（用于 mock 与契约测试）

• Notes：兼容性、版本策略（如适用）

## API: POST /api/v1/points/check-inAuth: Bearer TokenIdempotency: 同一 userId + 同一 date 必须幂等
### Request- date (string, optional): YYYY-MM-DD，不传则默认当天（以服务端时区为准）
### Response (Success)- checkedIn (boolean)- checkedInAt (string, ISO8601, nullable)- pointsEarned (int): 本次发放积分（已签到则为 0）- totalPoints (int)
### Error Codes- INVALID_DATE：date 格式非法- UNAUTHORIZED：未登录/Token 无效- INTERNAL_ERROR：服务端异常（需返回 requestId）
### ExamplesSuccess(first time):{ "checkedIn": true, "checkedInAt": "2026-01-02T09:00:00Z", "pointsEarned": 5, "totalPoints": 120 }
Success (already checked-in):{ "checkedIn": true, "checkedInAt": "2026-01-02T09:00:00Z", "pointsEarned": 0, "totalPoints": 120 }

门禁（写完才允许前端/测试并行、后端进入实施）

• 必须有成功 + 已签到（幂等） + 至少 1 个失败示例
• Error Codes 写清“触发条件”，避免后续实现随意发挥
• 字段定义要可直接生成类型（TypeScript/Java DTO），否则契约无法落地

C. Implementation Spec（实施细节）——执行层（给 AI Coder 的“施工图”）

定位：把“怎么改”写成可执行计划，控制 AI 的改动范围与顺序。主要读者：实现负责人、AI Coder、Reviewer。

最小模板：03_implementation.md

• 目标复述：用 3~5 行复述本次要实现什么（对齐）
• 变更范围：要改哪些文件/模块（带路径）
• 数据变更：表结构/索引/迁移（如适用）
• 核心流程：伪代码/步骤（含幂等、并发、事务边界）
• 关键校验与异常：输入校验、错误码映射、审计字段
• 分步执行计划：Step 1/2/3…（每步可独立验收）
• 回滚与兼容：怎么关、怎么回退、影响面

示例片段（实现计划）

## File Changes- backend/src/main/java/.../CheckInController.java- backend/src/main/java/.../PointsService.java- backend/src/main/java/.../PointsRepository.java- backend/src/test/java/.../PointsServiceTest.java
## Core Logic(pseudo)1) parse date(default today) -> validate format2) start tx3) try insert checkin_record(user_id, date) with unique(user_id, date)   - if conflict -> return already checked-in(pointsEarned=0)4) if inserted -> add points(+5)and write ledger/audit5) commit6) query totalPoints -> return response
## Execution Plan- Step1: 增加/确认 checkin_record 唯一约束与实体映射- Step2: 实现 PointsService.checkIn(date) 幂等逻辑 + 错误码映射- Step3: Controller 层对齐接口契约（02_interface.md）- Step4: 补单测（首次签到/重复签到/非法日期）

门禁（写完才允许进入编码）

• 明确文件路径 + 方法签名/职责边界
  （否则 AI 容易乱改）
• 核心流程必须覆盖：幂等/并发/事务/异常映射
• 执行计划可分步验收（每步完成后可自检/可回滚）

D. Test Spec（测试策略）——验证层（把验收落到可执行用例）

定位：把 AC 与接口契约转成测试策略与用例清单，避免“上线后才发现漏测”。主要读者：QA、研发（补单测/集成测试）、AI Test Agent（生成用例/脚本）。

最小模板：04_test_spec.md

• 测试范围：覆盖哪些层（Service/Controller/契约/集成）
• 测试策略：哪些用单测，哪些用集成，哪些做契约测试
• 用例列表：编号 + 场景 + 期望结果（对齐 AC/Error Codes）
• 数据准备：前置数据、时间/时区假设、Mock 依赖

• 回归影响：可能影响哪些老功能（提示回归点）

## Strategy- Service 层：单测覆盖幂等与错误码- Controller 层：契约测试校验 JSON 字段与类型（对齐 02_interface.md）
## Test Cases- TC1 首次签到：返回 checkedIn=true, pointsEarned=5，totalPoints 增加- TC2 重复签到：pointsEarned=0，总积分不变，checkedInAt 不变化- TC3 非法 date：返回 INVALID_DATE- TC4 并发重复请求：最多一次发放积分（验证唯一约束/幂等）

门禁（写完才允许合并/上线）

• 用例必须覆盖：AC 中的关键路径 + Error Codes + 并发/幂等
• 若线上问题修复：必须补充对应回归用例（防复发）

E. 交付与归档模板（让“可追溯”成为默认）

1) Implementation Summary（交付小结，建议进入 PR 描述）

- Feature：实现每日签到得积分（含幂等）- Changes：新增 checkin_record 唯一约束；新增/修改 PointsService.checkIn；补充单测- Risks：时区口径（服务端时间为准）；并发下依赖唯一约束兜底- Rollback：开关关闭签到入口；保留数据表但停止写入- Related Specs：docs/specs/feature-001-checkin/*

2) AI_CHANGELOG.md（决策日志：记录“为什么这么改”）

2026-01-02 feature-001-checkin- Decision：幂等通过数据库唯一约束实现，而不是 Redis 计数- Reason：降低一致性风险与依赖复杂度；数据库作为最终一致性来源- Risk：高并发写入压力；需关注索引与事务耗时

在你把 Spec 丢给 AI 之前，先自检 2 分钟：

• Requirement：AC 是否“可测试”、是否包含边界与失败？
• Interface：是否有幂等/错误码/示例？前端能否直接做 mock？
• Implementation：是否写清文件路径、步骤、事务/并发处理与回滚？
• Test：是否覆盖幂等与错误码？是否写清数据准备与回归点？
  做到以上四点，章节 3 的 RIPER 执行才会真正稳定；否则再强的模型也会在“缺口处自由发挥”。

如果说上一章解决的是“如何让 AI 帮你写好代码”，那么这一章要解决的是“如何让 AI 帮团队消除沟通噪音”。

现状是分裂的：我们每个人手里都有了核武器（大模型），但团队协作还在用冷兵器（开会、口述、聊天记录）。我们必须构建一套新的协作 SOP，核心理念只有一条：人与人的沟通只负责确认意图，AI 与 AI 的沟通负责传递细节。

虽然完全实现尚需时日，但我们应以此为北极星：

• 前线人员不再扔一堆杂乱的聊天记录给产品，而是先让 AI 总结：“把这段客户沟通整理成结构化的需求草案，去除废话，保留核心痛点。”
• 价值：从源头消灭“不说人话”的需求。

• 产品经理将草案喂给 AI，生成标准化的 PRD（需求规格书）。
• 价值：虽然开发人员知道需求是什么，但大模型不知道。PM 用 AI 生成的文档，本质上是在为开发的 AI 准备“精准的 Prompt”。

• Team Leader 维护一份 Team_Context.md（组员负责的方向、当前负荷、技术栈偏好）。
• 让 AI 辅助决策：“基于这个需求文档和团队现状，建议分配给谁？有什么技术风险？”

在实战中，我们发现强行要求“文档与代码实时完美同步”会严重拖慢开发节奏。因此，我们总结出了 “双态管理”策略，将文档区分为“热数据”与“冷数据”：

💡 经验之谈：

• 开发时：不要有心理负担，把 Spec 当作你的草稿纸。
• 合并时：就像你会 Squash 那些琐碎的 Git Commit 一样，你也应该 Squash 你的文档，只把最终生效的逻辑同步给团队。
• 最终这些文档会合并上传并沉淀在你团队的知识库，成为团队宝贵的资产。

鉴于业务侧的不确定性，我们可以优先在后端、前端/客户端、测试之间建立强制性的 Spec 协作流。

责任分工（建议，避免“文档写了没人维护”）

• 01_requirement.md：Owner=需求/产品或需求提出人；Sign-off=业务 Owner + TL。
• 02_interface.md：Owner=接口提供方（通常后端）；Sign-off=接口消费者（前端/客户端）+ QA。
• 03_implementation.md：Owner=实现负责人；Sign-off=TL/核心评审人。
• 04_test_spec.md：Owner=QA（或测试 Owner）；Sign-off=实现负责人 + QA。

阶段一：后端作为“定义者” (Backend as Definer)

后端开发不再是默默写代码，而是先产出“契约”。

• 动作：后端在写业务逻辑代码前，先让 AI 按照章节2的流程生成技术文档、实施文档和 02_interface.md（接口文档） 。
• 人类介入：Leader和同事只需要 Review 这些文档。文档通过，等于架构设计通过。

阶段二：并行开发 (Parallel Execution)

这是效率提升最显著的环节。传统的“前端等后端接口”模式被彻底打破。

• 前端/客户端 (The Consumer)：

• 输入：拿到后端发来的 02_interface.md。
• AI 动作：

• 结果：在后端一行代码没写的时候，前端已经基于 AI 生成的“完美模拟器”完成了 UI 开发和逻辑联调。

• 测试/QA (The Validator)：

• 输入：拿到 01_requirement.md (需求) + 02_interface.md (接口)。
• AI 动作：

阶段三：交付与归档 (Handover & Archive)

• 代码不是唯一的交付物：

• 提交代码时，必须附带由 AI 更新过的 Implementation Summary (实施总结)。
• 内容包括：改了什么？为什么这么改？哪里有潜在风险？配置项怎么配？

• 项目收尾归档：

• 项目结束后，将所有文档（需求、接口、实施、测试）丢给大模型。
• “把这些文档归档，更新到项目的 README.md 和 Architecture.md 中，保持项目知识库的鲜活。”

1. 大模型的“通天塔”作用：

• 前端看不懂后端的 Java 代码，测试看不懂前端的 React 代码。
• 但所有人的 AI 都能看懂 Markdown 文档。文档成为了跨语言、跨角色的通用字节码。

2. 消除“幻觉传递”：

• 口述最容易失真。A 说“大概两小时”，B 听成“两小时后上线”。
• 文档是静态的、可追溯的。AI 基于文档生成的代码，只会忠实于文档，不会忠实于你的“口误”。

3. 极低的接入成本：

• 不需要购买复杂的协作软件。
• 仅仅是多了几个 .md 文件。
• 大家依然用自己喜欢的 IDE 和 AI 工具，只是输入源变了。

4. 归档和溯源：

• 现在每个人都需要强制写文档和留存文档了，可以极大地增强文档的覆盖率。
• 如果出现一些误会和问题，可以快速准确的定位，不需要再翻聊天记录扯皮了。

千万不要觉得“全都交给 AI 了，人没事干了”。恰恰相反，在这个流程中，人的“决断力”变得前所未有的重要。

• PM 要决断：AI 生成的需求文档，逻辑是否自洽？是不是用户真正想要的？

• 后端 要决断：AI 建议的数据库设计，三年后是否会成为系统性风险？

• 前端 要决断：AI 写的 Mock 数据是不是太理想化了？真实网络环境会怎样？

  SOP 的目的不是把人变成机器，而是把人从“复读机”和“搬运工”的低级劳动中解放出来，去把控那些只有人类能理解的复杂性（Context & Humanity）。

在 SDD 模式下，代码变得廉价且易变（Disposable）。那么，团队究竟在积累什么？ 答案是：积累“如何让 AI 写出好代码”的知识。
以前，资深工程师的经验存在脑子里；现在，必须把这些经验固化为 Agent Skills。

"Taste is the ultimate filter." (品味是终极过滤器)

不要让每个人都去重复踩坑。

• 动作：在项目根目录维护一个 .cursorrules 文件或 docs/skills/SKILL.md。
• 内容：

• 技术偏好：“本项目使用 Java 17，优先使用 Record 类，禁止使用 Lombok。”
• 业务铁律：“所有涉及金额的字段，数据库必须用 _Decimal(19,4)_，Java 必须用 _BigDecimal_，禁止用 _Double_。”
• 测试规范：“单元测试必须使用 JUnit 5，且必须覆盖空指针异常。”
• 机制：每次有新同学（或新 AI Session）加入开发时，第一件事就是读取这份文件。这相当于给 AI 装载了团队的“集体记忆”。

这是 SDD 模式下最有复利的进化逻辑。

• 传统模式：出现 Bug -> 修代码 -> 提交 -> 下次还敢。
• SDD 模式：出现 Bug -> 修 Skill -> 让 AI 重新生成代码。
• 如果你发现 AI 总是忘记处理分页，不要骂它。
• 请在 SKILL.md 里加一条：“规则 #42：所有列表查询接口必须默认包含分页参数。”
• 从此以后，这个问题绝迹了。
• 累计的错误记录，bug总结，修复方法也会成为团队的宝贵财富。

当代码不是人写的，“由于什么原因改了什么”变得比代码本身更重要。

• 强制维护 docs/decisions/AI_CHANGELOG.md（这点可以使用一些skill来简单高效的完成）。
• 这不是 Git Log，这是决策日志。
• 格式：“2026-01-01: 基于 _Spec-Auth-v2.md_ 重构了登录模块。风险点：废弃了旧版 Token 校验逻辑。”

文档最怕的是“写完即死”。为了防止 Spec Drift（规格漂移，即代码改了文档没改），必须建立严格的生命周期管理：

• 每份 Spec 必须有明确的 Human Owner（通常是提交 PR 的人）。AI 只是 Writer，人是 Owner。

• 需求变更：改代码前，必须先改 Requirement Spec。
• 代码重构：改逻辑前，必须先更新 Implementation Spec。
• 线上 Bug：执行 LAFR 流程修复后，必须回填 Test Spec（补录 Case）。

没有约束的 AI 也是一种灾难。作为架构师，你必须划定红线。

参考 C1/C2/C3 标准，建立严格的模型使用纪律：

• C3 (高敏感/核心代码)：如支付核心、用户隐私数据（在这个场景下，此方案变得尤其好用）。

• 红线：严禁把敏感信息喂给外部大模型。

• SOP：使用私有化部署模型（如内部的 Qwen）生成脱敏后的 Spec 文档，让外部大模型阅读修改脱敏后的文档，最后让内部大模型还原文档和实施代码。

• C1/C2 (通用逻辑/工具)：如前端 UI、工具类、单元测试。

• 策略：大胆使用最先进的外部模型（GPT-5.2/Claude 4.5），追求最高效率。

大模型最擅长“一本正经地胡说八道”。

• 不仅要看它写了什么，还要看它引用了什么。
• 如果 AI 调用了一个你没见过的库函数，90% 是幻觉。
• 对策：在 RIPER 流程 的 Step 5 (Review) 阶段，强制 AI 提供代码的出处或官方文档链接。
• 如果你看不懂 AI 写的代码，就不要用。
• SDD 的原则是：你必须有能力为 AI 的产出兜底。看不懂的代码就是埋在项目里的地雷。

• 基本法：谁 Sign-off 文档，谁 Sign-off 代码，谁就对 Bug 负责。
• 不要试图甩锅给“是 AI 写的”。AI 是你的笔，字写错了是人的问题。

Q1：新项目冷启动，怎么让大模型“快速上手”？

你本来就会让模型先做一次 research（读 README/架构/依赖/目录结构/关键约束），区别在于：不要让 research 只停留在对话里。

一个很实用的习惯：每次让模型做完 research，顺手补一句——

• “把你刚才的结论总结成规整文档，输出到 docs/（并给出建议的目录结构/后续要写的 01/02/03/04）。”

这样新项目的“上下文载体”就建立了：后续你 new chat、换模型、换人，都能从 docs/ 直接恢复状态，而不是靠人肉复述。

Q2：老项目冷启动（存量），没有文档怎么办？

存量项目迟早都要做文档；区别只是被动补救还是增量沉淀。

建议不要试图“一次性补齐全量文档”，而是从你下一次要做的变更开始增量补：

1. 选一个真实的 feature/bugfix，当场写一套最小 Spec（01/02/03/04）。

2. 让模型基于代码现状生成 03_implementation.md 骨架（改哪里、边界在哪、风险在哪）。

3. 每次合并 PR 时强制更新：docs/decisions/AI_CHANGELOG.md（为什么这么改），并回填测试用例（防复发）。

这样文档会自然“长出来”，而不是变成一个永远排不上期的“大重构”任务。

Q3：老项目已经有文档，怎么用才不浪费？

• 直接把现有文档作为上下文喂给模型，让模型补齐缺失的验收标准/边界/错误码，并重排成统一的 01/02/03/04 结构。

• 把最关键的“历史取舍/坑位”抽出来沉淀进 AI_CHANGELOG.md 与 SKILL.md，让后续迭代不需要靠“口口相传”。

Q4：这会不会变成“写文档负担”？

关键不在“写更多”，而在“写对地方”：

• 文档只写到能驱动实现与验收的程度（Spec 是指令集，不是长作文）。

• 让 AI 起草，你只做 Review/Sign-off；把文档写作成本压到“可接受的固定开销”。

• 用门禁保证文档不死：需求变更先改 01，重构先改 03，线上问题必须回填 04 + SKILL。

Q5：后续维护是不是都“基于文档”，不直接改代码？

理想状态是：人尽量不直接改代码，而是先改/补 Spec，再让 AI 按 Spec 改代码（然后由人做 Review/Sign-off）。

原因很简单：当你把编码执行交给模型之后，最大风险来自 new chat 的上下文缺失——同一个需求、同一段代码，换会话/换模型就可能出现理解偏差。Spec 作为“唯一事实来源”，能让后续的 feature/bugfix 复用同一套上下文与约束，避免每次都靠聊天重建。

现实落地时可以这么做（低摩擦）：

• 小改动：允许直接让 AI 出补丁，但必须同步更新对应的 Spec/Changelog（避免 Spec Drift）。

• 复杂改动/反复迭代的模块：强制“先文档后代码”，把新需求与旧实施/决策文档一起喂给模型，先对齐再执行。

Q6：现在是不是所有代码变更都走这套方法论？大概有多少真实代码实践？

不必教条化到“100% 的改动都写全套 Spec”。更现实的做法是：

• 主流程/复杂特性/高风险变更：强烈建议走完整链路（至少 01/02/03/04 + Changelog），收益最大。

• 小 bugfix/小需求：可以走 Lite（甚至直接让 AI 出补丁），但至少要留一份最小存档（例如更新 AI_CHANGELOG.md 或补一段简短的实施/测试记录），避免后续无法复盘。

至于“真实实践量”，更有意义的指标不是行数本身，而是：是否覆盖了“新功能上线 + 多轮优化 + 多次 bugfix + 需求增量”的完整生命周期；只要能在多次 new chat 下依然稳定复用上下文，说明方法论已经在真实场景里跑通。

Q7：别人还在写 Spec，我已经上线了，会不会被流程拖慢？

如果 Spec 变成“写完一套长作文才允许动手”，当然会拖慢；SDD 追求的是把最小必要的对齐与验收前置，让执行可以更快、更稳。

建议的节奏是：

• 先写最小 01/02（范围 + 契约），让并行与执行立刻启动。

• 03/04 可以在实现过程中增量补齐，但必须在合并/上线前达到门禁。

• 对于小改动，允许 Lite 甚至“先修再补留痕”，但要保证不会形成长期 Spec Drift。

Q8：有没有办法把“文档成本”再降一些？是不是要等 DeepWiki 之类的能力成熟？

文档能力当然会被工具持续增强（例如自动索引、统一检索、知识库/DeepWiki、MCP 接入等），但这不是 SDD 成败的前提。SDD 的重点是“上下文有载体 + 可验收 + 可追溯”，形态很灵活：

• 轻量玩法（马上能用）：让大模型在 research/实现后顺手把结论输出成文档，落到 repo 的 docs/ 里；你只做 Review/Sign-off。

• 重度玩法（组织化建设）：统一建设各项目的 Wiki/文档体系，配合索引与权限治理；再接入 MCP/统一查询，把“找信息”这件事变成基础设施能力。

换句话说：工具越强，成本越低；但即使没有 DeepWiki，你也可以从“顺手落 docs/”开始，把上下文沉淀起来，先跑通闭环。

Q9：有人觉得写 Spec 太重，不够 Vibe Coding？

这是一个误区。没有 Spec 的 Vibe Coding 不是“快”，而是“赌”。 Vibe Coding 提倡 "If fixing takes too long, regenerate"。但如果没有 Spec 文档作为基准，你每次 Regenerate 都是在碰运气（幻觉漂移）。SDD 实际上是 Vibe Coding 的“安全带”——它极轻（Lite 版），但能让你在高速飙车（Reroll）时，始终不偏离轨道。

Q10：既然有 OpenSpec 这种工具，我为什么要手写文档？

因为工具会过时，但“文本”永存。

• 反脆弱：使用专门的工具框架（OpenSpec/Spec-Kit）意味着你绑定了它的生态。如果有一天它不维护了，或者不支持最新的模型了，你的工作流就断了。
• 原生感：Manual SDD 是 LLM Native 的。它利用的是大模型最原始的阅读能力（Markdown），这意味着无论你是用 Cursor、Windsurf、还是未来的 GPT-6，这套方法论永远通用，不需要等工具适配。

Q11：文档维护会不会很麻烦？特别是开发期变动频繁时。

不会。采用“松耦合”策略，区分“个人工作台”与“团队知识库”。

正如你提到的，现代开发通常是“一人负责一个模块”：

• 开发期（热数据）：Spec 文档就在你的本地或 Feature 分支里。它是你的私人草稿本，随改随用，不需要实时同步给所有人，也不会影响主干。
• 归档期（冷数据）：等到月度或季度复盘时，再将这些经过代码验证的 Spec 精简后，上传到部门知识库（Wiki）。
  这样，既享受了 SDD 的开发便利，又自然而然地完成了团队的知识沉淀，还可以给知识库持续“造血”。

我们正站在软件工程历史的转折点上。

• 汇编时代，我们摆脱了二进制，开始用助记符编程。

• 高级语言时代，我们摆脱了寄存器，开始用对象和函数编程。

• 大模型时代，我们正在摆脱语法和细节，开始用“意图”和“文档”编程。

这篇教程里的 SOP（RIPER-5、文档驱动、Skill 沉淀），可能会让你觉得繁琐。你可能会想：“我自己写两行代码不就完了吗？”

但在 90% 的场景下，“快”是最大的陷阱。 你省下的那写文档的 10 分钟，未来会变成 10 个小时的 Debug 时间和无尽的维护噩梦。

SDD (文档驱动开发) 的本质，是逼迫你从“低头拉车”（Coding）变为“抬头看路”（Designing）。 它并没有剥夺你作为程序员的乐趣，相反，它剥夺的是那些枯燥的、重复的、易错的体力劳动，而把最宝贵的创造力、架构思维、业务洞察留给了你。

代码会过时，工具会迭代，模型会换代。但你对业务的理解、对架构的审美、以及驾驭 AI 的能力，将是你在这个时代最坚固的护城河。

不要等待未来，未来已来。 请打开你的 IDE，建立那个叫 docs/ 的文件夹，开始你的第一次 SDD 之旅吧。

注：以上图片均由Gemini3制作，内容由Gemini3、Qwen生成。