先问你三个问题。

你有没有让 AI 改一个函数，结果它把整个文件给你重构了？

你有没有让它装个包，它给你编了一条根本不存在的命令，还信誓旦旦说"已执行成功"？

你有没有排查一个 bug 排了两小时，最后发现是两处代码互相打架——因为 AI 前面改了 A，没告诉你 B 会跟着坏？

如果有，先别急着骂 AI。

八成不是它笨，是你给它的信息结构不对。

我手上常年并行跑着多个 AI 项目，从 RAG 问答、企业后台，到各种环境配置和模型接入，翻过的车能绕地球半圈。折腾到最后，我总结出一套东西：

提示词不是一个句子，是一个四段式结构。而且——不同的活，这四段的配比完全不一样。

---

先搞懂：AI 为什么老猜错

想让 AI 听话，得先知道它天生有哪些毛病。三个，一个比一个关键。

毛病 1：它没有记忆

每次开新会话，它都是从零开始。

你昨天跟它讲了两小时的项目架构，今天开个新窗口，它一句都不记得。这不是它偷懒，是架构决定的——大模型本身是无状态的。

后果：你不给它背景，它就只能靠猜。猜错了，你还怪它笨。

解药：把关键上下文固化成文件，每次开工先喂给它。（如有关项目阐述的README.md）

毛病 2：它对模糊信息会编

这条最要命。比如说"数据库用 MySQL，端口映射过了，密码在配置文件里"——人听着觉得"嗯，信息够了"。但 AI 听到的是：端口多少？密码多少？哪个配置文件？

它不会问你，它会自己编一个。编得很像真的，然后你就照着错的往下走了。

后果：你给的信息越模糊，它编得越起劲。

解药：凡是"值"——版本号、端口、路径、账号、命令——全部用键值对或表格写，不要写散文。

对比一下：

写法	AI 理解精度	为什么
「数据库用的是 MySQL，端口映射过了，密码在配置文件里」	低 ❌	关键值全缺，只能猜
「MySQL 端口 3316→3306，密码 ***，见 docker-compose.yml」	高 ✅	键值对，零歧义，直接引用

记住一句话：写散文，它读到的就是散文；写事实，它读到的才是事实。

毛病 3：它不知道"现在到哪了"

一个项目干到第三周，你开个新会话，它不知道：

• 哪些功能已经做完了

• 哪些坑已经踩过、已经有对策了

• 下一步该干什么

后果：它重复造轮子，或者跳过关键前置步骤（比如没跑迁移就先改表结构）。

解药：文档里必须有一块「当前状态 + 待办」，让它知道进度条。

---

解药：提示词四支柱

搞清楚了毛病的成因，解药就明确了。一条好用的提示词，必须包含四段：

支柱	回答什么问题	缺了会怎样
Context（上下文）	你是谁、现在是什么环境、已知什么	它凭空猜测，答非所问
Goal（目标）	要什么结果（描述结果，不是描述手段）	做了一堆事，没一件是要的
Constraints（约束）	边界：不许做什么、必须遵守什么	改对了功能，改坏了别处
Acceptance（验收）	怎样算"做完"，怎么验证	它说"完成了"，一跑就崩

大多数人写提示词，只写了 Goal，顶多加个 Context。

Constraints 和 Acceptance 基本是空的——而这两项恰恰是决定成败的。

因为 AI 有个特点：你不给它边界，它就会用最省事的方式达成目标。而"最省事"往往意味着"顺手把旁边的东西也改了"。

四支柱的写法要点

• Context 要写"事实"，不要写"背景故事"；
• Goal 要写"结果"，不要写"动作"；
• Constraints 要写"禁令"，越具体越好；
• Acceptance 要"可执行、可验证"。

---

重点：六类场景，四支柱怎么配

好，方法论讲完了。下面是本篇真正的干货。

同一套四支柱，在不同业务场景下，权重完全不一样。配比搞错了，模板抄得再漂亮也没用。

 

---

场景 1：接手陌生项目

本质：让 AI 快速建立"世界观"，还不许它动手。

配比：Context ●●● / Goal ● / Constraints ● / Acceptance ●●

这个场景最反直觉的地方是：Goal 要写得极小。

很多人一上来就说"帮我看看这个项目，然后优化一下"。结果 AI 啥也没看懂就开始改，改完你发现它连模块划分都搞错了。

正确做法：第一次只让它读，不许它写。

