企业官网建设流程全解析

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 的输出质量，接入文档里则详细说明了各种配置字段的完整语义。你可以先从代码审查这个场景开始，跑通之后再逐步加上测试和架构分析，不用一次性把三个都配齐。