跳到主要内容

CLAUDE.md 与 AGENTS.md

CLAUDE.md 和 AGENTS.md 是 AI Agent（Claude Code、Codex、Cursor 等）在每次会话开始时自动读取的项目说明文件。这篇笔记记录这两个文件的作用和写法，以及怎么让一份内容同时对多个工具生效。

两个文件是什么​

它们解决的是同一个问题：把需要交代给 AI 的项目背景放在约定好的位置，每次会话自动加载，不用反复在对话里说明。

  • AGENTS.md 是一份开放规范（现由 Linux Foundation 旗下的 Agentic AI Foundation 维护），定位是「给 agent 看的 README」。README 面向人类读者，AGENTS.md 放人类不需要、但 agent 需要的细节：构建命令、测试方式、代码约定。Codex、Cursor、Gemini CLI、Copilot 等几十个工具都支持，有 6 万多个开源项目在用。
  • CLAUDE.md 是 Claude Code 的指令文件。可以放在多个位置：用户主目录 ~/.claude/CLAUDE.md（对所有会话生效）、项目根目录（提交进 git 与团队共享）、CLAUDE.local.md（个人配置，加进 .gitignore）、以及 monorepo 的父/子目录。

两者都没有固定格式，就是普通 Markdown，标题随便起，工具只是把整份文本读进上下文。

让多个工具共用一份内容​

CLAUDE.md 支持 @path/to/file 导入语法，所以常见做法是把指令统一写在 AGENTS.md 里，CLAUDE.md 只留一行：

@AGENTS.md

这样 Claude Code 和其它支持 AGENTS.md 的工具读到的是同一份指令，维护一处即可。

monorepo 里可以在每个子项目下再放一份 AGENTS.md：agent 读离被编辑文件最近的那份，越近优先级越高。你在对话里直接下的指令优先级最高，可以覆盖文件里的任何规则。

该写什么、不该写什么​

指令文件每次会话都会加载，所以第一要求是短。官方给的检验标准：逐行自问「删掉这行，AI 会犯错吗」，不会就删。文件写得太长，重要规则反而会被淹没。

✅ 该写❌ 不该写
AI 猜不到的构建/测试命令读代码就能自己搞明白的东西
与默认习惯不同的代码风格语言的标准惯例（AI 本来就知道）
测试怎么跑、用哪个 runner详细的 API 文档（放个链接就行）
仓库规矩（分支命名、PR 约定）频繁变化的信息
项目特有的架构决策长篇解释和教程
环境的坑（必需的环境变量等）逐文件的代码结构描述
不明显的注意事项、踩过的坑「写干净的代码」这类废话

另外几点经验：

  • 必须遵守的规则可以加重语气（IMPORTANT、YOU MUST），确实能提高遵守程度。
  • AI 反复违反某条明明写了的规则，多半是文件太长、规则被淹没了；AI 跑来问文件里已经写明的问题，说明措辞有歧义。指令文件要当代码维护：出问题就回头审，定期删减，改完观察 AI 的行为有没有变。
  • 只在部分场景用得上的领域知识不要写进来，用工具的按需加载机制（如 Claude Code 的 skills）。
  • 文件里的指令对 AI 只是「建议」，可能不被执行。每次都必须发生的动作（比如编辑后跑 lint）要用 hooks 这类强制机制，不能指望提示词。

通用模板​

按 agents.md 官方示例整理，用的时候按项目情况删改：

# AGENTS.md

## 项目概述
<一两句话：这是什么、技术栈>

## 常用命令
- 安装依赖：`pnpm install`
- 启动开发服务器：`pnpm dev`
- 运行测试：`pnpm test`
- 单跑某个测试：`pnpm vitest run -t "<test name>"`

## 代码风格
- TypeScript strict 模式
- 单引号、无分号
- <与默认习惯不同的约定>

## 测试要求
- 改完代码必须跑 lint 和测试，全绿才算完成
- 改动的代码要补充/更新对应测试，即使没人要求

## PR 约定
- 标题格式：[<模块>] <标题>
- 提交前必须跑 `pnpm lint` 和 `pnpm test`

## 已知的坑
- <环境变量、依赖版本等非显而易见的注意事项>

新项目也可以让工具生成初稿（Claude Code 用 /init）再改。

例子：Next.js 的官方支持​

Next.js 从 v16 开始把整套官方文档打包进 next 包，位置在 node_modules/next/dist/docs/，内容与安装的版本一致。配套的 AGENTS.md 只有一条指令，让 agent 写代码前先读这些文档：

<!-- BEGIN:nextjs-agent-rules -->

# Next.js: ALWAYS read docs before coding

Before any Next.js work, find and read the relevant doc in
`node_modules/next/dist/docs/`. Your training data is outdated —
the docs are the source of truth.

<!-- END:nextjs-agent-rules -->

CLAUDE.md 则只有一行 @AGENTS.md。

这样做针对的是 AI 写 Next.js 代码的常见问题：训练数据里的 API 已经过时。文档随依赖一起安装，版本天然一致，查阅也不需要联网。BEGIN/END 注释之间是 Next.js 托管的部分，升级时会被自动覆盖更新，项目自己的规则写在标记之外即可。

启用方式：

  • 新项目：create-next-app（canary）会自动生成这两个文件，不需要就加 --no-agents-md。
  • 现有项目：Next.js v16.2.0-canary.37 起，手动在项目根目录添加上述两个文件。
  • v16.1 及更早：用 npx @next/codemod@latest agents-md 生成，文档会输出到项目根目录的 .next-docs/，生成的指令文件也指向那里。

这个思路不限于 Next.js：AI 对某个库的记忆不可靠时，可以在指令文件里给它指一条查得到的权威资料路径，本地文档、类型声明或官方文档链接都行。

来源​