基于 SDD 规范与 AI 知识库重塑 Vibe Coding 开发范式

引言：从“氛围编程”的狂欢到工程化治理的觉醒

在过去的一年中，以 Cursor、Claude Code 为代表的 AI 编码助手彻底引爆了开发者的生产力。 Vibe Coding（直觉驱动/氛围编程） 的新模式风靡技术圈：开发者无需严谨的架构设计，只需在输入框中用自然语言描述需求，AI 便能行云流水地生成代码。这种模式下，许多团队的出码率飙升至 80% 甚至 90% 以上。

然而，狂欢过后，研发团队却面临着一个令人困惑的深层困境：AI 写的代码越来越多，但项目的整体交付周期却没有明显缩短，开发者的工作量甚至因为无尽的 Code Review 和 Debug 而增加了。

很多在前沿大厂的实践复盘以及资深 AI 开发者的真实记录中所看到的，人工并发管理 AI 存在难以逾越的硬伤。当人类开发者试图同时管理 4-6 个 AI 终端窗口时（一个跑测试、一个重构组件、一个写文档），大脑的 Context Switch（上下文切换）会瞬间崩溃。AI 虽然有着强大的生成能力，但其天马行空的“自由发挥”往往与团队现有的架构规范格格不入。指令不清晰导致的反复修改，更是让 AI 从“提效神器”变成了“聊天黑洞”。

真正的命题不是“怎么让 AI 更聪明”，而是如何把依赖人类高频参与的“作坊式” AI 编码，改造成可持续、可观测、受约束的工业级系统。

为此，我们需要引入 SDD（Specification-Driven Development，规范驱动开发） 思想，并将其与基于 Obsidian + Submodule 的 AI 研发知识库 深度融合。本文将详细探讨如何利用这套新范式，终结 Vibe Coding 的混乱，实现真正的“24 小时无人值守”企业级 AI 研发。

一、 核心方案：SDD 规范与 Vibe Coding 的融合策略

1.1 Vibe Coding 的陷阱与 SDD 的“先难后易”哲学

大路平坦宽阔，但人偏偏喜欢走捷径。Vibe Coding 就是那条看起来省事的小捷径：直接跨过设计阶段，让 AI 开始堆砌代码。这种模式是“先易后难”，前期爽快，后期在处理庞杂的上下文漂移和架构腐化时极其痛苦。

SDD 的哲学恰好相反，它是“先难后易”。 写规范（Spec）很慢，做设计很枯燥，但一旦规范被清晰地结构化，后续的 AI 执行、测试验证、迭代重构就全都有据可循。SDD 的核心思想在于颠覆了传统的研发真理结构：在 AI 时代，代码不再是唯一的“真理之源”，结构化的规范（Specification）才是。

1.2 引入 Harness（驾驭工程）作为 AI 的护栏

如果说 SDD 解决的是“让 AI 做什么”的问题，那么 Harness 工程 解决的就是“让 AI 如何可控地做”的问题。 在融合方案中，我们利用 AI 知识库中的 lib/（公共依赖规范层）作为 Harness 护栏。AI 在生成代码前，必须强制读取架构约束（如：数据库表设计规范、接口鉴权标准、异常处理准则），确保 AI 生成的代码不是天马行空的“炫技”，而是严格对齐团队工程基线的工业级产物。

1.3 四阶自动化工作流的重构

将 SDD 与 AI 结合，我们把研发链路抽象为不可逾越的四个自动化阶段：

1. Specify（定义规范）：AI 将人类模糊的 PRD 转化为无歧义的、结构化的意图代码。

2. Plan（制定计划）：AI 像编译器一样，将规范“编译”为详细的技术方案和精确到文件的任务清单。

3. Implement（执行落地）：AI Agent（如 Claude Code）严格按照清单逐一修改代码。

4. Validate（验证闭环）：AI 基于 Spec 自动生成并执行测试用例，形成业务闭环。

二、 实施细节：重塑 SDD 文件目录体系与标准

为了让 AI Agent 能够完美融入上述工作流，我们需要在现有的 Obsidian 知识库文件架构（raw/, wiki/, lib/, assets/）基础上，重构并嵌入专门的 sdd/ 工作流目录体系。新的目录体系既是人类审阅的面板，也是 AI 程序的“内存状态机”。

2.1 全新目录树结构设计

