给智能体写项目说明：CLAUDE.md、AGENTS.md 与规则文件

这篇适合谁

这篇适合在真实项目里用编码智能体、希望它每次都守同一套约定的开发者。文章讲四种常见的说明文件格式、怎样写出智能体真正能执行的说明，以及我们在自己的文件里写了什么。

说明文件为什么要有

智能体每开一次会话，都不记得你的项目。说明文件就是填补这一空白的东西。Claude Code 有两套互补的记忆系统：CLAUDE.md 文件和自动记忆。两者都会在每次对话开始时加载，Claude 把它们当作上下文，而不是强制执行的配置。^[2] ## Claude Code 的 CLAUDE.md

CLAUDE.md 是一份持久指令文件，可以针对项目、你个人的工作方式，或整个组织。它是纯文本的 Markdown，Claude 在每次会话开始时读取。^[2]

它有几个位置，按照从宽到窄的顺序加载，所以项目说明会排在用户说明之后。托管策略文件在 macOS 上是 /Library/Application Support/ClaudeCode/CLAUDE.md，在 Linux 和 WSL 上是 /etc/claude-code/CLAUDE.md，在 Windows 上是 C:\Program Files\ClaudeCode\CLAUDE.md。用户说明在 ~/.claude/CLAUDE.md，项目说明在 ./CLAUDE.md 或 ./.claude/CLAUDE.md，本地说明在 ./CLAUDE.local.md。^[2]

Claude Code 会加载当前目录及其上层所有目录里的 CLAUDE.md 和 CLAUDE.local.md，把找到的文件全部拼接起来，而不是后者覆盖前者。子目录里的文件则是按需加载的，等 Claude 读取、写入或编辑了那个子目录里的文件之后才会加载。^[2]

想要一份起始版本，可以运行 /init。Claude 会分析代码库，生成包含构建命令、测试说明和项目约定的文件。^[2]

项目大了，说明可以拆开。.claude/rules/ 里的 Markdown 文件会被递归发现；没有 paths 字段的规则在启动时加载，优先级与 .claude/CLAUDE.md 相同。paths 是 Claude Code 唯一会读取的 frontmatter 字段。~/.claude/rules/ 里的个人规则则对本机的每个项目都生效。^[2]

AGENTS.md：通用的格式

AGENTS.md 是一种指导编码智能体的开放格式。它的网站称它为智能体的 README，是一个可预期的地方，用来放帮助智能体理解项目的上下文和指令。^[5] 它由 Linux 基金会旗下的 Agentic AI Foundation 维护，网站列出的支持工具包括 Codex、Jules、Cursor、Gemini CLI 和 GitHub Copilot 编码智能体。^[5]

创建它的方法是在仓库根目录放一个 AGENTS.md 文件。没有必填字段，它就是普通的 Markdown，标题随便写，智能体直接解析文本。^[5] 网站建议写清项目概述、构建和测试命令、代码风格、测试说明和安全注意事项。提交信息规范、部署步骤和安全上的坑也很常见。^[5]

Claude Code 把 AGENTS.md 当作项目说明来读，但前提是工作目录或其上层没有 CLAUDE.md 或 CLAUDE.local.md。直接读取 AGENTS.md 需要 Claude Code v2.1.277 或更新版本。^[2] 文档提到，多数用户只需要编辑 CLAUDE.md 和 settings.json。如果仓库里已经有给其他编码智能体用的 AGENTS.md，Claude Code 可以用它代替 CLAUDE.md。^[3]

Codex 在开始工作前会读取 AGENTS.md。在全局层面，它读取 Codex 主目录中的 AGENTS.override.md，没有的话读 AGENTS.md。主目录默认是 ~/.codex，除非设置了 CODEX_HOME。同一层级只使用第一个非空文件。^[6]

在项目层面，Codex 从项目根目录（通常是 Git 根目录）一路走到当前目录。每个目录依次检查 AGENTS.override.md、AGENTS.md，以及 project_doc_fallback_filenames 里的备用文件名，每个目录最多包含一个文件。它从根目录向下拼接文件，用空行连接，离当前目录越近的文件越能覆盖前面的指导。合并后的大小达到 project_doc_max_bytes（默认 32 KiB）后，就不再增加文件。^[6]

对于 monorepo，网站建议在每个包里放嵌套的 AGENTS.md。智能体读取目录树中最近的那个文件，因此离得最近的文件优先，每个子项目都能带自己的指令。指令发生冲突时，离被编辑文件最近的 AGENTS.md 胜出；明确的聊天提示则压过所有文件。^[5]

Cursor 规则

Cursor 把指令分成四类：存放在 .cursor/rules 里的项目规则（Project Rules）、适用于整个 Cursor 环境的用户规则（User Rules）、在控制台里管理的团队规则（Team Rules），以及 AGENTS.md。^[7]

