---
title: 第 6 章 上下文工程：以 AGENTS.md 为唯一规则源
seo:
  title: "上下文工程与 AGENTS.md 最佳实践"
description: "详细讲解如何统一维护项目规则，以 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 示例

```markdown
# 项目目标
- 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，不要全量粘贴。

- 大型仓库按模块启动会话，让当前工作目录和嵌套规则自然缩小范围。