AGENTS.md as Agent Contract
What it is
AGENTS.md（或 CLAUDE.md）是项目根目录下的一份结构化文档，定义 Agent 在该项目中的行为契约：工具使用规则、上下文边界、输出格式、安全约束。它从"给 Agent 的提示词"进化为"代码化的 Agent 配置"——可被版本控制、可被测试、可被复用。
Why it matters
- Voxyz_ai 的 10 lessons（162K star）将 AGENTS.md 列为多 Agent 项目的首要实践
- Karpathy 的模板被社区大量引用，形成事实标准
- 从 prompt 到 contract：AGENTS.md 不是"建议"而是"约束"——Agent 偏离时可以被检测和纠正
核心要素
| 要素 | 作用 | 示例 |
|---|---|---|
| 工具白名单 | 明确允许/禁止的工具 | "禁止执行 rm -rf" |
| 上下文边界 | 定义 Agent 的知识范围 | "只读取 src/ 目录" |
| 输出格式 | 标准化输出结构 | "所有回复必须包含 confidence 字段" |
| 决策日志 | 记录 Agent 的关键决策 | "每次工具调用需记录理由" |
| 人类接管触发器 | 定义何时暂停等待人类 | "涉及资金操作时必须暂停" |
与 CLAUDE.md 的关系
CLAUDE.md 是 Claude Code 的原生实现，AGENTS.md 是通用化标准。两者正在收敛：
- Claude Code 读取 CLAUDE.md
- 其他 Agent 框架（Cursor, Codex, Aider）开始支持 AGENTS.md
- 未来可能形成统一的 Agent 契约标准
工程实践
- 版本控制：AGENTS.md 与代码同级版本管理
- CI 测试：自动验证 Agent 是否遵守契约（如"是否调用了禁止的工具"）
- 项目模板：为新项目提供 AGENTS.md 模板，降低配置成本
- 组织级标准：团队/公司级别的 AGENTS.md 模板，确保一致性
Open questions
- AGENTS.md 是否应该成为行业标准（类似 .editorconfig）？
- 当 Agent 能力足够强时，AGENTS.md 是约束还是浪费？
- 多 Agent 协作时，每个 Agent 的契约如何协调？
Related
- claude-code/claude-code-knowledge-management — Claude Code 的知识管理
- claude-code/overview — Claude Code 核心概念
- harness-engineering/overview — Harness Engineering 框架
- harness-engineering/agent-trust-verification — Agent 信任验证