给智能体写项目说明：CLAUDE.md、AGENTS.md 与 Cursor Rules

智能体不会记得上一次对话。每开一个新会话，它都要重新摸索：用 npm 还是 pnpm、测试怎么跑、哪些目录不能动。项目说明文件就是写给它的入职文档，每次会话开始时自动读取。

三家的约定

几个值得注意的细节：

• Codex 从根目录向下合并所有 AGENTS.md，离当前目录越近的越靠后，所以子目录的说明会覆盖上层的。合并后默认最多 32 KiB，超出的部分不会加载
• Claude Code 在工作目录和上级目录里找不到 CLAUDE.md 时，会直接读 AGENTS.md（v2.1.277 起）；两个都有时默认只读 CLAUDE.md
• Cursor 的项目规则必须是 .mdc 扩展名，.cursor/rules 里的普通 .md 文件会被忽略

完整规则见 Claude Code：记忆与 CLAUDE.md、Codex：AGENTS.md 和 Cursor：Rules。

多个智能体共用一份

团队里有人用 Claude Code、有人用 Codex 或 Cursor，最省事的做法是以 AGENTS.md 为准：Codex 和 Cursor 直接读它，Claude Code 在没有 CLAUDE.md 时也会读它。

如果还有只给 Claude Code 的内容，在 CLAUDE.md 里导入 AGENTS.md，再在下面补充：

@AGENTS.md

## Claude Code

修改 `src/billing/` 下的代码前先进入计划模式。

这样共用的内容只维护一份，不会两边改着改着就对不上。

该写什么

只写每次会话都该知道、又没法从代码里直接看出来的事：

## 命令
- 安装依赖：`pnpm install`（不要用 npm）
- 提交前必须通过：`pnpm check` 和 `pnpm test`

## 结构
- 接口处理函数放 `src/api/handlers/`，一个资源一个文件
- `src/generated/` 是生成的代码，不要手改，改完 schema 后运行 `pnpm codegen`

## 约定
- 新增环境变量时同时更新 `.env.example`
- 数据库迁移只能新增，不能修改已经合并的迁移文件

写法上有三个原则（来自 Claude Code 官方的建议，对其他智能体同样适用）：

• 具体到可以验证：写「提交前运行 pnpm test」，不写「注意测试」；写「两个空格缩进」，不写「保持代码整洁」
• 短：Claude Code 建议每个文件控制在 200 行以内。越长越占上下文，遵守度也越低
• 不矛盾：两条说明冲突时，智能体可能随便选一条。定期清理过时的内容

不该写什么

• 常识：智能体已经知道 git、npm、pytest 怎么用，不用解释
• 完整的风格指南：交给 linter 和 formatter，比写在说明里更可靠
• 多步骤流程：比如发版步骤、代码评审清单。它们只在特定时候用到，却每次都占上下文，更适合写成 Skill，需要时再加载
• 必须百分之百执行的规则：项目说明是上下文，不是强制配置。真正不能违反的（比如禁止修改某个目录），用 Claude Code 的 Hook 或 CI 检查来保证

什么时候该更新

Claude Code 文档给了一个实用的信号：同一个纠正你说了第二遍，就该写进项目说明。比如智能体第二次用了 npm、第二次忘了跑类型检查，或者代码评审指出了它本该知道的约定。

刚开始可以让智能体自己起草：Claude Code 运行 /init，会分析代码库并生成一份起始的 CLAUDE.md，已有文件时会给出改进建议而不是覆盖。生成后逐条删改，留下真正有用的部分。