/docs/
├── raw/                 # 📦 原始资料输入区 (Read Only)
│   └── 01-prd/          # 业务提出的原始 PRD、会议纪要等非结构化文本
├── sdd/                 # 🚀 规范驱动开发区 (AI Agent 核心调度与状态区)
│   ├── templates/       # SDD 标准模板库
│   │   ├── 01-spec.tpl.md
│   │   ├── 02-plan.tpl.md
│   │   ├── 03-tasks.tpl.md
│   │   └── 04-validate.tpl.md
│   └── iterations/      # 迭代版本工作区 (按 Sprint 或发版周期进行物理隔离)
│       └── [v1.2.0-Sprint4]/    # 具体的迭代版本号
│           ├── [feature_user_login]/
│           │   ├── 01-spec.md     # [Specify] 规范定义（唯一真理源）
│           │   ├── 02-plan.md     # [Plan] 技术方案与文件变更清单
│           │   ├── 03-tasks.md    # [Implement] AI 任务执行打勾清单
│           │   └── 04-validate.md # [Validate] 验收标准与自动化测试断言
│           └── [bugfix_pagination]/
│               └── ...
├── wiki/                # 🧠 沉淀知识库 (Obsidian 呈现区 / Write & Read)
│   ├── index.md
│   └── sources/         # SDD 上线后，自动提炼更新至此，形成长效系统图谱
├── lib/                 # 📚 Harness 架构约束层 (Submodule / Read Only)
│   ├── arch-kb/         # 全局架构规范（强制约束 AI 生成 plan.md）
│   └── prompt-kb/       # 团队沉淀的系统 Prompt 与 AI 角色设定
└── assets/              # 🖼️ 静态资源区 (如自动生成的白板架构图)

2.2 文件夹用途、文件类型说明与需求生命周期闭环

• raw/ 与 sdd/01-spec.md 的职责解耦（拒绝重复）： 表面上看，raw/01-prd/ 存放需求，sdd/01-spec.md 也记录规范，似乎是重复的。但在新范式中，它们代表了截然不同的两种“物种”：

  • raw/ 是面向人类的“输入倾倒区”：它极度宽容、格式混乱，主要用于记录业务背景（Why）和讨论的轨迹（如聊天记录截图、会议纪要）。它是追加写入（Append-only）的，保留了需求演变的历史现场。

  • sdd/01-spec.md 是面向机器的“精密图纸”：它极度严苛、结构化且无歧义。它是代码的“前置编译器”，永远只反映当前时刻最终拍板的“验收基线”（What）。

• 需求生命周期闭环：

  • 孕育期：人类在 raw/ 中天马行空地写文档、贴语料。

  • 定板期：AI 抓取 raw，提炼并生成冷酷无情的 sdd/01-spec.md（唯一真理源）。

  • 变更/讨论期：开发中途发现逻辑不通，人类在群里讨论，将结论丢回 raw/。此时，唤醒 AI 覆写（更新） sdd/01-spec.md。修改 Spec 即等同于修改代码。

  • 验证期：测试脚本只认 sdd/01-spec.md，绝不会去管 raw/ 里当初怎么讨论的。

• /docs/sdd/iterations/ (按迭代版本管理的动态工作台)：这是非常契合敏捷开发（Agile）的设计。我们不再使用扁平的目录，而是以发版周期或 Sprint（如 v1.2.0-Sprint4）为第一级目录，下方再挂载具体的 Feature 或 Bugfix。

  • 好处 1（版本追溯）：发版时，发布说明（Release Notes）可以直接让 AI 扫描该迭代文件夹下的所有 01-spec.md 自动生成。

  • 好处 2（安全归档）：当该版本发版完毕，整个 v1.2.0-Sprint4 文件夹可以被打包移动到归档区（Archive），同时触发 AI 将其中的领域知识提炼到 wiki/ 目录中，保持工作区的清爽。

• 01-spec.md：记录用户故事、交互流程和业务约束。这是唯一真理源，如果需求变更，人类只允许修改此文件，后续文件由 AI 级联重构。

• 02-plan.md：包含架构选型、数据库变更（SQL）、API 接口定义以及需要修改的具体文件路径。

• 03-tasks.md：以 Markdown 任务列表 (- [ ]) 形式存在的状态机。AI 每完成一个文件的修改，就打上勾 (- [x])，这使得中断的任务可以随时恢复。

• 04-validate.md：测试用例描述，以及对应的自动化测试执行脚本或结果反馈。

2.3 命名规范与 AI 标识（给机器看的“身份证”）

