AGENTS.md 与 CLAUDE.md——AI 编码代理的上下文工程

发表于 2026-04-22 更新于 2026-06-20 分类于 AI Agent

本文为「AI Agent 技术系列」第 6 篇，独立性较强。与前 5 篇聚焦”应用 Agent”不同，本文聚焦”编码代理”的上下文工程。

一、主题定义与背景

问题背景：AI 编码代理的训练数据会过时

AI 编程代理最大的坑不是模型不够聪明，而是训练数据过时。当框架发布新 API 时，代理仍在用半年前的写法生成代码——你 review 的时候才发现全是废的。

典型场景：Next.js 16 发布了 use cache、connection()、forbidden()、cacheLife() / cacheTag() 等新 API，这些不在任何模型的训练数据中。代理会生成错误代码或回退到旧模式 [1]。

AGENTS.md 的正式定义

2025 年 8 月，OpenAI 发布 AGENTS.md [2]：

“AGENTS.md 是一个简单、通用的标准，为 AI 编码代理提供一致的项目特定指南，使其能可靠地运行。它是一个面向 AI 编码代理的 README。”

2025 年 12 月 9 日，OpenAI 和 Anthropic 将 AGENTS.md 捐赠给 Linux 基金会，联合创立 Agentic AI Foundation（AAIF），同时 Anthropic 捐赠 MCP 协议、Block 捐赠 Goose 框架 [2]。

AGENTS.md vs README.md 的定位差异

对比维度	README.md	AGENTS.md
目标受众	人类开发者	AI 编码代理
内容方向	快速入门、贡献指南	构建命令、测试、代码规范
格式	自由格式 Markdown	标准 Markdown，无强制字段
核心定位	面向人类	面向 AI 代理

核心洞察：README.md 面向人类 → AGENTS.md 面向 AI 代理。两者互补，不是替代。

二、核心技术原理与架构设计

2.1 AGENTS.md 生态架构

graph TB
    A[AGENTS.md<br/>开放指令格式]

    A --> B[AI 编码代理]
    A --> C[IDE 与编辑器]
    A --> D[CLI 工具]
    A --> E[其他平台]

    B --> B1[OpenAI Codex]
    B --> B2[Google Jules]
    B --> B3[Factory / Devin]

    C --> C1[VS Code]
    C --> C2[Cursor]
    C --> C3[Zed]
    C --> C4[JetBrains Junie]

    D --> D1[Aider]
    D --> D2[goose]
    D --> D3[Gemini CLI]

    E --> E1[GitHub Copilot Agent]
    E --> E2[Windsurf]
    E --> E3[RooCode]

截至 2026 年，AGENTS.md 已被 60,000+ 开源项目采用，由 Linux 基金会旗下 AAIF 维护，20+ 工具原生支持 [2]。

2.2 CLAUDE.md 四级作用域

CLAUDE.md 有四级作用域，按优先级从低到高：

graph TB
    A["~/.claude/CLAUDE.md<br/>全局 - 所有 Claude 会话"]
    B["./CLAUDE.md<br/>项目根 - 团队共享"]
    C["./CLAUDE.local.md<br/>项目本地 - 个人配置"]
    D["子目录/CLAUDE.md<br/>子目录 - 按需加载"]

    A --> B --> C --> D

作用域	位置	用途	是否提交 Git
全局	`~/.claude/CLAUDE.md`	所有 Claude 会话生效	否
项目根	`./CLAUDE.md`	团队共享的项目配置	是
项目本地	`./CLAUDE.local.md`	个人配置（如偏好）	否（应加入 .gitignore）
子目录	`子目录/CLAUDE.md`	按需加载，就近生效	是

核心原则：每一条内容都问——“删除这条会导致 AI 犯错吗？”如果否，就删掉。臃肿的文件会导致 AI 忽略你的实际指令 [3]。

2.3 内容指南：应该包含 vs 不应包含

