Vibe Coding学习笔记写到第六篇之前聊过怎么把需求说清楚、怎么拆任务、怎么让AI自己生成测试。今天这篇想讲一个更偏“管理”的东西给AI写“工作手册”。你肯定遇到过这种情况——AI把功能做出来了但代码风格跟项目完全不是一路人变量命名随心所欲注释想写就写甚至顺手把不该动的配置文件改花了。问题不一定出在AI笨而是它“没有规矩”。我自己的经验是与其每次都花时间叮嘱不如一次性把规矩写进一份专门给AI看的“工作手册”让它在每一次 Vibe Coding 动手之前先“读一遍制度再上岗”。1. 为什么AI老做“蠢事”——因为没人给它立规矩1.1 翻车现场一次“好心办坏事”的改动先说一件最近发生的事。某个周五下午某开发者让AI帮忙把一个列表页的过滤逻辑从三层嵌套循环优化成使用哈希表。需求本身不复杂AI也很快给出了一版新函数看起来跑得通。但等他把改动提交到代码评审平台时整个文件几乎“红透了”——AI不仅改了目标函数还把整个文件里所有的双引号换成了单引号把十几个普通函数声明改成了箭头函数甚至顺手给一段老代码重新排了版。评审结果当然是被打回而且很难快速定位真正的逻辑改动因为“噪音”太多。这种场景在Vibe Coding里太典型了。AI不是不聪明它对任务本身的完成度可能很高但缺少一个“什么能做、什么不能做”的边界感。它默认自己对整个文件有完全的“编辑权”默认格式化代码不会影响业务默认统一风格是“加分项”。在项目主人看来这些默认值全是灾难。我后来复盘这个翻车事件发现问题不在AI模型能力而在于我给出的指令里只描述了“目标状态”没有描述“操作边界”。你没有告诉它“只许改函数体内部”它就会自由发挥。你告诉它“优化性能”它就会顺手“优化”它觉得不顺手的一切。Vibe Coding的轻松感容易让人忽略一点缺少约束的自由发挥在代码协作中就是事故高发地。1.2 问题根源上下文窗口与“默认知识”缺失为什么AI会这么“皮”底层原因有两个一个是技术层面的上下文窗口一个是协作层面的隐性知识缺失。先说上下文窗口。无论AI工具支持多长的上下文它真正有效处理的仍然是对话开始后的一段输入。随着任务越来越复杂底层代码文件、报错信息、历史讨论都会被塞进去AI对“早期指令”的注意力会逐渐下降。即使你在一开始说过“不要改格式”等它读到第10个文件时这条指令可能已经“虚拟消失”了。上下文是有限的而你一直在往里面添加新的信息旧规则必然会被挤出“注意力中心”。再说隐性知识。每个项目都有很多“写在空气里”的规矩变量命名习惯、目录结构约定、依赖管理策略、测试文件的组织方式、提交信息的风格。这些知识对老成员来说是肌肉记忆对人来说不需要写下来。可AI没有参与过团队例会它不可能天然知道这个项目的路由必须注册在哪张表里、组件样式为什么不能用CSS模块、为什么某个目录不能随便新增文件。它唯一知道的是你喂给它的那些代码和文档。工作手册要解决的正是这两件事。它充当AI的“外部记忆”把上下文窗口里容易丢失的指令固化下来它也是隐性知识的显式化容器把团队默认的规则变成可读取、可匹配、可执行的文本。你可以把它理解成给新人准备的“入职培训手册”既然AI每次开会话都像一个失忆的新人那就让它先读手册再干活。1.3 工作手册和提示词到底有什么区别很多人一听“给AI写工作手册”第一反应是这不就是写一段超长的提示词吗还真不是。提示词和工作手册属于两种不同层级的东西。提示词是“针对某一次任务说的话”。比如“把这段代码改成异步版本注意不要改变原有接口”这是一次性交流作用域只存在于当前会话。任务结束提示词过期。下次你再想约束AI得重新说一遍。问题是人的精力有限不可能每次对话都把项目规范复述一遍复述得越多上下文越拥挤执行效果反而越差。工作手册是“针对所有任务立下的规矩”。它不随某次会话结束而失效而是和项目共存。你可以在每个新对话开始时只加一句话——“请先阅读项目根目录下的AI工作手册再开始处理请求”剩下的细节全部由手册提供。长期看这比每次手工输入几十条规则要稳定得多而且手册本身可以版本化、评审、迭代。Vibe Coding里常有一种误解越自由越好让AI随便发挥反而有惊喜。但我的体会是真正高质量Vibe Coding是“探索在边界之内创新在框架之上”。没有边界的自由是混乱有边界的自由才是效率。工作手册就是那个边界的地基。2. 一份能被有效执行的工作手册应该包含哪些模块2.1 模块一角色与目标——让AI知道自己在哪个项目里干活写工作手册的第一个模块是让AI建立基本的“项目身份认知”。很多AI出错根源是它根本不知道当前项目是什么、用什么技术栈、目录怎么组织、自己扮演什么角色。比如你让它写一个后端接口它默认项目用的是Java Spring结果发现实际项目是Node.js Express你让它修改前端组件它默认样式方案是Tailwind实际项目用的却是普通CSS变量。这不是模型太笨而是你缺失了最基础的背景信息。这一模块不需要长篇大论但必须精确。项目名称、一句话定位、主要技术栈、关键目录结构、测试框架、包管理器、运行脚本这几项写清楚就够了。如果项目里存在一些只有老成员才知道的“坑”比如“生产环境构建前必须先执行迁移脚本”或者“新接口必须通过网关注册”也应该放进这个模块。AI不是人类它不会主动去问“这个项目是什么”它只会从对话内容里猜。与其让它猜不如在手册开头直接告诉它“你在哪、你是谁”。这一模块还有一个重要作用就是给AI一个“优先级的锚点”。当AI面对两类指令冲突时——用户临时说“这里改成硬编码”和项目规范“所有配置项必须从环境变量读取”——角色定义能帮助它判断应该遵守哪个。前提是你在手册里明确写了规范的优先级。建议在角色模块末尾加一句本手册的规则优先于会话过程中的一般性口头指令除非用户明确表示要临时覆盖。2.2 模块二编码规范与风格约束——把肉眼审查的问题写进文档AI编程助手对语法和逻辑的把握通常不差最让代码评审头疼的是风格问题命名混乱、组件过大、副作用藏在渲染逻辑里、函数返回值类型不稳定。这些问题是人眼审查时最容易发现也最耗费精力的。如果能让AI在动手时就遵守这些约束评审压力会骤减。写这个模块时不要试图照搬一整套冗长的编码规范文档那是给人类员工看的不是给AI看的。要挑“AI最容易犯、且影响最大”的十条以内写进去。常见的有变量和函数命名必须使用项目既有风格不能自造缩写单个函数控制在2040行以内超过就必须拆分禁止在render函数/渲染逻辑中写副作用调用外部接口、修改全局状态保持现有缩进和引号风格不要为了“统一”而改动无关代码新增依赖必须先列出原因和包名等待确认后再执行安装。写这些规则时有一个技巧每条规则都要配上反例和正例。AI非常擅长从对比示例中提取模式只写“命名要清晰”这种抽象表达它的理解可能跑偏但如果你直接给出“不要用data、temp、obj作为变量名用customerList、orderDetail”执行准确度会高很多。这个模块也是最容易和工作手册其他部分产生联动的地方。如果你在团队里已经建了ESLint或代码风格配置文件可以在手册里直接写“所有改动必须通过npm run lint检查”让AI把约束内化成自检行为。机器规则和手册规则互为备份效果比单靠某一边好得多。2.3 模块三工作流准则——先读后写、小步提交、测试先行除了“怎么写代码”工作手册还要管“怎么干活”。AI在完成任务时天然倾向于“尽快写出最终结果”这是它被训练出来的生成逻辑。但这种一步到位的生成方式在真实项目环境里往往行不通它可能漏掉调用方、可能没考虑兼容旧接口、可能没注意到某个工具函数已经存在。所以工作手册需要给AI定义一套执行任务的“标准动作序列”。我常用的一套工作流是先搜索项目里相关文件和调用处确认改动的全貌再列出改动清单一项项和需求对照确认无遗漏后开始写代码写完运行相关测试最终输出动说明包括改了哪些文件、为什么这么改、有没有需要人工确认的地方。这套工作流听起来机械但它恰恰能解决Vibe Coding最常见的失败模式“AI直接生成了自以为完整的结果结果连文件依赖都没搞清楚。” 当AI在动手前先读代码、再列清单它的输出质量会有质的提升。工作手册里应该明确告诉AI遇到不确定的调用关系宁可停下来提问不要自己脑补接口。要注意的是工作流准则不该写得太繁琐否则AI会把大量精力消耗在遵守流程上反而忽略了目标本身。核心就是三条先读后写、小步确认、有测试才叫完成。其余细节可以根据具体项目补充。2.4 模块四禁止事项与红线——划定安全边界如果说前面三块是教AI“怎么做”这一块就是教AI“绝对不能做什么”。给AI划定红线本身就是一种效率提升因为它替AI省掉了试探边界的过程也让人类少承担“被意外破坏”的风险。哪些内容适合写进红线挑那些一旦发生就会造成严重后果、且AI很可能无意中触发的事情。我在多个项目里沉淀下来几条通用性较强的禁止修改锁文件如包管理器的lockfile除非明确要求升级依赖禁止删除或移动不属于任务范围的测试数据和配置项禁止对整文件做格式化、全局重命名、批量替换等影响范围超过任务本身的改动禁止在未经过确认的情况下执行数据迁移、删除表、清空日志等破坏性命令禁止擅自新增第三方依赖必须先把方案拿出来讨论。红线的表达方式要足够硬。不要写“尽量不要格式化整个文件”要写“任何时候都不得对任务范围之外的行进行格式化”。AI对“不得”和“不要”的理解程度是不同的在训练数据和指令遵循中“不得”这类强约束词的执行效果明显更好。还要记住红线条目不能太多。如果每一项都划成红线AI会处于一种过度紧张的防御状态导致它不敢做应该做的事。我个人的经验是红线最多10条优先选“会造成不可逆损失”和“会产生大量评审噪音”的事情。红线是安全网不是行为清单。2.5 模块五验收标准与自检清单——让AI在交付前自己打分最后一个模块也是最容易被忽略的模块验收标准。很多开发者在工作手册里写了角色、规范、流程但没告诉AI“什么样算做完”结果AI交上来的东西总差一口气。其实只要你在手册里定义一份自检清单让AI在交付前逐项打钩它就能提前发现大量问题。自检清单可以是通用项和项目项的组合。通用项包括是否运行过测试是否有新增依赖改动范围是否最小是否更新了相关文档项目项则要结合实际场景比如“本地化文案是否已经同步新增key”或“新增接口是否在网关配置中登记”。这些清单条款最好写成问句因为问句会触发AI的检查行为让它沿着问题去核查代码而不是凭空回顾。我习惯在工作手册里加一个固定格式的“交付摘要模板”要求AI完成改动后按这个模板输出本次改动涉及的文件列表每个文件的关键改动点和原因是否新增/修改了测试已执行过的检验指令和结果是否有需要人工确认的遗留问题。这个模板一开始会觉得多余但执行几轮之后你会发现它其实是在替评审者分担工作量。AI把改动说清楚人只需要检查它说的和实际改的是否一致Vibe Coding的整体循环就快多了。验收标准和自检清单的价值就是让AI从“生成代码的机器”变成“会对自己负责的协作伙伴”。3. 怎么写才不踩坑语言、结构和维护3.1 用约束性语言别用鼓励性语言我见过不少工作手册初稿写出来的感觉像小学班主任评语请保持代码整洁尽量提高性能注意代码可读性合理安排目录结构。这些话没有错但拿到AI那里基本等于没说。原因是它们描述的是“抽象美德”没有给出可操作的判断条件。AI不具务“这个项目里什么叫整洁”的常识它只能从字面上理解“整洁”然后按自己训练数据里的普遍规律执行结果往往和团队预期相去甚远。约束性语言的特点是具体到“动作范围条件”。比如不要把“请保持代码整洁”写成“当修改一个函数时只改动函数体内部的逻辑不得调整缩进、引号、换行、注释位置”不要把“尽量提高性能”写成“如果算法复杂度超过O(n²)必须先拆分数据集或用哈希表并在提交说明里注明前后复杂度对比”不要把“注意可读性”写成“超过3个参数时用对象参数替代变量名长度低于3个字符时改为完整单词”。这类写法最大的好处是让“规则”变得可检测——AI能明确判断自己是否违反了某条规则人也能在评审时对照规则快速验证。就算AI偶尔还是做错你也能从规则本身找到具体哪一步缺了条件而不是含糊地归因于“AI能力不行”。3.2 用“当A时必须B”的条件句替代形容词我在写工作手册时的另外一个偏好是把规则全部改写成“条件句”。条件句的形式是“当{某种情况出现}时必须{执行某个动作}”或“当{某种情况出现}时禁止{某个动作}”。这种结构非常符合AI处理指令的模式因为它给出的是“如果…就…”的映射关系而不是需要推理的模糊要求。举一些实际例子当新增的函数超过40行时必须先拆分成多个小函数再提交代码当需要修改tsconfig.json或package.json时必须先暂停把改动内容列出来等用户确认当修改某个接口返回结构时必须同时更新类型定义和调用方当遇到一个已有函数可以复用时禁止新建重复函数必须复用旧函数。条件句之所以有效是因为它把AI的“自由决策空间”压缩到了最小。AI不需要反复猜测“用户这句话到底想让我怎么办”只需要检查当前情境是否匹配“当”字后面的条件。匹配就执行不匹配就跳过。这有点像给AI装上一组规则引擎每条规则都是独立的、可解释的。工作手册测下来条件句的遵循率远高于形容词堆砌的句子。当然条件句不适合覆盖所有场景。有些规则确实难以完全枚举这时候我通常的做法是在手册里加一句“未覆盖情况下的兜底原则”比如“如果拿不准是否应该修改某个文件不要修改在交付摘要里提出疑问”。兜底原则不算条件句但它给了AI在规则盲区里的行动指南反过来降低了乱试的风险。3.3 分层设计从全局手册到任务卡片刚开始写工作手册时我犯过一个典型错误把所有规则塞进一个超长文件里。结果AI在读取短任务时被迫“吞下”几千行规则不仅消耗上下文空间而且后面的规则经常被忽略。后来我改成分层设计效果明显改善。分层结构大致是这样项目根目录放一份AI_WORKBOOK.md作为入口和最高优先级规则它只写核心身份、红线、默认工作流控制在100行以内。其次如果有复杂的模块比如“数据访问层规范”“前端组件规范”把这些内容拆到docs/ai/下的独立文件里由入口文件按需引用。最后每次具体会话里可以再附一张“任务卡片”它只包含本次需求的目标、约束、交付格式。这个设计背后的考量是AI的注意力是分层消耗的。入口文件离对话最近被执行的优先级最高深层文件只有在任务涉及对应模块时才会被读取但一旦被读取它的上下文成本就值了。任务卡片则负责承载“临时规则”比如“这次只做接口联调不碰样式”它不污染全局手册也不会在任务结束后残留。从实际维护角度看分层还有一个好处不同模块规则变更的频率不同。技术栈约束可能一年不变模块命名规范可能随重构而变。如果全部堆在一个文件里每次小修改都要读一遍全量内容拆开后可以只更新相关的子文件降低维护噪音。3.4 版本化维护手册也是代码需要评审和迭代工作手册写完后不是放进仓库就结束了。它的真正生命周期从你第一次使用它才开始。几乎每一次AI“翻车”都是手册改进的契机。所以我建议把工作手册当作代码一样管理提交历史、版本号、评审记录都保留下来。具体做法是让手册文件跟随项目仓库一起走每次基于实际使用效果修订后提交一个清晰的commit信息比如“AI工作手册v1.2增加禁止修改lockfile红线”。同时可以打开一个“手册修订记录”区域简单记下每版改了什么、为什么改、由谁提出。这在个人项目里不是必须的但一旦进入团队协作它就是非常关键的上下文。迭代的节奏不需要太快。我的习惯是每两周抽15分钟过一遍过去两周所有由AI辅助完成的改动找出那些“评审阶段被发现、且根因是手册缺失或表述不清”的问题然后逐条修订手册。如果某条规则写了一个月都未被触发我会考虑删除它或把它移到低优先级的子文件里避免手册越来越臃肿。这里有一个很现实的认知工作手册不是一次写好的文档而是随着你和AI的协作方式不断磨合出来的活契约。第一次写出来的版本大概率只能解决60%的问题但每迭代一次剩下的20%、10%就在被逐步清除。最忌讳的是手册写完就封存AI犯完错也不回去补规则。没有迭代的手册很快会从向导变成废纸。4. 实操全过程给“某模拟项目X”写第一版工作手册4.1 项目背景与问题清单为了把这篇文章写得可以落地方案我拿一个虚构的“某模拟项目X”来演示完整编写过程。项目背景如下一个内部数据分析面板技术栈是React 18 Vite TypeScript后端是Express SQLite包管理器是pnpm测试用的是Vitest团队共三人维护代码仓库里有不少历史遗留的旧风格代码大部分模块没有完整测试覆盖率。这个项目在引入AI辅助编程后效率确实提高了但随之而来的是几个稳定的“摩擦点”。某开发者专门记录了连续两周的数据把AI辅助改动造成的返工分成三类第一类是改动范围失控AI顺手格式化了大量无关文件第二类是测试缺失AI经常直接提交没有配套测试的新功能第三类是命名不一致AI自创了简写风格的变量名和项目现有的完整命名习惯冲突。这些问题的共性是“AI没有一份可查阅的项目规则”。于是我们决定写一份工作手册。整个编写过程分三步梳理问题、起草条目、投入运行。接下来按步骤展开。4.2 第一步把“最近被AI坑过的5件事”整理成规则写第一版工作手册时最忌讳的是凭空罗列“通用最佳实践”。更可靠的方法是从真实问题反推规则。我让某开发者翻出过去两周的AI辅助改动记录挑出5件最典型的事故然后逐条转化为手册条目。这5件事和对应规则大概是这样事故1AI优化一个函数把整个文件从双引号改成单引号diff爆炸。规则修改单个函数时只改动函数体内部逻辑不得调整缩进、引号、换行、注释等与任务无关的格式。事故2AI为了使用某个工具库直接安装了新依赖但没通知任何人导致锁文件大范围变化。规则新增第三方依赖前必须先列出包名、版本、用途等待确认后再安装。事故3AI把新增的路由直接写在主入口文件中而项目实际约定路由必须放在src/router/routes.ts中的统一配置里。规则所有路由定义必须添加到已有路由文件不得在入口文件或组件内新建路由。事故4AI写完新功能后直接结束会话没有运行任何测试。规则每项任务完成后必须运行Vitest中与改动相关的测试用例并在自检清单中输出执行结果。事故5AI给一个已有函数起了新名字但调用方仍引用旧名字导致运行时错误。规则重命名函数前必须搜索所有调用处并同步更新如果调用方过多先列出改动清单再动手。从事故反推规则的优点很直接每一条规则都找到了它存在的理由你写进手册的内容不会显得空泛。后续你在复现问题时也可以从具体的“事故记录”出发解释为什么需要某条规则而不是说“这是团队规范”。4.3 第二步手册V1.0的正文与逐条解释基于问题清单我们写出了一个简化版手册V1.0。下面给出手册的核心内容并在每条后附一句设计意图方便你理解为什么这么写# AI 工作手册 - 某模拟项目X 在开始任何任务前请先阅读本手册。本手册中的规则优先于一般口头指令除非用户明确说明覆盖某项规则。 ## 项目角色与技术栈 - 你是一名熟悉前后端全栈的AI开发助手负责本项目功能开发、缺陷修复和测试补充。 - 前端React 18 Vite TypeScript后端Express SQLite包管理器pnpm测试Vitest。 - 项目目录src/main入口、src/pages页面、src/components组件、src/services接口服务、src/utils工具函数。 ## 编码规范 - 变量和函数命名必须以完整单词为主禁止使用 a、b、tmp、data 这类无意义短名。 - 单个函数不超过40行超过时必须拆分并在交付摘要中说明拆分思路。 - 所有新页面必须放到src/pages目录新路由统一在src/router/routes.ts中注册。 - 禁止修改与任务无关的格式。只改动任务范围内的代码行不调整引号、缩进、换行。 ## 工作流程 1. 先搜索项目中与任务相关的文件和调用关系确认改动影响面。 2. 在正式生成代码前先输出一个简短改动计划包含涉及文件、改动点、风险点。 3. 完成实现后运行与本次改动相关的所有Vitest测试。 4. 不允许直接提交未运行测试的代码。 ## 红线 - 新增依赖必须先说明用途再安装等待确认。 - 不修改pnpm-lock.yaml除非确认要升级依赖。 - 不删除或移动测试数据、数据库初始化和配置文件。 - 不执行任何破坏性操作删除表、清空数据、批量替换等除非得到明确授权。 ## 交付摘要 完成任何任务后请按以下格式输出 - 涉及文件列表 - 每个文件的关键改动点与原因 - 是否新增测试测试结果 - 可能存在的风险和需要人工确认的地方。这个版本刻意控制在一页半以内因为我们的目标是让AI在启动时的读取成本尽量低。编码规范里没有收录各种边界情况只收录了从5个事故事件中提炼的硬约束。工作流部分使用了数字编号因为AI对有序步骤的理解通常比无序段落更强。红线部分每条都用了“不”“禁止”“等待确认”等强约束词。4.4 第三步运行两周观察指标变化手册V1.0投入运行后我们保持了与之前相同的观察方式连续记录了两周数据。为了让结果可对比这里用三个关键指标来描述前后的变化。第一个指标是任务平均返工次数。之前平均每个AI辅助任务要经过约4.2次迭代才能通过评审其中大部分返工原因集中在风格混乱和依赖无谓变更。引入手册后这个数字降到1.8次左右。最明显的改善是“改动范围失控”类问题几乎绝迹因为AI通过“只改任务范围内的行”这条规则自动收敛了操作边界。第二个指标是改动diff的行数。我们抽查了十个功能类似的任务对比修改前后diff的总行数。之前平均每次修改产生约310行diff其中不少是格式调整、引号替换造成的噪音手册生效后平均diff降到约80行主要来自真实逻辑改动。diff越小评审速度越快代码审查质量也明显提升。第三个指标是“未测试就提交”的次数。之前每周大概有7次AI改动没有配套测试评审判定需要打回。手册明确规定了“不运行测试不允许交付”之后两周内只出现了2次遗漏而且都发生在长对话后期AI可能忽略了更早的指令。针对这个问题我们后来把“必须运行测试”这条放到了手册最顶部以及对话的固定开场提示里遗漏率进一步下降。这些数据并不代表工作手册能解决所有问题但它确实说明了一个朴素规律给AI写清楚边界比事后补救省力得多。4.5 踩坑复盘版本1.0失败和调整虽然V1.0整体效果不错但运行中也暴露了三个比较典型的坑后来调整到了V1.1。第一个坑是手册太长尾部的规则容易被忽略。初期手册还包括一长串“适合本项目的代码风格补充说明”放在文件末尾。几轮测试后发现当对话任务较长时AI对下半部分规则的执行率明显下降。解决办法是把最重要三条规则——只改范围内的代码、新增依赖必须先确认、必须运行测试——移到文件最前面并且坚绝控制正文篇幅。第二个坑是手册规则和用户临时指令冲突时AI通常会选择满足用户当前最直接的请求。比如手册里说“新增依赖必须先确认”但在一次任务中用户随口说了句“用lodash处理一下数据”AI直接就把lodash写进了package.json。这是典型的“即时指令权重高于文档规则”问题。调整方案是在手册开头增加了一句“手册规则优先于一般口头指令除非明确说明覆盖某项规则”同时在对话开始时口头强调“按手册规则执行”。第三个坑是抽象词问题。V1.0某条规则写的是“尽量保持命名一致性”实际执行下来很差。AI不知道什么算一致还是按它自己的偏好命名。后来改成“当新建函数需要命名时先搜索项目内已有类似函数的名字采用相同前缀或相同动词搭配”并给出了具体正反例。改成条件句示例之后命名一致性检查通过率提升非常明显。这三处调整我认为对任何要从0开始写工作手册的人都很有参考价值。5. 常见问题与排查技巧实录5.1 手册写了AI根本不看怎么“逼”它看指南最容易遇到的问题手册躺在仓库里AI依然我行我素。这时候不要急着怪模型先检查“手册是否出现在了对话上下文中”。AI不会主动打开你项目根目录里的某个Markdown文件除非你在对话里明确要求或你的工具配置里做了文件读取。我自己常用的方法有几种。第一种在每次新对话的第一句固定写“请先阅读项目根目录下的AI工作手册然后根据手册要求处理我的请求。”这句话保证了手册入口文件至少一次进入上下文。第二种把核心规则浓缩成几条“系统提示/项目指令”放在工具的用户自定义规则区域这样每次对话开始时它都会被自动带进上下文。第三种对于支持自动扫描项目文件的AI工具可在配置中把AI_WORKBOOK.md列为启动读取文件。我实测下来的体验是放在对话第一轮的“请阅读手册”比手册深处写什么内容都更有效。一旦AI真的读了一遍它后续的行动会明显更守规矩。如果读完一遍还是频繁违规可以考虑把最重要的三条规则直接写进系统提示词手册只作为详细参考形成“精简规则详细手册”的组合。5.2 手册越长越可能没用到底多少条合适经常有人担心手册内容不够详细AI会不会漏掉细节但我的经验是工作手册的规则密度需要一个“平衡点”不是越多越好。AI对规则列表的处理能力并不是线性增长的当规则条数超过一定阈值后面的规则被遵守的概率就会明显下滑。我会给单文件版本设定一个上限正文不超过200行核心规则不超过20条。如果某类细节更丰富比如“前端编码规范”有30条以上不要硬塞应该拆成独立的子文件按需引用。入口手册只保留最高优先级、适用范围最广的规则。这个策略让AI能轻松消化入口又不放弃深层细节。另一个判断标准是“规则与任务的相关性”。如果一条规则在大部分普通任务中都不会被触发那它就不应该待在入口文件里。比如“生产数据库迁移策略”可能一年只涉及几次完全可以在任务涉及数据库迁移时单独补充而不需要让AI在写一个按钮组件的时候也背着这条规则。手册的价值在于降低决策负载不在于信息覆盖完整。5.3 工作手册和README、代码规范文档怎么分工项目里已经有README、架构文档、编码规范再写一份AI工作手册会不会重复我的看法是会有重叠但分工完全可以拉开。README面向人AI工作手册面向模型架构文档描述现状AI工作手册描述“在现状下你该怎么做”编码规范可能是长篇参考AI工作手册则是可执行的规则子集。实际操作中我不建议把项目现有文档全盘复制进工作手册。那只会让AI在无关信息里消耗上下文。正确姿势是在手册里写“引用关系”比如“关于路由注册的详细规则请阅读docs/architecture.md中的第3节”或者“组件命名遵循components目录下README的风格约定”。AI在真正需要处理路由问题时可以按引用去读取对应文档平时阅读入口手册时则不背上全部重量。还有一点值得注意不要让AI工作手册代替人的文档。手册的最终服务对象是模型可读性、上下文开销、规则匹配度才是优先考虑人要有疑问还是走正常项目文档流程。把两类文档彻底混在一起人和AI都会被干扰。5.4 个人使用和团队使用有什么不同如果你是个人在项目中使用Vibe Coding工作手册可以非常个性化甚至可以把“我讨厌YYYY-MM-DD之外的日期格式”这种偏好写进去。但一旦进入团队协作工作手册就要考虑共同维护和评审。团队环境下我建议把手册纳入代码评审范围任何修改都通过PR提交而不是某个人悄悄改。这样可以避免AI的行为随某个人对手册的私自修改而漂移。团队还要统一约定“AI交接说明”的格式比如要求AI每次改动后必须生成“AI_Change_Summary.md”或按固定格式输出交付摘要这样任何成员接手都能理解AI改了啥。另一个团队场景下的关键点是手册中的规则必须经过一段时间的验证才进入正式版本不能把主观偏好直接全量铺开。团队应该从“事故驱动”入手先收集两周内AI所有引发问题的改动再提炼规则。这比一开始就开会讨论几十条理想规范要高效得多也更不容易被抵制。5.5 后续还能怎么升级手册和自动化卡口联动工作手册做到后期可以跟自动化检查结合起来形成“软约束硬卡口”的双保险。手册约束AI的行为自动化工具约束代码入库的底线两者是递进关系。比如对于手册里的编码规范条目如果项目本身有ESLint和Prettier配置可以让AI工作手册直接写明“所有改动必须能通过npm run lint且不得产生新的lint错误”。这样AI在交付前可以自行跑一遍检查。接着在CI流程里加入lint验证和测试覆盖率卡口如果AI漏了机器也会拦住。依赖审计也可以通过脚本检查pnpm-lock.yaml是否在非预期时被修改一旦发现就阻止合并。我个人的体会是把手册规则逐步映射到自动化工具里是“给AI写工作手册”这个玩法最有价值的进阶方向。手册负责高层次的决策和判断机器负责低层次的强制校验。两者各自弥补对方的短板AI对规则的遵循会波动但机器不会机器对复杂语义的理解不足但手册可以让AI提前避免掉很多低级问题。最终人只需要关注设计层面和业务层面的事情而不是天天给AI善后。最后再分享一个小技巧把你第一次事故反推出来的规则连同当时的diff快照一起留在手册的附录里。后续某天你觉得某条规则太啰嗦、想删掉它的时候翻一下那个快照就知道当初为什么要写它。手册维护这种事靠记性是靠不住的靠记录才靠得住。