2.4 规则文件与复用模板——把 AI 变成长期搭档的基础设施模块二：AI 协作方法论

模块二：AI 协作方法论 | 第04讲：规则文件与复用模板——把 AI 变成长期搭档的基础设施

项目：VibeNote 智能笔记 · 技术栈：Next.js / React / TypeScript / Tailwind
核心观点：规范是新的源代码——规则文件不是文档装饰，而是稳定产出的前置条件。
本讲与第03讲的关系：上下文解决「带什么材料」；规则文件解决「默认相信什么」。

一、开场：为什么「每次临场发挥」一定输

如果你读过 reference/articles/03-toolchain-frameworks.md，会记住一条很硬的判断：很多协作问题表面像工具问题，根子上是规格不清、目标不明、验收标准缺失。Addy Osmani 在「如何为 AI 智能体编写好的规范」那篇里进一步把话说透：智能体成功率的核心变量，往往是规范质量，而不是模型参数。

再结合核心概念文章列表里「规范是新的源代码」：当实现可以被 AI 规模化承担时，人类的主要产出会从逐行代码迁移到可执行规格。规则文件（AGENTS.md、.cursorrules、CLAUDE.md 等）就是把规格被动挂载到每一次协作里的工程机制。

本讲要做三件事：讲清这些文件各自适合放什么；给你一套可复制的模板；说明它们如何与 VibeNote 的目录和分形文档（第03讲）咬合。

我想再强调一个现实：你会在第三周开始感受到规则文件的复利。第一周你觉得「写规则好麻烦」，第二周你发现少吵一半架，第三周你会把新同学 onboarding 时间从几天压到几小时——不是因为他们更聪明，而是默认值对了。规则文件本质上是在给团队与 AI 同时提供默认值：默认值越准，越不需要长篇 Prompt。

另一个常被低估的点：规则文件是可 diff 的协作界面。你可以在 PR 里讨论「这条红线是否过严」，就像讨论代码一样严肃。相反，散落在聊天软件里的「团队约定」几乎不可治理，最后变成「老员工懂、新人猜、AI 乱」。

flowchart LR
  R[规则文件 被动上下文] --> A[每轮协作默认加载]
  T[复用模板 工单库] --> U[当次 User Prompt]
  A --> O[稳定输出]
  U --> O

flowchart TD
  P[项目原则] --> G[AGENTS.md / 规则]
  G --> M[模块 README]
  M --> F[源码文件头注释]
  F --> P

二、AGENTS.md、.cursorrules、CLAUDE.md：分别是什么、谁来读

名称会随工具演进变化，但角色分工稳定：

AGENTS.md（或 AGENTS.md 生态）

偏「给代理/助手看的项目说明书」：栈、目录、命令、测试方式、禁止事项、提交流程。优点是可读性高、可版本管理、可 Code Review。

.cursorrules / Cursor Rules

Cursor 的规则体系会把约束注入对话。适合放高频硬约束：代码风格、必须使用的库、不要改的路径。注意别写成小说，短而硬更有效。

CLAUDE.md

在 Claude Code 等工作流里常见，作用类似「项目启动卡」。如果你团队混用多种工具，可以维护一份源文件再同步到各工具（避免三份互相漂移）。

关键原则：只维护一份「真相源」，其他位置做链接或自动生成（哪怕手动复制也要有 checklist）。

三、规则文件里应该放什么：七类信息

技术栈与版本：Next.js App Router、TS 严格模式、包管理器。
目录地图：app/、components/、lib/ 各自边界。
运行命令：pnpm dev、pnpm lint、pnpm test。
安全红线：密钥、PII、内网地址、依赖安装来源。
编码规范：import 顺序、错误处理、日志、i18n 文案规则。
测试要求：哪些改动必须补测试、最小验收命令。
协作流程：方案先行、三连跪停手、合并前文档同步（承接第02/03讲）。

四、好规范长什么样：对照 Addy Osmani 的「智能体规格」思路

工具链文章总结的好规范特征，翻译成中文实战就是：

可执行：不是「要注意性能」，而是「列表页首屏禁止同步请求 N+1」。
可验证：不是「用户体验要好」，而是「空态/错态/加载态必须可截图验收」。
有边界：写清楚「不做什么」比写「做什么」更能防止模型发挥。
有上下文：给出与决策相关的最短证据（文件、类型、接口），而不是全文粘贴。

五、反模式：规则文件写成百科全书

