三份Markdown文件训练AI从胡编乱造到工程监理

首页

AI教程

热心网友

转载

2026-05-28

前段时间，我差点就把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文件，其效果可能比换一个更强大的模型还要显著十倍。

来源:https://juejin.cn/post/7643757385782476826

免责声明：游乐网为非赢利性网站，所展示的游戏/软件/文章内容均来自于互联网或第三方用户上传分享，版权归原作者所有，本站不承担相应法律责任。如您发现有涉嫌抄袭侵权的内容，请联系youleyoucom@outlook.com。

上一篇：涂鸦变艺术：从简单线条到惊艳画作的创作指南下一篇：清明节放假安排通知与假期规划指南