1. 为什么单次对话搞不定代码审查、测试和架构分析如果你已经在用 Claude Code 写代码大概率遇到过这种场景让它审查一个模块它回复得头头是道但漏掉了两个关键调用点让它补测试生成的用例跑起来一半是红的让它分析架构它把三个服务的职责说串了。问题不在于模型不够聪明而在于你把三种性质完全不同的任务塞进了同一个上下文窗口。代码审查需要的是“挑刺”视角——关注边界条件、异常路径、权限校验测试生成需要的是“覆盖”视角——关注分支、mock、断言架构分析需要的是“全局”视角——关注模块依赖、数据流向、耦合点。这三种视角放在一个对话里模型会不自觉地用同一种语气处理所有事情结果就是审查不够尖锐、测试不够全面、架构分析浮于表面。Claude Code 的 Subagents 机制解决的正是这个问题。它允许主代理把一个大任务拆成若干子任务每个子任务带着独立的上下文和明确的角色定义去执行最后把结果汇总回来。你可以把它理解成以前你是在跟一个“全栈工程师”对话现在你是在指挥一个“审查员 测试员 架构师”的小团队每个人只干自己最擅长的事。这篇文章不讲概念直接给配置。我会围绕代码审查、测试、架构分析三类场景给出可复制的settings.json骨架定义每个 subagent 的触发条件、权限边界和调用链然后通过一次真实的审查任务验证输出是否符合预期。你跟着配一遍就能在自己的项目里跑起来。2. 前置准备TaoToken 接入与 Claude Code 环境确认Subagents 的配置本身不依赖特定的 API 供应商但你需要一个稳定的模型接入点来驱动 Claude Code。我目前用的是 TaoToken 的接入方案它的 API 端点兼容 Anthropic 格式配置起来比较直接。首先确认你的 Claude Code 已经能正常调用模型。如果你还没配好接入层可以先去 TaoToken 的控制台创建一个 API Key。地址是 https://taotoken.net/api 注意这个地址不带任何追踪参数直接访问即可。创建 Key 之后在 Claude Code 的配置里把 base URL 指向 TaoToken 的 API 端点模型名称按你实际使用的 Claude 版本填写。这里有一个容易踩的坑Claude Code 的settings.json里同时存在“全局设置”和“项目级设置”。Subagents 的定义建议放在项目级设置里也就是你项目根目录下的.claude/settings.json。全局设置里只放 API Key 和默认模型这样不同项目可以有不同的 subagent 配置互不干扰。确认环境可用的方法很简单在项目目录下运行一次claude命令输入一句“列出当前目录的文件”看它能否正常返回。如果这一步就报错先解决接入问题再往下配 subagents。3. settings.json 骨架三类 Subagent 的完整配置下面这份配置是我在实际项目中跑通的骨架你可以直接复制到.claude/settings.json里然后根据自己项目的路径和命令做调整。配置的核心是subagents字段每个 subagent 包含name、description、trigger、tools、permissions和prompt六个部分。{ subagents: { code-reviewer: { name: code-reviewer, description: 对指定文件或目录进行代码审查关注边界条件、异常处理、权限校验和潜在 bug, trigger: { keywords: [审查, review, 检查代码, 找问题, code review], filePatterns: [*.py, *.ts, *.js, *.go, *.java] }, tools: [read_file, search_files, run_command], permissions: { read: [src/**, lib/**, app/**], write: [], commandWhitelist: [grep, find, wc, cat] }, prompt: 你是一名严格的代码审查员。你的任务是找出代码中的问题而不是赞美它。重点关注1) 边界条件是否处理空值、越界、超时2) 异常路径是否有兜底3) 权限校验是否完整4) 是否存在资源泄漏。输出格式按文件分组每条问题标注严重级别高/中/低和具体行号。不要修改代码只输出审查报告。 }, test-writer: { name: test-writer, description: 为指定模块生成单元测试或集成测试覆盖正常路径、边界条件和异常路径, trigger: { keywords: [写测试, 补测试, 生成测试, test, 单元测试, 集成测试], filePatterns: [*_test.py, *.test.ts, *.spec.js, test_*.py] }, tools: [read_file, write_file, run_command], permissions: { read: [src/**, tests/**, conftest.py, pytest.ini], write: [tests/**], commandWhitelist: [pytest, python -m pytest, npm test, jest] }, prompt: 你是一名测试工程师。你的任务是为指定模块生成可运行的测试代码。要求1) 覆盖正常路径、边界条件、异常路径三类场景2) 使用项目已有的测试框架和 fixture不要引入新依赖3) 生成后必须运行一次测试确认能通过4) 如果测试失败先检查是测试代码问题还是业务代码问题不要擅自修改业务代码。输出格式测试文件路径 测试用例列表 运行结果。 }, arch-analyzer: { name: arch-analyzer, description: 分析指定模块的架构依赖、数据流向和耦合点输出结构化分析报告, trigger: { keywords: [架构分析, 依赖分析, 模块关系, 数据流, architecture], filePatterns: [*.py, *.ts, *.go, *.java, *.md] }, tools: [read_file, search_files], permissions: { read: [src/**, docs/**, README.md, package.json, requirements.txt], write: [], commandWhitelist: [grep, find, tree] }, prompt: 你是一名架构分析师。你的任务是分析指定模块的架构关系。重点关注1) 模块之间的依赖方向谁依赖谁2) 数据在模块间的流转路径3) 是否存在循环依赖或过度耦合4) 对外暴露的接口边界是否清晰。输出格式依赖关系图用文字描述 数据流路径 风险点列表。不要修改任何代码只输出分析报告。 } } }这份配置里每个 subagent 的permissions字段是关键。read和write用 glob 模式限定范围commandWhitelist限定可以执行的命令。这样做的目的是让每个 subagent 只能在自己的一亩三分地里活动避免它越权修改不该改的文件。trigger字段决定了主代理什么时候会调用这个 subagent。keywords是自然语言触发词filePatterns是文件类型触发条件。两者是“或”的关系只要命中一个主代理就会考虑调用对应的 subagent。4. 触发条件、权限边界与调用链的设计逻辑配置写完了但如果你不理解每个字段背后的设计意图遇到问题就不知道怎么调。这一节我把三类 subagent 的设计逻辑拆开讲。代码审查 subagent 的权限设计是“只读 受限命令”。它不能写文件只能读src/**和lib/**下的代码能执行的命令只有grep、find、wc、cat这类只读工具。为什么这么严因为审查的本质是“发现问题”不是“修复问题”。如果让审查 subagent 有写权限它可能会在审查过程中顺手改代码导致你分不清哪些是审查建议、哪些是已经落地的修改。审查报告应该是一份独立的文档由你决定是否采纳。测试 subagent 的权限设计是“读业务代码 写测试目录”。它能读src/**来理解被测逻辑但只能写tests/**。命令白名单里放了pytest和npm test因为测试生成后必须运行一次验证。这里有一个细节prompt里明确写了“如果测试失败先检查是测试代码问题还是业务代码问题不要擅自修改业务代码”。这是为了防止测试 subagent 为了让测试通过而篡改业务逻辑那就本末倒置了。架构分析 subagent 的权限最窄只有读权限连命令白名单都只保留了grep、find、tree。架构分析需要的是全局视野但它不应该修改任何东西。它的输出是一份分析报告你拿着这份报告去决定要不要重构。调用链方面主代理的调度逻辑是这样的当你输入一个任务描述时主代理先做一次意图识别看命中哪些 subagent 的trigger。如果命中多个它会按“分析 → 审查 → 测试”的顺序串行调度。比如你说“审查一下 auth 模块并补上测试”主代理会先调code-reviewer审查拿到审查报告后再调test-writer针对审查中发现的问题生成测试。这个顺序不是硬编码的而是主代理根据任务语义动态决定的。5. 验证请求跑一次真实的代码审查任务配置写好了接下来验证它能不能跑通。我准备了一个有问题的 Python 文件作为测试目标文件路径是src/auth/login.py里面故意留了几个典型问题没有处理空密码、异常捕获过于宽泛、日志里打印了敏感信息。在 Claude Code 里输入这样的任务描述审查 src/auth/login.py找出所有潜在问题按严重级别分类。主代理识别到“审查”这个关键词命中code-reviewer的 trigger于是派发子任务。子代理读取文件后返回的审查报告应该包含以下内容## 审查报告src/auth/login.py ### 高严重级别 - 第 23 行password 参数未做空值检查传入 None 时会在 hashlib.md5 处抛出 TypeError - 第 31 行except Exception 捕获了所有异常包括 KeyboardInterrupt建议缩小捕获范围 - 第 38 行日志中打印了 password 明文存在敏感信息泄露风险 ### 中严重级别 - 第 15 行数据库查询未使用参数化查询存在 SQL 注入风险 - 第 27 行token 生成使用了固定的 secret建议从环境变量读取 ### 低严重级别 - 第 42 行函数缺少 docstring - 第 45 行魔法数字 3600 建议提取为常量如果你拿到的报告和上面类似说明审查 subagent 工作正常。注意报告里没有直接修改代码只是列出了问题和行号这正是我们想要的“只读审查”行为。接下来验证测试 subagent。输入为 src/auth/login.py 生成单元测试覆盖正常登录、密码错误、用户不存在三种情况。主代理命中test-writer子代理读取src/auth/login.py和现有的tests/目录结构生成tests/test_login.py然后运行pytest tests/test_login.py -v。如果测试通过你会看到类似这样的输出tests/test_login.py::test_login_success PASSED tests/test_login.py::test_login_wrong_password PASSED tests/test_login.py::test_login_user_not_found PASSED 3 passed in 0.42s如果测试失败子代理会在报告里说明失败原因并区分是测试代码问题还是业务代码问题。这一步的验证标准是测试文件确实写入了tests/目录且运行结果符合预期。6. 本篇常见错排查配置过程中最容易出问题的几个地方我按出现频率排个序。第一个坑subagent 不触发。你输入了任务描述但主代理没有调用任何 subagent而是自己直接回答了。原因通常是trigger.keywords里没有匹配到你用的词。比如你写的是“帮我看看这段代码”但 keywords 里只有“审查”和“review”。解决办法是在 keywords 里多放几个同义词或者直接用配置里定义的触发词。第二个坑权限报错。子代理尝试读取一个不在permissions.read范围内的文件被拒绝后任务中断。比如你的项目代码在packages/目录下但配置里只写了src/**。解决办法是把实际路径加到 read 列表里或者用更宽泛的 glob 模式。第三个坑命令白名单太窄。测试 subagent 需要运行pytest但你的项目用的是python -m pytest白名单里没有这一条导致测试无法执行。解决办法是把项目实际使用的命令加进commandWhitelist。第四个坑多个 subagent 互相干扰。你同时触发了审查和测试但测试 subagent 读取了审查 subagent 的中间输出导致上下文污染。这种情况一般不会发生因为每个 subagent 的上下文是隔离的。但如果你的任务描述里同时包含了审查和测试的指令主代理可能会把两个任务的结果混在一起返回。解决办法是分两次输入先审查拿到报告后再单独发测试任务。第五个坑settings.json 格式错误。JSON 里多了一个逗号、少了一个引号都会导致整个配置不生效。Claude Code 启动时如果解析失败会静默忽略 subagents 配置。验证方法是运行claude --debug看启动日志里有没有配置解析错误。7. 把 Subagents 接入你的日常编码流程配置跑通之后你可以把这三个 subagent 固化到日常流程里。我的习惯是每次提交代码前先跑一次code-reviewer把审查报告里的高严重级别问题修掉然后跑test-writer补上新增逻辑的测试如果是跨模块的改动再跑一次arch-analyzer确认没有引入意外的依赖。如果你需要长期在项目里使用这套配置建议把 API Key 和模型接入信息放在全局设置里把 subagents 定义放在项目级设置里。这样换项目时只需要复制.claude/settings.json不用重新配接入层。TaoToken 的 API Key 可以在控制台里管理地址是 https://taotoken.net/api 创建后直接填入 Claude Code 的配置即可。对于需要长时间跑编码任务的场景比如批量重构或持续集成可以考虑用 Coding Plan 来管理调用配额和并发限制。模型对话入口适合快速验证单个 subagent 的输出质量接入文档里则详细说明了各种配置字段的完整语义。你可以先从代码审查这个场景开始跑通之后再逐步加上测试和架构分析不用一次性把三个都配齐。
