Agent 配置文件工程化 2026：从 CLAUDE.md 到 AGENTS.md 的 spec-driven 开发范式
当 Anthropic 推出 CLAUDE.md、Cline 推出 AGENTS.md、Cursor 推出 .cursorrules 时，spec-driven 开发正在重写 AI 编程的工程边界——本文拆解 5 套主流 schema、团队共享机制与 token 成本的真实博弈。
约 18 分钟阅读5,137 字77 次阅读博主
当 Anthropic 推出 CLAUDE.md、Cline 推出 AGENTS.md、Cursor 推出 .cursorrules 时，spec-driven 开发正在重写 AI 编程的工程边界——本文拆解 5 套主流 schema、团队共享机制与 token 成本的真实博弈。
一句话摘要：当 Anthropic 推出 CLAUDE.md、Cline 推出 AGENTS.md、Cursor 推出 .cursorrules 时，spec-driven 开发正在重写 AI 编程的工程边界——本文拆解 5 套主流 schema、团队共享机制与 token 成本的真实博弈。
2024 年开发者与 LLM 协作的默认形态是"在 chat 框里手敲一段 prompt"——临时、不可版本化、无法在团队内复用。2025 年下半年开始，主流 AI 编程工具陆续引入项目级声明式配置文件作为 Agent 行为的事实契约：把 prompt 提升为可被 Git 追踪、可被 CI 校验、可被多人协作编辑的工程制品。
这一转移的工程意义远大于"换了一种写法"。一个 3000 行的代码库，开发者不再需要在每次开新会话时重复描述"项目用 pnpm、测试用 vitest、commit message 遵循 conventional commits"——这些规范被固化在仓库根目录的 CLAUDE.md 或 AGENTS.md 里，Agent 启动时一次性加载，作为整个会话的全局约束。
图表加载中…
配置文件作为"工程制品"的核心价值可以用一个简化的成本函数来刻画。设单次 Agent 会话平均轮数为 ，单轮 prompt 中需要重复的规范信息量为 （字节），无配置文件时单次会话重复成本为 ；引入配置文件后，加载开销 是固定的（通常在 1-3KB 之间），重复成本下降为 。则配置文件的投资回报条件为：
当 且 时，配置文件在第二轮之后就回本。考虑到真实项目里 通常在 5-15KB 区间， 经常超过 10 轮——配置文件的工程经济性是压倒性的。
截至 2026 年 6 月，市面上并存至少 5 套有实际部署量的 Agent 配置文件规范。下表从 schema 设计哲学、信息承载能力、工具支持广度三个维度对比：
| 配置文件 | 发起方 | 加载位置 | 核心字段 | 工具支持 |
|---|---|---|---|---|
CLAUDE.md | Anthropic | 仓库根 + 各级子目录 | 自然语言段落 + 工具权限声明 | Claude Code, Cursor（部分） |
AGENTS.md | Cline 社区 + 逐渐开放标准 | 仓库根 | 任务边界 + 子 Agent 调度 | Cline, Continue, Roo Code |
.cursorrules | Cursor | 仓库根 + .cursor/rules/*.mdc | 全局规则 + 上下文片段 | Cursor |
copilot-instructions.md | GitHub | .github/ 目录 | 路径相关指令（path-specific） | Copilot Workspace, Copilot Chat |
.clinerules / .roo/ | Cline 衍生态 | 工作区根 | 工作流模板 + 权限矩阵 | Cline, Roo Code |
关键差异在于 schema 的结构化程度。CLAUDE.md 本质上是"自由格式的 Markdown + 几条 Anthropic 约定的 hint 段落"（如 # Tools 段、# Workflow 段），schema 是软约束；AGENTS.md 引入了结构化 YAML frontmatter，把任务边界、子 Agent 关系、工具白名单写成可被解析的字段；.cursorrules 走的是中间路线——主文件是自由格式 Markdown，但支持 .cursor/rules/ 下挂多个 .mdc 文件并以 glob 模式做 path-specific 触发。
伪代码示例：在 Cursor 中实现 path-specific 规则加载：
// .cursor/rules/frontend-component.mdc
---
description: "React 组件编写规范"
globs: ["src/components/**/*.tsx"]
alwaysApply: false
---
// 规则正文
- 所有组件必须用 function 声明而非 arrow function
- props 用 interface 而非 type 定义
- 禁止在 component 内直接调用 fetch，改为通过 useSWR
这条规则只在 src/components/**/*.tsx 路径下被加载，对其他文件零干扰——这是 path-specific 配置文件的关键工程价值：按上下文按需加载，token 预算可控。
配置文件的"加载时机"和"加载策略"是 spec-driven 范式里最容易被低估的工程细节。不同工具的策略差异巨大：
CLAUDE.md（全量），子目录有同名文件会叠加加载。这意味着一个 monorepo 仓库如果每个子包都有自己的 CLAUDE.md，最终加载量可能达到 10-20KB——在长会话里会被反复加进上下文窗口。.cursorrules 全量加载，.cursor/rules/*.mdc 按 globs 模式懒加载。后者的设计更精细，但用户必须显式理解 glob 语法。imports 字段把多个配置文件组合成"配置集"，类似 ESM 的模块化。最大好处是可复用——团队可以把通用规范放在 common.md，业务规范放在 business.md，在项目级 AGENTS.md 里 import 两份。.github/ 下并显式声明 applies-to 路径。加载策略的工程影响可以用下面的 token 消耗模型刻画。设 Agent 上下文窗口为 ，配置加载量为 ，单次工具调用平均上下文增长 ：
当 从 1KB 增长到 15KB，对话轮数会减少约 7-10 轮（按 估算）。这意味着配置文件不是越大越好——一个 30KB 的"完美规范文档"实际上会让 Agent 的有效工作能力下降 30% 以上。
工程实践的经验法则：
即配置文件总量应控制在上下文窗口的 2-5% 区间。在 200K 上下文窗口的工具（如 Claude Code）里，这意味着 ；在 8K 上下文窗口的工具里则压缩到 字节。
配置文件作为"团队契约"的最大工程突破是它可被 Git 追踪。这意味着：
AGENTS.md 加了一条"禁止使用 lodash"的规则，团队成员能在 code review 阶段就发现并讨论——这与"代码评审发现 lodash 滥用"是前置的工程治理。.cursorrules 已经有第三方 linter 工具，AGENTS.md 的 YAML frontmatter 可以用 js-yaml 写一个 pre-commit hook 校验。feature/experimental-agents.md 分支用一套激进的配置，合并到 main 后切换到稳定版。工程上的难点在于"规范的所有权"——谁有权修改 AGENTS.md？一种成熟的做法是：
图表加载中…
任何涉及工具权限、文件读写范围、网络白名单的规范变更必须经过 Security Team 审批；纯业务规范（命名约定、测试要求）由 Tech Lead 评审即可。
一种常见误解是"spec-driven 会取代 prompt engineering"。实际上二者是互补层：
工程上的最佳实践是把二者解耦：配置文件永远不进会话内 prompt，会话内 prompt 永远不承担全局规范描述。这样配置文件可以被 100% 复用，会话内 prompt 可以被 100% 灵活定制。
图表加载中…
spec-driven 工程化目前最薄弱的一环是可观测性——配置文件加载后，没有任何标准化的方式去观测"Agent 是否真的遵循了 AGENTS.md 第 3 条规则"。当前的工程现实是：
lint 工具可以校验语法（schema 合规性）这一空白催生了 2026 H1 的一波"Agent spec compliance"创业项目——核心思路是把配置文件转成可执行的 assertion，在 Agent 每次产出后跑一次校验。断言式样例：
# agent-compliance.yml
- rule: "no-lodash-import"
forbidden_pattern: "from 'lodash'"
applies_to: ["src/**/*.ts"]
severity: error
- rule: "test-coverage-min"
requires: "every modified .ts file has corresponding .test.ts"
severity: warning
这类工具目前还在 0.x 版本阶段，但代表了 spec-driven 范式向"工程闭环"演进的明确方向。
成功模式：
AGENTS.md 200 行覆盖了命名、测试、依赖管理、commit message、错误处理五大类规范。.cursorrules 强制统一了所有 PR 的代码风格，maintainer 的 review 负担下降 40%。失败模式：
CLAUDE.md，结果 Agent 的有效对话轮数从 25 轮降到 8 轮，工程师反馈"AI 越来越笨"，根因是上下文窗口被配置文件挤占。AGENTS.md 说"用 pnpm"，但项目里 80% 的包已经迁移到 bun。Agent 严格遵循配置文件反而产出了错误的命令。基于当前工程实践的演进速度，未来一年可预见的方向：
AGENTS.md 演化的开放协议），吸收其他 4 套的核心特性。awesome-agent-configs 仓库 + 模板市场，团队可以一键 import 业界最佳实践。从 prompt 字符串到声明式配置文件的范式转移，本质上是 AI 编程从"个人工具"走向"团队工程"的必然结果。配置文件作为可版本化、可评审、可 CI 校验的工程制品，正在补齐 LLM 协作的最后一公里——把"如何与 AI 协作"从个人经验变成团队知识。
但这一范式也引入了新的工程挑战：token 预算控制、语义合规验证、规范陈旧治理、团队所有权分配。这些问题在 2026 H2 将成为 AI 编程工程化的核心议题。
给团队的建议：
AGENTS.md 或 .cursorrules。配置文件不会让 AI 更聪明，但会让 AI 更可预测。在一个 200 人团队里，可预测比聪明重要 10 倍。
Agent 配置文件（CLAUDE.md / AGENTS.md / .cursorrules 等）正在把"如何与 AI 协作"从个人 prompt 经验变成团队级别的工程制品——它的核心价值不在于让 LLM 更聪明，而在于让 AI 编程从工具走向工程化、可预测化、团队化。
Conversation
0 条