✅ 应该包含	❌ 不应包含
AI 无法从代码中推断的命令	AI 通过阅读代码就能明白的内容
与默认不同的代码风格规则	标准语言约定（AI 已知的常识）
测试说明和首选的测试运行器	详细的 API 文档（应链接引用）
仓库规范（分支命名、PR 约定）	频繁变化的信息
项目特有的架构决策	冗长的解释或教程
开发者环境特殊配置	对代码库的逐文件描述

CLAUDE.md 支持 @path/to/file 导入语法，可引用 README.md、package.json 等文件，避免重复维护 [3]。

2.4 快速开始

运行 /init 命令即可基于项目结构自动生成 CLAUDE.md：

# 在 Claude Code 中运行
/init

# 会自动扫描项目结构，生成初始 CLAUDE.md
# 包含：构建命令、测试命令、代码风格、项目结构

三、实际应用场景与最佳实践

场景一：Monorepo 多层级 AGENTS.md 配置

# 根目录 AGENTS.md（全局规则）

## 构建命令
- 安装依赖：`pnpm install`
- 构建所有包：`pnpm build`
- 运行所有测试：`pnpm test`

## 代码风格
- 使用 ESLint + Prettier，配置在根目录
- 提交前运行 `pnpm lint`

## 分支命名
- feature/xxx, fix/xxx, chore/xxx

# packages/frontend/AGENTS.md（前端子包规则）

## 构建
- 开发：`pnpm dev`（Vite dev server）
- 构建：`pnpm build`（输出到 dist/）

## 测试
- 单元测试：`pnpm test`（Vitest）
- E2E 测试：`pnpm test:e2e`（Playwright）

## 注意事项
- 组件使用 PascalCase 命名
- 样式使用 Tailwind CSS v4，不要用内联 style

# packages/backend/AGENTS.md（后端子包规则）

## 构建
- 开发：`pnpm dev`（Nodemon 热重载）
- 构建：`pnpm build`（tsc 编译到 dist/）

## 测试
- 测试：`pnpm test`（Jest）
- 测试覆盖率：`pnpm test:coverage`

## 数据库
- 迁移：`pnpm migrate`
- 回滚：`pnpm migrate:rollback`

Monorepo 中，子包的 AGENTS.md 会就近生效，覆盖根目录的通用规则。案例：OpenAI 主仓库已有 88 个 AGENTS.md 文件 [2]。

场景二：团队级 CLAUDE.md 标准化配置

# CLAUDE.md（项目根，提交到 Git）

## 项目概述
本项目是 RTMP 设计系统前端，基于 Vite + React 18 + TypeScript。

## 构建与测试
- 开发：`yarn dev`
- 构建：`yarn build`
- 测试：`yarn test`
- Lint：`yarn lint`

## 代码风格
- 使用函数组件 + Hooks，不要用 class 组件
- 状态管理用 Zustand，不要引入 Redux
- 样式用 Tailwind CSS v4

## Vite Proxy 配置
- dev-api 代理到 :8080
- oss-api 代理到 :9300
- 详见 vite.config.ts

## 分支与 PR
- 分支：feature/xxx, fix/xxx
- PR 需要 2 个 review
- 提交信息遵循 Conventional Commits

@README.md  # 导入 README 获取更多上下文

Vercel 评估实验详解

2026 年 1 月，Vercel 团队发布了一项关键评估 [1]：

实验设计：测试 AI 编码代理对 Next.js 16 新 API（不在训练数据中）的掌握程度。

四种方案对比：

方案	说明
基线	不提供任何额外文档
Skill	将 Next.js 16 文档打包成技能包
Skill + 指令	技能包 + 明确指令”先调用技能”
AGENTS.md	将压缩的 8KB 文档索引放入 AGENTS.md

评估结果：

指标	基线	Skill	Skill+指令	AGENTS.md
配置	84%	84%	95%	100%
构建	95%	89%	100%	100%
Lint	63%	58%	84%	100%
测试	53%	53%	79%	100%

