CLAUDE.md与AGENTS.md与SKILL.md的区别：内容应放在哪里以及原因是什么。

任何开始使用 Claude Code 的人都会创建一个 CLAUDE.md，并将所有内容都放进去：项目设置、编码规范、拉取请求的注意事项、技术栈详情以及入职指南。随后 AGENTS.md 和 SKILL.md 也加入了这个体系，看起来好像同一项工作需要三个文件。但实际上并非如此。把它们混为一谈意味着要为那些对你毫无用处的资源支付代币费用。

一个简单的思维模型

想象一家公司。CLAUDE.md 就是每位新员工入职第一天就会阅读的员工手册，它始终存在于背景之中。AGENTS.md 也是同样的手册，但它的编写方式能让任何外包机构的临时人员也能理解，而不仅仅是正式员工。SKILL.md 则像是架子上的操作手册，只有在进行特定任务时才会取出来查看。三个文件，三种用途，三种加载方式。

CLAUDE.md：始终被加载

这是 Claude Code 的主要配置文件。在会话开始时，Claude 会读取该文件并将其存储在系统提示词中。它仅被加载一次，成为整个会话期间上下文的一部分，无需在每条消息发送时都从磁盘读取。因此，当你输入问候语时，这些指令已经存在；之后当你请求修复错误时，它们依然会在那里。

其后果是，一个较大的文件会永久占用部分上下文窗口空间，即便在大部分内容都无关紧要的任务中也是如此。正因如此，简洁精炼的配置文件更为有效。

三个层级

指令来自多个来源并会被整合在一起：

1. 位于 ~/.claude/CLAUDE.md 的个人文件，其中存储适用于所有项目的偏好设置，如缩进风格或提交信息格式。团队成员无法看到该文件。

项目文件，可以是.claude/CLAUDE.md，也可以是存储在仓库根目录中的文件。该文件会被提交到Git中，因此克隆该仓库的所有人都会获得相同的规则。堆栈详情、命令以及团队标准都应放在这里。

针对特定路径的规则，存储在.claude/rules/目录下，并在前置信息中指定路径。例如，测试规则文件仅在编辑测试文件时才会被加载，这样可以避免无关的指导内容出现在当前上下文中。

更具体的项目指南会在通用的用户级说明之后加载，因此当两者出现冲突时，项目的版本规则优先生效。实际原则是：个人偏好应放在个人配置中，而团队共用的规范则应放在项目文件中。

内容包含什么

保持简短。200行左右是一个合理的目标，但这只是指导原则而非硬性限制。只需包含Claude完成每项任务所需的信息：技术栈、用于运行测试和启动开发服务器的命令、诸如绝不对用户数据进行日志记录之类的绝对规则，以及主要的架构决策。

省略任何与特定任务相关的内容。关于代码审查的详细指南或边缘案例列表更适合放在其他地方，具体内容见下文。

一个需要注意的问题

如果在会话进行中编辑CLAUDE.md，正在运行的会话不会察觉到变化。该文件在会话开始时仅被读取一次，因此需要启动新会话才能使更改生效。这也是新添加的规则看似被忽略的最常见原因。

AGENTS.md：适用于使用多种工具的团队

AGENTS.md具有相同的作用，用于存储项目上下文和说明。不同之处在于谁可以读取它。Claude Code会读取CLAUDE.md，而OpenAI Codex、Cursor、Gemini CLI以及GitHub Copilot则会读取AGENTS.md。

根据目前的描述，Claude Code无法直接识别AGENTS.md，但通过创建符号链接将两个名称指向同一个文件即可解决此问题（如支持情况有所变化，请查阅最新文档）：

ln -s AGENTS.md CLAUDE.md

现在只有一个文件，所有工具都会读取它，不会出现信息分散的情况。

适用场景

如果整个团队都只使用 Claude Code，那么CLAUDE.md就足够了。如果团队使用多种工具，或者 CI 运行的代理与开发者本地使用的不同，AGENTS.md就能成为涵盖所有工具的统一信息来源。

隐性指令丢失问题

多智能体流水线存在一种严重的故障模式。假设其中一个阶段在 Claude Code 中运行，另一个阶段则在其他供应商的工具中运行。如果规则仅保存在 CLAUDE.md 中，第二个工具会直接忽略这些规则，而不会给出任何错误或警告。智能体会正常运行，但不会遵循你原本认为应适用的规范。这样一来输出结果就会不一致，行为也会出现偏差，由于表面上看没有任何问题，因此很难找到故障原因。使用 AGENTS.md 作为共享基准，可以让流水线中的所有工具看到相同的规则。

