企业官网建设流程全解析

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最容易犯、且影响最大”的十条以内写进去。常见的有：

• 变量和函数命名必须使用项目既有风格，不能自造缩写；
• 单个函数控制在20～40行以内，超过就必须拆分；
• 禁止在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件事和对应规则大概是这样：

• 事故1：AI优化一个函数，把整个文件从双引号改成单引号，diff爆炸。规则：修改单个函数时，只改动函数体内部逻辑，不得调整缩进、引号、换行、注释等与任务无关的格式。
• 事故2：AI为了使用某个工具库，直接安装了新依赖，但没通知任何人，导致锁文件大范围变化。规则：新增第三方依赖前，必须先列出包名、版本、用途，等待确认后再安装。
• 事故3：AI把新增的路由直接写在主入口文件中，而项目实际约定路由必须放在src/router/routes.ts中的统一配置里。规则：所有路由定义必须添加到已有路由文件，不得在入口文件或组件内新建路由。
• 事故4：AI写完新功能后直接结束会话，没有运行任何测试。规则：每项任务完成后，必须运行Vitest中与改动相关的测试用例，并在自检清单中输出执行结果。
• 事故5：AI给一个已有函数起了新名字，但调用方仍引用旧名字，导致运行时错误。规则：重命名函数前必须搜索所有调用处，并同步更新；如果调用方过多，先列出改动清单再动手。

从事故反推规则的优点很直接：每一条规则都找到了它存在的理由，你写进手册的内容不会显得空泛。后续你在复现问题时，也可以从具体的“事故记录”出发解释为什么需要某条规则，而不是说“这是团队规范”。

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快照一起留在手册的附录里。后续某天你觉得某条规则太啰嗦、想删掉它的时候，翻一下那个快照，就知道当初为什么要写它。手册维护这种事，靠记性是靠不住的，靠记录才靠得住。