规则太长会带来两类问题：

注意力稀释：模型「看了但好像没看」，关键约束被淹没。
维护失败：团队不敢改，最后规则与代码双轨漂移。

建议：硬规则短，长解释放 docs/，规则里只保留链接与要点。

六、模板库：四种高复用工单模板

模板 1：新功能

背景 / 用户故事
非目标
验收标准（可勾选）
影响文件猜测（可先空）

模板 2：Bug

复现步骤
期望 vs 实际
根因假设（可空）
相关日志（裁剪后）

模板 3：重构

行为不变声明
分步计划
每步验证命令

模板 4：依赖升级

动机
破坏性变更检查清单
回滚策略

模板建议放 docs/templates/，并在 AGENTS.md 里指一路径。

补一句落地建议：模板字段不要贪多，宁可少而必填。字段太多，大家会跳过；跳过之后，模板就死了。你可以从四个字段开始跑两周，看哪些字段每次空白，再决定删或改。

【附】把模板接进 Cursor：「自定义指令」的一句话

你可以在规则里写：「新功能必须使用 docs/templates/feature.md 的结构回答」。这会把「记得用模板」从人的记忆，变成每次对话的默认行为。记住：模板不是形式主义，是降低沟通熵的工具。

七、AI 记忆通过文档：别指望对话「永远记得」

参考方法论提醒我们：模型没有人类意义上的持久记忆。记忆要外置：决策放 ADR，接口放 OpenAPI/类型，踩坑放 docs/incidents/。规则文件是「每次对话都记得的那层记忆」，文档库是「需要时检索的那层记忆」。

你也可以把规则文件理解成对话的 bootloader：开机先加载内核参数，业务线程才能稳定跑。没有 bootloader，每次都要手工输入参数，人类会烦，模型也会漂。别嫌比喻土，土东西往往好用。真的，去写吧，从三条红线开始，写完就能用，别等完美版本，迭代会帮你完善，先起步，别拖了，动手吧。

八、可运行示例：从 YAML Frontmatter 生成工单 Markdown