项目规则是 .cursor/rules 里的 .mdc 文件，可以纳入版本控制。该目录下的普通 .md 文件会被规则系统忽略，因为它没有用来声明 description、globs 和 alwaysApply 的 frontmatter。^[7] 每条规则的类型决定它何时生效：Always Apply 对每次聊天都生效；Apply Intelligently 由智能体根据描述判断是否相关；Apply to Specific Files 在文件匹配指定模式时生效；Apply Manually 则在聊天里 @ 提到它时生效。^[7]

Cursor 同样支持项目根目录和子目录中的 AGENTS.md。嵌套的文件在你处理其目录或下级目录的文件时生效，更具体的指令优先。^[7] Cursor 的规则质量建议：规则控制在 500 行以内，大规则拆成可组合的小规则，避免含糊的指导。能用 linter 强制的风格规范不要整段复制，不要记录所有可能的命令，也不要重复代码库里已经能看到的内容。^[7]

Gemini CLI 的 GEMINI.md

Gemini CLI 把 GEMINI.md 作为默认的上下文文件，用来提供项目相关的指令、人设，或者编码风格指南。^[8]

Gemini CLI 会从几个位置加载上下文文件，把找到的内容全部拼接起来，然后随每个提示一起发送给模型。全局文件是 ~/.gemini/GEMINI.md。环境和工作区上下文文件来自配置的工作区目录及其父目录。 文件太大时，可以用 @file.md 导入语法拆分，它支持相对路径和绝对路径。settings.json 里的 context.fileName 可以改用别的文件名，也可以列出多个名字，比如 ["AGENTS.md", "CONTEXT.md", "GEMINI.md"]。^[8]

一个为 TypeScript 库写的最小 GEMINI.md 示例如下：^[8]

# Project: My TypeScript Library

## General Instructions

- When you generate new TypeScript code, follow the existing coding style.
- Ensure all new functions and classes have JSDoc comments.
- Prefer functional programming paradigms where appropriate.

## Coding Style

- Use 2 spaces for indentation.
- Prefix interface names with `I` (for example, `IUserService`).
- Always use strict equality (`===` and `!==`).

怎样写出智能体能照做的说明

Claude Code 的建议是：把 CLAUDE.md 当作你每次会话都要重复解释的内容的归宿。只放智能体每次会话都应该知道的事实，比如构建命令、约定、项目结构和必须遵守的规则。多步骤的流程，或只与代码库某一部分相关的规则，应该放进技能（skill）或按路径限定的规则里。^[2]

说明要具体到能检查。“使用 2 个空格缩进”可以验证，“格式要规范”不行。“提交前运行 npm test”是可执行的，“测试你的改动”则不是。每个 CLAUDE.md 控制在 200 行以内，因为更长的文件会占用更多上下文，遵守程度也会下降。^[2]

TellWorld 的 CLAUDE.md 怎么写

TellWorld 有两份说明文件：一份是适用于所有项目的用户级文件，另一份是项目级文件，写的是本项目的约定。项目文件把同时运行的子 agent 数量上限定为 3 个，并要求前面的全部跑完后再启动新的。^[1] 它要求把固定流程的工作，比如核对资料、转换格式和批量改写，交给更便宜的 Haiku 模型；只有需要深度判断的任务才使用更贵的模型。^[1]

项目文件里还记录了队列的接手规则。负责整理资料的应用超过约 30 分钟没有更新文件时，Claude 可以接手队列里的任务，但要先在队列文件里把它标记为“进行中（Claude）”。^[1]

用户级文件有两条长期规则。一条是关于代码注释：只写代码本身看不出来的内容，比如数字从哪来、外部契约是什么、踩过什么坑。另一条固定了分支命名规则，并规定不同的 Git 托管平台用哪个命令行工具，这样智能体就不必每次都来问。^[1]

限制和常见问题

说明是上下文，不是强制执行。Claude 不一定完美遵守每条规则，所以必须成立的事情，比如权限或禁止的命令，应该写进设置或 hooks，而不是只写在说明文字里。^[2][4]

存在多个文件时，冲突很容易出现。Gemini CLI 会拼接所有找到的文件，Claude Code 拼接 CLAUDE.md 文件，Codex 和 Cursor 则各有自己的优先级规则。在假定某条规则生效之前，先确认哪些文件被加载了。^[2][6][7][8]

下一步

读 Claude Code 的记忆页面，可以了解这些文件如何加载；.claude 目录页面则说明每个文件放在哪里。^[2][3] 设置和优先级读设置页面。^[4] Codex 的查找顺序读 AGENTS.md 指南。^[6] Cursor 和 Gemini CLI 的规则与上下文文件，分别读它们的页面。^[7][8]