如何用 AGENTS.md 为 Cursor、Claude Code 与 Aider 建立通用项目规则

Cursor

Claude Code

Aider

在 AI 辅助开发中，Coding Agent 指的是能够借助模型推理、工程上下文与系统工具执行软件工程任务的智能体；而 Harness 则是承载智能体运行的宿主环境与产品，负责处理上下文检索、文件读写、终端调度、权限裁决与交互循环。我们日常使用的 Cursor Agent、Claude Code 与 Aider，本质上都属于 Harness。

为了建立清晰的工程共识，本文将团队长期遵循的技术与协作约定称为“工程规约”，而将专门写入 AGENTS.md、CLAUDE.md 或 Harness 配置中直接指导智能体行动的指令称为“项目规则”。一份真正高效的项目规则绝不应充斥“写出高质量代码”这类模糊口号，而必须将无法仅从现有代码反推的关键事实与边界阐述透彻。

项目规则必须覆盖的三类关键信息

1. 不可撼动的仓库事实：技术选型基线、模块目录边界、服务启动与调试方式。这类信息在相当长周期内应保持稳定。
2. 具象可执行的工程规约：向下兼容性策略、权限架构、数据库 Migration 命名规范与严禁触碰的架构红线。这类规约必须具备明确的可验证性。
3. 隔离的任务级需求边界：当前业务功能的具体取舍与验收标准（Acceptance Criteria）。这类信息应当由具体的 Issue 或 Prompt 承载，严禁随意固化进全局规则文件中。

如果开发者不加区分地将临时实现的偏好写入全局规则，Coding Agent 就会把局部权宜之计误当成长期架构准则，规则文件也会随之迅速退化失信。

一份可跨 Harness 复用的 AGENTS.md 骨架

下面的 AGENTS.md 可以作为团队跨 Harness 的单一共享规则源：

• Cursor 原生支持读取项目根目录与特定子目录下的 AGENTS.md；
• Aider 可以通过 --read AGENTS.md 将其作为只读上下文安全载入；
• Claude Code 则可通过下一节介绍的轻量 CLAUDE.md 引用语法无缝导入。

# Project instructions

## Architecture
- `app/` owns routes and server rendering.
- `components/` contains reusable UI.
- `lib/` contains framework-light domain logic.

## Change boundaries
- Preserve public API behavior unless the task explicitly changes it.
- Never mix generated files with hand-authored source.
- Add a migration for every persistent schema change; never edit an applied migration.

## Verification
- Run `npm test` for domain behavior.
- Run `npm run build` before delivery.
- Report every skipped check and its exact reason.

## Delivery
- Keep each commit focused on one logical change.
- Summarize changed behavior, not only changed filenames.

用“可观测动作”替代抽象形容词

“注意安全性”、“保持高可读性”这类抽象词汇不仅无法为 Coding Agent 提供决策依据，反而容易引发大模型的空泛敷衍。必须将其全部重构为具备确定性结果的验证动作：

• 拒绝抽象表达：“确保页面具备良好的 SEO 表现。”
• 改写为可执行动作：“详情页必须显式输出 canonical 标签、Article 维度的 OpenGraph 元数据，并在静态构建中通过参数验证。”
• 拒绝抽象表达：“避免破坏生产数据库。”
• 改写为可执行动作：“严禁修改已应用的 migration 文件；新增数据库迁移必须使用下一个三位数编号作为前缀。”
• 拒绝抽象表达：“对改动进行全面测试。”
• 改写为可执行动作：“提交前必须依次运行 npm test 与 npm run build，并提供关键业务路径的终端执行结果。”

规则的价值不在于字数篇幅，而在于当代码方案发生冲突与取舍时，能否给出毋庸置疑的裁决依据。

用 CLAUDE.md 接入 Claude Code

Claude Code 原生支持项目级 CLAUDE.md 记忆文件，并提供了 @path/to/file 形式的外部文件引入语法。

由于 Claude Code 官方并未将 AGENTS.md 设定为主规则入口，我们可以通过一个极薄的 CLAUDE.md 适配层直接 @AGENTS.md，从而彻底避免在多个规则文件之间人肉同步副本的维护灾难：

# Claude Code project instructions

@AGENTS.md

- Use the current user request as the task-specific acceptance criteria.
- Before high-risk changes, run `/context` and confirm this file is listed under Memory files.

在这个组合结构中，两份文件各司其职，职责边界极其清晰：

• AGENTS.md：承载所有 Harness 共用的仓库事实、工程规约与流水线命令；
• CLAUDE.md：仅负责处理 Claude Code 特有的载入语法与环境专属指令，不复制共享规约。

当团队需要更新通用规约时，仅需在 AGENTS.md 处维护一次改动；而不同 Harness 的差异化配置，则完全交由各自的轻量适配层完成挂载。

规则编写与发布前自检清单

在将新的项目规则纳入代码仓库前，建议对照以下四条标准进行自检：

1. 新手自洽性：一个刚进入仓库的新成员，仅阅读该规则是否就能正确启动项目并完成构建验证？
2. 冲突仲裁力：当两条业务需求发生实现路径分歧时，规则是否提供了清晰的优先级指引？
3. 结果可度量：规则中的每一处“必须”和“严禁”，是否有明确的命令输出、文件边界或检查脚本予以支撑？
4. 长效纯洁性：规则正文中是否混入了仅针对当下某个临时任务的偶发性细节？

最优秀的项目规则应当像一本精悍的战地操作手册：短小、具体、经得起检验，并且始终与仓库的最新演进同频共振。

参考资料

本文根据爱买 AI 的实际多 Agent 混合工程经验整理。所涉及的规范行为与载入机制均对照官方文档一手核验：

• AGENTS.md 官方规范：标准开放格式、推荐目录作用域与声明语法，核验日期 2026-09-08。
• Cursor：Rules 官方指南，阐述 AGENTS.md 与 .cursor/rules/*.mdc 的层级支持，核验日期 2026-09-08。
• Claude Code：Memory 机制文档，阐述 CLAUDE.md 导入语法与 /context 状态检查，核验日期 2026-09-08。
• Aider：编码规约指定指南，阐述 --read 与 .aider.conf.yml 只读挂载机制，核验日期 2026-09-08。