核心结论：AGENTS.md 100% 通过率 vs Skills 最高 79%，基线仅 53% [1]。

四、常见挑战与解决方案

挑战	表现	解决方案
AGENTS.md 内容膨胀	文件过长导致 AI 忽略指令	精简原则 + 定期修剪（像维护代码一样维护）
Skills 未被可靠触发	56% 的评估案例中技能从未被调用	措辞优化 + 主动提示
Skills 措辞脆弱	“先调用技能” vs “先探索” 差异达 26pp	标准化模板 + A/B 测试
团队配置冲突	不同成员的 CLAUDE.local.md 产生不同行为	全局规则用 CLAUDE.md，个人偏好用 CLAUDE.local.md
文档重复维护	README.md 和 AGENTS.md 内容重复	用 `@README.md` 导入语法

AGENTS.md 三大核心优势

AGENTS.md 100% 通过率的背后是三个机制优势 [1]：

优势	说明	vs Skills
无需决策点	AI 无需判断”我是否应该查这个？”，信息已在上下文中	Skills 需要代理主动决定是否加载
一致的可用性	内容在每个交互回合中都存在于系统提示中，100% 可靠	Skills 是异步加载，只在调用时可用
无顺序问题	被动上下文完全避免了”先读文档还是先探索？”的困境	Skills 产生顺序决策问题

Skills 的两大局限

局限一：技能未被可靠触发

56% 的评估案例中，技能从未被调用。即使代理有文档访问权，也选择不使用。添加技能后与基线相比没有任何改善（均为 53%）[1]。

局限二：措辞极度脆弱

"先调用技能" vs "先探索项目，再调用技能"
→ 细微的措辞变化导致巨大的行为差异（+26pp）

先调用方式：写对了 page.tsx 但漏掉了 next.config.ts 变更
先探索方式：两者都正确

五、行业趋势与前沿进展

AGENTS.md 采用数据更新

截至 2026 年 6 月：

60,000+ 开源项目已采用 AGENTS.md [2]
20+ 工具原生支持（含 OpenAI Codex、Google Jules、Cursor、VS Code、Aider 等）
AAIF 基金会：2025 年 12 月成立，由 OpenAI、Anthropic、Block 联合发起，Google、微软等 30 余家科技公司参与 [2]

AI 编码代理 2025-2026 年最新动态

工具	最新动态
Claude Code	Anthropic 分析了 40 万次 Claude Code 交互数据，验证 CLAUDE.md 的有效性 [4]
OpenAI Codex	AGENTS.md 的首发支持平台
Cursor	原生支持 AGENTS.md，可在项目根目录配置
GitHub Copilot	Agent 模式支持 AGENTS.md
Google Jules	新发布的 AI 编码代理，支持 AGENTS.md

上下文工程（Context Engineering）作为新兴概念

2025-2026 年，”上下文工程”作为概念逐渐成形——它比 Prompt Engineering 更广，涵盖：

提示词工程（狭义上下文）
工具集成（Tools 即上下文的一部分）
文件系统即上下文（AGENTS.md / CLAUDE.md 模式）
多 Agent 间上下文共享（详见系列第 7 篇）

Andrej Karpathy 总结了 CLAUDE.md 的四大核心原则 [5]：

思考优先：让 AI 先理解再行动
简洁至上：避免过度复杂化
精准修改：不擅自修改无关代码
目标驱动：以目标为导向，而非过程

最佳实践总结

场景	推荐方案
构建和测试命令标准化	AGENTS.md
代码风格与架构指南	AGENTS.md
项目级持久上下文	AGENTS.md
Monorepo 多层级指令	AGENTS.md（子包部署）
版本升级（如升级 Next.js）	Skills
架构迁移（如迁移到 App Router）	Skills
框架最佳实践应用	Skills
用户显式触发的特定工作流	Skills