在日常工作中，我们人类看文件名就能大概猜出文档内容（比如看到 登录需求v2.md 就知道是需求）。但是，如果我们要打造一个无人值守的自动化系统，让后台脚本或者 AI 去批量处理这些文件，光靠猜是不行的。

因此，我们引入了 YAML Frontmatter（这是 Obsidian 等笔记软件支持的一种标准元数据格式，通常放在文件最顶部的 --- 之间）。你可以把它理解为贴在每个文件脑门上的“电子身份证”或“状态标签”。

---
type: sdd_document
stage: plan
feature_id: "F-202605-001"
feature_name: "用户登录重构"
status: "in_progress" # 这里的状态就像是流水线上的红绿灯
ai_generated: true
last_updated: "2026-05-07 10:00:00"
related_lib: ["[[arch-kb/auth-standard]]"] 
---

这个“身份证”有什么用？

• 状态流转的“红绿灯”：比如调度系统每分钟扫描一次文件夹，当它看到某个 01-spec.md 的 status 是 in_progress 时，它就不管；当它发现状态被人类改成了 approved（已审批），系统就会立马自动唤醒 AI 说：“需求已经定稿，开始写代码吧！”

• 知识库的智能检索：在 Obsidian 中，你可以利用这些属性，一秒钟筛选出“所有由 AI 生成的、目前状态处于卡壳的”需求文档。

2.4 文档模板标准（把提示词“缝”进模板里）

以前我们用 AI，总是要在聊天框里手敲很长的提示词（Prompt），比如：“你现在是一个架构师，请帮我分析以下需求，不要写代码，只写验收标准……”。每次都要写，不仅累，而且很容易漏掉关键约束。

在我们的新范式中，我们把这些复杂的提示词直接内嵌到模板文件（Templates）中。

以 01-spec.tpl.md（规范定义模板）为例，它不只是一个包含“需求背景”、“验收标准”等标题的空壳文档，它里面还用 HTML 注释的格式（人类看不到，但 AI 能看到）写着这样的指令：

<!-- AI Instruction: 请从 raw/01-prd/ 中提取内容，并严格按照以下结构输出。注意：如果发现产品需求与现有架构冲突，请在这里用加粗字体标出，并禁止在此阶段生成任何代码。 -->

这样做的巨大好处： 这种设计叫做**“Prompt as Template（模板即提示词）”**。当调度系统新建一个需求时，它直接把这个模板丢给 AI。AI 一读模板，瞬间就知道自己该扮演什么角色、该遵守什么规矩、该输出什么格式。我们再也不需要和 AI 在聊天框里反复拉扯了，极大地降低了沟通成本，实现了真正的自动化。

三、 技术架构设计与 AI 知识库应用场景

3.1 技术架构图：基于文件与轮询的轻量级调度层

我们要造的不是一个取代大模型的黑盒 Agent，而是一个管理 Agent 的“调度层”。正如优秀开发者所总结的：“代码优先于 Prompt。能用 10 行 Bash 解决的，别折腾 AI 的 LangChain。”

我们的技术架构回归到了最本质的 Unix 哲学：文件 + 轮询 (File + Polling)。

• 存储层：就是上述的 Obsidian 本地 Markdown 文件夹。

• 调度层：一个轻量级的 Bash 或 Python 守护进程（Daemon），监控 sdd/active_features/ 下文件的 status 变更。

• 执行层：当监控到 01-spec.md 的状态变为 approved_by_human 时，调度层自动触发 Claude Code CLI，传入 Prompt：“读取 01-spec.md 并结合 lib/arch-kb，生成 02-plan.md”。

3.2 AI 知识库在文档生成中的具体应用场景

在这个架构中，Obsidian 知识库不再是静态的记录本，而是参与 Vibe Coding 闭环的核心组件：

1. 智能对齐（Harness 注入）：AI 在编写 02-plan.md 时，会被知识库中的 lib/ 强制拦截。例如，如果知识库规定“所有对外接口必须使用统一的 Result<T> 包装”，AI 就会在方案中自动规避直接返回原生对象的错误实现。

2. 长效图谱反哺：当一个特性在 sdd/ 目录下完成开发并合并到主分支后，AI Agent 会触发最后的“归档”动作。它会将 01-spec.md 和 02-plan.md 中的核心业务逻辑提炼，并通过 obsidian-skills 自动写入到 /docs/wiki/sources/ 中，同时更新 [[双向链接]]。这样，Vibe Coding 产生的代码不仅运行在服务器上，其业务意图也永久沉淀在了 Obsidian 的关系图谱中。

