CLAUDE.md 和 AGENTS.md：让 AI 编程智能体真正遵循你规则的配置层

你的 AI 编程助手不记得昨天发生了什么。每个会话都是冷启动的 —— 它不知道你使用的是 yarn 而不是 npm，不知道你禁用 any 类型，也不知道 src/generated/ 目录是神圣不可侵犯的，永远不应该手动编辑。因此，它会使用错误的包管理器生成代码，在你禁止的地方引入 any，偶尔还会覆盖掉那些需要你花一小时才能恢复的生成文件。你纠正了它。明天它又犯同样的错误。你再次纠正它。

这不是模型质量问题。这是一个配置问题 —— 解决方案就是一个纯 Markdown 文件。

CLAUDE.md、AGENTS.md 及其针对特定工具的同类文件，是 AI 编程助手在每个会话开始前阅读的简报。它们编码了助手原本需要重新发现或被纠正的内容：运行哪些命令、避免哪些模式、团队的工作流如何构建，以及哪些目录是禁区。它们相当于一份详尽的工程入职文档，被压缩成了一种优化过的、适合机器阅读的形式。

投资于这些文件的团队不再需要重复纠正相同的错误。而不投资这些文件的团队，最终监督助手所花费的时间比使用助手节省的时间还要多。

这些文件究竟起什么作用

AI 编程助手是无状态的。如果没有明确的指令，它们会默认使用在训练数据中看到的通用模式 —— 而这往往不是你项目的模式。CLAUDE.md 或 AGENTS.md 文件为助手提供了一个跨会话持久存在的项目上下文层。

最关键的内容是助手无法仅从代码中推断出的东西：

• 工具链详情：yarn vs. npm vs. pnpm；为什么项目使用特定的测试运行器；从 package.json 中无法一眼看出的构建标志
• 工作流预期：如何构建 commit、PR 惯例、在完成前是否需要运行类型检查
• 非显式约束：自动生成的且绝对不能编辑的目录、在构建时从别处复制的文件、运行时需要的环境变量
• 架构决策：哪一层负责什么、为什么存在特定的抽象、团队已经拒绝的已知反模式

助手在每个会话开始时都会阅读此文件，并以此来校准其整个过程中的决策。你可以将其视为一种能够跨越模型更新、团队更迭和会话边界的集体记忆。

CLAUDE.md vs. AGENTS.md：选择合适的格式

这两种格式的用途相同，但在范围和功能上有所不同。

CLAUDE.md 是 Claude Code 的原生格式。在所有助手指令格式中，它的功能集最为丰富：

• @import 语法：通过 @path/to/file.md 引用外部文件。这允许你实现模块化 —— 将特定领域的指南保存在 agent_docs/database.md、agent_docs/api-conventions.md 等文件中，并仅导入相关内容。
• 路径限定规则：YAML frontmatter 可以将规则限制在特定的文件模式中。带有 globs: ["**/*.tsx"] 的部分仅在 Claude 编辑 React 组件时激活，而在修复 Shell 脚本时不激活。
• 五级层次结构：全局 (~/.claude/CLAUDE.md) → 项目根目录 (./CLAUDE.md) → 子目录文件（按需加载） → 路径限定规则 → 用户个人导入。所有层级都会级联；低层级是对高层级的补充而非替换。
• 自动记忆：Claude 可以将会话笔记写入 ~/.claude/projects/<project>/memory/，在你明确的指令之上创建一个有机学习层。
• Hooks：对于必须毫无例外执行的行为 —— 例如每次编辑后运行 linter，或者在测试未通过时拒绝 push —— 请使用 .claude/settings.json 中的 hooks 而不是 CLAUDE.md 指令。Hooks 是确定性的，而指令是建议性的。

AGENTS.md 是由 Linux 基金会旗下的 Agentic AI Foundation 管理的开放标准。它得到了 60 多种工具的支持：OpenAI Codex、Cursor、GitHub Copilot、Windsurf、Aider、Gemini CLI、Zed、Warp、Devin、JetBrains Junie 等。该格式是纯 Markdown —— 没有必填字段，没有特殊语法。在目录树中，距离被编辑代码最近的文件具有最高优先级。

