跨工具通用的 AGENTS.md

适用场景

团队里有人用 Claude Code，有人用别的编码智能体，每个工具各读各的说明文件，内容很快就会不一致。把项目通用的约定集中写在仓库根目录的 AGENTS.md，再让各工具都读到它，是维护成本最低的做法。

先说一个与旧认知不同的地方：较新的 Claude Code 已经能直接读取 AGENTS.md，不再必须靠引用或软链接绕一圈。但读取是有条件的，下面会讲清楚。

模板

仓库根目录的 AGENTS.md，只放所有工具都适用的内容：

# AGENTS.md

## 项目概览
【项目名】：【一句话说明】。主要语言与框架：【技术栈】。

## 命令
- 安装：`【命令】`
- 开发：`【命令】`
- 测试（单文件）：`【命令】`
- 测试（全量）：`【命令】`
- Lint / 类型检查：`【命令】`

## 目录约定
- `【路径】`：【用途】

## 代码约定
- 【可验证的规则】

## 工作流
- 先读相关代码再修改，改动保持最小。
- 提交前运行 Lint 与测试，并如实汇报结果。
- 不直接推送到默认分支；不提交密钥与 `.env`。

## 禁区
- 不要修改：`【路径】`

如果项目里同时存在 CLAUDE.md，在它的开头引用 AGENTS.md，再追加只属于 Claude Code 的内容：

@AGENTS.md

## Claude Code 专用
- 修改 `src/billing/` 前先进入计划模式（Plan Mode），把方案给我确认。

怎么用 / 怎么改

Claude Code 对三种仓库状态的默认行为如下：

仓库里有	Claude Code 读取
只有 AGENTS.md，工作目录及上层没有任何 CLAUDE.md 或 CLAUDE.local.md	AGENTS.md
AGENTS.md 与 CLAUDE.md 都有	只读 CLAUDE.md
CLAUDE.md 中写了 @AGENTS.md	CLAUDE.md，并通过引用带入 AGENTS.md

根据这张表选方案：

1. 全员都用支持 AGENTS.md 的工具，且没有 Claude 专用内容。 只放 AGENTS.md，什么都不用加。直接读取要求 Claude Code v2.1.277 及以上。
2. 有 Claude 专用内容。 保留 CLAUDE.md，第一行写 @AGENTS.md，下面追加专用部分。这样通用部分只维护一份。
3. 不需要专用内容，又想兼容旧版本。 可以用软链接 ln -s AGENTS.md CLAUDE.md。
4. 想让 Claude 同时读两个文件。 在会话里运行 /config，把 Project instructions 设为 claude-md-and-agents-md。

配置完成后，运行 /memory 或 /context 看一眼列表，确认 Claude 读到了正确的文件。

常见问题或注意事项

• 加了个人的 CLAUDE.local.md 后 AGENTS.md 就不读了。 因为 CLAUDE.local.md 也算作「存在 CLAUDE 文件」。解决办法是把 Project instructions 设为 claude-md-and-agents-md。你家目录下的 ~/.claude/CLAUDE.md 和 .claude/rules/ 不受影响。
• 只会读 AGENTS.md，不会读 AGENTS.local.md、AGENTS.override.md 或 .agents/ 目录。 这些别的工具支持的变体，Claude Code 目前不读。
• Windows 用户慎用软链接。 创建软链接需要管理员权限或开发者模式，而且 Git 检出时若未启用符号链接，软链接会变成只有一行路径的普通文本文件。团队里有 Windows 同事时，请用 @AGENTS.md 引用。
• 软链接的编辑限制。 Claude 的编辑和写入工具不会穿过软链接写文件，它会被引导去改链接指向的 AGENTS.md。
• 旧的变通方案可以清理了。 比如在 CLAUDE.md 里用文字叫 Claude「去读 AGENTS.md」，或者用 SessionStart hook 把内容打印出来，现在要么改成 @AGENTS.md 引用，要么删掉，避免同一份内容进入上下文两次。
• 其他工具如何读取，以各自官方文档为准。 本页只核实了 Claude Code 一侧的行为。