❌ 典型翻车

"这是我新接手的项目，你看一下有什么问题，顺手优化下。"

→ AI 扫了几个文件名，猜了个架构，改了三个文件，全改错地方了。

✅ 模板（直接抄）

你是这个项目的接手开发者。这一轮只做一件事：读懂它，不要改任何代码。
【项目位置】D:\projects\report-service

【必读】根目录的 AI_CONTEXT.md，先读完再回答

【本次目标】回答我三个问题：
1． 这个项目的核心业务是什么？一句话说清
2． 主要模块怎么划分，各自职责是什么
3． 如果要新增“报告批量导出”功能，应该动哪些文件？为什么
【约束】
－ 不许修改任何文件，只读
－ 不确定的地方直接说“不确定”，不许猜
－ 每个结论必须给出依据（哪个文件、哪个函数）
【验收】
－ 三个问题都有明确答案
－ 每个结论都能指到具体文件路径
－ 最后列出“你还不知道、需要我补充的信息”

为什么 Acceptance 要加"列出你不知道的信息"？

因为这一条能帮你发现文档的缺口。AI 说"我不知道菜单是怎么渲染的"，你就知道该往 AI_CONTEXT.md 里补一条了。

这个场景的关键认知

有些项目的架构是反直觉的，你不写清楚，AI 必错。

举个真实例子：我用 django-vue3-admin 做二开，它的侧边栏菜单是数据驱动的——菜单存在数据库表里，前端登录后调接口动态生成路由。

也就是说：改菜单不是改前端代码，是改数据库。

这条不写进文档，AI 有 100% 概率去 web/src/router/ 里翻代码，然后告诉你"没找到菜单配置"。

这类"架构事实"是文档里最值钱的部分，比技术栈清单重要十倍。

---

场景 2：加功能 / 改代码

本质：在别人（或三个月前的自己）的地盘上动刀。

配比：Context ●● / Goal ●●● / Constraints ●●● / Acceptance ●●

这是日常最高频的场景，也是最容易"改对了 A、弄坏了 B"的场景。

❌ 典型翻车

"帮我加个批量导出功能。"

→ AI 加了个按钮，自己新写了一套导出逻辑，还顺手"优化"了原有的单条导出，结果两个导出格式不一致，测试全挂。

✅ 模板（直接抄）

【上下文】
项目见 AI_CONTEXT.md (先读)。
本次改动范围：plugins/report_service/

【目标】
新增“报告批量导出”功能：
- 入口：报告列表页右上角，新增“批量导出”按钮
- 行为：勾选多条 → 点击 → 导出为一个 Excel（多条 sheet 或单 sheet 多行，你判断哪种更适合并说明理由）
- 导出字段：与现有单条导出完全一致

【约束】
- 只改 plugins/report_service/ 下的文件，其他模块不许动
- 必须复用现有的 utils/export.py，不许新写导出逻辑
- 数据库只允许新增字段，不许改已有字段名
- 前端只加按钮和调用，不许改列表页其他交互
- 每完成一步，告诉我我改了哪些文件、为什么改

【验收】
- 列表页出现“批量导出”按钮
- 勾选 3 条导出，字段与单条导出逐列对齐
- 给出验证命令和预期输出

三个细节值得说

1. "只改 X 目录" —— 这条能挡掉 80% 的"顺手改坏"。

1. "复用现有的 X" —— 不给这条，AI 默认会新写一套，因为它不知道你已经有轮子了。

1. "你判断哪种更合适并说明理由" —— 遇到有多个合理方案的地方，别自己纠结，让它给建议 + 理由，你来拍板。这叫把决策权留在自己手上。

---

场景 3：排障 / 定位 Bug

本质：先诊断，再动手。顺序错了必翻车。

配比：Context ●●● / Goal ●● / Constraints ●●● / Acceptance ●●●

排障场景有个铁律：

不要让 AI 直接改代码。让它先给"假设 + 验证方法"，你确认后再动手。

为什么？因为 AI 面对报错的第一反应是"改点什么让它不报错"。而"不报错"和"修好了"是两件事。

❌ 典型翻车

"这个报错怎么解决？[贴报错]"

→ AI 直接改了三个地方，报错消失了，但功能也坏了——它把出问题的那段逻辑注释掉了。

✅ 模板（直接抄）

【现象】
执行 xxx 时报错，完整报错如下：
[粘贴完整报错，不要截断]

