企业官网建设流程全解析

最近在研究多代理协作开发时，被同一个问题反复绊倒：单靠一个 Claude Code 实例处理跨模块需求，经常出现改完 A 文件忘了 B 文件依赖的情况。后来我把项目拆给多个代理并行处理，效率提升非常明显。这篇内容就把我配置 Agent Team 的完整过程、踩过的坑和最终沉淀下来的方案整理出来，希望能帮到正在折腾 Claude Code 多代理模式的朋友。

Agent Team 是 Claude Code 里用于组织多个子代理协同工作的配置机制。它不改变底层模型能力，而是通过一套任务拆解、角色定义和工作流编排，让多个代理各司其职。这套机制比较适合中型以上的代码库、跨文件重构、全栈功能开发这类任务。如果你是刚开始接触 Claude Code，建议先跑通单代理的基础用法，再进入 Team 模式，否则排查问题时会混淆到底是模型能力问题还是编排问题。

1. Agent Team 到底解决了什么问题

很多人在刚接触 Agent Team 时，第一反应是"这不就是把多个 AI 窗口拼在一起吗"。实际用下来，差距很大。单窗口的 AI 助手是线性逻辑：你给它一个任务，它从头做到尾，过程中的每个决策都由同一个上下文推导。这种模式在任务范围明确、涉及文件少时没问题，但一旦任务跨度变大，比如"给整个项目增加权限系统"+ "重构所有接口错误处理"，单代理就会暴露出明显的短板。

1.1 单个 Agent 的上下文瓶颈

Claude Code 的单代理在同一时刻只能维护一份上下文状态。当对话轮次变多、文件改动范围变大时，早期对话里确定的设计决策会被慢慢遗忘，或者被后续的信息覆盖。我实测过一个 30 分钟以上的长会话，代理开始出现前后矛盾的操作，比如先确定了接口返回结构{code, data, message}，处理到后半程又按老结构{status, result}去写前端调用。这种问题不是模型笨，是上下文窗口有限导致的必然衰减。

1.2 并行与专精的差距

Agent Team 的核心价值在于两点：并行和专精。

所谓并行，是指多个子代理可以同时处理互不依赖的任务。比如一个代理负责数据库模型设计，另一个代理同时写 API 路由，还有一个代理做前端页面骨架。三个任务并行推进，总耗时不再是单代理那种线性累加。

所谓专精，则体现在角色定位上。你可以给子代理注入专属的系统提示词和工具白名单，比如"后端代理只能读写server/目录下的文件、不允许修改前端代码"，这种硬性边界在单代理模式下几乎做不到——你叮嘱它别碰前端代码，它十有八九还是会碰。

1.3 什么样的任务适合上 Team

按照我现在的经验，以下场景适合配置 Agent Team：

• 跨模块全栈功能开发，比如从数据库到 API 再到前端页面的完整链路
• 大规模重构，需要同时修改数十个文件且保持风格统一
• 批量任务，比如一套数据迁移脚本需要在多个环境跑
• 需要多角色审查的流程，比如编码完成后立刻有独立代理做 code review

反之，如果只是改个文案、调一个接口参数、修个简单 bug，用单代理就好。为这些轻量任务配置 Agent Team，配置成本反而比节省的时间更高。

2. 从零装好 Claude Code 并完成基础验证

在聊配置之前，先把安装这步理清楚。Claude Code 目前提供命令行工具和 VS Code 插件两种形态，两者可以同时使用，共享同一份配置。

2.1 CLI 安装方式

命令行工具基于 Node.js 发行，安装前先确认本机 Node 版本。我建议 Node 18 以上，实测 Node 16 也能跑，但部分新功能会有兼容告警。

# 检查 node 版本 node -v # 全局安装 Claude Code npm install -g @anthropic-ai/claude-code # 验证安装 claude --version

安装完成后，直接输入claude会进入交互式会话。首次运行需要登录授权，按提示跳转到浏览器完成认证，认证通过后会自动生成本地凭据，后续使用时不需要重复登录。

如果你用的是 macOS 或 Linux，还可能需要给claude命令配置 PATH 环境变量。npm 全局安装的目录通常在/usr/local/bin或$(npm prefix -g)/bin，遇到command not found时优先检查这个路径。

