前段时间，我差点就把AI编程工具给卸载了。
问题不在于它写代码太慢，恰恰相反——是生成得太快了。一个登录功能，Claude Code十秒钟就能输出近两千行代码，乍一看结构完整。但一进入测试，各种隐患就暴露无遗：验证码校验逻辑缺失、Token刷新机制是凭空捏造的、错误处理直接用console.log敷衍了事。统计数据显示，其代码的Bug率比人工编写高出60%，功能遗漏成为最突出的问题。
更棘手的是，面对这海量生成的代码，根本无从审阅，你甚至无法确定AI究竟在里面实现了什么。
后来，我们团队做了一次关键调整。没有去钻研更复杂的提示词工程，也没有更换更强大的模型，仅仅是在项目根目录里添加了三份Markdown文档。
一段时间后，效果立竿见影：AI生成代码的返工率从47%骤降至11%。整个团队与AI协作的模式被统一了，甚至新人入职第一天，就能在AI的辅助下交付质量达标的代码。
今天，我将完整分享这三份文档的核心思路与具体使用方法。
一、先看一个真实对比：同一需求，两种结果
需求很简单：实现一个手机号加验证码登录功能。
没有规范文档的AI输出（真实案例）
// 这代码AI自己写的，看着还行？
async function login(phone, code) {
// 某AI虚构的API，项目里根本没有
const res = await request.post('/api/login', { phone, code });
if (res.code === 200) {
// 项目里也没有这个storage
storage.set('token', res.data.token);
// 跳转？需求没说，AI自己加了
router.push('/home');
} else {
// 错误处理？需求没说验证码错误怎么办
alert('登录失败');
}
}问题清单：
- ❌
request.post— 项目里根本没有这个封装 - ❌
storage.set— 项目用的是localStorage，不是这个 - ❌ 自动跳转 — 需求没写，AI自作主张
- ❌ 错误处理 — 只弹了个框，没有具体错误信息
- ❌ 手机号格式验证 — 完全没做
有规范文档的AI输出（模板约束后）
// 来源：src/api/request.js 第24行的 post 方法
import { post } from '@/api/request';
// 来源：src/utils/storage.js 第8行的 setStorage
import { setStorage } from '@/utils/storage';
// 来源：src/utils/validator.js 第15行的 isPhone
import { isPhone } from '@/utils/validator';
export async function loginWithCode(phone, code) {
// 需求AC-02：手机号格式校验
if (!isPhone(phone)) {
throw { code: 'INVALID_PHONE', message: '手机号格式错误' };
}
const res = await post('/auth/login', { phone, code });
if (res.code !== 0) {
throw { code: res.code, message: res.message };
}
setStorage('token', res.data.token);
return { success: true };
}
// 验收表见下方（AI自动输出）区别在哪里？并非AI突然变聪明了，而是我们用Markdown文档为它划定了三条不可逾越的底线。
二、核心武器：三份让AI“循规蹈矩”的Markdown文档
这三份文档被放置在项目根目录的.ai/文件夹下。任何AI编程工具（无论是Claude Code、Cursor还是GitHub Copilot）在开始编写代码前，都必须先读取它们。
文档1：rules.md — 工作流铁律
这份文档的核心是告知AI：不遵循既定流程，就不能编写代码。
# AI工作流规则 — 强制执行
## 每次对话开始，必须：
1. 读取 state.md 了解当前进度
2. 读取 plan.md 了解整体计划
3. 输出以下三个区块才能写代码：
- 状态回顾（上一步做了什么、做到什么程度）
- 下一步动作（具体任务+预期效果）
- 确认请求（等待用户说“继续”）
## 写完代码后，必须：
1. 输出验收自检表（逐条对照需求打勾）
2. 更新 state.md 中的进度
3. 声明每个调用的API来自哪个文件（防止虚构）
## 禁止事项：
- ❌ 禁止在未确认的情况下直接修改代码
- ❌ 禁止调用未声明来源的函数
- ❌ 禁止实现需求中没有的功能这条铁律，直接将AI从“天马行空的自由创作者”转变为“按图施工的严谨工程师”。
文档2：plan.md — 分阶段作战地图
缺乏计划，AI就容易“思维发散”。这份文档将整个项目拆解为一个个小任务，每个任务都附带明确的验收标准。
# 整体计划 — 记账小程序 v1.0
## Phase 1: 基础设施
- [ ] T1.1 初始化目录结构
- [ ] T1.2 封装API请求（src/api/request.js）
- [ ] T1.3 封装本地存储（src/utils/storage.js）
**验收**：npm run dev 无报错，request.js包含get/post方法
## Phase 2: 用户认证
- [ ] T2.1 手机号+验证码登录页面
- [ ] T2.2 登录API对接
- [ ] T2.3 token存储与自动携带
**验收**：有效手机号+验证码能登录，无效验证码显示错误提示
## Phase 3: 账本管理...这里有一个关键设计：每个任务的代码量上限被设定在600行左右。这是AI能保持高质量输出的粒度红线，任务一旦过大，AI就容易开始“敷衍了事”。
文档3：state.md — 实时进度跟踪
这份文档是AI与开发者之间的“共享记忆区”。AI每完成一步，就必须更新此文档。下次对话时，AI会先读取它，从而明确“我上次完成了T1.2，现在该进行T1.3”。
# 当前执行状态
最后更新：2026-05-26 14:30
## 整体进度
- 当前阶段：Phase 2
- 完成度：40%
- 已完成：T1.1, T1.2, T1.3, T2.1
- 进行中：T2.2（登录API对接）
## 上一步做了什么
T2.1 登录页面UI完成，包含手机号+验证码输入框、获取验证码按钮
## 下一步动作
- 任务ID：T2.2
- 描述：实现登录API调用，对接后端 /auth/login
- 预期效果：输入有效验证码能拿到token
- 涉及文件：src/api/login.js, src/views/Login.vue
## 阻塞问题
无这套机制的强大之处在于，AI从此“永不遗忘”。即使开发者间隔一周再回来，只需对AI说一句“继续”，AI读完state.md后，立刻就能无缝衔接之前的工作。
三、实测数据：使用规范文档前后对比
我们以一个前后端分离、约8000行代码规模的项目进行了对照测试，结果如下：
| 指标 | 无规范文档 | 有规范文档 | 变化 |
|---|---|---|---|
| AI代码返工率 | 47% | 11% | ↓76% |
| 功能遗漏率 | 34% | 5% | ↓85% |
| 虚构API次数 | 每会话2.3次 | 0.1次 | ↓96% |
| 代码评审时间 | 3.5小时/次 | 1.2小时/次 | ↓66% |
| 新人上手时间 | 3天 | 0.5天 | ↓83% |
以上数据来源于团队8个项目、累计320次AI对话的统计。
最令人惊喜的是新人上手效率的显著提升。以往新同事需要花费数天来熟悉项目规范、代码风格和工作流程。现在，只需将这三个文档交给他，并指示AI“请遵守.ai/目录下的规范”，AI就能直接引导他以正确的节奏开始工作。
四、为什么这三份文档比“优化提示词”有效100倍？
我见过太多团队陷入“提示词竞赛”——反复调试、精炼提示词，期望AI能更听话。但提示词有一个天生的缺陷：它只存在于单次对话的上下文中，一旦开启新会话，一切归零。
而这套Markdown规范文档，是实实在在的项目资产：
- 可以提交到Git进行版本管理；
- 团队共享，一人完善，全员受益；
- AI每次启动时自动读取，无需开发者重复输入。
本质区别在于：提示词是开发者对AI说的“悄悄话”，而规范文档是项目给AI立的“规章制度”。
这里还包含一个心理学机制：将规则白纸黑字地写下来，比口头叮嘱有效十倍。AI的行为逻辑也类似。当它看到文档里明确写着“禁止虚构API”，它就会老老实实地去代码库中寻找真实的函数来源。
五、手把手教程：30分钟为你的项目配置这套规范
第1步：创建.ai文件夹
mkdir .ai第2步：复制三份模板
将上述三份Markdown内容分别保存为：
.ai/rules.md.ai/plan.md（根据你的项目填写阶段）.ai/state.md（初始状态）
第3步：填写plan.md的关键部分
无需一次性写完整，先完成第一个Phase即可。格式参考：
## Phase 1: [阶段名]
- [ ] 任务1: 具体做什么
- [ ] 任务2: ...
**验收**：[可验证的条件]第4步：启动AI，输入第一句话
在任何AI编程工具（Claude Code、Cursor、Copilot）中，输入以下指令：
请阅读项目根目录下.ai/文件夹中的所有规范文档，并按照规则开始工作。
接下来你会发现，AI不再急于抢答。它会先输出状态回顾、下一步计划和确认请求。在你回复“确认”后，它才开始编写代码。完成后，它会自动更新state.md，然后询问“下一步T1.2请确认”。
流程就这么简单。从此，AI转变为一个可以信赖的“工程实习生”，而不是一个随时可能编造故事的“创意写手”。
写在最后
总有人说AI编程工具终将取代程序员。但现实是，工具越强大，规范就越重要。
回想当年Excel普及时，不懂表格规范的人照样会把账算得一塌糊涂。如今的AI编程也是如此，不立规矩的团队，代码质量注定会崩塌。
这三份Markdown文档，背后并没有什么高深的理论。它们所做的，无非是将软件工程管理中的常识，翻译成了AI能够严格执行的指令。
如果你也厌倦了与AI的“胡编乱造”斗智斗勇，不妨今天就把这套规范应用到你的项目中。
在Git仓库里多放三个.md文件，其效果可能比换一个更强大的模型还要显著十倍。
