在 .claude/agents/*.md 放项目子智能体，只在本机生效的放 ~/.claude/agents/；小组的验收角色跟仓库走。它在单独的上下文里运行，description 决定什么时候把工作交过来，也可以在对话里输入 @ 从列表点名。限权靠 tools 允许列表：只读角色写 tools: Read, Grep, Glob，不写 Write、Edit、Bash。
会在三种情况下打开这一页：要给验收或复核配一个只读角色 → 按「限权靠 tools 允许列表」里的四步建；它建了却从没被叫到，或验收时把源码改了 → 看「子智能体越权或不被叫到的四种现象」；从 Cursor 或 TraeCode 迁子智能体过来 → 看「子智能体在三个工具里的字段」。
最容易写错的是把它当成「更安全的助手」——它只是换了一个上下文，tools 不限权，它照样能改文件、跑命令。它也不是每次都会被叫到，所以数据范围这类硬约束仍要写在 CLAUDE.md，不能只写在某个子智能体里；tools 里写了 Bash，等于把写权限又绕回来了。
它跑完一次验收之后，git status --short 的输出是空的吗？
答「不是空的」，说明 tools 里留了写类工具或 Bash。删掉它们，只留 Read, Grep, Glob，再让它跑一次。
子智能体的权限来自 tools 这一行：写哪些工具，它就只能用哪些。不写 tools 等于不限制，这是验收角色最容易出问题的地方。
tools 写法 | 它能做什么 | 代价 |
|---|---|---|
tools: Read, Grep, Glob | 读文件、搜代码、列文件；改不了文件，也跑不了命令 | 只做静态复核，跑不了测试，动态问题得另有人验 |
在上面加 Bash | 还能跑任意命令 | 命令本身能改文件、能提交，等于间接放开了写 |
不写 tools | 用得到全部工具，包括 Write、Edit | 等于没有限制，不能用来做验收 |
.claude/agents/verifier.md，文件名即角色名。name 与文件名一致；description 写明什么时候交过来；tools 只留 Read, Grep, Glob。git status --short；有改动就说明权限没收住，回去删掉 Bash 或写类工具。git status 确认仓库没被动过。
Write 或 Bash；把数据范围、密钥规则只写在子智能体里；用子智能体代替人做最终合并决定。
三处目录同名不同父，限权字段完全不一样：Claude Code 和 TraeCode 用工具允许列表，Cursor 用一个 readonly: true 开关。迁子智能体之前先在这张表里对一遍。
| 项 | Claude Code | Cursor | TraeCode |
|---|---|---|---|
| 项目位置 | .claude/agents/*.md | .cursor/agents/*.md | .trae/agents/*.md |
| 个人位置 | ~/.claude/agents/ | 无对等位置 | ~/.trae-cn/agents/ |
| 限制权限 | tools: Read, Grep, Glob（不写 Write／Edit／Bash） | readonly: true | tools: Read, Grep, Glob 加 disallowedTools: Write, Edit, Bash |
| 模型 | 无对等字段 | model: inherit 沿用当前对话的模型 | 不写 model 时用对话里当前选的模型 |
| 名称约束 | name 与文件名一致 | 无对等说明 | name 只能用字母、数字、连字符，≤50 字符；name 与 description 必填 |
| 怎么被叫到 | 由 description 决定；对话里也可输入 @ 点名 | 由 description 决定 | 由 description 决定；也可在提示里直接说「使用 verifier 检查这次改动」 |
本课只建两个只读角色，都放项目目录。tools 用逗号分隔，中间的空格可有可无，但工具名要和实际工具名一致。写错的名字等于没写——配完让它跑一次验收，再用 git status --short 看它有没有改文件：改得动，就说明哪个工具名写多了。
两份都用 tools: Read, Grep, Glob，验收时既不能改文件，也不能跑命令。第一份查数据范围，第二份查改动是否越出 README 写明的范围。抄过去后改角色名与检查项。
只读子智能体。tools 里没有写类工具与 Bash，所以它只能看，不能动。每次验收后跑 git status --short 复核。
--- name: verifier description: 验收数据范围。在改完查询、上传或检索之后使用。只读，不改文件。 tools: Read, Grep, Glob --- 用两个所属范围的账号各看一次。 当前所属范围的数据能读到。 其他所属范围的数据读不到，且与记录不存在无法从响应区分。 没有命中时返回无依据，不出现材料中没有的句子。 只报告看到的请求、SQL 或接口结果，不改代码。 回报格式：检查项 / 结论（通过或未通过）/ 证据（文件:行）。 若发现某一步需要改代码，只写出建议，不执行修改。
第二个只读角色，判据指向 README.md 的「当前阶段」。能用 @spec-reviewer 点名它，它也会在改到范围相关文件时被叫到。
--- name: spec-reviewer description: 核对这次改动是否越出 README 写明的范围。在合并请求合并前使用。只读，不改文件。 tools: Read, Grep, Glob --- 对照 README.md 的「当前阶段」一节，逐条判断改动属于范围内还是范围外。 列出本次改动涉及的目录。 指出任何「顺便加上」的角色、存储或接口。 不修改任何文件；结论只写「范围内」或「越界，应停」。 回报格式：条目 / 判断 / 依据的小节标题。
两个角色都只读，所以它们的结论必须由人复核并决定是否合并。子智能体给出的是证据，不是通过与否的最终判断——合并决定仍在 合并与审查 里做。
前两种是权限没收住，后两种是没被叫到或结论不可靠。按「现象 → 原因 → 修法」对号入座，改完让它再跑一次验收，并用 git status --short 确认。
| 现象 | 原因 | 修法 |
|---|---|---|
验收子智能体跑完，git status 里多出改动 | tools 里写了 Edit／Write，或写了 Bash 而命令能改文件 | tools 只留 Read, Grep, Glob，删掉 Bash 与写类工具；每次验收后用 git status --short 确认没有改动 |
建了 verifier.md，助手从没把工作交给它 | description 写成「验收的子智能体」，没说在什么任务后用 | 改成「在改完查询、上传或检索之后使用」；验证时也可在对话里输入 @verifier 点名 |
| 子智能体回报「其他范围读不到」，但其实没人切换过账号 | 只读子智能体只能看代码，不会真的换账号登录、发请求 | 把「用两个所属范围各看一次」写进 CLAUDE.md 与可执行规约，由人或接口测试执行；子智能体只做静态复核 |
只在 verifier.md 里写了「不许读 .env」，别的对话照读 | 子智能体不是每次会话都加载，约束不跟着走 | 硬约束写 CLAUDE.md，并用 钩子 拦住读取；不放子智能体里 |