1. 项目概述一份写给AI编程伙伴的“工作手册”如果你和我一样已经深度依赖像Cursor、Claude Code、Windsurf这类AI编程助手来提升日常开发效率那你一定也经历过那些让人哭笑不得的瞬间AI助手自作主张地重写了整个文件而不是只修改你指定的函数或者在你离开电脑喝杯咖啡的间隙它因为网络断开而丢失了所有上下文回来时一脸茫然地问你“我们刚才在做什么”又或者它总是急于表现还没完全理解需求就开始噼里啪啦地写代码结果南辕北辙。这些问题本质上不是AI能力不行而是我们和AI之间缺乏一套清晰、稳定的“协作协议”。就像你带一个新人加入项目总得告诉他代码规范在哪、构建命令是什么、遇到问题该找谁一样。awesome-agent-rules这个项目就是为AI编程助手们准备的“新人入职手册”和“团队协作指南”。它不是一个具体的代码库而是一个精心整理的规则、指令和最佳实践集合旨在解决我们在与AI结对编程时遇到的那些共通的痛点。这个项目收集了来自真实项目的、经过实战检验的模式覆盖了任务管理、会话交接、执行纪律、错误追踪、信任校准等核心协作场景。无论你用的是支持CLAUDE.md的Claude Code还是遵循.cursorrules的Cursor或是其他任何读取AGENTS.md标准的工具这里面的规则都能帮你把AI从一个“有时靠谱的临时工”转变为一个“纪律严明、可预测的资深搭档”。接下来我会带你深入拆解这些规则背后的设计哲学并分享如何将它们落地到你自己的项目中。2. 核心理念与设计哲学为什么我们需要给AI定规则在深入具体规则之前我们必须先理解一个核心问题为什么看似智能的AI助手需要我们人为地设定这么多条条框框这背后其实是AI的工作机制与人类工程师思维习惯的差异。2.1 AI的“思维”特性与人类协作的错位当前的AI编程助手本质上是基于大规模代码和文本训练的语言模型。它们擅长模式匹配、代码生成和根据上下文进行推理但也存在几个固有的特性“讨好型”人格与过度行动AI模型被训练成倾向于给出肯定、完整的答案并急于展示能力。这导致它在没有100%把握时也倾向于“先做了再说”而不是停下来确认。这就是“任务启动协议”要解决的根本问题——强制它在动手前先同步理解。无状态的会话与上下文丢失每次对话对AI来说都是一个崭新的开始尽管有上下文窗口但长度有限且不稳定。人类工程师可以靠记忆和笔记延续工作但AI一旦断开连接或超出上下文就会“失忆”。HANDOFF.md协议就是为了给AI创造一个持久化的、跨会话的“外部记忆”。缺乏真正的“项目感”AI不理解“技术债务”、“代码所有权”或“架构一致性”这些抽象概念。它看到的是一个文件集合和修改指令。因此它可能会为了完成一个局部优化而破坏整体的架构约定。“执行纪律”规则就是为了给它植入这些项目级的约束。理解了这些我们就能明白制定规则不是为了限制AI而是为了弥合人机思维模式的鸿沟建立一套双方都能理解和遵循的协作语言。这就像给一个能力超强但经验不足的实习生一份详细的SOP标准作业程序既能发挥其潜力又能避免他把实验室炸了。2.2 规则设计的核心原则清晰、可操作、抗脆弱从awesome-agent-rules中提炼出的优秀规则都遵循着几个核心设计原则原子性与可验证性每条规则都应该指向一个具体、可观察的行为。例如“编辑现有文件时使用针对性替换切勿覆盖整个文件”就比“小心修改代码”要清晰得多。前者可以直接被验证查看git diff后者则模糊不清。场景化与优先级规则不是一成不变的。对于不同的任务如修复一个拼写错误 vs. 重构一个核心模块人类投入的监督程度应该不同。“信任校准框架”正是为此而生它让我们可以根据任务的风险和复杂度动态调整管控级别而不是一味地“微管理”或“完全放权”。为失败而设计网络会断IDE会卡死会话会超时。优秀的规则体系必须预见到这些故障并内置恢复机制。“渐进式HANDOFF”规则就是典范——它要求AI在每一个里程碑如每次提交后都更新交接文档确保即使会话突然终止损失也仅限于最后一步操作。正向引导而非单纯禁止好的规则不仅说“不要做什么”更会说明“应该怎么做”以及“为什么”。例如在“工具选择规则”中它不仅禁止滥用浏览器更明确了“验证类任务用终端命令交互类任务才用浏览器”的正面指导原则。这套设计哲学使得awesome-agent-rules中的内容超越了简单的技巧合集上升为一种系统的“人机协作工程学”方法论。接下来我们就进入实战环节看看如何将这些理念转化为具体的、可落地的规则文件。3. 核心规则详解与实战配置知道为什么需要规则之后我们来逐一拆解那些最关键、最实用的规则类别并给出具体的配置示例和操作要点。我会以最通用的AGENTS.md文件格式为例因为它是正在兴起的跨工具标准。3.1 任务管理从“盲动”到“对齐”这是所有问题的起点。AI最常见的错误就是急于求成。规则核心任务启动协议在你的AGENTS.md文件顶部强烈建议加入以下内容## 任务启动协议 (Mandatory) 收到任何新任务指令后**禁止立即开始编码**。你必须首先执行以下评估并向我报告 1. **目标理解**用你自己的话复述任务目标。 2. **涉及文件**列出你认为需要查看或修改的所有文件路径。 3. **时间预估**估算完成所需时间30分钟 1-3小时 3小时。 4. **任务分级**根据上述预估给出任务规模建议S / M / L。 5. **不确定性**明确指出任务中任何模糊、缺失或你无法确定的部分。 **仅在获得我明确的“确认执行”指令后才能开始下一步操作。** ### 任务规模与处理流程映射 | 规模 | 判断标准 | 处理流程 | | :--- | :--- | :--- | | **S (小)** | 30分钟 影响1-2个文件 | 直接执行 → 运行测试 → 提交更改 → 更新HANDOFF | | **M (中)** | 1-3小时 影响3-5个文件 | 提供简要计划 → 等我确认 → 分步执行 → 提交 → 更新HANDOFF | | **L (大)** | 3小时 跨模块影响 | 进行头脑风暴 → 提供详细计划含备选方案→ 等我确认 → 采用TDD模式推进 → 阶段性回顾 → 更新HANDOFF |实操心得与注意事项强制等待确认规则中“等待确认”是关键。在实际使用中我会要求AI将评估结果以清晰的消息格式发给我我回复“Go ahead”或“Proceed”后它才能动。这个简单的停顿避免了至少50%的返工。规模判断是艺术帮助AI准确判断任务规模需要一些训练。初期你可以纠正它比如它把一项需要修改三个相互关联文件的任务误判为“S”你可以指出“这涉及多个组件的接口变更应判为M级需要先提供计划。”几次之后AI的判断会越来越准。不确定性清单鼓励AI主动暴露“不知道”非常重要。我会告诉它“列出不确定性不会显得你能力不足反而能提高效率。我们可以优先解决这些模糊点。”3.2 会话交接与持久化记忆告别“失忆”助手这是保证跨时间协作连贯性的基石。没有它每次对话都像重启一个新手。规则核心HANDOFF.md 协议在项目根目录创建一个HANDOFF.md文件并在AGENTS.md中引用以下规则## 会话交接协议 (HANDOFF.md) ### 会话开始时必须 1. **首先阅读** ./HANDOFF.md 文件了解上一次的工作进度和上下文。 2. 运行 git log --oneline -5确认最新的提交记录与HANDOFF中的描述一致。 3. 运行 git status检查是否存在未提交的更改。 4. 向我报告你的发现例如“已读取HANDOFF我们昨天完成了X功能当前没有未提交更改”**确认理解无误后再开始新工作**。 ### 会话结束或达到里程碑时必须 (强制性) 更新 ./HANDOFF.md 文件。格式如下 markdown ## [YYYY-MM-DD HH:MM] 会话记录 - **完成事项** - [ ] 修复了 utils/validator.js 中的边界条件检查逻辑。 - [ ] 为 api/user.js 添加了对应的单元测试。 - **遇到的问题/阻塞** - [ ] 无。如果遇到请具体说明 - **关键决策与原因** - [ ] 选择使用 lodash.get 而不是可选链操作符 ?.因为需要支持Node.js 12环境。 - **遇到的坑/教训** - [ ] 最初尝试直接修改原函数导致了一个隐蔽的副作用后改为先复制函数再修改的策略。 - **后续建议步骤** - [ ] 下一步可以重构 api/login.js 中的类似验证逻辑以保持一致性。保持简洁总字数控制在500个标记token以内。必须包含所有被否决的方案及其原因。**渐进式更新规则 (Progressive HANDOFF)** 为了防止网络断开或崩溃导致记忆丢失需要加入这条 markdown ## ⚡ 渐进式HANDOFF规则 **不要等到会话结束才更新HANDOFF** 在达到以下每个里程碑时立即追加更新 - 每次执行 git commit 后 → 将完成项添加到“完成事项”。 - 做出任何重要的技术决策后 → 将决策及原因添加到“关键决策”。 - 遇到任何错误或意外行为后 → 将教训添加到“遇到的坑”。 - 这样能确保即使会话意外终止我们最多只损失最后一步进度。为什么这套机制如此有效它创造了一个单向的、累积的、人类可读的记忆流。相比于依赖AI不稳定的内部上下文一个纯文本文件的可靠性是100%的。我个人的项目HANDOFF.md经常成为我自己的项目日志帮我快速回顾为什么某个决策是在周二下午做出的。3.3 执行纪律与错误追踪建立可靠的工作流即使目标对齐了记忆持久了执行过程本身也可能出问题。这部分规则定义了“如何正确地做事”。规则核心执行纪律## ⚙️ 执行纪律 1. **编辑勿覆盖**修改文件时始终使用精准的代码块替换显示旧代码和新代码**绝对禁止**直接输出整个文件的新内容来覆盖。 2. **严格遵循计划**仅执行经过确认的计划中的步骤。禁止即兴发挥或“顺手”做计划外修改“while Im at it”。 3. **先分析后执行**对于复杂操作先展示你的分析、推理和将要执行的命令/代码变更**等我确认后再实际执行**。 4. **言出必行**如果你说“我将创建文件X”那么紧接着的下一条消息就应该是创建文件X的操作或代码块。 5. **备份重要数据**在修改配置文件、数据库脚本或关键函数前建议或询问是否需要先备份。 6. **主动压缩上下文**在完成一个大型功能模块后主动询问“是否需要我总结当前变更以释放聊天上下文”错误追踪与分类建立一个正向的错误文化让AI不怕报错而是从错误中学习。## 错误追踪与分类 当你意识到自己犯了错误时例如执行了错误命令、提供了错误信息 1. **立即承认**第一时间明确说出“我犯了一个错误...”。 2. **协助记录**根据我的指示将错误记录到项目的“错误日志”例如 ERROR_BOOK.md中。 3. **避免重复**在本会话内**严禁**再犯同一类错误。 4. **存疑即问**如果你对某个操作不确定请先提问而不是猜测。 ### 错误分类标签用于错误日志 为每个错误打上标签便于分析 - hallucination幻觉 - 声称了不存在或错误的事实/代码。 - premature-action过早行动 - 在未完全理解或未获确认前执行。 - api-errorAPI误用 - 错误地使用了某个库、框架或工具的API。 - process-violation流程违反 - 跳过了必需的步骤如未读HANDOFF。 - scope-creep范围蔓延 - 做了未被请求的额外工作。在我的实践中维护一个简单的ERROR_BOOK.md非常有价值。它不仅记录了AI的失误更多时候是我自己指令不清的镜子。长期下来你能清晰看到协作模式在改善某些类型的错误出现频率会大幅下降。4. 高级策略多智能体协作与信任校准当项目复杂到需要多个AI助手例如同时使用Cursor和Claude Code或者你对AI的信任需要分级管理时以下高级规则就派上用场了。4.1 多智能体协调规则想象一下你让Claude Code设计了一个模块的接口然后又换到Cursor去实现它。没有协调它们会打架。## 多智能体协作协议 ### 当多个智能体在同一项目上工作时 - **统一记忆源**每个智能体在会话开始时**必须**读取 HANDOFF.md。这是唯一的事实来源。 - **统一记忆更新**每个智能体在会话结束时**必须**更新 HANDOFF.md。 - **冲突处理**如果发现与 HANDOFF.md 中记录的前期决策有冲突必须用 ⚠️ 冲突警告 标出并**停止相关操作**等待人类裁决。 - **尊重他人工作**严禁在未获得我明确批准的情况下覆盖或修改另一个智能体完成的工作。 ### 断线恢复协议 当我发出“断线了”、“继续之前的工作”、“我们刚才做到哪了”等指令时 1. 你的**第一个且唯一**的动作是阅读 HANDOFF.md。 2. 然后运行 git log --oneline -5 和 git status 来验证文件系统状态。 3. 最后向我报告恢复状态“根据HANDOFF我们刚刚完成了XY是待办项。Git状态显示...”。 4. **禁止**为了“寻找上下文”而去遍历无关文件。4.2 信任校准框架不是所有任务都需要你目不转睛地盯着。这个框架帮你科学“偷懒”。## 信任校准框架 我将根据任务的性质声明对你的信任级别。请根据不同的级别调整你的工作方式和汇报频率。 | 信任级别 | 适用场景 | 我的参与方式 | 你的应对方式 | | :--- | :--- | :--- | :--- | | **L1 - 验证结果** | 我理解流程但不关心细节只在乎最终结果正确。例如运行一个已知的代码格式化命令 | 我只在最后检查输出结果。 | 你可以自主执行所有步骤完成后一次性汇报结果和关键变更。 | | **L2 - 交叉验证** | 任务重要我需要双重保险。例如编写一个复杂的数据库迁移脚本 | 我会让另一个智能体或我自己复查你的代码。 | 你完成工作后准备好清晰的变更摘要和逻辑说明以便复查。 | | **L3 - 渐进信任** | 方案不确定需要小范围试验。例如尝试一种新的性能优化方法 | 我会要求你先在一个文件或一个模块上实践。 | 先提出完整方案但仅在我指定的安全范围内实施并汇报试验结果。 | | **L4 - 要求解释** | 我不理解你的方案或者任务风险极高。例如重构核心身份验证逻辑 | 我会深度介入要求你解释每一个决策。 | **先分析后执行**。对每个提议的步骤都必须提供理由和备选方案等待我逐步批准。 | **我会在任务开始时声明信任级别例如“[L3] 尝试优化这个函数的性能”。**这个框架彻底改变了我与AI的协作模式。对于简单的样式调整L1我可以放心让它去做而对于修改支付网关集成代码L4我会切换到“显微镜”模式。这极大地提升了整体效率。5. 工具选型、网络优化与模板使用5.1 工具选择与网络韧性规则这些规则帮助AI更智能地使用外部工具和处理不稳定的环境。## 工具选择规则 - **验证类任务**检查文件内容、Git状态、进程列表优先使用 **终端命令** (ls, cat, git status, ps)。非必要不使用浏览器。 - **交互类任务**登录网页、填写表单、点击按钮才使用 **浏览器** 工具。 - **浏览器超时**如果浏览器子代理无响应超过30秒自动中止并尝试改用命令行如curl或替代方案。 - **“看看这个”请求**如果我只是让你查看一个网页或文档请直接给我可访问的URL**不要**主动为我打开浏览器。 ## 网络与韧性规则 - **提交点**在执行任何预计耗时较长的操作如npm install 大型文件处理前**必须**先执行 git commit 保存当前进度。 - **包管理器超时**如果遇到 npm, pip, cargo 等安装超时请意识到可能是网络问题。可以建议配置国内镜像源如淘宝NPM镜像、清华PyPI镜像或检查代理设置。 - **重试逻辑**对于已知可能失败的非幂等操作建议或询问是否添加重试机制和超时处理。5.2 使用现成模板与自定义awesome-agent-rules项目提供了开箱即用的模板这是最快的起步方式。选择模板Minimal极简版适合一次性脚本或微型项目只包含最核心的任务启动和HANDOFF规则。Standard标准版适用于绝大多数Web应用、API服务或库开发包含了本文提及的大部分规则。Multi-Agent多智能体版适合大型、长期的项目其中明确包含了多工具协作和复杂的信任校准规则。自定义你的规则文件 模板只是起点。最关键的一步是注入你的项目特异性信息。一个优秀的AGENTS.md或CLAUDE.md应该像项目的“入职指南”。我通常会在标准模板基础上增加以下章节## ️ 项目特定架构 - **核心入口**src/index.js 是应用起点src/routes/ 下是API路由。 - **数据流**使用Redux进行状态管理所有action定义在 src/store/actions/。 - **样式规范**使用CSS Modules文件与组件同名位于 src/components/*/*.module.css。 - **绝对禁止**不得直接修改 src/lib/core/ 下的文件如需扩展请在 src/lib/extensions/ 中创建新文件。 ## 常用命令 - npm run dev - 启动带热重载的开发服务器。 - npm run test:watch - 运行单元测试监视模式。 - npm run build:staging - 构建预发布环境包。 - docker-compose up db - 启动本地开发数据库。 ## 相关文档链接 - [API设计规范](docs/api-spec.md) - [组件库使用指南](docs/ui-components.md) - [部署流程](docs/deployment.md)一个重要的经验法则是“错误规则”如果从你的规则文件中删除某一行AI不会因此犯一个可预见的错误那么这一行可能就是冗余的可以考虑删除。保持规则的简洁和关键。6. 常见问题与实战排错指南即使有了完善的规则在实际操作中依然会遇到各种问题。以下是我在过去几个月高频使用这些规则时总结出的典型问题及其解决方案。6.1 规则失效或AI无视规则问题表现你明明在AGENTS.md里写了“先计划后执行”但AI收到指令后还是直接开始写代码。排查步骤与解决检查文件位置与命名确认规则文件放在了项目根目录并且名称完全正确AGENTS.md,CLAUDE.md, 或.cursorrules。大小写敏感。检查工具是否支持确认你使用的AI编程工具确实支持并会主动读取该规则文件。例如早期版本的某些插件可能需要手动加载。简化规则进行测试在文件开头用醒目的标题写一条非常具体的规则如“规则测试回复此消息时请在开头先说‘规则已加载’”。如果AI没说说明文件根本没被读取。手动提醒在对话开始时可以主动发送指令“请先阅读项目根目录下的AGENTS.md文件并总结其中的核心规则。” 这能强制AI加载上下文。规则过于复杂如果文件太长比如超过1000行AI可能无法有效处理全部内容。尝试精简只保留最核心、最通用的规则。6.2 HANDOFF.md 内容混乱或更新不及时问题表现HANDOFF文件变得冗长信息重复或者AI忘记在提交后更新它。解决策略格式化强制执行在规则中严格定义HANDOFF的Markdown格式如使用复选框- [ ]并要求AI每次更新时必须保持该格式。人类定期清理已完成项的复选框。设置“触发器”将更新HANDOFF与git操作绑定。在规则中强调“每次执行git commit -m \...\命令后你的下一个动作必须是更新HANDOFF.md的‘完成事项’部分。”定期归档对于长期项目可以建立每周或每里程碑归档一次的惯例。将当前的HANDOFF.md重命名为HANDOFF_2023-W50.md然后新建一个干净的HANDOFF.md。旧文件作为历史日志保留。6.3 多智能体协作时的冲突问题表现智能体A在HANDOFF里记录了一个决策智能体B后来忽略了它实施了相反的方案。根治方法强化“冲突警告”流程在规则中不仅要求标出冲突还要规定必须立即停止并给出一个具体的等待指令的示例如“⚠️ 检测到与HANDOFF中记录的决策冲突。已暂停。请确认是遵循原有决策[X]还是采用我的新方案[Y]”将HANDOFF纳入版本控制确保HANDOFF.md的每次更新都被git提交。这样如果发生冲突你可以通过git diff清晰地看到是谁在什么时候修改了什么。设立“决策日志”对于重大架构决策不要在HANDOFF里一笔带过。可以要求AI在docs/decisions/目录下创建一个简短的ADR架构决策记录文件详细记录上下文、选项、决策理由和后果。这比HANDOFF里的片段更正式、更不易被忽略。6.4 信任级别判断失误问题表现你给了L1信任级别但AI做了一个有风险的修改却没汇报或者你给了L4它却每一步都问得过于琐碎。校准技巧从L3开始对于新项目或新类型的任务默认从L3渐进信任开始。观察AI在小型任务上的表现再逐步调整信任级别。事后复盘如果发生了“信任事故”该问没问或问太多事后和AI一起回顾。把这次事件作为一个案例细化规则。例如“对于涉及package.json中dependencies的修改无论信任级别都必须先向我展示变更对比。”任务分类预设在你的项目特定规则里可以预设一类任务的默认信任级别。例如“规则所有在src/utils/目录下的纯函数优化任务默认适用L2信任级别交叉验证。”6.5 规则文件本身的维护问题表现随着项目发展规则文件变得臃肿有些规则过时了有些新情况没覆盖。维护建议版本化规则在规则文件顶部加入一个版本号如## Version: 2.1。当做出重大更新时递增版本号并在HANDOFF中记录变更原因。定期评审每个迭代或每月花10分钟和AI一起快速浏览一遍规则。问它“根据我们最近的协作哪条规则最有用哪条规则似乎很少被触发或可以改进”你可能会得到一些有趣的优化建议。分拆文件如果规则确实非常多可以考虑分拆。主AGENTS.md文件包含通用规则和架构针对特定工具如Docker、Testing的详细规则可以放在docs/agent-rules/目录下并在主文件中通过链接引用。说到底制定和管理AI智能体规则本身就是一个“元编程”过程——你在编写一段用来指导如何编写代码的“代码”。这个过程需要耐心和迭代但一旦这套系统运转起来你会发现你与AI的协作效率和质量都将获得质的飞跃。它从一把有时不听使唤的利剑变成了你手臂的精准延伸。