前阵子不是写了Vibe Coding学习笔记系列嘛，前面几篇讲的是怎么和AI结对编程、怎么把大需求拆成小块、怎么用自然语言把逻辑边界说清楚。到了第六篇，我想聊聊一个特别容易被忽略但极其影响产出质量的东西——给AI准备一份"工作手册"。
说白了，Vibe Coding刚上手的时候，大家都喜欢直接甩需求："帮我写个后端接口""把这个页面样式调一下"，然后AI出什么我就用什么。前几周这么干没觉得有什么问题，反正demo能跑就行。但一旦项目复杂度上来，马上发现不对劲：AI队友的记性是真差，上午刚定好的技术约定，下午换个上下文窗口它全忘了；明明说好接口统一返回{code, message, data}结构，它下一页就开始返回{status, data}；说好了目录结构按模块划分，它就跑出一个平铺的直筒结构。
你当然可以一遍遍地在对话里重复这些规则，但每次重复都是token，都是成本，而且总有漏掉的时候。后来我找到一个更治本的做法：把那些反反复复要交代的内容整理成一份专门给AI看的"工作手册"，每次开始新会话的第一件事就是把它喂给AI。
这篇笔记就详细聊聊我是怎么把散落在对话里的各种约定、偏好、限制，沉淀成一份AI真正能读懂、能用起来的"工作手册"的。不只是一份文档模板，更是一套和AI协作的方式调整。
1. 为什么要给AI写"工作手册"：从"每次重新调教"到"一次配置，长期复用"
先说一个我自己的观察。刚用AI写代码的头两周，我对它的预期是"像一个人一样，聊过的事情都能记住"。结果现实狠狠打脸——AI的上下文窗口虽然越来越大，但它在处理长对话时依然存在严重的"遗忘曲线"。尤其是当你的项目有几百个文件、几十个接口、一堆历史决策时，AI在回答中段开始就会逐渐"失忆"，优先参考最近几轮对话的内容，而不是更早的、但更关键的约定。
我试过一个比较极端的例子：某天下午，我和AI讨论了大概两小时的数据库表结构设计，包括字段命名规范、索引策略、外键约束风格。当时聊得明明白白，AI也很配合。但到了晚上，我让它基于那个结构写一个新的查询接口，它直接用了完全不同的命名方式，还把几个字段类型给改了。我一看，那股火直接顶到脑门——这不等于白聊了吗？
后来我复盘，问题不在AI，而在我。我在用一个适合人类协作的方式去跟AI合作，但AI根本不是人类，它的工作记忆机制完全不同。人类同事能通过长期共事形成默契，哪怕不提也能照做；AI没有这个"长远记忆"，它只认当前上下文里明确写出来的规则。
所以"工作手册"这个概念就顺理成章了。它不是普通的开发文档，而是一份专门写给AI看、以约束AI输出行为为目标的结构化约定集。你可以把它理解成给新来的实习生准备的入职手册，只不过这个实习生每周都会失忆一次，你每次都得重新给他发一遍手册，让他快速进入状态。
有了这份手册之后，效果是立竿见影的。我统计过自己一周的AI协作情况：在引入手册之前，每次会话前30%的时间都在重复交代背景和规则；引入手册之后，这部分时间压缩到几乎没有，而且产出的代码质量显著更稳定，返工次数大概减少了一半以上。
这里有一个很关键的认知转变要分享给大家：AI不是把人从代码中解放出来，而是把人从重复劳动中解放出来。你花30分钟整理一份手册，可能省下的是之后几十个小时的返工和扯皮。
那这份手册到底要解决哪些具体问题？根据我自己的实战经验，至少覆盖这几类：项目背景与目标、技术栈与版本约束、目录结构与职责划分、代码风格与命名规范、接口与数据格式约定、常见的已知坑、AI被禁止做的事、以及任务执行流程的默认偏好。每一类我都会在下面详细展开。
2. 工作手册的内容设计：从"想到什么写什么"到"围绕决策点组织信息"
最开始我写这份手册特别随意，就是打开一个Markdown文件，把脑子里能想到的规则一条条列出来。结果AI确实看了，但执行效果一般。后来我琢磨了一下原因：规则太零散，缺乏上下文，AI不知道在什么场景下应用哪条规则。比如你写"接口返回格式要统一"，它看到了，但它怎么判断自己正在写的是不是接口？它需要更明确的触发条件。
2.1 项目背景与边界约束——让AI知道自己在做什么
手册的第一部分必须是项目的整体介绍，但不要写成长篇大论的项目汇报，要写得像"电梯演讲"一样精炼。我一般用100到200字说清楚：这个项目是什么、核心解决什么问题、目标用户是谁、当前处于什么阶段（原型、MVP、生产）、有哪些明显的边界和限制。
举个我自己的例子。某次我在做一个内部数据可视化平台，手册里对背景的描述就是这样的：
项目是面向内部运营团队的数据报表平台，当前处于MVP阶段。 核心目标是帮助运营同学通过可视化看板快速定位异常指标，不需要专业的SQL能力。 技术方面使用前后端分离架构，前端React + TypeScript，后端Python FastAPI。 MVP阶段不需要考虑多租户、权限分级等复杂特性，但需要预留后续扩展空间。这段描述看着简单，但对AI来说价值巨大。它理解了背景之后，很多默认决策自然就对了。比如它会倾向用更直观的图表组件，而不是Table；会倾向把查询条件设计得更傻瓜式，而不是给一堆高级筛选；会在设计数据模型时预留一些扩展字段，因为知道后面要考虑权限扩展。
边界约束同样重要。你给AI设置一条"本阶段不做X"，能帮它省下一大堆不必要的脑洞。比如"MVP阶段不接入消息队列""不用做移动端适配""不做国际化"。这些约束写在手册里，AI在方案设计阶段就会主动绕开这些路，而不是走一半再问你"要不要考虑一下类似方案"。
2.2 技术栈与版本的硬性规定——不妥协的部分
第二部分是技术选型的硬性约束。很多人会忽略这一部分，觉得"我用React写代码，AI肯定知道"。但实际上，AI知道的React和你想用的React中间可能隔了好几层版本差异和生态偏好。
举例来说，如果你项目里用的React Router是v6，但你忘了在手册里写明，AI基于训练数据中的更老版本记忆，可能给你生成一大堆v5的写法；你用的UI库如果是从某个内部组件库封装的，AI根本不可能知道有这个库存在，它会默认用Ant Design或者Material UI的写法，最后给你产出一堆需要推倒重来的死代码。
我通常会在手册这一部分列一个表格，极其明确地写出技术栈清单，包括：
| 层面 | 所选方案 | 版本/说明 |
|---|---|---|
| 前端框架 | React | 18.x，函数组件 + Hooks |
| 构建工具 | Vite | 5.x，不用webpack |
| UI组件库 | 内部封装组件库 | 包名：@internal/ui，部分组件是基于antd二次封装 |
| 路由 | React Router | 6.x，使用createBrowserRouter |
| 状态管理 | Zustand | 4.x，不使用redux |
| HTTP请求 | Axios | 统一封装在src/utils/request.ts |
| 后端框架 | FastAPI | Python 3.11 |
| ORM | SQLAlchemy | 2.x，使用declarative模式 |
| 数据库 | PostgreSQL | 15，使用asyncpg驱动 |
这个表格写出来，AI在代码生成时的选择空间就完全被框住了，不会出现"重造轮子"的写法。它看到@internal/ui这个包名，就会主动去查这个组件库的API（如果它能在代码库里检索到的话），而不是凭空想象一个不存在的组件。
2.3 代码风格、命名规范与目录结构——定死"长什么样"
这一节是手册中我花时间最多的地方，也是收益最明显的地方。AI生成的代码，功能上往往问题不大，但代码风格和可读性真的是千奇百怪。有的喜欢用超长函数名加详细注释，有的喜欢极简命名加零注释，有的喜欢把一切逻辑塞进一个巨大的useEffect里，有的喜欢拆成十几个自定义Hook。
我踩坑比较深的一次是目录结构。某次项目，我想按feature来组织目录，每个功能模块一个文件夹，包含组件、hooks、API调用、类型定义。但我没在手册里写这个，AI默认按技术类型去组织，把所有hooks扔进一个src/hooks目录，所有API调用扔进一个src/api目录。等到后期维护的时候，改一个功能要跨五个目录跳来跳去，真叫一个痛苦。
后来我在手册里明确写了目录结构规范：
src/ ├── features/ # 按功能模块划分 │ ├── orders/ # 订单模块 │ │ ├── components/ # 只给订单模块用的组件 │ │ ├── hooks/ # 只给订单模块用的hooks │ │ ├── api.ts # 订单模块的API调用 │ │ ├── types.ts # 订单模块的类型定义 │ │ └── index.ts # 模块入口，统一导出 │ └── products/ # 商品模块 ├── shared/ # 跨模块共享的内容 │ ├── components/ │ ├── hooks/ │ ├── utils/ │ └── types/ └── app/ # 应用级配置，路由、布局等AI看到这个结构之后，它生成的代码自动就会"按图索骥"地放进合适的目录。偶尔它还是会犹豫，但至少大方向不会跑偏。
命名规范我建议也不用写太多条，抓住最核心的三四条就行。我写的比如：组件文件用大驼峰命名，变量和函数用小驼峰；布尔类型变量一律以is/has/should开头；API函数统一以fetch、create、update、remove作为前缀；样式类名用BEM的简化版（block-element）。这些规则不需要解释理由，AI也不需要理解，它只需要照着做就行。
2.4 接口协议与数据格式约定——防止前后端定义打架
这一部分可能是实际开发中沟通成本最高的地方。前后端接口的字段名、返回结构、错误码体系，任何一个不一致都能造成一堆联调问题。更麻烦的是，AI在后端写接口逻辑、前端调接口的时候，经常自发地"临场发挥"。
有一次我在做登录功能，后端AI生成的接口返回的是{access_token, refresh_token, user_info}，前端AI调用的时候却按照{token, user}去解析，结果一联调就报错。你说这两个AI谁对谁错？其实都是错，因为它们根本没有共享同一本手册。
我在手册里把接口约定写成了这样：
统一请求前缀：/api/v1 统一响应结构： { "code": 0, // 0表示成功，非0表示业务错误码 "message": "ok", // 成功时为"ok"，失败时为错误描述 "data": {} // 实际业务数据，可以是对象、数组或null } 分页请求统一使用page和pageSize参数，响应data统一为： { "list": [], "total": 0 } 错误码分段约定： 40001 - 参数校验失败 40101 - 未登录或登录过期 40301 - 无权限访问 50000 - 服务内部错误写完这段之后，我就明确要求AI在后端实现时必须遵循这套结构，前端封装的request.ts必须统一解包code字段，业务代码里只处理data部分。这个约定一写，前后端AI协作的摩擦瞬间少了很多。
2.5 已知的坑和AI禁区——有些路就是不能走
最后一部分是我觉得最体现"老司机"价值的部分：把项目里踩过的坑、AI容易犯的错、以及明确禁止做的一些事情统统写进去。这部分不是给AI提供知识，而是给它装上"护栏"。
比如我写过这么几条：
- 禁止在组件内部直接使用window.location.reload刷新页面，统一通过路由跳转 - 禁止用any类型绕过TypeScript类型检查，除非有注释说明理由 - 禁止在useEffect里直接修改state对象，所有更新必须走setState - 已知坑：antd的Table组件在同时使用rowSelection和固定列时存在横向滚动问题，不要同时开启 - 已知坑：FastAPI的Pydantic v2中对Optional字段的处理和v1不同，不要用`field = None`做默认值，要用`field: str | None = None` - 后端不要在业务逻辑里抛HTTPException，统一抛自定义BizException，由全局异常处理器转换这些规则很多是我在之前的对话中已经和AI反复强调过的，但AI就是记不住。我把它们收集到手册里，相当于"一次痛苦，长期受益"。每次新会话的第一件事，就是把手册喂给AI，让它先读一遍再开始干活。实测下来，它踩这些已知坑的概率大幅降低。
3. 手册的格式与"喂法"：AI不是人类，需要结构化的指令语言
内容想清楚了，接下来就要解决"怎么把这本手册高效地交给AI"的问题。最开始我是一股脑把整个Markdown文件丢给AI，但发现它虽然"读"了，后面的执行却不够到位。我分析了一下，问题出在手册太像人类文档，目标感不强，AI就像一个被塞了一堆背景材料的学生，不知道重点在哪。
3.1 用"指令式语气"而非"描述式语气"写规则
给AI写规则，要用祈使句，要明确"你应该做什么、不该做什么"，而不是"一般来说，我们可以怎么做"。这个区别非常微小，但影响巨大。
对比一下两种写法：
描述式："接口返回格式最好保持一致，这样前后端联调会比较顺畅。"
指令式："所有接口必须返回{code, message, data}结构；业务代码只解析data字段；错误码遵循分段约定。"
你能感受到差异吗？AI在理解描述式语言时会"自由解读"，而在理解指令式语言时会把它当成硬性要求。后来我几乎把手册里所有条目都改成了"必须/禁止/统一/不要"这种强指令词语，AI的执行符合率明显上来了。
还有一个技巧是给规则加"触发条件"。比如"当你在创建新页面时，路由配置必须添加到src/app/router.tsx，并同步在左侧菜单配置中注册"。这句话的前半部分是触发条件，后半部分是动作要求。AI在面对具体任务时，能自动匹配触发条件，然后调用对应的规则。比一条孤零零的"要添加路由配置"好用得多。
3.2 控制单条规则的粒度，不要让AI猜
我早期写手册还有一个问题：有些规则写得太细了，细到AI反而不好执行。比如我写过"按钮文字不要超过四个字"，这种规则本质上缺乏上下文，AI无法判断"提交订单"算不算超过四个字。
后来我学会了一个原则：规则要么足够具体到可直接判断，要么就干脆不写，让AI基于上下文自己决策。比如把"按钮文字不要超过四个字"改成"操作按钮的标题使用动词+目标名词的格式，例如'提交订单'、'取消导出'，避免使用长句"。这样AI需要做的就是从"要不要缩句"变成了"判断这个按钮的文案符不符合指定格式"，执行难度低了很多。
还有一点很重要：手册里尽量用肯定句描述期望行为，而不是用否定句描述不允许行为。不是说禁区不能用否定句，但大部分内容应该是"你要怎么做"，而不是"你不要怎么怎么做"。AI对肯定句的执行准确率要明显高于否定句。我怀疑是肯定句给了一个明确的目标，否定句则让AI停留在"避免做X"的模糊状态，它不知道用什么替代方案。
3.3 每次会话开头的"投喂仪式"与对齐动作
有了手册之后，每次开始新会话我都有一个固定的"投喂仪式"：
- 把手册完整贴给AI，附上一句话："这是项目的《AI工作手册》，请先完整阅读，并在后续所有任务中严格遵守手册中的规则。如果遇到手册未覆盖的情况，请先向我确认，不要自行假设。"
- 过几秒让AI给我复述一遍手册的核心要点，确认它真的"读了"而不是"装作读了"。这一步特别关键，能帮我识别AI是否真的理解了结构。
- 让AI基于手册内容，对当前任务做一个简要的执行计划，我再审核计划是否符合预期。如果执行计划就偏了，后面写的代码肯定也不对。
这套投喂仪式看起来有点繁琐，但实际耗时也就两三分钟。对比之前"聊十分钟才能让AI明白背景"的效率，已经提升了很多。
我遇到过一种特殊情况：当项目文件特别多、AI的上下文窗口装不下所有内容时，手册的作用就更关键了。这时候手册不仅是行为准则，更是项目的"信息压缩包"——把最核心的背景、规则、约束浓缩进去，AI不需要读全部代码，只要靠手册就能给出一致性的输出。
4. 实战复盘：一份高质量手册怎么把一个混乱项目救了回来
前面讲的都是方法论，下面用一个我实际经历过的混乱项目来复盘一下手册的实战价值。这个项目是一次内部工具开发，时间紧任务重，一开始我压根没想写手册，直接拉着AI就开干。项目有三块主要功能：数据导入、规则配置、报表查看。三个人（我、前端AI、后端AI）并行推进，没有任何共享约定。
4.1 混乱是怎么产生的：三方约定互相对不上
前端AI负责数据导入页面，它自己定了一套接口参数，比如导入任务用task_id标识，状态字段叫status，取值是pending/running/success/failed。后端AI实现的时候完全不知道前端这边的约定，它自己设计成了job_id和state字段，取值也变成了processing/completed/error。两边一联调，直接就是"车同轨，书同文"的翻版——完全对不上。
更离谱的是数据库表结构。后端AI为了图省事，建了一个config表，把所有规则配置都塞进一个JSON字段，而前端AI设计表单时是按照结构化字段来的。结果就是前端辛辛苦苦做的表单布局，提交之后只能把全部内容序列化成一个JSON字符串存进去，后期的规则筛选和校验全都做不了。
那段时间我的日常就是救火。前端说"接口返回的字段对不上"，后端说"前端传的参数我在文档里没看到"，我夹在中间疯狂传话。每次对话轮次一多，AI就忘了之前聊过的内容，又产生新的不一致。项目进度肉眼可见地慢下来。
4.2 手册如何力挽狂澜：从救火到预防
在我彻底被搞烦的一天，我强行按下暂停键，花了一整个下午把项目从头到尾捋了一遍，把所有已经踩过的坑、反复出现的矛盾点、以及我期望的目标状态全部写成了第一版工作手册。手册大概五六百行，核心内容包括：
- 项目的全局数据模型定义（每个实体有哪些字段、类型、含义、取值枚举）
- 前后端接口的完整列表和参数契约
- 前端组件状态管理和路由的约定
- 后端API实现的流程规范（先校验参数、再处理业务、后统一异常处理）
- 数据库表结构和命名约定
然后我重新开了三个新会话，每个AI进场时都先读手册，然后让它复述一遍和执行一遍计划。结果一个下午加一个晚上，之前两三天都没理清的混乱状态就彻底理顺了。
最明显的变化是，之后两天的开发基本没再出现字段对不上的情况。前端AI调了一个不存在的接口，后端AI竟然能根据手册主动指出来"手册中定义的接口是X，你调的Y不存在，是否需要新增"——这在之前是绝对不可能的。AI像是从一群各说各话的实习生，变成了读过同一本SOP的正式员工。
4.3 从这次复盘中沉淀的手册维护方法
那次经历之后，我对手册维护有了一个固定的习惯：每次发现AI做出不符合预期的行为，第一反应不是当场纠正它，而是回到手册里想：这条规则手册里有没有？如果有，是我写得不够清楚还是它违反规则？如果没有，我应该怎么补充？
把"临时纠正"变成"手册迭代"，这个思维转变很重要。当场纠正AI只影响当前会话，下次它又忘了；手册迭代则是一次修改，长期受益。所以我的手册是活文档，基本每两三天就会更新一次。更新频率最高的部分，通常是已知坑和禁区，以及接口协议的增补。
我也给手册分了版本号，每次大改都会在顶部加一条变更日志。这样万一AI出了一些怪问题，我可以回溯查证是不是手册某次变更引入了矛盾规则。这种习惯帮我避过好几次"规则自相矛盾"的坑——有两次就是因为新加的规则覆盖了旧规则，而旧规则没删掉，AI无所适从选择了错误的那条。
5. 手册的边界与"AI仍会犯错"的现实：期望管理很重要
写到这我得泼点冷水。工作手册不是银弹，它不能保证AI完全不出错。我自己在使用手册大半年之后的体会是：手册能把AI的错误率从"很高"降到"可控"，但不会降到零。依然是会有漏网之鱼。
一种常见的情况是，AI读懂了手册，但在处理复杂任务时"顾此失彼"。比如我要求它实现一个同时涉及文件上传、数据处理、结果展示的功能，它可能数据处理的逻辑是对的，但忘了文件上传组件要遵循手册里指定的那个内部组件库的API。这不是它没读手册，而是多线程处理任务时优先级排错了。
另一种更头痛的情况是，手册里写了一条规则，但AI在执行时发现真实代码里的情况和规则描述的不完全一致，于是它选择了"灵活变通"。很多AI的"变通"其实都是自作聪明，最后还是要你返工。我的处理方式是，在手册开头加了一条总纲："当手册规则和实际代码出现冲突时，停下并询问，不要自行更改任一方向。"这么一条兜底规则，能防住相当一部分AI的"擅自行动"。
还有一个不得不提的现实：手册不能替代你自己对项目的理解。如果你自己都不清楚项目的模块划分、接口设计、数据流向，你就没法写出一本高质量手册。AI是一个执行力很强的执行者，但它不是架构师。它可以在你给出的框架内做到90分，但框架本身得由你来搭。所以写手册的过程，某种程度也是逼自己把项目想清楚的过程。这一点，对长期想通过Vibe Coding提效的人来说，可能反而是手册带来的最大隐性收益。
我用下来，真的觉得这个工具是Vibe Coding流程里"性价比最高"的一环。它的成本是前几次会多花一两个小时来搭建和打磨，但之后每个会话节省下来的时间和返工量，早就把这一两个小时连本带利赚回来了。而且手册越用越厚，积累的坑越多，AI表现得越像一个"懂行的老员工"。
如果你也在用Vibe Coding，而且开始感觉到"每次都要重新教AI做事有点累"，我强烈建议你试试给自己的项目写一本《AI工作手册》。不需要追求完美，先写一个初版，在实战中不断迭代。等到哪一天你发现自己不用反复重复项目背景、AI就能给出贴合项目风格的代码时，你就知道这功夫花得值。