OpenAI 的 Codex 实现增加了三级层次结构（全局 ~/.codex/AGENTS.md → 项目根目录 → 子目录 AGENTS.override.md）、32 KiB 的大小限制以及可配置的备用文件名。openai/codex 仓库本身在其目录结构中分布使用了 88 个 AGENTS.md 文件。

实际的问题是该使用哪一个。如果你的团队主要使用 Claude Code，CLAUDE.md 通过导入、路径限定和 hooks 为你提供更大的杠杆作用。如果你的团队使用多种工具 —— 或者如果你维护一个开源项目，贡献者可能使用任何助手 —— 那么 AGENTS.md 是更有价值的选择，因为一个文件就能让所有人受益。

许多团队两者兼顾：AGENTS.md 保存适用于任何助手的通用规则，而 CLAUDE.md 则导入 AGENTS.md 并添加针对 Claude 的增强功能。GitHub Copilot 的 .github/copilot-instructions.md 通常可以通过符号链接（symlink）连接到 AGENTS.md，以避免重复。

指令预算问题

这是大多数工程师在第一次编写这些文件时会忽略的约束：前沿 LLM 大约能以合理的连贯性遵循 150–200 条指令。Claude Code 的内置系统提示词已经消耗了大约 50 个位置。你添加的每一行都在竞争剩下的预算。

一个 600 行的 CLAUDE.md 文件并不能为你的 Agent 提供 600 条指导意见——它提供的是一个文件，Agent 会从中选择性地关注一小部分，并可能忽略你最关心的规则。Claude Code 自身的系统提示词中包含一条提醒：CLAUDE.md 的上下文“可能与你的任务相关，也可能不相关”，这信号表明 Claude 会主动丢弃它认为无关的部分。

这意味着编写这些文件的准则不是全面性，而是无情的优先级排序。

应当包含：

• Claude 无法通过阅读代码猜出的 Bash 命令
• 与语言默认配置不同的代码风格规则
• 带有精确参数标志的测试和构建命令
• 仓库工作流约定（分支命名、提交格式、PR 预期）
• 针对你项目的特定架构约束
• 不明显的陷阱和已知故障模式

应当排除：

• Agent 通过阅读代码就能弄明白的任何内容
• 它已经掌握的标准语言规范
• 详细的 API 文档（改为提供链接）
• 诸如“编写简洁代码”或“使用有意义的变量名”之类的通用建议
• 变动频繁的信息（很快就会过时）
• 对代码库逐个文件的完整描述

Claude Code 的官方文档明确指出：“臃肿的 CLAUDE.md 文件会导致 Claude 忽略你的实际指令。”HumanLayer 将其 CLAUDE.md 保持在 60 行以内。对于大多数项目来说，300 行是一个合理的上限。如果你超过了这个字数，你应该将内容提取到 @imported 子文档中，而不是继续往根文件里塞。

一个推论：使用 Linter 而不是指令来规范代码风格。永远不要让 LLM 去做 Linter 该做的工作。Prettier、Biome 和带有自动修复功能的 ESLint 能够以零 Token 成本确定性地执行风格规范。如果你的 CLAUDE.md 中充斥着空格和格式规则，说明你的 Linter 配置有问题，而不是上下文有问题。

结构良好的文件是什么样的

一个良好的记忆文件遵循简单的结构：是什么（技术栈、架构、关键目录）、为什么（项目目的、组件角色、代码中不明显的决策）以及如何做（命令、工作流、例外情况）。在实践中：

# 项目：MyApp

## 技术栈
- 前端：React 18, TypeScript, Tailwind CSS
- 后端：Koa.js, GraphQL, MongoDB (Typegoose)
- 包管理器：yarn (不是 npm)

## 关键规则
- 永远不要修改 src/generated/ 中的文件 —— 这些文件在构建时自动生成
- 在完成任何 TypeScript 更改前运行 `yarn typecheck`
- 使用 ES 模块 (import/export)，不要使用 CommonJS (require)