2.2 VS Code 插件集成

VS Code 插件的方式更适合日常编码场景。在扩展市场搜索 Claude Code 或 Claude Code for VS Code，安装后会在侧边栏生成一个聊天面板。插件的好处是能直接读取当前打开的工作区文件，配合编辑器的上下文做修改时，代理对项目结构的理解比纯 CLI 模式更准确。

需要注意，VS Code 插件和 CLI 共用同一份配置文件。如果你已经用 CLI 配置过 Agent Team，插件侧可以直接继承配置，不需要重复设置。

2.3 版本升级

Claude Code 的迭代频率很高，新功能基本都是随版本更新发布。升级方式很简单：

npm update -g @anthropic-ai/claude-code

我在实践中遇到过一个典型问题：配置了 Agent Team 后发现部分子代理行为异常，查了半天发现是本地的 Claude Code 版本太旧，某些加载配置时用到的解析能力在旧版本没有。所以遇到诡异问题，第一件事先升级版本看看能不能解决。

2.4 关于地区可用性的说明

在安装或运行过程中，如果看到类似 "Claude Code might not be available in your country" 的提示，说明你当前所在的网络环境不在官方支持范围内。遇到这种情况，请直接查看 Anthropic 官方文档中列出的支持国家/地区列表，以官方说明为准。务必通过正规渠道核实与操作，不要使用任何非官方手段绕过限制，这既影响账户安全，也存在使用风险。

3. Agent Team 的运行机制拆解

配置 Agent Team 之前，先搞清楚它内部是怎么工作的。理解了运行机制，后面配置时就知道每个字段的意义了。

3.1 主代理与子代理的关系

在 Claude Code 的 Team 模式中，存在一个主代理（Lead Agent）和若干子代理（Subagents）。主代理是入口，它接收你的初始任务，决定如何拆解、是否委派、以及如何汇总结果。

子代理是执行单元。每个子代理有独立的上下文窗口和独立的系统提示词，它们之间的对话历史不共享。这意味着子代理 A 改了什么文件，子代理 B 并不会自动知道，只能通过主代理转述任务要求、或通过读取共享文件来获取信息。

这个设计有一个重要含义：不要让两个子代理同时修改同一个文件。如果 A 和 B 都在编辑config.ts，后写入的一方会覆盖前者的成果，而且还不会报错——因为两个代理之间没有消息互通。

3.2 任务委派流程

一个典型的 Agent Team 任务流程大致如下：

1. 主代理收到用户请求"给用户模块增加导出 Excel 功能"
2. 主代理判断需要改动server/下的导出接口和web/下的导出按钮
3. 主代理把接口任务委派给后端子代理，把按钮和前端逻辑委派给前端子代理
4. 两个子代理并行开始处理，各自维护独立会话
5. 子代理完成回传结果后，主代理汇总、验证、给出最终交付说明

实际运行中，主代理不一定等待所有子代理全部完成才收尾，它可能先拿到 A 的结果，就基于这个结果决定下一步是继续指派还是直接结束。这种动态调度能力，是 Team 模式和单纯并行发多个请求的本质区别。

3.3 核心配置字段解读

Claude Code 的 Agent Team 配置由 JSON 文件承载，通常存放在项目根目录下的.claude/目录中。配置文件里字段不多，但每个字段都直接决定子代理的行为边界。

我用一个简化示例说明核心字段：

{ "name": "api-backend-agent", "description": "负责后端 API 接口开发与数据库模型设计", "tools": ["Read", "Edit", "Bash", "Glob"], "prompt": "你是一个资深后端工程师，只负责 server/ 目录下的开发工作。不得修改 web/ 目录下的任何文件。", "model": "opus" }

• name：子代理标识，主代理委派任务时用它来指定目标代理
• description：描述这个代理擅长什么。主代理会读这段文字来决定是否把任务委派给它
• tools：允许代理使用的工具白名单，不给的它就用不了
• prompt：系统提示词，定义代理的角色、职责边界和风格
• model：可选字段，指定该子代理使用哪个模型。不同模型成本、能力差异较大，可以根据任务重要程度分开配置

