很多人在使用 Claude Code 时，会注意到
~/.claude/目录下有一个agents文件夹，但不清楚它的用途、文件格式，以及它和CLAUDE.md的区别。本文做一个系统性的梳理。
1. agents 目录是什么？
~/.claude/agents/ 用于存放自定义子代理（sub-agent）定义文件 。每个 .md 文件定义一个专门的 AI 助手，可以被 Claude Code 通过 Agent 工具按需调用。
子代理的核心价值：
- 上下文隔离 --- 每个 agent 有独立的上下文窗口，不会污染主会话
- 并行执行 --- 多个 agent 可以同时工作，提升效率
- 专门化配置 --- 每个 agent 可以有自己的模型、工具集、权限策略
存放位置支持两级：
| 级别 | 路径 | 作用域 |
|---|---|---|
| 全局 | ~/.claude/agents/ |
所有项目可用 |
| 项目级 | <project>/.claude/agents/ |
仅当前项目可用 |
2. 文件格式规范
Agent 文件采用 Markdown + YAML frontmatter 格式，文件扩展名通常为 .md 或 .agent.md。
基本结构
markdown
---
name: my-agent
description: 简短描述何时触发这个 agent
model: sonnet
tools: [Read, Grep, Glob, Bash]
maxTurns: 50
---
# Agent 的具体指令
这里写 markdown 格式的指令内容...常用 frontmatter 字段
| 字段 | 类型 | 说明 |
|---|---|---|
name |
string | Agent 标识名称 |
description |
string | 描述何时触发（帮助 Claude 决定是否调用） |
model |
string | 使用的模型：sonnet / opus / haiku / inherit |
tools |
list | 允许使用的工具列表 |
disallowedTools |
list | 明确禁止使用的工具 |
permissionMode |
string | 权限模式：strict / relaxed / inherit |
maxTurns |
number | 最大对话轮次 |
skills |
list | 可使用的 skills 列表 |
mcpServers |
list | 可访问的 MCP 服务器 |
memory |
boolean | 是否持久化上下文 |
color |
string | UI 显示颜色（如 "#hexcode"） |
示例：一个代码审查 Agent
markdown
---
name: code-reviewer
description: Use this agent to perform thorough code reviews on pull requests or changed files.
model: opus
tools: [Read, Grep, Glob, Agent]
maxTurns: 30
---
# Code Review Agent
You are a senior code reviewer. When reviewing code:
1. Check for correctness and potential bugs
2. Evaluate code style and consistency
3. Look for security vulnerabilities
4. Suggest performance improvements
5. Verify error handling completeness
Output a structured review report with severity levels: Critical / Warning / Info.3. agents 目录名能改吗？
不能。 agents 是 Claude Code 硬编码的查找路径，无法更名。Claude Code 会固定在以下两个位置查找 agent 定义：
~/.claude/agents/ # 全局
<project>/.claude/agents/ # 项目级如果你需要在多个工具间共享 agent 配置，可以考虑使用符号链接（symlink）。
4. agents 与 CLAUDE.md 的区别
这是最容易混淆的地方。两者虽然都在 ~/.claude/ 目录下，但定位完全不同：
| 对比维度 | CLAUDE.md | agents/*.md |
|---|---|---|
| 定位 | 全局指令和项目规范 | 专门化的子代理 worker |
| 加载方式 | 每次会话自动加载 | 按需调用或触发时加载 |
| 上下文 | 共享主会话上下文 | 独立隔离的上下文窗口 |
| 执行方式 | 作为主 agent 的一部分运行 | 作为独立子进程运行 |
| 文件格式 | 纯 Markdown | YAML frontmatter + Markdown |
| 层级机制 | 支持（全局 → 项目 → 子目录） | 不支持层级覆盖 |
| 并行能力 | 单线程执行 | 多个 agent 可并行 |
用一句话总结：
- CLAUDE.md = "我是谁、我的规矩是什么"（身份和规范）
- agents/ = "我手下有哪些专家可以调遣"（专门化工具人）
CLAUDE.md 适合放什么
markdown
# CLAUDE.md 示例
- 项目使用 TypeScript + React
- 代码风格遵循 Airbnb 规范
- 提交信息使用 Conventional Commits 格式
- 构建命令：npm run build
- 测试命令：npm testagents 适合放什么
- Crash 分析专家（自动 GDB 调试）
- 代码审查员（专注 review 逻辑）
- 文档生成器（自动生成 API 文档）
- 安全审计员（扫描漏洞模式）
5. 为什么 CLAUDE.md 不能放在 agents 目录里？
这是由两者完全不同的加载机制决定的：
原因一：加载时机不同
CLAUDE.md 在每次对话开始时自动注入到系统提示中，始终生效。而 agents 目录下的文件只在匹配到特定任务时才被加载。如果把 CLAUDE.md 放进 agents 目录，它就变成了一个"子代理定义"，不再是全局指令了。
原因二：层级加载机制
CLAUDE.md 支持多级覆盖：
Enterprise 策略（如有）
└── ~/.claude/CLAUDE.md（个人全局）
└── <project>/CLAUDE.md（项目级）
└── <project>/src/CLAUDE.md（子目录级）越具体的目录，CLAUDE.md 的优先级越高。agents 不具备这种层级关系。
原因三：文件格式不同
CLAUDE.md 是纯 Markdown，Claude Code 直接将其内容作为上下文注入。而 agent 文件需要 YAML frontmatter 来声明模型、工具、权限等配置，两者的解析逻辑完全不同。
原因四：架构职责分离
将"我应该遵守的规则"和"我可以调用的专家"混在一起，会导致职责不清。这是良好的软件设计原则 ------ 关注点分离。
6. 最佳实践
- CLAUDE.md 保持精简：只放始终需要的全局指令，避免超过 200 行
- Agent 按职责拆分：每个 agent 专注一个领域，不要做"全能 agent"
- 善用项目级 agents：通用 agent 放全局，项目特定的放项目目录
- 合理设置 maxTurns：避免 agent 无限循环，一般 30-50 轮足够
- 选择合适的 model ：简单任务用
haiku/sonnet，复杂推理用opus
总结
| 你想要... | 用什么 |
|---|---|
| 设置全局编码规范 | CLAUDE.md |
| 定义项目构建命令 | CLAUDE.md |
| 创建专门的 crash 分析助手 | agents/ |
| 创建并行工作的代码审查员 | agents/ |
| 保存用户偏好设置 | CLAUDE.md |
| 隔离复杂任务避免上下文溢出 | agents/ |
~/.claude/ 目录的设计体现了清晰的架构思想：CLAUDE.md 是记忆，agents 是能力。理解这个区别，才能更好地定制你的 Claude Code 工作流。