Claude Code怎么创建只读子代理？工具白名单、作用域与结果核对

主会话为了找几个入口文件读了大量日志，后续任务可能被无关内容挤满。Claude Code子代理可在独立上下文调查，再返回摘要。本文定义一个仅能读文件和搜索的repo-map代理，讲配置、调用与验收；这与同时启动多个独立会话或代理团队不同，不需要把整个开发流程拆成一群代理。

第一步：决定是否真的需要子代理

一次小问题直接在主会话查即可。只有重复进行同类仓库调查，或搜索细节不值得长期留在主上下文时，才适合封装。子代理仍发出模型请求并计入同一用量范围，不能把独立上下文理解成免费资源或无限并发。

先确定职责，例如找入口、解释调用路径、报告依据，不兼任自动修复、部署和任务管理。描述清楚何时该用它，避免任何问题都被转交。输出应短而有来源，让主会话知道哪些结论可采用，哪些仍需检查。

第二步：选择正确保存位置

项目专用文件放.claude/agents/，个人跨项目放~/.claude/agents/。本例在练习项目创建.claude/agents/repo-map.md，先检查是否已有同名定义。不同作用域和嵌套目录存在优先级，同名可能覆盖另一版本，不能只凭文件名判断本次实际用的是哪份。

---
name: repo-map
description: 只读定位仓库入口、目录关系和已有验证命令，适合代码导览，不负责修改。
tools: Read, Grep, Glob
model: sonnet
---
只读取和搜索文件。每个结论提供真实文件路径与依据。
找不到时写未确认，不猜框架或启动命令。
报告包括：入口、调用路径、已有检查、未知项。
不修改、不安装、不联网，不提出已执行的虚假验证。

model与tools来自官方支持的配置形状，使用前确认账户和当前环境可用。工具白名单只列Read、Grep、Glob，不加入Bash、Write或Edit；不要仅在自然语言中说“只读”，同时给所有工具。配置文件是可审阅文本，保存前检查没有秘密或无关指令。

第三步：加载并明确请求使用

可直接让Claude创建并审阅该文件，也可手写。当前/agents主要提示你用自然语言或编辑文件，不应照搬旧版交互向导。若此前用户agents目录不存在、运行中才新建而找不到代理，按官方说明重启Claude Code后再试，先保存重要任务上下文。

请使用repo-map子代理，只读调查本练习项目的登录入口和相关调用关系。返回真实路径、依据与未知项，不修改仓库、不运行构建或测试。主会话先核对摘要，再给我下一步建议。

在会话记录中查看实际委派工具行及代理名称，不仅看回答里提到“已交给代理”。若没有实际调用，检查描述、作用域和名称是否匹配；不为触发委派扩大所有代理权限，也不连续启动重复调查浪费用量。

第四步：对照原文件验证报告

打开报告列出的入口文件和配置，检查引用是否真实、调用关系是否成立。代理没有执行测试，就不能宣称测试通过；只看到某个脚本名，也不能保证它目前可运行。把读取事实、推断和待验证项分开，避免主会话把摘要误当不可更改的事实。

请核对子代理摘要中的三项关键结论，逐项回到真实文件。发现名称或路径过期时说明原因，不替它补造结果。只读完成核对，暂不实施修复。

任务前后查看Git状态，确认练习中没有意外写入。子代理带回的是调查摘要，不自动恢复或锁定工作区；其他程序可能同时改文件，实施前仍需检查当前状态。

第五步：维护职责与适用边界

如果经常把无关信息带回，把输出格式与职责收窄；需要某种工具时再按真实任务调整并重新审阅。项目内已有规则也要核对加载情况，不能把代理文件当成替代所有长期项目说明。避免不同目录声明相同name导致难以辨认。

完成标准是调用到了正确代理、工具范围符合只读、摘要有依据且未知项明确。它解决的是隔离调查上下文与复用专业流程，不保证调查结论天然正确，也不替代主会话对实际改动和交付结果的责任。

官方资料

资料核对日期：2026年11月9日。

• Anthropic：Create custom subagents