自从定义好了设计文档，AI听话多了
  昨晚十一点，客户又改需求了，我心里确不着急，毕竟代码是 AI 写的，改起来很容易。结果一联调，三个接口三种口径，返回值半真半假。那一刻我突然明白：不是 AI 不行，是我没把规则说清楚。第二天把设计文档补齐，再丢给 AI，同样的需求，丝滑落地。
  先上图，都是我现在常用的那套骨架。

  说真的，这些文档不是为了“走流程”，而是为了降低沟通成本，让 AI 不再靠猜。你把边界、约束、验收写清楚，它就能按图施工；你让它“自由发挥”，它就会一本正经地瞎忙活。

这套文档都是干啥的

00_PROJECT_CONTEXT

  项目的基础文档，包含项目背景与愿景、核心业务流程，目标用户和使用场景、业务术语表、核心指标与成功标准、外部依赖与第三方服务。这个文档是项目的核心业务文档，能够让AI知道你这个项目是干什么的。

01_TECH_SPEC

  技术规范文档，包含技术栈、设计原则、项目目录结构、编码风格、错误处理、日志规范等等，这个主要是为了让 AI 知道项目的技术实现细节。

02_DATA_MODEL

  数据模型，主要定义实体和实体关系，数据库表结构的定义。

03_API_CONTRACT

  API 合约与字段字典，主要定义接口路径、方法、入参出参、状态码、错误语义等。相当于接口文档

04_UI_THEME

  UI相关的定义，包括核心配色方案、字体方案、设计规范等等，指导AI进行UI设计。

05_COMPONENT_REUSE

  组件复用设计文档，主要定义组件的复用规则、组件的接口定义、已经实现的组件列表。
  数据与状态说明
别让状态在脑子里飞。哪些是持久态，哪些是计算态；缓存多久过期；一致性怎么保证；允许多久的延迟。AI 最容易在这里踩坑：它会把“方便”写成“事实”。你把事实和规则先写在文档里，它就不至于发善思维。
  边界与约束清单
所有“不允许”的事情，都该出现在这里。比如“不得引入新依赖”“不改变现有接口”“时间复杂度不高于 O(n)”“只能读从库”“必须兼容安卓 8+”。这部分是护栏。没有护栏，AI 就会很热情地把路修到河里去。
  验收与样例（Given-When-Then）
验收是这套文档的灵魂。你怎么判断“做对了”，就怎么写。最简单的就是三五条样例，甚至是一段伪单测。比如：

  或者接口示例：给定入参，期待响应结构。AI 有了样例，基本不会偏轨。
  风险与开关
这活不是“上线就一锤子”。该有开关就有开关，能灰度就灰度，回滚怎么做也写清楚。AI 写代码快，写完就走；工程化的兜底，要靠我们先想周到。
  日志与监控
出了问题去哪看。关键埋点、日志字段、异常等级、报警阈值，放在一页纸上。AI 照着埋，运维不用猜。哪怕是本地脚本，也写清楚最少的输出口径和关键字。
  代码风格与目录约定
别让 AI 发明规范。统一格式化、lint、命名风格、文件组织，都截一段放进文档。它的建议才能“有据可依”，而不是“我觉得这样更优雅”。有了基线，生成的代码和团队风格不至于分道扬镳。

和传统 vibe coding 有什么不一样

  传统的 vibe coding，爽在“现在就开写”。问题也在这里：信息是碎的，要求是现想的，边写边补课，改来改去。你觉得快，其实是在拼幸运。
  设计文档先行这套，更像是把话说在前面。任务说准，上下文给足，约束立住，验收落地。AI 拿到的是一张清晰的施工图：该走直线就走直线，不用靠感觉试探。它的优点被放大，缺点被关在护栏里。最明显的变化有三个——编码更稳定、返工更少、人机协作更省心。哪怕换个模型，换个AI，也能接着干，因为“规则”在这儿，所有人都能对齐。

怎么落地

  大家别被这些文档吓到，这么多文档，定义这么细，要写到猴年马月啊。我建议不要自己写，先让AI写初稿，自己再做调整，这样就省事多了。多和AI磨合几轮，一上午的时间就能写出来比较完善的文档了。有了文档，后面开发不返工节省出来的时间远远超过一上午。
项目越做越多，你会发现这些设计文档会相同的结构，就可以沉淀下来。设计文档会越写越快。

来一块感受一下

  没文档时候，这样写提示词：
“帮我实现数据库查询，并把结果分页显示到首页。”
结果AI按照自己的想法实现了，数据不准，UI不好看，自己还得慢慢调。
  有文档后，是这样：
“参考设计文档中的数据结构，UI和组件定义，查询数据库，结果显示到首页。”
AI 给出的实现，很少偏题；我们也能一眼判断好坏。不是因为模型变聪明了，而是我们把题目出清楚了。
  我现在做新需求，第一反应已经不是直接写代码，而是把设计文档先填满。这不是慢，而是真正的快。等你把设计文档变成肌肉记忆，AI的效率会像踩了油门，合作也会稳到出奇。