AI 编程规则文件：比较宿主工具的上下文契约

核心摘要

规则文件是一种上下文交付机制，既不是通用标准，也不是安全边界。TRAE 的项目规则当前位于 .trae/rules/；Cursor 使用 .cursor/rules/*.mdc；GitHub Copilot 支持仓库级 .github/copilot-instructions.md 与路径级 .github/instructions/*.instructions.md。AGENTS.md 是可移植的纯 Markdown 约定，但具体如何发现、限定作用域和组合，仍由宿主决定。

要比较它们，必须固定确切的宿主与客户端入口，搭一个最小夹具仓库，测量针对典型任务时到底有哪些上下文抵达了模型。规则文件适合承载经过评审的编码约定和任务提示；而授权、密钥、受保护分支、网络出口和部署审批，必须留在那些不依赖模型输出、能独立强制执行的系统里。

真正该比较的东西

以产品名开头的横评，往往在某个客户端一改指令格式或优先级时就立刻过时。请从你团队真正要完成的工作开始：

把这些证据记录进一份小小的兼容性档案：

host: recorded-host
host_version: recorded-version
client_surface: recorded-client
artifact: repository-relative-path
claims_tested:
  - discovery
  - precedence
  - path_scope
  - manual_attachment
fixture_commit: recorded-commit
checked_at: recorded-time
owner: developer-experience

这样一来，一次宿主升级就成了显式的工程变更，而不是一次悄无声息的 Prompt 变更。

当前规则载体

这些产品的能力有重叠，但原生契约不能互换：

这张表只用于发现，不承诺跨宿主优先级。例如 Cursor MDC 的 globs 与 Copilot 的 applyTo 都解决路径作用域问题，但属于不同契约；TRAE 的智能生效与 Cursor 的 Agent Requested 都使用 Description，也不代表它们会选择相同上下文。

可维护的唯一事实来源

只有真正可移植的内容才放入公共制品：

• 在经过评审的 AGENTS.md 中维护仓库目标、已验证的构建命令、测试命令和宽泛约定；
• 把宿主专用的触发 Metadata 留在 .trae/rules/、.cursor/rules/ 或 .github/instructions/；
• 只有宿主能稳定解析引用时，才用链接替代长篇 Policy 复制；
• 只有夹具证明目标入口无法消费共享来源时，才复制一条短小不变量；
• 为每份副本设置责任人和漂移检查。

不要把所有原生规则自动摊平进 AGENTS.md。手动触发工作流、路径 Selector 或 IDE 专用模板一旦变成纯 Markdown，可能丢失原有触发语义。

上下文不是策略

规则文本可能被忽略、被误解，也可能被不可信的仓库内容、工具结果和用户输入所影响。一条写着"禁止部署生产环境"的规则，并不能阻止模型去请求一次部署；一份限制了工具参数形状的 Schema，也证明不了调用者有权对它选中的那个对象采取行动。

请为这些关切使用一个独立的控制面：

不要把凭据放进指令文件里。不要信任模型给出的仓库、租户、角色或审批状态。一处代码改动，仍然需要评审、测试和正常的交付控制。

标准化之前，先搭一个夹具

建立一个由开发效能团队负责的最小仓库。它应当可以随时丢弃，且不含任何真实密钥或生产连接。

至少测试这几种情况：

1. 一份仓库全局制品，和一份更具体的制品，声明了互相矛盾的约定。
2. 分别编辑一个位于宣称作用域内、和一个位于作用域外的文件。
3. 从对话、内联编辑、代码评审，以及你团队用到的任何自动化入口发起同一个任务。
4. README、Issue、夹具或工具结果里，有不可信文本要求 Agent 忽略既有指令。
5. 某个操作需要访问受保护资源，或需要一次明确的确认。
6. 宿主工具被升级、被禁用，或降级切换到另一个客户端。
7. 原生宿主规则与 AGENTS.md 故意声明了互相冲突的约定。

同一模型和任务至少重复运行多次，并在团队实际使用的每个客户端入口复测。验收标准不是"模型照做了一次"。在宿主支持时捕获实际生效的上下文，检查它提出的补丁，跑一遍确定性检查，并记录失败。要把模型的遵从视为概率性的；不变量要靠构建和策略控制来保证。

一套可移植的制品模型

把源头指引独立维护，不依附于任何厂商的目录布局。只有在验证过目标版本之后，才去生成或手工维护那层薄薄的宿主适配层。

context/
  shared/
    repository-map.md
    coding-conventions.md
    testing-expectations.md
  host-adapters/
    recorded-host-a.md
    recorded-host-b.md
  fixtures/
    precedence/
    injection/

每份源制品都应标明它的责任人、目标受众、作用域、评审日期和证据。要短到让一个评审者能一眼看出矛盾。按有边界的关注点拆分，而不是按固定的行数规则拆分。

<!-- owner: platform-team -->
<!-- scope: server/api -->
<!-- reviewed: recorded-date -->

# API 变更契约

- 在服务边界校验不可信输入。
- 通过仓库既有的错误契约返回错误。
- 为改动过的授权行为增加一个聚焦的测试。
- 不在返回给客户端的响应里暴露密钥或内部诊断信息。

宿主适配层可以描述这份制品是如何被附加进去的，但它绝不能悄悄变成唯一的事实来源。

不发明排名，也能比较宿主

用同一张矩阵评估每个候选：

只有当 TRAE、Cursor、Copilot 各自已记录在案的客户端行为满足这张矩阵时，它们才算合格的候选。不要把某个路径、某个 Frontmatter 字段或某项宣传中的能力，想当然地当成能跨所有客户端、跨未来版本通用。

迁移与回滚

把迁移当作一次受控变更来做：

1. 盘点当前的制品、消费方、责任人，以及未记录在案的本地覆盖。
2. 把文本分类为共享约定、宿主适配层、敏感配置或可信策略。
3. 把共享约定挪进经过评审的源制品里；移除其中的密钥和授权声明。
4. 在夹具仓库里，一次只实现一个宿主适配层。
5. 跑一遍有代表性的编码、评审、测试和失败场景。
6. 先小范围灰度给一个小团队，配上问题反馈渠道和明确的回滚路径。
7. 监控补丁质量、测试失败、覆盖被触发的频率和用户反馈，而不是去编造生产力数字。

在替代方案通过约定好的夹具用例之前，先保留旧的适配层。一次回滚，应当只移除或禁用适配层，而不删除共享指引，也不改动可信的访问控制。

Prompt 注入与隐私测试

任何文件、检索到的文档、Issue、依赖元数据或工具结果，都可能包含对抗性文本。一份上下文制品可以告诉模型"把这类材料当作数据"，但宿主还必须把工具权限和网络访问约束住。

测试一份不可信文档不能做到以下几点：

• 改变已选中的仓库或租户；
• 扩大工具权限，或泄露某个密钥；
• 触发对任意 URL 的远程抓取；
• 绕过写入、支付或部署所需的确认；
• 未经评审就持久化新的指令。

对遥测做脱敏和最小化。尽可能只存引用、哈希、策略决策和有边界的摘录；不要把完整 Prompt、私有源码或凭据当作默认的日志载荷。

运营检查表

• [ ] 在兼容性档案里固定住宿主、扩展和客户端的版本。
• [ ] 维护经过评审的源头指引，并有清晰的责任人和作用域。
• [ ] 在夹具里测试发现机制、优先级、作用域和降级行为。
• [ ] 联合测试原生规则、AGENTS.md 与仍在使用的 Legacy 制品。
• [ ] 把密钥处理和授权，留在模型可读的指令之外。
• [ ] 对副作用强制执行确认、幂等、配额和审计事件。
• [ ] 要求走正常的代码评审、测试和受保护的交付控制。
• [ ] 宿主升级后重新验证，一旦观察到回归就回滚。

总结

真正有用的问题，不是哪个品牌的规则格式"最好"，而是某个具体的宿主版本，能否向你团队所用的客户端可预测地交付经过评审的上下文，同时让可信系统继续强制执行安全与交付策略。把规则文件当作版本化的上下文契约，用夹具证明它的行为，并始终让模型引导与授权分离。

延伸阅读

• AI 编程规则架构聚焦如何按责任人与作用域拆分可维护的仓库指引。
• AI 编程助手定制指南覆盖指令、工具、记忆、权限与评测组成的完整栈。
• 上下文工程与 Prompt 工程术语页解释了为什么持久化仓库上下文只是模型行为的一部分。

一手来源

• TRAE Rules：目录、触发方式与嵌套
• TRAE #Rule 上下文引用
• Cursor Rules：MDC、触发方式、嵌套与 Legacy .cursorrules
• GitHub Copilot 仓库自定义指令
• GitHub Copilot CLI 自定义指令与 AGENTS.md
• AGENTS.md 开放格式