【环境】
Windows 10 / Node v22.22.2 / 国内网络无代理

【已排除】
我确认不是 xxx 的问题（已单独验证过）

【约束】
- 这一轮只做诊断，不许改任何代码
- 列出 2~3 个最可能的原因，按可能性排序
- 每个原因给出：为什么怀疑它 + 怎么验证它
- 我确认后你再动手，一次只改一处
- 不顺手重构无关代码

【验收】
- 我按你的验证方法能确认或排除每个假设
- 最终修复后，给出「复现 → 修复 → 验证」完整步骤
- 说明根因，不接受“试出来的”

真实案例：一个字符导致的谜案

前段时间配 Claude Code，npm install 明明成功了，claude --version 却一直提示"不是内部或外部命令"。

直觉反应是"PATH 没配"。但查下去发现——PATH 里确实有那个目录。

真正的原因是：那条路径坏的。

更坑的是，同一个毛病坏了 4 条路径，另外 3 个软件的 bin 目录也一直失效，只是没人发现。

这类问题的教训：

如果当时直接对 AI 说"claude 命令找不到，帮我修一下"，它大概率会执行 setx PATH "%PATH%;..." 再加一遍——而这恰恰是把 PATH 写坏的原因（%PATH% 会把系统级和用户级揉在一起，而且 setx 有 1024 字符上限，超长会静默截断）。

所以排障场景里，"先诊断"这条约束救的是你的系统。

---

场景 4：环境配置 / 第三方接入

本质：确定性事实必须零歧义，这是幻觉重灾区。

配比：Context ●●● / Goal ●● / Constraints ●●● / Acceptance ●●●

装环境、接第三方 API、改系统配置——这类任务 AI 编造的概率最高。

因为它见过的"教程"太多了，各种版本混在一起，它会把 A 项目的命令拼到 B 场景里。

❌ 典型翻车

"帮我在 Windows 上装 Claude Code，接国内大模型。"

→ AI 给了条 setx PATH "%PATH%;..."，你以为搞定了，结果 PATH 被写坏，一周后另一个软件突然用不了。

✅ 模板（直接抄）

【目标】
在 Windows 上装好 X，并接入 Y 服务。

【环境事实】
－ OS：Windows 10 21H2 / 64 位
－ 终端：CMD（不是 PowerShell）
－ 运行时：Node v22.2.2
－ 网络：中国大陆，无代理
－ 已装：Git、Python 3.11
－ 已排除：之前装过旧版本，已卸载

【约束】
－ 每条命令必须标明在哪个终端执行（CMD / PowerShell）
－ 不确定的命令不要给，直接说“需要确认”
－ 涉及修改系统配置（PATH / 注册表 / 服务）的，先给方案 + 风险，我确认后再执行
－ 禁止使用 setx PATH "%PATH%;..." 这类写法
－ 如果官方下载源在国内不可达，直接告诉我替代方案

【验收】
－ 每步给出可直接复制的命令
－ 每步给出验收标准（看到什么算成功、看到什么算失败）
－ 失败时给出排查路径，不是"重试一下"

两个关键点

① 环境事实要写全

"Windows"这三个字不够。CMD 和 PowerShell 的命令不通用，32 位和 64 位不一样，有代理和没代理的安装路径完全不同。

我见过太多人卡在 irm 不是内部或外部命令——因为在 CMD 里跑了 PowerShell 的命令。

② 主动告诉它"哪些命令有坑"

AI 不知道你踩过什么坑。你得告诉它。

比如 setx PATH "%PATH%;新路径" 这条命令，看起来人畜无害，实际上：

• %PATH% 会把系统级 + 用户级 PATH 全揉在一起，再写回用户级 → 大量重复、体积膨胀

• setx 有 1024 字符上限，超长会被静默截断，把后面的条目整段砍掉

• 破坏后会出现 C:\Users 被拆成 C: 和 Users 这类碎片，极难人工发现

正确做法是用图形界面改，或者只操作用户级。

这个坑，写进 Constraints 一次，以后就再也不用踩了。

---

场景 5：重构 / 迁移

本质：大面积改动，防破坏优先于效率。

配比：Context ●● / Goal ●●● / Constraints ●●●● / Acceptance ●●

这是唯一一个 Constraints 权重高于一切的场景。

因为重构的本质不是"改成什么样"，而是"在改的过程中不出事"。

❌ 典型翻车

"把这个模块从同步改成异步。"

