前阵子不是写了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的写法最后给你产出一堆需要推倒重来的死代码。我通常会在手册这一部分列一个表格极其明确地写出技术栈清单包括层面所选方案版本/说明前端框架React18.x函数组件 Hooks构建工具Vite5.x不用webpackUI组件库内部封装组件库包名internal/ui部分组件是基于antd二次封装路由React Router6.x使用createBrowserRouter状态管理Zustand4.x不使用reduxHTTP请求Axios统一封装在src/utils/request.ts后端框架FastAPIPython 3.11ORMSQLAlchemy2.x使用declarative模式数据库PostgreSQL15使用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就能给出贴合项目风格的代码时你就知道这功夫花得值。
