我靠三份Markdown文件，把AI从“胡编乱造”训成了“工程监理”

从Bug率飙升60%到交付周期缩短2倍，我只加了三个文件

前段时间，我差点把AI编程工具卸载了。

不是因为它写得慢，恰恰相反------写得太快了。

一个登录功能，Claude Code十秒生成1800行代码，看着挺像回事。上线后测试发现：验证码校验逻辑漏了、token刷新机制是虚构的、错误处理直接用console.log糊弄。Bug率比人工编码高了60%，功能遗漏成了第一大问题。

最恐怖的是：我根本不知道AI到底写了什么。1800行，审不过来了。

后来我做了三件事。不是写更好的提示词，不是换更强的模型。而是在项目根目录放了三份Markdown文件。

一段时间后，AI的代码返工率从47%降到了11%。团队里所有人跟AI协作的方式统一了，新人入职第一天就能用AI交付高质量代码。

这三份文件，今天完整公开。

---

一、先看一个真实对比：同一需求，两个结果

需求很简单：实现一个手机号+验证码登录功能。

没有规范文件的AI输出（真实案例）

javascript

// 这代码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输出（模板约束后）

javascript

// 来源：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、Copilot）在写代码前必须先读它们。

文件1：rules.md --- 工作流铁律

这个文件告诉AI：不按流程走，不许写代码。

markdown

# AI工作流规则 --- 强制执行

## 每次对话开始，必须：
1. 读取 state.md 了解当前进度
2. 读取 plan.md 了解整体计划
3. 输出以下三个区块才能写代码：
   - 状态回顾（上一步做了什么、做到什么程度）
   - 下一步动作（具体任务+预期效果）
   - 确认请求（等待用户说"继续"）

## 写完代码后，必须：
1. 输出验收自检表（逐条对照需求打勾）
2. 更新 state.md 中的进度
3. 声明每个调用的API来自哪个文件（防止虚构）

## 禁止事项：
- ❌ 禁止在未确认的情况下直接修改代码
- ❌ 禁止调用未声明来源的函数
- ❌ 禁止实现需求中没有的功能

这条铁律把AI从"自由创作者"变成了"按图施工的工人"。

文件2：plan.md --- 分阶段作战地图

没有计划，AI就容易"发散"。这个文件把项目拆成小任务，每个任务都有明确的验收条件。

markdown

# 整体计划 --- 记账小程序 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了"。

markdown

# 当前执行状态

最后更新：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读完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立的"规矩"。

还有一个心理学机制：把规则写下来，比口头说有效10倍。AI也一样。当它看到文件里白纸黑字写着"禁止虚构API"，它就会老老实实去代码库里找来源。

---

五、手把手：30分钟给你的项目配上这套规范

第1步：创建.ai文件夹

bash

mkdir .ai

第2步：复制三份模板（我会在文末放完整下载链接）

把上面三份Markdown内容分别保存为：

• .ai/rules.md
• .ai/plan.md（按你的项目填写阶段）
• .ai/state.md（初始状态）

第3步：填写plan.md的关键部分

不需要写全，先写第一个Phase就够了。格式：

text

## Phase 1: [阶段名]
- [ ] 任务1: 具体做什么
- [ ] 任务2: ...
**验收**：[可验证的条件]

第4步：启动AI，输入第一句话

在任何AI工具（Claude Code、Cursor、Copilot）中：

"请先阅读 .ai/rules.md、.ai/state.md 和 .ai/plan.md，然后严格按照工作流执行第一个任务。"

然后你会发现，AI不再抢答了。它会先输出：

状态回顾 ：当前Phase 0，未开始任何任务。
下一步动作 ：T1.1 初始化目录结构，预期创建 src/api/, src/utils/...
确认请求：请确认是否执行？

你说"确认"，它干活。干完了，更新state.md，然后问"下一步T1.2请确认"。

就这么简单。从此AI变成了可以信赖的"工程实习生"，而不是一个随时会编故事的"创意写手"。

---

写在最后

有人说AI编程工具会取代程序员。我只想说：工具越强，规范越重要。

当年Excel普及的时候，不会做表格的人照样算错账。现在AI编程也一样，不立规矩的团队，代码质量一定崩。

这三份Markdown文件，不是什么高深理论。就是把工程管理的常识，翻译成了AI能执行的指令。

如果你不想再被AI的"胡编乱造"折磨，今天就把这套规范放进你的项目里。

在Git仓库里多放三个.md文件，比换一个更强的模型管用10倍。

关于作者：boonya

---

资深开发工程师，高级架构师。熟悉GIS、车联网、物联网、供应链、林业、互联网家居、游戏、商旅服务。你可以在微信公众号：智驭未来掌门人 找到我！