SKILL.md：按需加载

它的运作方式有所不同。前两种规则会在每次会话开始时加载并保留在上下文中，而技能则只有当当前任务与其描述匹配时才会被加载。

技能是一个包含 SKILL.md 文件的文件夹。该文件以简短的 YAML 标头开头，注明技能的名称和一行描述文字，Claude 就通过这些描述来判断该技能是否适用。当你发送消息时，Claude 会将其与所有技能的描述进行比对，并加载匹配的技能。任务完成后，该技能就会被移除。以下是 frontmatter 的示例格式：

---
name: pr-review
description: Use when the user asks to review a pull request or check code quality.
allowed-tools: [Read, Grep, Glob]
---

为何这样能节省令牌

假设你已经记录了十种工作流程。将这十种都放在CLAUDE.md中，那么每条消息都会加载这十种流程，哪怕只是请求修正拼写错误。作为技能，只有相关的那个会被加载，其余九个则不会消耗任何资源。在混合不同任务类型的长时间会话中，这样能保持上下文简洁，专注于手头的工作。

描述最为重要

Claude依靠描述来做出选择。像“帮助处理代码”这样模糊的描述要么根本不会被触发，要么会对所有情况都起作用。而像“审查Python拉取请求中的SQL注入或硬编码敏感信息等漏洞”这样具体的描述，则能可靠地在相关情况下被触发。文件夹名称是给用户看的，描述则是给Claude看的，因此要为Claude来撰写描述。

两个实用的前置内容选项

allowed-tools用于限制该技能启用时Claude可以执行的操作。对于需要浏览代码库的技能，将其设置为读取、grep和glob即可让Claude查看内容而无需编辑或写入文件，即便您要求进行修改，这一限制依然有效。

context: fork会在隔离的上下文中运行该技能的功能。中间步骤会被隐藏，只有最终结果会返回到主会话中，这非常适合那些需要生成大量无需阅读的内容的任务，比如扫描五十个文件以得出一个总结。

保持技能简洁

规模较大的技能加载后会占用更多上下文空间。如果某个工作流需要大量的文档、示例或参考资料，应将这些内容放在单独的文件中，让技能在需要时再读取它们。主要指令则应保留在工作流本身上。

三种方式的比较

如何选择

• 适用于每轮会话中所有任务的规则应放入 CLAUDE.md 中。
• 如果团队使用多种 AI 编程工具，或工作流程中混用了这些工具，则应将 AGENTS.md 设为权威依据，并将 CLAUDE.md 与之关联。

那些你需要反复执行的特定工作流程，比如审核 Pull Request、生成简历或查找文档，都应该被转化为一种技能。

如果某个工作流程要求 Claude 仅以只读模式运行，可通过设置 allowed-tools 将其转化为技能。

如果你想通过一条命令手动触发某项操作，可以在 .claude/commands/ 中使用斜杠命令。

整洁的布局

your-project/
├── AGENTS.md                   <- shared source of truth for all tools
├── CLAUDE.md                   <- imports AGENTS.md, adds Claude-specific rules
├── .claude/
│   ├── rules/
│   │   ├── testing.md          <- loads only when editing test files
│   │   └── security.md         <- loads only when editing auth-related files
│   ├── skills/
│   │   ├── pr-review/
│   │   │   └── SKILL.md        <- loads when you ask for a PR review
│   │   └── latex-resume/
│   │       └── SKILL.md        <- loads when you ask to build a resume
│   └── commands/
│       └── standup.md          <- /standup generates your daily update
└── ~/.claude/
    └── CLAUDE.md               <- your personal preferences, not in the repo

CLAUDE.md 的内容保持简短，因为它仅包含每项任务真正需要的信息。复杂的、特定于任务的流程则由技能来处理。AGENTS.md 能确保当团队成员更换工具时，一切仍能正常运行。

经验法则

如果 CLAUDE.md 的行数超过200行，或token数量超出1,200到1,500左右，那么你在大多数消息中可能都在为不需要的指令付费。请按每条指令的适用时间进行排序：始终需要则放在 CLAUDE.md 中，跨不同工具都需要则放在 AGENTS.md 中，仅适用于某一种任务则用技能来表示。上下文窗口就像一笔预算——主文件会在每条消息中占用一部分预算，而技能则仅在被使用时才会消耗预算，因此设计时需以此为依据。