四、 案例分析：一个复杂特性的 24h 无人值守开发

让我们来看一个真实的场景：业务提出了一个“搜索结果列表分页异常重构”的需求。在传统 Vibe Coding 中，开发者会在 Cursor 里一顿狂敲，结果往往是修复了前端分页，却搞崩了后端的总数计算。

在融合 SDD 规范的新范式下，流程如下：

第一步：触发与解析 (Specify) 开发者将运营群里的一段反馈聊天记录直接丢进 /docs/raw/01-prd/bug-pagination.md。 调度层感知到新文件，唤起 AI Agent。AI 自动分析该文本，并在 sdd/active_features/fix_pagination/ 下生成了 01-spec.md。它将“分页有问题”精准翻译成了验收标准：“切换页码后列表数据必须刷新，入参需包含 page 和 size”。

第二步：方案编译 (Plan) 调度层读取到 Spec 生成完毕，继续唤起 AI：“请查阅 docs/lib/arch-kb/ 中的数据库分页规范，为该需求生成技术方案”。 AI 在 02-plan.md 中指出了需要修改的具体文件：前端的 PaginationComponent.tsx 和后端的 SearchService.java，并列出了详细的 SQL 优化策略。此时，系统暂停，向人类发送飞书通知请求 Review。

第三步：无人值守执行 (Implement) 人类看了一眼 02-plan.md，敲入 approve。 调度层将任务转化为 03-tasks.md 的清单，并将控制权完全交给 Claude Code CLI。Claude Code 自动穿梭在前后端代码库中，每改完一个文件，就在 03-tasks.md 中打勾 - [x]。即便中间遇到了大模型 API 速率限制而中断，系统重启后也能通过读取打勾状态，从断点继续执行。

第四步：验证与沉淀 (Validate & Wiki) 代码修改完毕后，AI 自动编写了相关的单元测试并执行（04-validate.md 状态变为 Pass）。 最后，AI 将本次重构的分页逻辑提炼成系统架构笔记，自动合并到 /docs/wiki/sources/search-domain.md 中，供未来查阅。

整个过程中，人类只做了一次 Review 决策，其余时间系统都在可控的轨道上自行运转。

五、 可量化的效果评估标准

引入这套新范式，我们需要用明确的指标来评估其对研发效能的真实提升，不能再被单纯的“出码率”所迷惑。核心评估标准包括：

1. 需求交付周期 (Lead Time for Changes)

   1. 传统 Vibe Coding：出码快，但联调与 Bug 修复时间极长。

   2. SDD 新范式：由于“先难后易”和 Harness 约束，重做率大幅下降。我们预期整体需求从接手到上线的周期能缩短 30% - 40%。

2. Code Review 耗时与打回率

   1. 由于代码完全按照 02-plan.md 生成，且在前期已经对齐了 lib/ 架构规范，架构偏离度趋近于 0。可量化的指标是：代码审查阶段的架构级 Review 意见减少 80% 以上。

3. 自动化测试覆盖与通过率

   1. Validate 阶段强制要求 AI 生成测试代码，且直接对应 Spec 中的验收标准。一次性 CI Pipeline 构建通过率应提升至 90% 以上。

4. 知识图谱沉淀率 (Knowledge Retention Rate)

   1. 量化知识库中 wiki/ 目录的自动更新频率。传统开发中，文档更新滞后率接近 100%。而在 SDD 闭环中，每次 Feature 合并都会带来 Wiki 节点和双链的增加，实现 100% 的代码与文档同步率。

六、 总结展望

Vibe Coding 释放了 AI 的创造力，但也打开了工程混乱的潘多拉魔盒。我们必须认识到：AI 的价值不是替人做事，而是把依赖人的高频工作，改造成可以持续执行、可观测、可复盘、可优化的系统。

基于 SDD 规范与 AI 知识库（Obsidian）的新一代开发范式，正是这样一个系统。它通过“三层隔离”（Raw 输入、SDD 工作区、Wiki 沉淀区）和“四步走”状态机，完美地给脱缰的 AI 套上了 Harness 缰绳。

未来，开发者的核心能力将不再是“手写代码”或“花式写 Prompt”，而是架构系统、定义规范 (Spec) 以及维护知识库体系。当团队的 Obsidian 知识图谱越来越繁茂时，AI Agent 就会越来越懂你的业务，真正的企业级“24 小时无人值守研发”也就水到渠成了。