## 命令
- 开发服务器：yarn start
- 构建：yarn build
- Lint 检查：yarn lint --fix

## 工作流
- 分支命名：feat/*, fix/*, chore/*
- 每个 PR 仅包含一个逻辑变更 —— 不要捆绑无关的修复
- 合并前压缩 (Squash) 提交

对于大型项目，请使用渐进式披露。将特定任务的指南存储在 agent_docs/ 目录中，并在根文件中通过简短说明和导入路径引用它们。Claude 会在开始该领域的工作前加载相关文件，而不会让每个会话都充斥着极少用到的上下文。

OpenAI Codex 团队自己的 AGENTS.md 在语气和密度方面是一个非常有用的参考。它涵盖了 Rust 命名约定、Clippy 合规性、测试库、TUI 样式模式和 API Payload 命名 —— 大约 300 个词的密集、可操作的指南。没有不言自明的内容，没有废话。

各工具之间的对比

每种主要的 AI 编程工具都有其特定风格的指令文件：

Cursor 最初使用 .cursorrules —— 现在该文件在 Agent 模式下已弃用并被忽略。目前的 Cursor 使用 .cursor/rules/*.mdc 文件，具有四种激活模式：始终激活 (Always Active)、自动附加 (Auto Attached，基于 Glob 匹配)、Agent 请求 (Agent Requested，Agent 在相关时自行提取) 和手动 (Manual)。这使得 Cursor 拥有所有工具中最细颗粒度的单条规则控制。

Windsurf 使用 .windsurf/rules/*.md 存放开发者编写的规则，并独立维护 Cascade 记忆 (Cascade Memories) —— 这些记忆是从交互中自动生成并存储在 ~/.codeium/windsurf/memories/ 中的。这种双层模型将显性的团队规范（版本控制）与有机的学习过程（仅本地）分离开来。团队可以将自动生成的记忆提升为显性规则。

GitHub Copilot 读取 .github/copilot-instructions.md 获取仓库级别的指令，读取 .github/instructions/*.instructions.md 获取特定路径的规则（使用 applyTo: 前置参数）。个人指令存放在 ~/.github/copilot-instructions.md，优先级最高。组织级指令已于 2026 年 4 月全面推出。

Aider 使用 YAML 配置文件 (.aider.conf.yml)，并在内容级指南上回退到 AGENTS.md。

AGENTS.md 标准的价值在于互操作性：只需编写一次，即可在 Codex、Copilot、Aider、Gemini CLI、Cursor、Windsurf 以及其他 55 多种工具中运行，无需针对每个工具进行维护。

让投资获得回报

关于 AI 编程工具采用的数据褒贬不一。使用 AI 工具的开发者个人完成的任务更多，但组织层面往往看不到公司级交付指标的提升。对数千名开发者的研究发现，个人的 PR 吞吐量增加了，但 PR 评审时间大幅增长，导致了下游瓶颈 —— 并且 AI 工具的采用与每位开发者的 Bug 数量小幅增加相关。

避开这些失败模式的团队是那些将配置视为头等工程事项的团队。一个精心编写的指令文件，结合通过 linting 钩子和测试要求的确定性强制执行，是区分“AI 辅助但混乱”与“AI 辅助且高效”的关键。

具体来说：如果你的智能体反复犯同样的错误，这就是添加规则的信号。如果规则没有改变其行为，这说明文件中的噪音太多，规则被淹没了。与其增加规则的细节，不如减少噪音。

Claude Code 中的 /init 命令是一个非常有用的起点 —— 它会分析你的代码库并生成一个 CLAUDE.md 草案。将输出视为初稿。删除任何智能体在不被告知的情况下也能做对的内容。然后将该文件视为一份动态文档：将其提交到 git，由团队共同拥有，并在发现重复出现的错误时及时更新。

这样做的团队报告了最一致的结果：纠错循环缩小了，智能体的初次尝试更接近可接受的标准，而那些让部分 AI 工具采用者感到自己在倒退的监督开销也开始消失。

这就是这些文件的承诺 —— 不是魔法，而是记忆。