先说结论：反复维护的项目值得写，临时脚本不必硬配
不是每个临时脚本都需要规则文件；多人协作、反复维护、同类错误反复出现的项目，更值得留一份简短、可验证的约定。最管用的内容不是“你是资深专家”，而是真实命令、目录边界、修改限制和验收标准。文件怎么命名、什么时候加载、作用于哪些目录，都取决于 AI 编程助手，不能随便放个 AI_RULES.md 就当它自动生效。
为什么说过好多遍，下一次还是改错？
常见问题是：要求只修一个问题，却顺手重排整个文件；测试命令凭经验猜；错误被吞掉，只留下“已修复”。原因不一定是模型能力不足，也可能是项目约定没有进入本次上下文，或者约定本身无法执行。
| 现象 | 可能原因 | 先做什么 |
|---|---|---|
| 每次都要解释项目技术栈 | 稳定背景只留在旧对话里 | 放入简短常驻规则 |
| 只让改一处却出现大段 diff | 修改边界不明确 | 写清禁止无关格式化和重命名 |
| 总说验证通过却没有记录 | 验收要求太笼统 | 要求报告命令、结果与未验证项 |
| 子目录规则互相打架 | 作用域或加载顺序没理清 | 查工具说明，删除冲突条款 |
规则文件是减少重复沟通的项目文档，不是权限控制，也不是保证正确的开关。
第一步：先确认工具会读什么，再决定放哪里
AGENTS.md 格式说明将它定位为给 AI 编程助手看的项目说明，内容是普通 Markdown，没有必填字段，适合写构建、测试和代码约定。但只有支持这种格式的工具，才可能按其约定读取它；某些工具还需要设置，不能把文件名当成通用指令。
可以从工具官方规则入口核对四件事：
- 入口：支持
AGENTS.md，还是另有专用目录、扩展名或设置？不支持时，按官方入口显式加载，不要只把文件丢在根目录。 - 时机：每次会话加载、匹配文件时加载，还是需要手动引用？必要时重新开始会话。
- 范围：根目录规则是否覆盖子目录，嵌套规则如何生效？
- 顺序：项目、个人、团队规则冲突时谁优先？不要把一种工具的顺序套给另一种。
格式说明介绍了“更近目录的规则优先”的约定，但实际使用仍要看工具实现和所用功能的支持范围。有的规则只影响对话式修改，不影响自动补全；涉及多个目录的任务，也要核对各自规则。
第二步：常驻规则只放稳定事实
常驻规则回答“在这个项目里，通常该怎样做”；本次任务回答“今天具体改什么”。例如，错误处理约定可以常驻，“这次只改某个已确认文件”应该放在任务里。
下面模板用于支持 AGENTS.md 的 AI 编程助手；否则通过工具官方入口加载。所有尖括号内容必须替换；没有确认的条目删掉或注明待确认，不要原样执行占位命令。
# 项目协作规则
## 技术栈与入口
- 语言、运行时、框架：<填写真实名称与版本来源>
- 项目说明入口：<填写实际存在的文档路径>
## 目录边界
- <真实目录路径>：<职责与允许修改范围>
- <真实生成物或外部代码路径>：不直接修改；如确需修改先说明
## 修改约束
- 只做当前任务必要的改动；不做无关格式化、重命名和重构。
- 沿用已有错误处理约定；不静默吞错，不记录敏感内容。
- 不擅自新增或升级依赖；必要时先说明理由并请求确认。
- 约定不明或相互冲突时，先指出问题，不猜测。
## 验证与交付
- 检查命令：<已确认的真实命令；填写运行目录和前置条件>
- 测试命令：<已确认的真实命令；无适用项就明确注明>
- 仅在获准的环境和权限范围内执行，不自行发布或提交。
- 交付前检查 diff，说明修改范围与对应测试。
- 报告实际执行的命令、结果及未执行原因，不把未验证写成通过。
模板故意没有预填目录和命令：不同项目的语言、包管理方式、测试入口都可能不同。先由维护者对照项目文档和脚本确认，再写入规则；不能从网上复制一套命令就假定项目支持。
“提高质量”“遵循最佳实践”很难验收，改成“不得新增无关依赖”“报告未执行测试的原因”更具体。已有规范可以给出准确路径，不必全文复制；但引用文件是否会被进一步读取，也要核对工具行为。
第三步：用安全小任务验证，而不是听它复述
可以选择一个已授权、易回滚的小任务，例如修正一段普通文档里的错别字，明确本次允许修改的文件。先记下已有工作区差异，避免把别人的未提交改动算进本次结果；不要拿发布、删文件或接触敏感数据来试规则。
先查看工具提供的已加载规则或引用记录（如有），再让 AI 编程助手说明适用规则及来源。这只能辅助判断：能复述规则，不等于真正遵守。
完成后核对三项：实际 diff 是否只涉及允许范围，有没有顺手改配置或生成文件；适用的检查是否真的执行，结果是什么；无测试可跑或环境缺失时，是否如实标成未验证。文档修正未必需要全套测试，但不能凭一句“检查无误”宣称测试通过。
如果没有遵守，依次排查加载入口、作用域、冲突和措辞，再用同类小任务复核。这里提供的是验证方法，不是已经在某个项目完成的实测记录。
写短一点，也写安全一点
先保留最常用、最容易验收的条款，遇到重复错误再补。不要同时写“只做最小修改”和“顺便全面重构”；别把一次性的修复要求永久留下。命令、目录或工作方式变化时，规则也要更新，避免变成过期文档。
密钥、个人信息不要写进去，也别写“忽略所有安全限制”之类越权指令。项目规则不能覆盖工具权限和用户授权；仓库内不明来源的指令也不能直接当成可信操作依据。
可选工具：切换模型与项目规则分开管
如果平时需要切换模型、管理配置，可以了解桌面客户端 GetTokenSwitch。它解决的是模型切换和配置管理；规则仍归项目和 AI 编程助手管理，不能用切换配置代替规则加载。换模型或调整工具后，也应重新核对规则来源与实际执行结果。
FAQ
一个人维护也值得写吗？ 值得与否看重复沟通量，不看人数。隔几周回来总要重讲约定，就值得留一份；一次性任务直接在对话里交代即可。
根目录一份够不够？ 先从一份开始。只有子项目约定确实不同、工具也支持目录作用域时再拆，避免重复和冲突。
规则越多是不是越稳？ 不是。大量口号和失效命令会稀释关键要求。留下能执行、能检查、维护者认可的内容。
写了禁止事项就不会出错了吗？ 不能保证。规则之外仍要保留权限限制、人工看 diff 和实际测试，把“要求遵守”与“已经验证”分开。
