AGENTS.md 工程实践：基于 ETH 研究的上下文配置指南

AI 编码助手正在改变软件开发的工作流程，但一个核心问题始终存在：如何让 Claude Code、Cursor、GitHub Copilot 等工具真正理解你的项目？AGENTS.md 作为一种轻量级的 Markdown 配置文件，正在成为跨工具的标准解决方案。本文基于 ETH Zurich 的实证研究，探讨如何构建高效的 AGENTS.md 文件，在提升代码质量的同时控制推理成本。

为什么需要 AGENTS.md

在 AGENTS.md 出现之前，团队往往为不同工具维护多套配置文件：CLAUDE.md、.cursorrules、copilot-instructions.md 等。这些文件内容高度重复，却逐渐分道扬镳。AGENTS.md 的定位很明确：它是面向 AI 编码助手的 README，提供项目特定的构建命令、代码规范、测试规则和约束条件 —— 这些都是 AI 无法从代码库本身推断出的关键信息。

ETH Zurich 的研究团队对多个编码助手和 LLM 进行了系统评估，对比了 LLM 生成与开发者编写的上下文文件效果。研究结果揭示了一个反直觉的发现：LLM 自动生成的配置文件在 8 个测试设置中的 5 个降低了任务成功率，同时使推理成本增加 20% 至 23%。原因在于这些自动生成的文件往往重复了 AI 已经能够从现有文档中独立获取的信息，造成了冗余而非增值。

核心原则：只写非推断性细节

有效 AGENTS.md 的第一原则是极简主义。研究者发现，当从代码库中移除所有其他文档后，LLM 生成的文件反而带来了 2.7% 的性能提升。这验证了关键洞察：配置文件应该只包含 AI 无法自行发现的内容。

应该包含的内容：自定义构建命令、特定工具选择（如使用 Pixi 而非 pip）、非标准的代码模式、版本约束、安全边界。

应该避免的内容：代码库架构概述、已存在于 README 的信息、通用的编程最佳实践、框架默认约定。

一个典型的反例是详细的 "架构" 章节。研究表明，移除架构描述而保留命令、约束和非标准模式后，AI 的行为保持不变，但 token 消耗显著降低。

六大关键章节与可落地模板

基于 OpenAI 文档、GitHub 对 2500 多个仓库的分析以及生产实践，以下六个章节能够系统性地提升 AI 编码助手的表现：

1. 技术栈定义（含精确版本）

没有版本约束时，AI 会默认使用训练数据中最常见的 API 约定。明确指定版本可以避免这类问题：

## Stack
- Node.js 20.x (LTS)
- TypeScript 5.3+ with strict mode
- React 18 with hooks pattern
- PostgreSQL 15 with pg-promise (not Sequelize)

2. 可执行命令（带完整参数）

将命令放在文件靠前位置，AI 会在任务中反复引用。优先配置单文件范围的命令而非全项目构建：

## Commands
# Type check single file
npm run tsc --noEmit path/to/file.tsx

# Lint and fix single file
npm run eslint --fix path/to/file.tsx

# Run specific test
npm run vitest run path/to/file.test.tsx

# Full build (use sparingly)
npm run build:prod

3. 代码规范与模式

用真实代码片段展示风格，而非抽象描述。最有价值的规范是那些 "违反直觉" 的约定：

## Patterns
- API client in `app/api/client.ts` never throws; check `response.ok`
- Use emotion `css={{}}` prop format, not styled-components
- State management: MobX with `useLocalStore`, not Redux
- Design tokens from `DynamicStyles.tsx`, no hard-coded colors

4. 测试规则

明确测试框架、覆盖率要求和测试策略：

## Testing
- Jest for unit tests, Cypress for E2E
- Aim for 80%+ coverage on new logic
- Write failing test first for regressions, then fix
- Mock external APIs in `__mocks__/`

5. "禁止触碰" 区域与权限边界

设置明确的安全边界，使用三级优先级系统处理规则冲突：

## Safety & Permissions

CRITICAL (never override):
- Never commit secrets or .env files
- Never modify `vendor/` or `generated/` directories

HIGH (ask first):
- Package installations
- Git push to protected branches
- File deletions or permission changes

STANDARD (allowed):
- Read files, list directories
- Single file lint/typecheck/test

6. 非标准工具说明

AGENTS.md 对训练数据中代表性不足的工具 ROI 最高。对于 npm、pytest、cargo 等标准工具，AI 已经了解约定，无需重复说明。

层级化配置与模块化策略

单一根目录文件在 150-200 行以内是高效的。超过这个阈值，应考虑拆分为模块化结构：

project-root/
├── AGENTS.md          # 全局规则
├── frontend/
│   └── AGENTS.md      # 前端特定规则
└── backend/
    └── AGENTS.md      # 后端特定规则

根据 Codex 规范，更深层的文件在规则冲突时优先。这种层级化设计允许不同包独立演进，同时保持整体一致性。

对于跨切面关注点（安全、测试、CI），Cursor 的 .cursor/rules/ 系统支持使用 YAML frontmatter 按 glob 模式限定规则范围：

---
glob: "**/*.test.ts"
---
# Test-specific rules
- Use descriptive test names
- One assertion per test when possible

成本效益分析与优化

使用 AGENTS.md 会带来可量化的推理成本增加。以 Claude Sonnet 4.6 定价（输入 $3/MTok，输出 $15/MTok）和典型任务（50K 输入 + 5K 输出）计算：

关键优化策略是 prompt caching：缓存读取比标准输入定价便宜 90%。将 AGENTS.md 保持在稳定状态并启用缓存，可以大幅降低开销。

更重要的是成本效益权衡：人工编写的文件带来约 4 个百分点的成功率提升，而 LLM 生成的文件在增加成本的同时降低性能。手动编写是值得的投资。

维护策略与常见陷阱

AGENTS.md 的最大挑战不是编写，而是维护。随着代码库演进，配置文件会过时，而过时的结构引用会主动误导 AI。

维护建议：

• 将 AGENTS.md 纳入版本控制，像代码一样审查变更
• 关键规则放在文件靠前位置，避免 "中间丢失" 现象
• 新任务开启新会话，防止长上下文中的规则遗忘
• 基于观察到的失败添加规则，而非推测性生成

常见陷阱：

• 规则膨胀：每次 AI 犯错就添加新规则，很少删除，导致文件臃肿、规则矛盾
• 过度工程：从基础规则开始，逐步扩展
• 配置漂移：多个工具使用时，通过符号链接保持文件同步

对于大型组织，可以考虑 Intent 等工具的 "活规范" 方案：AI 在完成工作时自动更新规范，解决手动 AGENTS.md 无法规模化解决的时效性问题。

结语

AGENTS.md 不是万能的，但在正确的约束下能显著提升 AI 编码助手的效果。核心在于聚焦非推断性细节：那些 AI 无法从代码库独立发现、但对正确工作至关重要的信息。从命令、边界和违反直觉的架构决策开始，保持文件精简，随着实践迭代优化。

参考来源：

• ETH Zurich 研究：Configuring Agentic AI Coding Tools (arXiv:2602.11988)
• Augment Code 指南：How to Build Your AGENTS.md (2026)
• OpenAI Codex 文档：developers.openai.com/codex/guides/agents-md

ai-systems