→ AI 一次性改了 15 个文件，跑不起来，你也不知道哪一步错了，git diff 看半天，最后只能全部回滚。

✅ 模板（直接抄）

【目标】
把 report_service 的报告生成逻辑从同步改为 Celery 异步。

【范围】
只动以下文件（其他一律不碰）：
- plugins/report_service/views.py
- plugins/report_service/tasks.py（新建）
- plugins/report_service/services/generator.py

【约束】
- 拆成 5 步以内执行，每步必须能独立跑通、独立验证
- 每步开始前我手动 git commit，你必须提醒我
- 不许改任何业务逻辑，只改执行方式
- 不许改数据库结构
- 遇到不确定的地方停下来问，不许自己拍板
- 保留原有同步调用的兼容路径，直到我确认可以删

【验收】
- 每步完成后，原有功能仍可用
- 最终：调用接口立即返回 task_id，Celery 后台执行，完成后钉钉推送
- 旧代码路径标记 @deprecated，不直接删除

为什么"每步必须可独立验证"这么重要？

因为重构出错时，最痛苦的不是"坏了"，而是"不知道哪一步坏的"。

拆成 5 步，每步都验证，出错时你只需要回退一步。一次性改完，出错只能全部回滚。

还有一条容易被忽略的：保留兼容路径。

别让 AI 直接把老代码删了。先并存，跑通一段时间，你确认没问题了再删。这是成年人的做法。

---

场景 6：文档 / 教程产出

本质：产出物要能被别人执行，不是被你自己看懂。

配比：Context ●● / Goal ●●● / Constraints ●● / Acceptance ●●●●

这个场景 Acceptance 权重最高，因为没有验收标准的教程，100% 是废的。

❌ 典型翻车

"写个安装教程。"

→ 拿到一份排版漂亮、逻辑清晰、但照着做跑不通的文档。因为里面全是"根据实际情况调整"、"配置好相应参数即可"。

✅ 模板（直接抄）

【读者】
完全没接触过这个工具的新人，会开终端，但不懂命令行参数。
【目标】
写一份 Windows 安装教程，读者照着做能跑通。
【约束】
每个操作步骤都要给可直接复制的命令
明确区分 CMD 和 PowerShell 的命令
不许出现“根据实际情况调整”、“相应配置”这类废话
每一步都要写失败时怎么办
涉及凭据的地方用占位符，不要用真实 Key
【验收】
一个没装过的人照着做能跑通
每一步都有验收指标：看到什么算成功，看到什么算失败
附一张常见报错速查表（报错 → 原因 → 解决）
最后有一个可勾选的总验收清单

好教程和烂教程的分界线只有一条：有没有验收指标。

"点击下一步完成安装" —— 这是步骤，不是验收。 "安装完成后，新开一个终端执行 xxx --version，输出形如 2.1.301 的版本号" —— 这才是验收。

---

真实复盘：一个 Django 项目的上下文改造

理论讲完，看个真事。

我手上有个肠道微生态检测报告服务系统，基于 django-vue3-admin 二开，Django 4.2 + Vue3 + MySQL，业务是检测数据管理、报告模板配置、报告生成/审核/推送。

刚接手时，AI 表现得像个"聪明但总帮倒忙的实习生"：

• 让它改菜单，它去改前端路由文件 —— 但这个项目的菜单是数据库驱动的

• 让它查数据库配置，它翻出三个不同的密码 —— 因为配置散落在 4 个地方

• 让它跑迁移，它跳过了 init 步骤 —— 因为有个 migration 在 init 前跑会被跳过

问题不在 AI，在于我没告诉它这个项目的"世界观"。

于是我写了份 README.MD，结构是这样：

0. 一句话定位      ← 它是什么  
1. 技术栈（确定性清单）   ← 表格，版本号精确到小数点  
2. 目录结构（只列关键路径）  
3. 运行时约定（端口/账号/密码）  
4. 核心业务模块        ← 每个模块干什么  
5. 关键架构事实        ← 最值钱的部分  
6. 已知坑             ← 踩过的坑 + 对策  
7. 常用命令  
8. 当前状态 / 待办  
9. 变更日志

其中第 5 节和第 6 节是含金量最高的。

第 5 节「关键架构事实」我写了这么几条：

