每次都要重复说明时先建规则文件
如果你每次打开 AI Agent 都要重新说“这个仓库只能用 pnpm”“不要改生成文件”“改完要报告验证命令”，项目已经缺少规则文件了。
AI Agent 没有稳定项目记忆时，会按通用经验办事。通用经验在真实仓库里经常不够用。包管理器、测试命令、目录边界、不能碰的文件、部署禁区，都应该写成项目规则。
选择 AGENTS.md 还是 CLAUDE.md
Codex 读取 `AGENTS.md`。Claude Code 读取 `CLAUDE.md`。你同时使用两个工具时，可以让两份文件共享相同的工程规则，再保留各自工具需要的细节。
不要把规则文件写成项目介绍。Agent 不需要读一篇品牌故事。它需要知道怎么改、怎么验、哪里不能碰。
| AGENTS.md | 给 Codex 的项目规则 |
| CLAUDE.md | 给 Claude Code 的项目记忆 |
| settings.json | 放权限、环境变量或团队可共享配置 |
| settings.local.json | 放个人机器差异和本地实验 |
先写包管理器和验证命令
第一版规则文件不要长。先写能拦住错误的内容：包管理器、验证命令、禁止操作、修改范围、交付格式。
如果一条规则不能改变 Agent 的行为，就先别写。比如“代码要高质量”没有用。“不要改 public API，除非任务明确要求”更有用。
# Project Rules
Commands:
- pnpm run lint
- pnpm run typecheck
- pnpm run build
Rules:
- Use pnpm only.
- Keep edits scoped to the requested task.
- Read relevant files before editing.
- Do not edit generated files manually.
- Do not change package versions unless the task requires it.
- Protect user changes in the working tree.
Done means:
- Report changed files.
- Report commands run and results.
- Mention checks that were not run.把高风险动作写进禁止项
Agent 最容易翻车的地方，通常不是它不会写代码，而是它不知道哪些动作在这个项目里代价很高。你要把这些动作写成硬边界。
常见禁止项可以这样写：
这些规则不需要解释成一篇长文。短句更适合 Agent 执行。
- 不要创建 `package-lock.json` 或 `yarn.lock`
- 不要把真实 API Key 写进代码、日志或文档
- 不要手动编辑构建产物
- 不要顺手升级依赖
- 不要重构任务外模块
- 不要覆盖用户未提交改动
每次翻车只补一条规则
规则文件不需要一次写完。更好的方式是从失败里补规则。
比如 Agent 曾经用 npm 安装依赖，就补“Use pnpm only”。它曾经顺手改样式，就补“Do not refactor unrelated UI”。它曾经只说“已完成”，就补“Report commands run and results”。
一次失败只补一条具体规则。别把同一次事故写成一段复盘散文。
删掉不会影响行为的背景
`AGENTS.md` 和 `CLAUDE.md` 不是仓库百科。太长的规则会稀释重点，也会占上下文。
这些内容不适合放进去：
规则文件只保存稳定约束。会变化的信息，放到文档链接、脚本或外部系统里。
- 长篇业务背景
- 已经过期的命令
- 个人情绪化提醒
- 与当前仓库无关的通用 AI 技巧
- 需要实时查询的外部状态
大仓库按目录拆规则
项目变大后，根目录规则写通用约束，子目录规则写局部约束。前端、后端、内容、部署脚本经常需要不同规则。
这样做能让 Agent 在改具体目录时读到更近的规则，也能避免根目录文件越来越长。
AGENTS.md
apps/web/AGENTS.md
packages/api/AGENTS.md
content/AGENTS.md
scripts/AGENTS.md用一个小任务确认规则生效
规则文件写好后，不要马上交给 Agent 做大改。先用低风险任务验证它是否读到了规则。
比如让它只改一处文案、补一个小测试、检查一篇文章 frontmatter。重点不是任务本身，而是看它有没有遵守包管理器、修改范围和验证报告。
请做一个低风险验证任务：
1. 先说明你读到的项目规则
2. 只修改一个我指定的文件
3. 不运行未授权的命令
4. 最后报告 changed files 和未运行的检查项目规则至少包含这些项
你的项目至少需要这些规则：
- 使用哪个包管理器
- 常用验证命令是什么
- 哪些文件不能读或不能改
- 任务外重构是否禁止
- 如何处理用户已有改动
- 改完必须报告哪些验证证据