很多人在使用 Claude Code 时，会注意到 目录下有一个 文件夹，但不清楚它的用途、文件格式，以及它和 的区别。本文做一个系统性的梳理。
用于存放自定义子代理（sub-agent）定义文件 。每个 文件定义一个专门的 AI 助手，可以被 Claude Code 通过 工具按需调用。
子代理的核心价值：
- 上下文隔离 — 每个 agent 有独立的上下文窗口，不会污染主会话
- 并行执行 — 多个 agent 可以同时工作，提升效率
- 专门化配置 — 每个 agent 可以有自己的模型、工具集、权限策略
存放位置支持两级：
Agent 文件采用 Markdown + YAML frontmatter 格式，文件扩展名通常为 或 。
基本结构
常用 frontmatter 字段
示例：一个代码审查 Agent
不能。 是 Claude Code 硬编码的查找路径，无法更名。Claude Code 会固定在以下两个位置查找 agent 定义：
如果你需要在多个工具间共享 agent 配置，可以考虑使用符号链接（symlink）。
这是最容易混淆的地方。两者虽然都在 目录下，但定位完全不同：
用一句话总结：
- CLAUDE.md = “我是谁、我的规矩是什么”（身份和规范）
- agents/ = “我手下有哪些专家可以调遣”（专门化工具人）
CLAUDE.md 适合放什么
agents 适合放什么
- Crash 分析专家（自动 GDB 调试）
- 代码审查员（专注 review 逻辑）
- 文档生成器（自动生成 API 文档）
- 安全审计员（扫描漏洞模式）
这是由两者完全不同的加载机制决定的：
原因一：加载时机不同
CLAUDE.md 在每次对话开始时自动注入到系统提示中，始终生效。而 agents 目录下的文件只在匹配到特定任务时才被加载。如果把 CLAUDE.md 放进 agents 目录，它就变成了一个”子代理定义”，不再是全局指令了。
原因二：层级加载机制
CLAUDE.md 支持多级覆盖：
越具体的目录，CLAUDE.md 的优先级越高。agents 不具备这种层级关系。
原因三：文件格式不同
CLAUDE.md 是纯 Markdown，Claude Code 直接将其内容作为上下文注入。而 agent 文件需要 YAML frontmatter 来声明模型、工具、权限等配置，两者的解析逻辑完全不同。
原因四：架构职责分离
将”我应该遵守的规则”和”我可以调用的专家”混在一起，会导致职责不清。这是良好的软件设计原则 —— 关注点分离。
- CLAUDE.md 保持精简：只放始终需要的全局指令，避免超过 200 行
- Agent 按职责拆分：每个 agent 专注一个领域，不要做”全能 agent”
- 善用项目级 agents：通用 agent 放全局，项目特定的放项目目录
- 合理设置 maxTurns：避免 agent 无限循环，一般 30-50 轮足够
- 选择合适的 model ：简单任务用 /，复杂推理用
目录的设计体现了清晰的架构思想：CLAUDE.md 是记忆，agents 是能力。理解这个区别，才能更好地定制你的 Claude Code 工作流。
发布者：Ai探索者，转载请注明出处：https://javaforall.net/279752.html原文链接：https://javaforall.net