• 菜单是数据驱动的：侧边栏和路由由数据库表 dvadmin_system_menu 决定，前端登录后调接口动态生成。改菜单 = 改数据库，不是改前端代码。
• 菜单三要素：parent（层级）、is_catalog（True=目录只展开，False=进页面）、component（字符串，映射到 web/src/views/ 下的 .vue，路径不匹配就是白屏）。
• 权限是 RBAC + 列级：superadmin 走全量分支，不依赖角色-菜单关联表。
• 配置单一真相源：数据库配置以 docker-compose.yml 为准，conf/env.py 与之对齐。
• 响应契约：后端统一返回 {code, msg, data}，code=2000 成功，401 认证失败。

三条经验，直接抄

• 架构事实 > 技术栈清单。技术栈网上能查到，架构事实只有你知道。
• 一个事实只写一次，并指明权威来源。MySQL 配置散在 4 个地方时，AI 必然选错。
• 踩过的坑一定要写。写一次，长期免疫。

---

落地三步：搭起你的项目记忆库

别看上面写了一堆，落地其实就三步。

第一步：建一个 README.md

放项目根目录。不用写得很长，先按这个骨架填空：

## 项目背景

## 0．一句话定位  
（这个系统是干什么的，给谁用的）  

## 1．技术栈  
| 层 | 技术 | 版本 |  
|---|---|---|  

## 2．目录结构（只列关键路径）  
（每个关键目录一句话说明职责）  

### 3．运行时约定  
| 项 | 值 |  
|---|---|  
| 前端端口 | |  
| 后端端口 | |  
| 数据库 | |  
| 启动命令 | |  

## 4．核心模块  
（每个模块干什么，边界在哪）  

## 5．关键架构事实
（那些"不知道就一定会改错"的约定）  

## 6．已知坑  
| # | 现象 | 原因 | 对策 |  
|---|---|---|---|  

## 7．当前状态 / 待办  
- [ ] 待办一  
- [x] 已完成  

## 8．变更日志  
| 日期 | 变更 |  
|---|---|

写的时候记住一条：值用键值对，原因用散文。

版本号、端口、密码、路径 —— 全部表格化。 "为什么这么设计"、"当时踩了什么坑" —— 才用文字描述。

第二步：每次提任务，补齐 Constraints 和 Acceptance

大部分人只写 Goal。从今天开始，每条提示词强制补两段：

• Constraints（约束）：不许做什么、必须遵守什么

• Acceptance（验收）：怎样算做完、怎么验证

第三步：每次干完，回写文档

改完代码，顺手更新两处：

• 把待办勾掉

• 在变更日志加一行

这一步是闭环的关键。 不回写，文档三个月后就过期了，AI 拿着过期信息干活，比没有信息更危险。

---

避坑清单（建议收藏）

#	坑	对策
1	用散文写配置信息	值一律键值对/表格
2	只说"改一下"，不说边界	明确"只改 X 目录"
3	排障时直接让它改代码	先要"假设 + 验证方法"，确认后再动手
4	涉及系统配置直接执行	先要方案 + 风险，自己确认
5	一次让它干三件事	一次一件事，做完验证再做下一件
6	没有验收标准	每任务必写"怎么算成功"
7	同一事实有多个来源	指明"以 X 文件为准"
8	相信它说的"已完成"	自己跑一遍验证命令
9	踩过的坑不记录	写进「已知坑」，一次投入长期免疫
10	文档写完就不管了	每次干完回写状态和变更日志

---

最后

回到开头那个问题：为什么同一个 AI，别人用着像开挂，你用着像抽奖？

差别不在模型，在你给它的信息结构。

而信息结构该长什么样，取决于你在干哪类活：

• 接手项目 → Context 拉满，Goal 压到最小（只让它读）

• 加功能 → Constraints 拉满（划死范围）

• 排障 → 先诊断后动手，Acceptance 拉满（要能验证）

• 配环境 → 环境事实写全 + 主动给禁令

• 重构 → Constraints 压倒一切（每步可回滚）

• 写文档 → Acceptance 压倒一切（别人能跑通）

今天就可以做的三件事：

1. 给你的主力项目写一个 README.md，重点写「关键架构事实」和「已知坑」；
2. 下次提需求，强制自己补上 Constraints 和 Acceptance 两段；
3. 把今天踩的第一个坑，记进文档。

做完这三件事，你会发现 AI 突然"变聪明了"。

其实它没变，是你终于把话说清楚了。

---

如果这篇对你有用，可以点个赞让更多人看到。有问题评论区聊，我基本都会回。