# 跨工具通用的 AGENTS.md

> 用一份 AGENTS.md 同时服务多个编码智能体，并说明 Claude Code 何时直接读取它、何时需要 CLAUDE.md 里的 @AGENTS.md 引用或软链接。

## 适用场景

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

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

## 模板

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

```markdown
# AGENTS.md

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

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

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

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

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

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

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

```markdown
@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 一侧的行为。