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

Coding Agent 是执行软件工程任务的智能体；Harness 是承载智能体的产品与运行环境，负责提供上下文、文件编辑、终端、工具调用和权限控制。本文讨论的 Cursor Agent、Claude Code 与 Aider 都属于 Harness。

本文把团队长期遵守的约定称为“工程规约”，把写入 AGENTS.md、CLAUDE.md 或 Harness 配置并直接提供给 Coding Agent 的指令称为“项目规则”。有效的项目规则不应堆满“写好代码”之类的口号，而要把无法仅靠仓库代码推断的事实写清楚。

项目规则应覆盖三类信息

1. 仓库事实：技术栈、目录职责、启动方式，应长期稳定。
2. 工程规约：兼容性、权限边界、迁移命名等不可破坏的约束，应能被检查。
3. 任务边界：当前功能的取舍和验收条件，通常应放在 issue 或任务说明，不应永久写进全局规则。

如果不区分长期规则和一次性任务边界，Coding Agent 可能把临时实现偏好当作长期架构，规则文件也会迅速失去可信度。

一份可复用的 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；新增文件使用下一个三位数前缀”。
• 不要写“测试所有内容”，要列出最低验证命令与关键冒烟路径。

项目规则的价值不在篇幅，而在发生取舍时能否给出明确的选择。

用 CLAUDE.md 接入 Claude Code

Claude Code 官方支持项目级 CLAUDE.md，并支持使用 @path/to/file 导入其他文件。因为 Claude Code 并不把 AGENTS.md 作为其官方项目规则入口，所以这里用一个很薄的 CLAUDE.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 特有的加载方式和检查命令，不重复共享规则。

Cursor 可以直接读取 AGENTS.md；Aider 则在命令行或 .aider.conf.yml 的 read 配置中加载 AGENTS.md。更新共享规则时只修改一处，Harness 专属行为才写进各自的适配层。

发布前检查

• 新成员只读项目规则，是否能正确启动和验证项目？
• 两条规则冲突时，是否明确了优先级？
• 每个“必须”是否有命令、文件边界或验收结果支撑？
• 是否混入了只适用于某个任务的临时实现细节？

最好的项目规则像一份小型运行手册：短、具体，并且与仓库当前状态一致。

参考资料与生产说明

本文为本站原创整理，不是对单篇外部文章的翻译或转载。初稿由 Coding Agent 根据本站 /agents 产品需求生成；本次修订逐项对照以下一手资料核验了文件用途和加载方式：

• AGENTS.md 官方说明：开放格式、推荐内容与目录作用域。
• Cursor Rules 官方文档：Cursor 对 AGENTS.md 和 .cursor/rules/*.mdc 的支持。
• Claude Code 官方文档：Memory：CLAUDE.md、文件导入与 /context 检查方式。
• Aider 官方文档：Specifying coding conventions：通过 --read 或 .aider.conf.yml 加载只读规约文件。

资料核验日期：2026-09-08。内容经过术语检查、示例职责检查、MDX 构建和静态页面渲染检查后发布。