在实际配置中，description和prompt往往决定 Team 协作质量的一半。描述写得越精准，主代理的调度判断就越准确；提示词约束得越明确，子代理越不容易越界。

4. 搭建第一支 Agent Team 的完整过程

理论讲完，下面进入实操。我会用一个前后端分离项目作为示例，完整演示三角色 Agent Team 的配置过程。

4.1 项目背景与角色划分

假设现在有一个项目，server/是 Node.js 后端，web/是 React 前端，根目录还有一份部署脚本。目标是把配置过程做成三个子代理：

• backend-agent：负责后端 API、数据库相关开发
• frontend-agent：负责前端组件、页面开发
• review-agent：负责代码审查，不直接写代码，只读不改

为什么不把部署脚本也单独建一个代理？因为脚本规模通常较小，主代理顺手就能处理。代理数量并非越多越好，协作中的沟通开销是实打实的成本，这一点后面再展开。

4.2 编写三个子代理的配置

先在项目根目录创建.claude/agents/目录，存放子代理配置文件。

mkdir -p .claude/agents cd .claude/agents

第一个文件backend.json：

{ "name": "backend-agent", "description": "负责 server/ 目录下的所有开发任务，包括 API 接口、数据库模型、中间件，熟悉 Express 和 PostgreSQL", "tools": ["Read", "Edit", "Bash", "Glob", "Grep"], "prompt": "你是一名资深 Node.js 后端工程师。严格遵守以下规则：1. 只能修改 server/ 目录下的文件；2. 接口返回格式统一为 { code, data, message }；3. 修改数据库模型前必须检查现有迁移文件；4. 完成后输出：变更文件列表、新增接口说明、需要前端配合的字段变更。" }

这个配置里有两个关键设计。第一，tools中给了Bash，因为后端开发经常要跑测试、执行迁移命令；第二，prompt里强制规定了输出格式，这能让主代理在汇总结果时直接拿到结构化的信息，减少无谓的追问成本。

第二个文件frontend.json：

{ "name": "frontend-agent", "description": "负责 web/ 目录下的前端开发，包括 React 组件、页面、状态管理、样式，熟悉 Ant Design 和 Tailwind", "tools": ["Read", "Edit", "Glob", "Grep"], "prompt": "你是一名资深前端工程师。只负责 web/ 目录下的内容。调用后端接口时统一走 src/api/ 目录，禁止在其他位置直接写 fetch。组件样式优先使用 Tailwind 类，不新建 CSS 文件。完成后输出：变更组件列表、接口调用点、对后端接口格式的任何假设。" }

注意frontend-agent的tools里我没有给Bash。这是刻意为之——前端子代理不需要执行终端命令，不给Bash能避免它自作主张跑构建命令占用资源，也减少误操作风险。

第三个文件review.json：

{ "name": "review-agent", "description": "负责代码审查，只读不改，重点检查逻辑正确性、安全隐患、风格一致性", "tools": ["Read", "Glob", "Grep"], "prompt": "你是一名严格的代码审查员。只能读取文件，绝对不能修改任何文件。审查时关注：1. 是否有明显逻辑错误；2. 是否在文件中硬编码密钥；3. 是否违反项目统一规范；4. 变更是否超出任务范围。输出格式：问题列表（按严重程度排序）、每个问题的文件位置和修改建议。没有问题时明确说明。" }

审查代理不给编辑工具，是安全边界设计的一部分。让审查代理只读，可以有效避免它"顺手修复"引入新问题——审查和修改应该是两个分离的动作。

4.3 配置主代理的调度规则

子代理就绪后，还需要在主配置中声明这些代理。.claude/settings.json是 Claude Code 的主配置文件，里面可以设置代理列表和默认行为：

{ "agents": { "backend-agent": { "description": "后端开发子代理，使用场景：API 开发、数据库变更", "model": "opus" }, "frontend-agent": { "description": "前端开发子代理，使用场景：页面开发、组件调整", "model": "opus" }, "review-agent": { "description": "代码审查子代理，使用场景：功能完成后检查质量", "model": "sonnet" } } }

主配置里的description与子代理文件里的description可以相互补充。主配置里的描述更侧重"什么时候该用"——它帮助主代理理解调度策略；子代理文件里的描述更侧重"我是谁"——它塑造子代理的执行角色。

