摘要:我没写一行实现代码,但用一套「规范即代码」的方法,让 AI 独立交付了一个完整的多租户 SaaS——38 张表、多角色数据隔离、多智能体编排、长期记忆、自动化评测、流式断点续传,基本都有。
一、为什么我放弃了「Vibe Coding」
先说我踩过的坑。最早我也跟大多数人一样,靠一段段 Prompt 让 AI 写代码——业内叫「Vibe Coding(氛围编程)」。结果就是三个老问题:
- 架构跑偏:聊着聊着,AI 就把权限、数据隔离这些核心逻辑写散了,东一榔头西一棒。
- 代码碎片化:功能能跑,但之间没有契约,改一处崩三处。
- 上下文遗忘:会话一长,AI 就忘了前面定过的约束,开始自由发挥。
后来我意识到一个反直觉的事实:AI 写代码的能力不是瓶颈,我「说清楚要什么」的能力才是。
于是我把开发方式换成了 SDD——Spec-Driven Development,规范驱动开发。
二、SDD 的核心:把「写清楚你要什么」变成一门工程
SDD 的心法就一句话:
传统开发是「需求 → 敲代码 → 测试」;SDD 是「需求 → 写
.md规范 → AI 照规范生成代码 → 验证」。
关键差异在于:规范(Spec)是 AI 的「宪法与图纸」,代码只是照着施工。
我按这套方法,把整个项目沉淀成一张四层金字塔:
| 层 | 文件 | 职责 | 谁维护 |
|---|---|---|---|
| 🔒 宪法层 | CLAUDE.md | 全局技术栈、不可触碰的铁律(多租户隔离、禁直连 SDK 等) | 我 |
| 🏗️ 架构层 | 01_architecture.md 等 | 拓扑结构、流转逻辑、数据模型、设计思想 | 我 |
| 📜 契约层 | 02_database_design.md、04_api_specification.md | 前后端字段、类型、外键、接口契约 | 我 |
| 🧩 任务层 | backend/b*.md、frontend/f*.md | 原子化任务,一次只让 AI 执行一个 | AI |
越上层越稳定,越下层越频繁。 我负责上面三层(定方向),AI 负责最下面一层(落代码)。
这个分层带来的一个重要好处是:换一个模型,把 .md 喂给它,它通常能接手项目。 文档本身成了可复用的核心资产——这也是「规范即代码」名字的由来。
三、一套工作流:从需求到交付
光有分层还不够,还得有一套固定的流程,让流程有据可依:
flowchart LR
A[需求澄清] --> B[写/改 Spec]
B --> C[评估 Spec]
C --> D[实现]
D --> E[验证]
E --> F[回写文档]
F --> G[代码评审]
G --> H[提交推送]
其中我最看重的两环是「评估 Spec」和「回写文档」:
- 评估 Spec:在让 AI 动手前,先问自己六个问题——影响范围多大?有什么风险?有没有新依赖?怎么验证?成本多少?会不会越权/泄隐私?想清楚了再放 AI 去写。
- 回写文档:AI 改完代码,必须把「实现状态、关键决策、踩的坑」回写进 Spec。否则文档和代码脱节,下一个接手的人(包括下一次的 AI)会被误导。
我在这上面栽过跟头:改了一个字段的语义,没同步文档,结果下一个任务里 AI 照着旧文档写,越改越乱。从那以后,「改完必回写」成了硬规矩。
四、三个决定成败的机制
SDD 能不能落地,靠的是三个「硬门禁」,少了任何一个,AI 就容易偷懒。
1. DoD:把「完成」定义成可验证的验收标准
DoD(Definition of Done)是 Spec 的灵魂。 不写 DoD,AI 生成的代码往往漏掉异常处理。
反例(太模糊):
- [ ] 实现用户登录功能
正例(可验证、覆盖边界):
- [ ] 用 user_001 登录,能拿到 token 并访问 /me。
- [ ] 密码错误返回 401,且不泄露「用户不存在」还是「密码错误」。
- [ ] status=disabled 的用户登录被拒。
- [ ] 并发注册同名用户,唯一约束兜底返回冲突,不抛 500。
看出差别了吗?后者把「正常 / 异常 / 越界」三条路径都写死了,AI 没法糊弄。
2. 涉及文件白名单:防止 AI 乱改
AI 有个毛病——顺手重构。你让它改一个字段,它可能顺手把整个文件格式化一遍,甚至「优化」无关代码。
我的对策是:每个 Spec 都写死「涉及文件(只改这些)」和「禁止改动(不碰这些)」。
## 二、涉及文件与禁止改动(范围白名单)
| 类型 | 文件 | 说明 |
| **涉及文件(只改这些)** | `backend/app/ai/chat/chat.py` | 组装 state 时对 summary/history 补 mask_pii |
| **禁止改动(不碰这些)** | `backend/app/permission/tenancy.py` 等命门 | 权限隔离逻辑,动一点就是数据泄露 |
这样评审时,直接 git diff 核对,超出的改动一律回退。这招治好了 AI 的「顺手重构病」。
3. 真实验证:防止「编译通过 = 跑通」
这是最容易翻车的一环。AI 特别爱用「编译通过」或「内存库跑通」来糊弄你。我的铁律是:
前后端联动的功能,必须真开浏览器(Playwright)跑通核心交互,没验证就不提交。
五、那些让我返工的坑(真实复盘)
这套方法不是一开始就顺的,我踩了不少坑,挑四个最有代表性的:
-
过于宏大的 Spec:一开始我想把所有需求塞进一个大
.md,结果 AI 上下文超载、执行混乱。必须按模块拆文件,一次一个任务。 -
Spec 不含 DoD:AI 生成了登录功能,但没处理「密码错误要统一提示」这种异常,上线才发现。每个任务都应当带局部 DoD。
-
文档与代码脱节:改完代码不回写文档,结果「文档还停留在旧版、代码已迭代」,误导了下一个接手的 AI。改完必回写。
-
AI 炫技/过度设计:AI 一度建议上「桑基图」做数据洞察,看起来高大上,但是「看不懂」。复杂度若不能让用户一眼看懂,就是负债不是资产。 最后换成了环形图 + 大数字。
这些坑,几乎每一个都对应一条「铁律」。SDD 的意义,就是把「人踩过的坑」沉淀成「AI 必须遵守的约束」。
六、成果:一个完整的多租户 SaaS
用这套方法,我最终让 AI 交付了一个能真实跑起来的 AI 自我成长与关系产品,而不是又一个玩具 Demo。核心能力一览:
-
多智能体编排:安全员 → 倾听者 → 分析者 → 建议者 → 质检员,用 LangGraph 固定边串起来,聊天过程可展开查看中间步骤。
-
多租户数据隔离:C 端个人 / B 端员工 / 超管 / 运营 / 咨询师,7 角色分域,权限隔离收敛到一个唯一事实源,杜绝越权。
-
跨会话长期记忆:AI 能「记得住你」——结束的会话被异步萃取出事实,新会话自动带回。
-
自动化评测:LLM-as-Judge 打分 + 分层归因,能定位「检索层/模型层/规则层」哪一步出了问题。
-
数据看板 + 成本看板:调用量、趋势、Token 消耗、模型降级次数,全链路可观测。
-
智能洞察 + 敏感词合规:咨询分析、用户分群、红线命中统计,B 端管理员一眼看懂。
- 机构入驻审核 + 租户管理:营业执照上传、信用代码审核、通过后自动建租户。
这些功能不是「堆出来的」,而是靠 160+ 篇 Spec 文档、一层层约束出来的。几乎每一行代码,都能回溯到一份 Spec,而 Spec 又能回溯到一条铁律。
七、总结:人定方向,AI 落代码
回顾整个过程,SDD 核心改变的不是「AI 写了多少代码」,而是我和 AI 的分工:
- 我负责:创意、思考、判断——定产品方向、写 Spec、定铁律、踩坑复盘。
- AI 负责:把想法源源不断地落成代码——给速度、给规模。
那句让我印象最深的话是:「写清楚你要什么」比「动手做」更重要。
如果你也在用 AI 写代码、也受够了「改一处崩三处」的失控感,不妨试试 SDD。不用一步到位,先从 「给每个需求写一份带 DoD 的 Spec」 开始,你会发现 AI 的可控性会立刻上一个台阶。
本文基于「清风明月」项目的工程实践整理,供参考。