下面脚本演示「模板即代码」——你可以改成从 docs/templates/*.yaml 读取。

// scripts/render-ticket.ts
// 运行: npx tsx scripts/render-ticket.ts

type Ticket = {
  title: string;
  type: "feature" | "bug" | "refactor";
  background: string;
  nonGoals: string[];
  acceptance: string[];
};

const t: Ticket = {
  title: "VibeNote：Markdown 分栏预览",
  type: "feature",
  background: "用户在编辑长文时需要实时预览渲染效果，降低写作心智负担。",
  nonGoals: ["本期不做协同编辑", "不做所见即所得富文本"],
  acceptance: [
    "左右分栏：左侧编辑、右侧预览",
    "预览与编辑内容实时同步",
    "大文本输入不阻塞主线程（使用防抖）",
  ],
};

function render(x: Ticket): string {
  const lines: string[] = [];
  lines.push(`# ${x.title}`);
  lines.push(`类型：${x.type}`);
  lines.push("\n## 背景\n");
  lines.push(x.background);
  lines.push("\n## 非目标\n");
  x.nonGoals.forEach((g) => lines.push(`- ${g}`));
  lines.push("\n## 验收标准\n");
  x.acceptance.forEach((g) => lines.push(`- [ ] ${g}`));
  lines.push("\n## 给 AI 的约束（复制到对话）\n");
  lines.push("- 先输出方案与文件清单，等我确认后再改代码。");
  lines.push("- 不引入新的 Markdown 编辑器依赖（保持 textarea）。");
  lines.push("- 变更后给出 `pnpm lint` 与 `pnpm build` 验证步骤。");
  return lines.join("\n");
}

console.log(render(t));

九、示例：`AGENTS.md` 草案（VibeNote 可直接改）

# VibeNote — Agent 协作说明

## 技术栈
- Next.js (App Router) + React + TypeScript（strict）+ Tailwind

## 命令
- dev: `pnpm dev`
- lint: `pnpm lint`
- build: `pnpm build`

## 目录
- `app/` 路由与页面
- `components/` 可复用 UI
- `lib/` 纯函数、数据访问、AI 封装

## 安全
- 任何 API Key 只能出现在服务端（Route Handler / Server Action）
- 不在客户端打印敏感数据

## 流程
- 超过单文件的改动：先方案后代码
- 同一问题三次修复失败：停止盲试，先定位根因

## 文档
- 变更目录结构时同步更新对应 `README.md`

十、示例：`.cursorrules` 片段（保持极短）

你是 VibeNote 项目的实现助手。优先使用现有模式，不要无故引入新架构。
未经确认不要修改 prisma schema 与 migrations。
所有 AI 调用必须经服务端封装；客户端不得出现密钥。
输出代码前列出将修改的文件路径。

十一、与课程原稿的关系

课程内容/2.4 把AI变成长期搭档：规则文件与复用模板怎么建.md 原稿较泛；本讲对齐工具链文章与 Osmani「好规范」线索，给出可粘贴的样例与生成器。

十二、规则与 PR Review 的接口

建议在 Review 清单加两项：

是否违反 AGENTS.md 红线？
是否同步文档/模板所需条目？

这会把「规范」从文本变成门闸。

十三、VibeNote 推荐：`docs/templates/README.md`

列出模板索引+使用说明+示例链接，让新同学 10 分钟上手。

十四、规则分层：全局 / 包级 / 目录级

大型仓库可以分层维护规则，避免「一份 AGENTS 管全世界」：

全局：安全、Git 流程、通用命令。
包级（monorepo）：例如 apps/web/AGENTS.md 专管 Next。
目录级：components/editor/README.md 写交互约束。

Cursor 支持 nested rules 的能力随版本变化，但文档分层永远有价值：人先找得着，AI 才带得对。

十五、与 Skills 的关系：什么时候不放进规则

工具链文章提醒：Skills 若触发不稳定，会带来「以为带了其实没带」的风险。务实建议：

每次都必须遵守的：放规则文件。
偶尔使用、且很专业的：放 Skill（并写清楚触发词与边界）。
一次性的：当次 Prompt。

不要迷信「Skill 越多越好」，Vercel 工程博客里「删掉 80% 工具」本质也在说：选项太多会降低稳定性。

十六、规范评审：每月 15 分钟的「规则 lint」

设一个循环会议，只做四件事：

最近一周对话里重复纠正最多的是什么？
规则文件是否与实际冲突？
是否有规则过长需要下沉到 docs/？
是否有新红线（安全/合规）必须加急写入？

十七、给 VibeNote 的「提示词片段库」目录建议

docs/snippets/ 下可放：

api-route.md：创建 Route Handler 的 RCTFC 模板
server-action.md：Server Action 校验与错误映射模板
ui-state.md：加载/错误/空态三件套提示片段

规则文件只指向目录，不复制全文，避免双维护。

十八、把「代码所有权」写进规则

Agentic Engineering 强调代码所有权仍在人。规则里建议明确：

谁对 lib/ai/* 变更负责（可以是轮值）
AI 生成代码默认需要人 Review（除非白名单目录）

这不是官僚，是风险分配。

十九、对比表：规则 vs 文档 vs 注释

载体	适合内容	更新频率	AI 可见性
规则文件	硬约束、短	中	高（被动）
docs/	解释、流程图	低到中	中（需 @）
注释	局部陷阱	高	中（需 @file）

二十、可运行示例 2：检查 AGENTS.md 是否过长的脚本

// scripts/agents-size.mjs
import fs from "node:fs";
const p = "AGENTS.md";
if (!fs.existsSync(p)) {
  console.log("no AGENTS.md");
  process.exit(0);
}
const n = fs.readFileSync(p, "utf8").split(/\r?\n/).length;
console.log({ file: p, lines: n, ok: n <= 120 });

建议把 lines <= 120 当作软上限；超过就拆分。

二十一、规则文件的版本策略

规则变更要走 PR，理由与代码同等：规则错了会把所有后续生成带偏。可以在 PR 模板问：「是否更新 AGENTS.md / 规则？」

二十二、与分形文档的合流

第03讲的分形结构解决「地图」；规则文件解决「默认值」。两者叠加效果：模型既知道往哪走，也知道怎么走。

二十三、坏规则示例：形容词堆叠

代码要优雅、可维护、具备扩展性。

这类话对模型几乎不可执行。改成：

新增模块不得超过 3 个文件；不得引入新状态管理库；必须包含错误边界与空态。

二十四、好规则示例：可验证语句

所有 Route Handler 必须使用 zod 校验 body；错误返回 { error: { code, message } }；HTTP 状态码与 code 映射表见 docs/api-errors.md。

二十五、FAQ

Q：规则会不会限制模型发挥？
A：会限制「乱发挥」，这正是目的。你要的是可控创造。

Q：规则要不要中英文双语？
A：团队统一即可；关键是一致，不要混用导致歧义。

Q：开源项目规则怎么写？
A：对贡献者友好：命令、目录、PR 要求写清楚；内部红线单独放 CONTRIBUTING.md。

Q：规则多久更新一次？
A：建议跟迭代走：出现第三次重复纠正，就评估是否入库；每月再做一次总复盘。

Q：要不要给规则写版本号？
A：可选。更简单的做法是：规则变更必须 PR，用 Git history 当版本。

二十六、从「个人规则」到「团队规则」：合并冲突怎么处理

多人协作时，最常见冲突是：A 同学把规则改成「必须用 X」，B 同学改成「必须用 Y」。建议在 docs/adr/ 留一条决策记录：为什么选 X，弃用 Y 的条件是什么。规则文件只写结论，ADR 写论据。这样 AI 不会读到冗长争论，但人类能追溯。

二十七、VibeNote 专项：AI 功能相关的规则该怎么写

至少覆盖：

数据出境与日志：哪些字段禁止进日志。
提示词注入：用户笔记内容视为不可信输入；服务端 prompt 必须分层（系统/用户材料分离）。
输出展示：AI 生成内容必须标注免责声明（产品文案规则）。
降级：模型失败时的 UX（可编辑、可重试、可关闭）。

这些不是「合规部门的洁癖」，是你上线后少挨骂的基本盘。

二十八、把「测试要求」写成机器可读

除了 human-readable 规则，你可以在 package.json scripts 里固定 pnpm check 组合，并在规则文件写：合并前必须跑 pnpm check。当命令单一且明确，模型也更不容易漏。

二十九、规则与脚手架：create-next-app 之后第一件事

新建项目后我建议第一件事不是写功能，而是：

放 AGENTS.md
配最小 .cursorrules
建 docs/templates/

你会感觉慢半天，但接下来每一周都会快。

三十、再谈「规范是新的源代码」：对职业路径的含义

当规范驱动实现，高级工程师的产出会更像「平台 + 规范 + 审查」。这不是降级，是杠杆上移：你写的是「让团队与 AI 同时变强」的东西。对想在 AI 时代继续走技术路线的人，这是值得押注的方向。

三十一、团队练习：规则接龙

每人提交一条「最想禁止模型做的事」，再合并去重，挑前 10 条进规则。你会惊讶：共识往往比想象更一致，只是以前没写下来。

三十二、长文规则的拆分技巧：「总则 + 附录」

总则保留在规则文件（硬、短）。附录放 docs/policies/（长、可搜索）。模型需要长文时你再 @，平时不占用被动上下文。

三十三、与 PR 模板结合的示例字段

## AI 协作记录（可选）
- [ ] 是否先输出方案并获得确认？
- [ ] 是否列出修改文件清单？
- [ ] 是否运行 `pnpm lint` / `pnpm build`？
- [ ] 是否更新相关文档/目录 README？

三十四、反模式：复制网上「超全 Cursor 规则」

网上模板未必匹配你的栈与约束，容易引入：

不适用的目录约定
过时依赖建议
与团队真实流程冲突的命令

正确姿势：从空规则开始，只加你确实重复纠正过三次以上的条目。

三十五、规则如何在团队里「落地」：一张协作时序图

sequenceDiagram
  participant Dev as 开发者
  participant Repo as 仓库规则
  participant AI as AI
  participant Review as 审查者
  Dev->>Repo: 更新 AGENTS.md / 模板
  Dev->>AI: 携带规则(被动) + 工单(主动)
  AI-->>Dev: 方案/代码
  Dev->>Review: PR + 文档同步勾选
  Review-->>Dev: 批准/修改
  Dev->>Repo: 合并后持续迭代规则

三十六、把「验收标准」嵌进模板：Feature 示例（可复制）

验收标准（必须可勾选）

首屏无阻塞请求（或明确 loading）
空态/错态/加载态齐全
键盘可操作主路径（或可解释为何不）
不引入未解释依赖
pnpm lint 与 pnpm build 通过

给 AI 的硬约束

先方案后代码；方案包含文件清单与风险。
不得修改与需求无关目录。
AI 相关密钥仅服务端。

三十七、再补一段：为什么「链接官方文档」比「复制官方文档」更好

规则文件里引用 Next.js / AI SDK 文档链接，而不是复制大段英文，是为了：减少 token、减少过期。模型若需要细节，让它用检索工具或你手动 @Docs；规则层只保留「必须遵守的项目内决策」。

三十八、规则如何帮助「减少工具切换」

很多团队同时用 ChatGPT、Cursor、CLI Agent。规则文件的价值在于：把共同部分抽到仓库，工具差异只留在「触发方式」。否则你会在三个地方维护三套略有冲突的提示词，最后谁也说不清哪个是真相。

三十九、给「设计/产品」同学的接口：PRD → 规范 → 实现

当规范成为源头，产品文档也要升级：PRD 里尽量写可验证行为，而不是形容词。你可以要求产品同事在 PRD 末尾附「验收勾选」，开发再把勾选映射到测试用例。AI 只是加速器，需求清晰度仍是上限（第03讲 PRD 文章也会呼应）。

四十、再谈模板：Bugfix 工单完整示例（VibeNote）

标题：笔记保存偶发 500
复现：在慢网络下连续点击保存 5 次
期望：幂等或排队；不应堆叠错误状态
实际：第二次请求失败后 UI 仍显示已保存
日志：route.ts 返回 ECONNRESET（贴首尾）
根因假设：客户端未处理并发保存（可空）
约束：不改数据库 schema；优先最小修复

这类模板的价值是：把调试对话从「猜谜」变成「填表」。

四十一、再谈模板：Refactor 工单完整示例

行为不变声明：对外 API JSON 形状不变；笔记列表排序规则不变。
动机：lib/notes.ts 同时被 server/client 引用导致 bundle 异常。
分步：① 拆分 shared/server ② 调整 import ③ build 验证 ④ 手工点验创建/编辑。
回滚：单 PR，可 git revert。

四十二、规则文件与「合规」：你可以写进去的最低限度

即便你是个人项目，也建议写：

不在日志打印用户正文
AI 提示词不把密钥拼进用户可控字段
依赖安装来源（npm/pnpm 官方/registry）

公司项目再把法务条款链接附到 docs/compliance.md。

四十三、结尾寄语

规则文件是慢变量：第一天像累赘，第 30 天像空气。你愿意为它付一点维护成本，它就会把团队与 AI 的输出方差一起压下去。

如果你现在只想做一件最小行动：打开 AGENTS.md，写下你们项目的三条安全红线与三条目录边界。写完你就已经超过大多数「只会写提示词」的团队了。

四十四、本讲小结

规则文件是被动上下文的核心载体，解决「每次重复讲」的问题。
AGENTS / Cursor Rules / CLAUDE 分工不同，但应维护单一真相源。
好规范要可执行、可验证、有边界；形容词无效。
模板库把工单字段化，和 Workflow（第02讲）天然咬合。
规则也要 Review 与长度控制，否则从资产变负债。

把小结再翻译成行动：今天先在仓库加一份 80 行的 AGENTS.md，别追求完美，追求可用。

四十五、思考题

你现在最常在对话里重复的三句话是什么？能否下沉到规则文件？
你的规则「真相源」准备放哪？如何避免多份漂移？
你会给规范加哪些「可验证」标准，而不是形容词？

附加题：把你们团队最近一条「口头约定」改写成可验证规则，并评估它是否应进入 AGENTS.md。

再想一想：如果没有规则文件，你的团队靠什么对齐默认值？靠记忆吗？靠群公告吗？它们分别会在第几天开始失效？

四十六、下讲预告

下一讲进入AI 协作调试法：三连跪停手、结构化报错、复现—隔离—诊断—修复—验证，以及何时重置上下文。我们会把参考方法论里「无效调试循环」讲成你能照做的剧本。建议你提前准备一段真实报错（脱敏后），下讲直接拿来练「结构化粘贴」。

参考阅读：reference/articles/03-toolchain-frameworks.md（AGENTS.md vs Skills、好规范）；reference/articles/01-core-concepts.md（规范与 Agentic Engineering）；课程内容/2.4 把AI变成长期搭档：规则文件与复用模板怎么建.md。

最后一句话：把规则写进仓库，比把希望写进模型名字里可靠得多。

再补一句：规则不是锁死创新，而是锁死低级错误；创新应该发生在产品与技术决策层，而不是发生在「密钥怎么又进客户端了」这种层。

再补一句更实在的：好规则会让你少写 Prompt，因为它把默认约束变成了空气；空气看不见，但你会呼吸得更稳。

2.4 规则文件与复用模板——把 AI 变成长期搭档的基础设施