model字段我给了不同的值：两个开发代理用能力更强的模型，审查代理用成本更低的模型。审查任务是只读分析，对模型的推理深度要求没那么极端，成本控制在这个环节最值得做。

4.4 验证配置与首次调用

配置完成后，在项目根目录启动 Claude Code：

claude

进入交互界面后，输入/agents应该能看到刚配置的三个子代理。之后可以直接下达任务，比如：

"给用户模块增加导出Excel功能，后端代理负责接口，前端代理负责按钮和下载逻辑，完成后由审查代理检查变更"

主代理会按配置中的职责描述自动拆解并分别调用对应子代理。从指令下达方式可以看出，你不需要手动逐个唤起子代理，只需描述目标，主代理负责编排。

4.5 各文件在项目中的位置

把涉及的路径和职责汇总成一张表，方便对照检查：

所有配置文件都应该提交到版本库。这样团队其他成员克隆项目后，无需额外设置即可复用同一套 Agent Team 配置。

5. 对接第三方 API 模型的配置经验

不少团队在实际使用中，会希望让 Claude Code 的 Agent Team 跑在其他模型上，比如 DeepSeek、Qwen、GLM 这类开放接口的模型。这个需求本身是合理的，出于成本、数据合规或已有供应商协议等考虑。但在实际操作前，有几个基础概念必须先说清楚。

5.1 修改模型接入点的方式

Claude Code 默认连接 Anthropic 的官方 API 接口。要切换到其他兼容端点，通常用环境变量指定 Base URL 和 API Key：

export ANTHROPIC_BASE_URL="https://your-endpoint.example.com" export ANTHROPIC_AUTH_TOKEN="your-token" claude

设置完成后再启动 Claude Code，请求就会打到新端点上。这种做法的前提是目标服务提供的 API 与 Anthropic 的接口格式保持兼容。兼容层做得好的服务，跑起来基本无感；兼容层只覆盖了部分功能的，就需要实测确认哪些能力可用、哪些不可用。

5.2 使用网关工具管理多模型

手动改环境变量略显繁琐，如果想在多个模型之间来回切换，网关类工具会更顺手。这类工具通常提供一个本地中转服务，统一管理各家 API 的 Key 和路由规则。目前社区里比较常见的选择包括各类开源 API 网关，用它们也能实现类似 CC Switch 那种图形化切换的效果。

我用网关工具的感受是，切换速度比改环境变量快很多，尤其是在对比不同模型在相同 Agent Team 配置下的表现时，来回切几次就能得出结论。但成本也需要注意——网关本身多一跳网络转发，在请求量大时延迟会有小幅上升。

5.3 第三方模型下的 Agent Team 表现差异

把同一个 Team 配置切换到不同模型上运行后，我观察到的差异主要有三类。

第一类是工具调用稳定性差异。Agent Team 的运行高度依赖主代理正确调用Task工具来完成子代理委派。部分模型在单轮对话里表现不错，但进入多轮工具调用循环后，偶尔出现"忘了正在做任务"的断片现象。这类问题只能通过更换模型或缩小任务粒度来缓解。

第二类是提示词遵循度差异。prompt中定义的输出格式、禁止修改的目录等硬性约束，在不同模型身上的遵守程度不一样。表现好的模型能全程守住边界；表现弱一点的，中间会走出约束范围，需要主代理拉回来。这会导致"同一套配置，换模型后效果打折"的现象。

第三类是上下文管理效率差异。子代理回传的任务结果如果信息密度高、结构清晰，主代理汇总时就很省事；反过来，如果子代理输出啰嗦、重点埋藏深，主代理的上下文就会被无效信息填满，出现类似长会话后忘记早期决策的问题。

5.4 我的选择建议

如果你所在的环境用不了官方模型，或者你想降低成本，我的建议是：先保持官方架构不变，只替换底层模型接口，不要一上来就大改配置。换句话说，优先用环境变量或网关方式做兼容接入，先跑通一个子代理，再做整个 Team 的验证。

如果你对比了多个模型，发现 Agent Team 的模式在某个第三方模型上频繁出错，不要急着骂工具，先回到单代理模式测一下同一个任务是否流畅运行。单代理都有问题的模型，团队模式下只会放大问题。

