当多个同名 subagent 同时存在于用户家目录的 .claude/agents 与项目内的 .claude/agents，Claude Code 按”位置优先级”解决冲突；嵌套项目结构里，从工作目录向上逐层扫描的每一级 .claude/agents 都参与解析，离工作目录最近的同名定义覆盖更外层。理解这两条规则，就能预判同一条 subagent 在不同目录下被加载到的版本。
一、subagent 是什么：一句话定位
subagent 是拥有独立上下文窗口、自有系统提示、工具白名单和权限模式的 AI 实例，主对话通过 Task 工具把任务委派给它，子代理跑完把摘要回传。子代理只拿到自己的系统提示加基础环境信息，不会继承完整的 Claude Code 系统提示——这条边界决定了 subagent 文件既能定义”角色”，也能定义”能调什么工具、能进什么权限”。
定义 subagent 的文件是带 YAML frontmatter 的 Markdown，frontmatter 存配置，Markdown 正文是系统提示：
---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---
You are a code reviewer. Analyze the code and provide specific, actionable feedback.name 字段是 subagent 的唯一标识，subagent 文件放在哪个目录、文件名怎么取，都不影响它的身份——只跟 name 有关。
二、作用域的五个层级与优先级
subagent 文件可以放在五种位置，Claude Code 启动时按优先级合并，同名时高优先级覆盖低优先级。
| 优先级 | 位置 | 作用域 | 创建方式 |
|---|---|---|---|
| 1（最高） | 托管设置 | 组织范围 | 管理员下发 |
| 2 | --agents CLI 标志 |
当前会话 | 启动时传 JSON |
| 3 | 项目内的 .claude/agents | 当前项目 | 询问 Claude 或手动建 |
| 4 | 用户家目录的 .claude/agents | 当前用户所有项目 | 询问 Claude 或手动建 |
| 5（最低） | 外挂的 agents 目录 | 启用外挂的范围 | 随外挂安装 |
把它读三遍：”项目内配置”优先级高于”用户家目录配置”——这与很多开发者直觉相反的”项目覆盖用户”恰好一致；项目级 subagent 通常要进版本控制，团队共用；用户级 subagent 是个人跨项目习惯。
三、同名冲突的解析步骤
当多个 subagent 共享同一 name，Claude Code 走完整解析流程如下：
- 把”项目内的 .claude/agents”（含子目录）作为最高优先项目级来源；
- 把”用户家目录的 .claude/agents”（含子目录）作为个人级来源；
- 把当前会话通过
--agents传入的 JSON 作为会话级来源（最高优先）； - 把当前启用的外挂的
agents/目录作为外挂级来源（最低优先）； - 同名时按优先级表选胜出者；同层冲突则按文件系统读取顺序加载其中之一。
CLI 会话级之所以高于项目级，是为了支持临时测试和自动化脚本：”我想这次跑一个临时版本，但不动项目文件”，传 --agents 即可。
四、嵌套项目结构的加载规则
仓库里嵌套目录的情况非常多：monorepo 里 apps/web/.claude/agents/ 和 apps/api/.claude/agents/ 同时存在，仓库根还有 .claude/agents/。从 v2.1.178 起，Claude Code 从”当前工作目录”向上逐层扫描，每一级 .claude/agents 都会被加载，最靠近工作目录的同名定义胜出。
| 当前工作目录 | 扫描路径 | 同名 code-reviewer 胜出者 |
|---|---|---|
apps/web/ |
apps/web → 仓库根 | apps/web/.claude/agents/code-reviewer.md |
| 仓库根 | 仅仓库根 | .claude/agents/code-reviewer.md |
apps/web/src/ |
apps/web/src → apps/web → 仓库根 | apps/web/.claude/agents/code-reviewer.md |
最后这一行是新规则的精髓：把工作目录切到 apps/web/src/ 时，Claude Code 仍然从 src/ 向上找到 apps/web 的定义，而不是仓库根的版本。这意味着”我在哪个子目录工作，就用哪个 subagent 配置”，对 monorepo 来说非常顺手。
通过 --add-dir 显式添加的目录也会被纳入扫描，其内部的 .claude/agents 与项目级 subagent 一起加载，便于跨目录协作。
五、目录子树内的重名陷阱
subagent 的身份只看 name，不看文件路径。因此”两个子目录下各有一个同 name 的 subagent 文件”也是冲突。/doctor 自检会报这种重复：同一目录下两个同名文件只会有一个被加载，由文件系统读取顺序决定，没有文档化的优先级。修复方式是改名或合并。
外挂 agents 目录的子目录结构会进入 scoped identifier：my-plugin/agents/review/security.md 注册为 my-plugin:review:security，与项目级和用户级的扁平命名空间分开。这避免了外挂和项目内 subagent 重名时的误覆盖。
六、把规则落到一次发布
按下面五步把”项目内 subagent 覆盖同名用户级 subagent”这件事确认下来：
- 在用户家目录的 .claude/agents/code-reviewer.md 写一份个人版（用 sonnet 跑代码评审）；
- 在仓库根的 .claude/agents/code-reviewer.md 写一份项目版（用 opus 跑、禁用 Bash 工具）；
- 在仓库根跑
claude，让默认工作目录触发解析——/agents应显示项目版生效、用户版被覆盖； - 在仓库根的子目录里
cd apps/web再跑，验证仍是项目版（因为仓库根和子目录没新增 .claude/agents）； - 在
apps/web/.claude/agents/code-reviewer.md写一份更窄的子项目版，验证在apps/web下解析到子项目版，回仓库根解析到根项目版。
效果：subagent 配置随工作目录自动切换，不必手动切换。注意点：同名 subagent 在同一目录的子目录里重名会触发 /doctor 警告，文件名仍要保持唯一；通过 --add-dir 加入的目录会与项目级 subagent 一起参与解析，注意这些”动态目录”也可能引入冲突。
七、易混淆对照
| 场景 | 期望胜出 | 实际胜出 |
|---|---|---|
| 项目内与用户家目录同名 | 项目内 | 项目内 |
| 嵌套工作目录与仓库根同名 | 嵌套目录 | 嵌套目录（离 cwd 最近） |
| 同目录子文件夹下同名 | 看路径 | 文件系统读取顺序 |
CLI --agents 与项目内同名 |
CLI | CLI |
| 外挂与项目内同名 | 外挂看配置 | 项目内（项目级优先） |
最后一行的”反直觉”是文档原话——同名 subagent 在项目内定义时，会压过外挂同 name 里的定义。如果想保留外挂版本，要么改名，要么不把同名文件放进项目内。
常见问题（FAQ）
Q1：subagent 文件名重要吗？
不重要。name 字段才是身份，文件名仅决定加载顺序；同名冲突按文件读取顺序，没有文档化优先级。
Q2：在 monorepo 子目录跑会用到哪个 subagent？
从工作目录向上逐层找 .claude/agents，找到的第一个同名定义胜出；未命中则继续向上，直到仓库根。
Q3：托管设置能压过项目内配置吗？
能。组织托管设置优先级最高，可被企业管理员用来强制覆盖用户/项目级 subagent。
