第 6 章上下文工程：以 AGENTS.md 为唯一规则源

详细讲解如何统一维护项目规则，以 AGENTS.md 作为唯一事实源，分离配置与规则的最佳实践、团队协作方案以及多工具协作方式。

不要把长期经验留在聊天里，也不要维护两套相互复制的规则。团队只编辑 AGENTS.md；CLAUDE.md 只负责引用同目录的 AGENTS.md。

6.1 只维护 AGENTS.md：CLAUDE.md 只做兼容引用

层级	唯一规则源	CLAUDE.md 写法	维护原则
仓库根	`./AGENTS.md`	`@AGENTS.md`	所有跨工具规则只改 AGENTS.md
目录模块	`module/AGENTS.md`	`@AGENTS.md`	模块例外靠近代码，不复制到根目录
临时覆盖	`AGENTS.override.md`	不另写规则	仅用于明确覆盖，结束后清理
工具配置	不放业务规则	`.claude/settings.json`	配置与规则分离
可复用流程	`.agents/skills/`	按需调用 Skill	流程进 Skill，项目边界留在 AGENTS.md

资料依据：Anthropic Memory / Settings；OpenAI AGENTS.md / Config Basics。

6.2 AGENTS.md 的加载层级

Codex 会加载用户级规则，再从仓库根沿目录层级读取到当前工作目录。
在同一目录中，`AGENTS.override.md` 用于覆盖普通 `AGENTS.md`。
将特殊模块规则放在靠近该模块的位置；例如 payments 目录只放支付特定规则。
代码审查规则可以写入离目标代码最近的 `## Code Review Rules`。
已有团队手册文件时，可在配置中设置 fallback 文件名，但仍需控制最大读取体积。

资料依据：OpenAI Custom instructions with AGENTS.md。

6.3 团队单一事实源：AGENTS.md 负责内容，CLAUDE.md 只负责引用

一个事实源，一条兼容引用：项目规则只维护在 AGENTS.md。同目录 CLAUDE.md 只写一行 @AGENTS.md，不再复制命令、边界或验证要求；工具特有设置分别放入 .claude/ 与 .codex/。

双工具项目建议目录：

repo/
├── AGENTS.md # 唯一规则源：命令、边界、验证、发布
├── CLAUDE.md # 仅一行：@AGENTS.md
├── .claude/
│ ├── settings.json # Claude Code 特有配置
│ └── skills/
├── .codex/
│ └── config.toml # Codex 特有配置
├── .agents/
│ └── skills/ # 跨工具可复用流程
└── module/
    ├── AGENTS.md # 模块规则
    └── CLAUDE.md # 仅一行：@AGENTS.md

6.4 什么应该写，什么不应该写

类别	应该写	不要写
项目目标	业务边界、核心流程、关键术语	整份 PRD 或官网文案全文
唯一命令	dev / test / lint / typecheck / build / migrate	Agent 能从 package.json 稳定读出的无关细节
架构不变量	模块职责、API 约定、状态与数据边界	“遵循最佳实践”这类空话
风险边界	不能改什么、必须先确认什么、替代动作	只有禁止，没有安全路径
常见坑	迁移顺序、生成代码、重启条件、平台差异	每周变化且无人维护的版本清单
验证要求	功能、异常、权限、性能、回归与证据	只写“确保没问题”

6.5 精简 AGENTS.md 示例

# 项目目标
- B2B 采购与排产后台；核心链路：需求 -> 计划 -> 审批 -> 执行 -> 复盘
- 默认开发分支：develop；main 仅发布

# 必读
- 先阅读当前模块 SPEC 与 README

# 唯一正确命令
- dev: pnpm dev
- test: pnpm test
- typecheck: pnpm typecheck
- lint: pnpm lint
- build: pnpm build

# 实施约束
- 新增依赖先说明用途、许可证和替代方案
- 数据库只生成迁移，不自动执行生产变更

# 验证
- 完成前输出测试证据、剩余风险和回滚步骤

6.6 配置与规则分开

内容	放规则文件	放配置文件
业务目标、架构边界	是	否
模型、reasoning、UI 行为	少量说明	是
权限白名单、Hook、MCP server	只写治理原则	是
测试命令与验收	是	可由 Hook / CI 调用
个人偏好	用户级规则	用户级配置
组织强制策略	仓库规则 + 管理文档	管理员配置 / 设备策略

6.7 规则维护飞轮

1. 第一次做任务时不要预写十页规则，先观察真实错误。

2. 每个可复现错误只补一条能防住下次的最小规则。

3. 规则必须指向文件、目录、命令、验证或替代动作。

4. 同一句流程说明出现三次，升级为 Skill；必须每次执行的动作升级为 Hook / CI。

5. 每月做一次规则瘦身：删除过时、重复、互相矛盾和无法验证的条目。

6.8 上下文预算与渐进披露

规则文件只装“不可猜、猜错会返工”的信息；大文档通过索引与引用按需读取。
Skill 使用 name / description 做轻量发现，真正触发时才加载完整 SKILL.md；描述必须清晰且边界明确。
长日志先用命令筛选关键时间、错误码和请求 ID，再交给 Agent，不要全量粘贴。
大型仓库按模块启动会话，让当前工作目录和嵌套规则自然缩小范围。

第 6 章 上下文工程：以 AGENTS.md 为唯一规则源

第 6 章上下文工程：以 AGENTS.md 为唯一规则源