6. 我踩过的坑和沉淀下来的经验

配置 Agent Team 不是一蹴而就的事，我前后折腾了两周才找到顺手的工作流。过程中踩了不少坑，挑几个最关键的分享出来。

6.1 子代理职责边界不清晰的教训

最开始配置子代理时，我把description写得比较宽泛，比如"负责用户模块相关开发"。实际运行时出现了一个问题：主代理把涉及用户模块的所有任务都委派给同一个代理，包括前端、后端甚至部署脚本的修改。结果这个代理虽然名为主力开发，实际却干成了全能角色，而且因为职责过宽，它的上下文消耗速度极快，任务中途就开始遗忘前期约定。

后来我把每个子代理的边界改成目录级约束，比如"只负责server/目录"、"只负责web/目录"，并配合prompt里的硬性禁止项，情况才好转。职责边界定义得越细，主代理的调度准确率越高。

6.2 并行冲突问题

这是我踩过最贵的一个坑。两个子代理同时被委派任务，各自都不知情地修改了同一个公共工具文件src/utils/request.ts，结果后写入的代理覆盖了前一个代理的改动。最棘手的是，被覆盖的那部分改动完全没有日志提示，等到运行测试报错才追溯出来。

解决方案有两步。第一，在prompt中给每个子代理明确规定可写目录，公共文件的修改权限收归主代理；第二，任务下达时，如果预判两个子代理可能触及同一文件，就改成串行处理——先让 A 改完，再让 B 基于新结果继续。

6.3 审查代理形同虚设的问题

起初我把审查代理和开发代理放在同一轮任务里，期望开发完成后自动触发审查。实操发现审查代理经常在开发中途就被唤起，此时代码还没改完，它审查了一版半成品，输出的问题列表毫无价值。

调整方式是在任务描述中明确处理顺序，比如"后端代理开发完成后，再让审查代理检查"；另一个办法是审查代理单独一轮启动，专门审查已完成且经过测试的变更。审查这个动作必须以完整、运行不报错的代码为输入，否则就是浪费一次回调成本。

6.4 上下文与 Token 成本控制

Agent Team 虽然并行高效，但 Token 消耗也是并行的。跑一个三代理任务，总体 Token 消耗可能是单代理的 2 到 3 倍。如果你对成本敏感，我建议：

• 审查类只读任务用成本更低的模型，开发类任务用强模型
• 子代理prompt里要求输出精炼的结果摘要，不要回传大段完整代码，减少主代理上下文占用
• 任务粒度控制在单个子代理单轮能完成的范围内，避免过度拆分导致调度开销大于执行开销

我最后的方案是把普通功能开发维持在单代理，只有确需并行的大任务才启用完整 Team，成本和效率才达到平衡。

6.5 给新手的上手建议

如果你之前完全没接触过 Agent Team，我建议按这个顺序渐进推进：

1. 先用单代理完成日常开发，熟悉 Claude Code 的交互节奏
2. 配置一个最简子代理，比如只做一个"代码审查"角色，跑通委派流程
3. 增加第二个子代理，形成两个开发角色的简单分工
4. 再逐步加入第三个、第四个，同时观察各模块的 Token 消耗和任务完成质量

每个阶段都先拿小型任务验证，不要一上来就编排五六个代理跑一个大型重构，那会让问题排查变得非常困难，尤其是当问题可能出在配置、模型、任务描述三个环节中的任何一个时。

结束前的最后几点体会

回头看我配置 Agent Team 的整个过程，最大的感受是：这个功能的价值不在"多个代理同时干活"这个表面现象，而在于它逼迫你把项目边界和任务流程想清楚。把文件目录、职责范围、输出格式这些约束写进配置后，代理的执行质量变得可预期，这本身就是一种工程化收益。

最后再分享一个小技巧：配置文件的prompt不是写一次就完事的，建议每次任务结束后，根据主代理的汇报内容反向调整措辞。如果它经常漏掉某个约束，就把那条约束写得再显眼一点；如果某个输出格式总是不稳定，就在后面补一句"必须严格按此格式输出，不得遗漏字段"。模型对提示词的理解是动态的，配置也需要跟着实际效果迭代。