Claude Code Agent Team 配置实战：多角色协作与工具权限设计

最近在项目里把 Claude Code 和 Agent Team 这套玩法完整跑通了一遍。先说背景：我们维护一个老 Python 后端，单文件几千行，改动一次风险极大。我最早只是用 Claude Code 的单对话模式让它帮忙改代码，后来发现任务稍微一复杂，它就开始“精神分裂”——上一秒还在做架构设计，下一秒又去写测试，上下文一长经常漏掉关键约束。于是我把目光转向 Claude Code 里的子代理机制，也就是社区里说的 Agent Team：给不同角色配上独立的系统提示和工具权限，让它们像一个小型工程团队一样在项目里协作。折腾了几天，踩了不少坑，今天把配置思路、完整步骤、碰到的问题一次性写清楚，给正在用 Claude Code 的读者一份能直接抄作业的参考。

1. Agent Team为什么值得配，单线程模式有哪些天花板

1.1 Claude Code 单对话模式的常见瓶颈

Claude Code 默认就是在一个主会话里跟你连续对话：你给它一个任务，它在当前上下文里完成。这个模式初期很好用，但随着项目复杂度上升，问题会越来越明显。

第一个问题是上下文窗口被琐碎信息占满。你让它帮你重构一个模块，它读了一堆文件，中途你又让它顺手看一眼别的 bug，前面那些代码片段还留在记忆里，等到真正需要集中精力设计重构方案的时候，可用的上下文已经不多了。这时候模型的表现就是“记了后面忘了前面”，经常重复问你已经交代过的约束。

第二个问题是角色切换成本高。让同一个会话既做架构设计，又做具体编码，还要兼顾测试，等于让一个人同时干三个岗位。不是说不能干，而是每个岗位需要的思维方式和处理粒度完全不一样。架构设计希望它宏观、克制、不轻易动手；编码实现希望它果断、细致、按方案落地；测试又希望它带着批判眼光挑毛病。揉在同一个 prompt 里，模型很容易“随机切换人格”。我在实际使用中明显感觉到，给一个 agent 说“你先分析再动手，写方案不要改代码”，它开头还能忍住，上下文一长又开始自作主张改代码了。

第三个问题是权限无法区分。你不希望一个正在做测试的 agent 顺手改掉生产代码，也不希望架构师在执行命令时把环境搞乱。单会话模式下，所有工具权限对所有任务统一开放，安全问题只能靠人盯着，很累。

1.2 Agent Team 的核心思路：让专业的人做专业的事

Agent Team 不是一个新的独立产品，它是在 Claude Code 里通过“子代理（subagents）”机制组织出来的一种工作方式。每个子代理有独立的系统提示词（system prompt）、独立的工具权限，甚至可以选择不同的底层模型。你在主会话里负责调度，就像项目经理拆活派活，子代理负责各自领域的实际工作。

这种设计有几个直接的收益：

• 上下文隔离。每个子代理只需要了解自己职责范围内的信息，不会把架构分析的一堆中间产物全塞进编码环节。
• 角色专业化。给架构师写的 prompt 就是“读代码、分析依赖、输出方案”，给测试写的 prompt 就是“运行测试、报告问题、禁止修改源码”，每条指令都更聚焦。
• 权限控制。测试 agent 不给 Write 和 Edit 工具，它想改代码都改不了；架构师不给 Bash 工具，它就不会乱执行命令。这比靠口头交代“你不要乱动”靠谱得多。
• 模型灵活调配。轻量任务给 Haiku 或第三方小模型，重活给 Sonnet 甚至 Opus，成本能明显降下来。

我自己的体会是，这套东西特别适合重构、模块拆分、新增功能这类“需要多阶段处理”的任务。单一问答不适合用 Agent Team，反而会因为调度开销显得笨重。

2. Claude Code环境安装与登录方案，先把地基打牢

2.1 安装前置要求与环境检查

不管你是要用 Agent Team，还是只想跑个普通会话，Claude Code 的安装环境是绕不开的第一步。官方推荐的安装方式是通过 npm 全局安装：

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

安装完成后，在终端执行：

claude --version

能看到版本号就说明装好了。这里重点提醒一下 Node.js 的版本问题。Claude Code 对 Node 版本有最低要求，如果你是用系统自带的旧版 Node 装的，很可能会在运行时报各种莫名其妙的兼容性错误。我建议直接装一个 Node.js LTS 版本，用 nvm 管理是几个平台都比较省心的方式：

# Linux / macOS / WSL 都适用 curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash nvm install --lts nvm use --lts

Windows 原生环境我之前也试过。网上有人报过“claude code 与 64 位 Windows 不兼容”的问题，其实绝大多数情况不是 64 位的问题，而是终端环境太旧，或者 Node 没走官方安装包而是用了某些精简版。如果你在 Windows 上装完运行报错，优先检查 Node 版本，还是不行就直接上 WSL2，在 Ubuntu 子系统里跑，整体顺畅很多。还有一点，不要随便从第三方博客或 CSDN 下载所谓“桌面版安装包”，Claude Code 的更新走 npm 和官方渠道，你自己下载的很可能版本残缺，跟当前账号体系的协议对不上。

2.2 登录、订阅与第三方接入的路径选择

安装好之后第一件事就是身份认证。官方支持的路径是登录 Claude 账号并确认订阅，在项目目录里运行：

claude

首次运行会引导你完成浏览器授权。这个流程要特别说一下：Claude Code 的很多能力依赖账号服务，包括模型调用、会话同步、部分工具链支持，所以如果你有官方订阅，直接用官方登录是最省事的路径。

在团队场景里，如果登录时遇到提示“your organization has disabled claude subscription access for claude code”，这通常是企业管理员在后台关掉了 Claude Code 的企业订阅权限，不是你自己的账号问题。处理方式只有两个：要么找管理员开通，要么用个人订阅账号登录。别去网上搜那些改配置绕过组织限制的旁门左道，一方面容易把账号搞出合规风险，另一方面企业审计如果真的查起来，你个人是扛不住的。

也有不少人不想登录官方账号，想走第三方模型接口。Claude Code 本身支持通过环境变量指定自己的 API 基址和令牌，典型配置是这样：

export ANTHROPIC_BASE_URL="你的API服务商兼容端点" export ANTHROPIC_AUTH_TOKEN="你的API密钥" export ANTHROPIC_MODEL="你的模型名"

这种玩法适合三种人：已经有第三方 API 订阅、想本地跑模型、或者要做模型对比评测。但它有两个坎：第一，Claude Code 原生用的是 Anthropic 的协议格式，第三方接口如果不兼容这个格式，你改了 base_url 也跑不通；第二，子代理的“工具调用”依赖模型对 function calling 的支持，模型太弱或者格式兼容不到位，Agent Team 就容易变成空壳。所以我的建议是，本地模型和第三方模型适合研究，真正干活还是认准官方订阅。

2.3 VSCode、桌面端与终端三种使用姿势

Claude Code 不只有命令行这一种入口。最常见的是直接在终端里跑，这也是配置 Agent Team 最完整的姿势，因为子代理的提示词文件、工具权限配置、CLAUDE.md 这些都是在项目文件里定义的，终端里读得最顺畅。

VSCode 用户可以直接装官方扩展，装好后左边栏会出现 Claude Code 面板。它的底层还是调用已经安装的 cli，所以你在 VSCode 里如果找不到 claude 命令，多半是 PATH 里没有 node 全局目录。Mac/Linux 加一下这个路径就行：

export PATH="$HOME/.local/bin:$PATH" export PATH="$PATH:$(npm config get prefix)/bin"

桌面端也可以装，界面更友好一点，但我的经验是：一旦你用上了 Agent Team 这种多角色配置，终端和编辑器里的完整输出面板反而是最好用的，桌面版适合普通问答不适合做复杂工程调度。三个入口你根据习惯任选一个作为主力，其他两个作为辅助。

3. Agent配置实战：三个角色的分工与工具权限设计

3.1 Agent Team 的文件组织方式

Claude Code 读取子代理配置的路径是项目根目录下的.claude/agents/，每个 agent 对应一个 Markdown 文件，文件名就是 agent 的名字。在这个目录之外还推荐维护一个.claude/CLAUDE.md，它相当于整个项目的工作规则手册，所有子代理在开始干活的时候都会读取它。

一个最小可用的目录结构是这样的：

your-project/ ├── .claude/ │ ├── agents/ │ │ ├── architect.md │ │ ├── coder.md │ │ └── tester.md │ └── CLAUDE.md ├── src/ └── docs/

我在搭建第一版的时候踩过一个坑：把 agent 文件直接放到了项目根目录，结果启动 Claude Code 后怎么都调不出子代理。后来反应过来了，Claude Code 只在.claude/agents/目录下找。所以第一步就是建目录，不要怕它多套一层，这个结构反而能让项目级的通用规则和 agent 个人设定解耦。

.claude/agents/coder.md 也不要乱放，我见过有人直接在系统级配置里写所有 agent，这在当前项目里就会产生两个问题：一是不同项目共用一套 agent 定义，互相污染；二是跟着项目走的团队协作配置没法随仓库分享。正确的做法是坚持把 agent 定义放到项目仓库内，这样同事 clone 下来就自带整套 Agent Team。

3.2 三个核心 agent 的系统提示词样例

Agent 的 Markdown 文件采用“YAML front matter + 正文”的结构。front matter 里写元信息，正文部分就是给这个子代理的系统提示词。

我以一个常见的“架构师、编码员、测试工程师”三件套为例，给出可以直接修改使用的配置。

第一个是架构师，职责是读代码、理解现状、输出方案。为了避免它在分析阶段动手改文件，我只给了它只读类工具：

--- name: architect description: 资深架构师，负责阅读代码、分析依赖、识别风险，输出重构方案。只做分析，不直接实现。 tools: Read, Grep, Glob model: sonnet --- 你是一名有多年经验的后端架构师。你的任务是在动手前把问题想清楚。 工作原则： 1. 先阅读相关文件和依赖关系，不要凭记忆猜测。 2. 输出内容必须落到文件里，比如 docs/refactor-plan.md，而不是只写在对话里。 3. 除非被明确要求，否则不要修改任何源码文件。 4. 方案里需要说清楚：当前问题、目标结构、改动点、风险点、测试策略。 约束： - 不执行终端命令。 - 不创建或编辑代码文件，只输出设计文档。

第二个是编码工程师，负责真正动手改代码。它需要读写工具和命令执行权，但我刻意不把 grep 和 glob 单独列出来，因为这些读操作对编码来说属于基础能力：

--- name: coder description: 主程，负责按方案编写和重构代码，可以读写文件、执行命令。 tools: Read, Write, Edit, Bash, Grep, Glob model: opus --- 你是一名精通 Python 和系统设计的工程师。你的职责是按已有方案实现具体改动。 工作原则： 1. 动手前先读架构方案和现有代码结构。 2. 每次改动要小步推进，改完一部分就停下来确认，不要一次堆几千行。 3. 代码风格与项目现有风格保持一致。 4. 中途发现问题，先记录到 docs/refactor-notes.md，不要自作主张扩大范围。

第三个是测试工程师，任务是对改动进行验证。我给了它 Bash 权限，但通过提示词明确限制为只跑测试和检查命令，同时在工具列表里去掉了 Write 和 Edit，从根上杜绝代码被它误改：

--- name: tester description: 测试工程师，负责运行测试、定位问题，输出测试报告。不修改源码。 tools: Read, Grep, Glob, Bash model: sonnet --- 你是一名严谨的测试工程师。你的目标是验证代码是否满足要求。 工作原则： 1. 优先读取测试文件和被测模块，理解预期行为。 2. 使用 pytest 等命令运行测试，记录失败用例。 3. 输出测试结论到 docs/test-report.md，明确指出失败点。 4. 不要修改任何源码和测试文件。

这三个文件配置好之后，你在主会话里就可以直接“点名”调用了。调用方式可以是在对话里输入 @architect、@coder、@tester，后面跟上你的指令，Claude Code 会切换对应该子代理的上下文和工具集来执行。

3.3 工具权限和模型选择的几个底层原则

权限设计是整个 Agent Team 配置里最值得花时间的部分。我的原则是“默认最小，按需追加”。子代理能拿到的工具越少，越不容易出乱子。比如测试工程师，看似需要自由执行命令，但如果过于放开，它完全可能在项目里跑一些有副作用的脚本。所以我在 prompt 里特意加上一句“只运行测试和无副作用的检查命令”，这样即使它拿到 Bash，也还有个行为约束兜底。

模型选择上，我一般遵循：任务越精细、越需要代码生成质量，用越强的模型；任务越偏分析、模板化，用轻量模型。比如 coder 用 Opus 保证重构质量，architect 和 tester 用 Sonnet 就够，一些固定格式的杂活甚至可以直接用 Haiku。这样组合下来，单次任务的 token 消耗比全程用顶配模型要低不少。

还有一点容易忽略：agent 文件的正文部分要尽量“把边界写死”，不要给模型留太多自由发挥空间。你可以允许它思考，但你的输出格式、落地文件、禁止行为都要明确。我在项目里每次遇到“它偏离了我的意图”的情况，回头一看基本都是 prompt 里没有写禁止项，或者是工具给多了。

4. 一个真实重构任务跑通三个Agent的完整协作流程

4.1 任务拆解与启动方式

光讲配置不讲实战等于白说。下面用一个我实际跑过的例子走一遍完整流程。

假设有一个legacy_service.py，600 多行，里面数据库查询、HTTP 处理、业务逻辑全混在一起。目标是拆成 services、storage、routes 三个模块，并且补上 pytest 测试。处理这种重构，我不会一上来就让 coder 直接改，而是先在 Claude Code 主会话里把任务拆成三个阶段：

• 架构师阶段：分析现状，输出重构方案。
• 编码阶段：按方案拆模块、改调用关系。
• 测试阶段：跑测试，反馈问题，修复回归。

启动方式很简单，在项目根目录进入终端的 claude 交互界面，先呼出架构师：

@architect 请阅读 legacy_service.py，梳理里面的职责和依赖，输出一份拆分方案，写到 docs/refactor-plan.md

这里的关键是把“输出到哪个文件”写清楚。很多人的 Agent Team 越跑越乱，就是因为让 agent 把方案写在对话里，下一步的 coder 根本看不到完整内容，只能靠主会话转述，上下文就慢慢被冲掉了。让方案落到文件里，是 Agent Team 协作的基石。

4.2 三个阶段的执行过程与我的观察

架构师阶段的运行结果，通常会生成一份类似这样的方案摘要：

# 重构方案：legacy_service.py 模块拆分 ## 现状 - 文件包含 Database 连接逻辑、PaymentService 业务逻辑、FastAPI 路由定义。 - 三个部分之间通过函数直接调用，无清晰分层。 ## 目标结构 - app/storage/db.py：数据库连接与会话管理 - app/services/payment.py：支付业务 - app/routes/payment.py：HTTP 路由 ## 改动点 - 将 db 依赖从 service 中移到 storage 层 - 路由只负责解析参数，不直接访问 db - 新增 tests/test_payment.py 覆盖核心业务流程 ## 风险 - 路由层引入循环依赖，需要按依赖方向调整 import - 现有测试没有覆盖 db 回滚场景 ## 测试策略 - 用 fixture 管理数据库连接，每个用例独立回滚

拿到方案后，我会先自己扫一眼，确认没有明显方向错误，然后继续主会话调用 coder：

@coder 请按照 docs/refactor-plan.md 执行重构。先完成文件拆分和 import 调整，每完成一个文件就确认一次。

这里让 coder“分步确认”是我后来加上的。最初我没有这句话，coder 一口气写了好几个文件，结果有一个 import 顺序错了，排查起来非常费劲。后来改成小步确认，每步输出到docs/refactor-notes.md，问题就好追溯多了。

编码部分跑完后，接着调用测试工程师：

@tester 请检查重构后的代码结构是否完整，运行 pytest，输出报告到 docs/test-report.md。

tester 会读取改动，运行测试，然后把失败用例和原因写进报告。我遇到过测试报告里写着“fixture 作用域导致数据污染”，这时候只需要回到主会话，让 coder 针对失败点修复，再让 tester 重新跑一轮。这个“编码-测试-回归”的循环是 Agent Team 效率最高的环节，一个上午我就能完成以前需要一下午的模块拆分工作。

4.3 为什么用文件传递上下文比对话内传递更稳

我在实战里最大的认知更新，就是“不要用对话记忆传递信息，要用文件系统传递信息”。一开始我以为，主会话里先让 architect 说方案，再让 coder 做实现，子代理应该能“看到”前面聊了什么。实际测试下来发现，子代理的上下文与主会话并不是完全共享的，它更依赖项目文件和环境。如果你只在对话里铺垫了很多细节，coder 启动时可能根本没拿到全部信息。

用文件传递有几个额外好处：一是可追溯，重构完你能回看 plan、notes、test-report 三个文档，等于项目自带过程记录；二是可复用，下一次改动可以直接对比之前的方案，不让架构师每次都从零开始读代码；三是让主会话保持轻量，主对话只负责调度和决策，不会被大量代码细节占满上下文。

5. cc-switch 与本地模型：接入 DeepSeek、Qwen、GLM 和 LM Studio 的进阶玩法

5.1 用 cc-switch 管理多个第三方 API 供应商

如果你手上有多个 API 服务商，逐个改环境变量会非常烦。社区里常用的做法是借助 cc-switch 这类配置管理工具，把不同服务商的基址、密钥、模型名集中管理，一键切换。

它的原理其实不神秘：本质上还是修改 Claude Code 读取的环境变量，只不过帮你做了配置持久化和切换。我一般会在 cc-switch 里维护几套配置：

实际切换时，cc-switch 会把对应环境变量写入当前 shell 或 Claude Code 的配置，然后你需要重启 claude 进程让配置生效。这个“重启生效”的步骤很多人会漏掉，结果切换半天发现没变化，又跑来问为什么，其实只是进程还留着旧变量。

需要特别提醒的是：不是随便填一个 OpenAI 风格的 base_url 就能跑。Claude Code 默认走 Anthropic 的消息协议，很多第三方 API 原生只支持 OpenAI 的 chat/completions 格式。真正能无缝接入的端点，要么服务商自己做了 Anthropic 协议兼容，要么你走一层转换网关，把协议转成 Claude Code 认识的格式。我一开始图省事直接填了裸 base_url，启动后报一堆格式错误，回头才发现是少做了一次协议转换。这个坑一定要提前避开。

5.2 用 LM Studio 跑本地模型作为 Agent Team 的模型来源

本地模型是另一个方向，特别适合隐私敏感项目、无网环境，或者你想白盒观察模型推理过程的场景。LM Studio 是跑 GGUF 量化模型的常见选择，它自带一个 OpenAI 兼容的本地服务启动器，默认监听端口 1234。

把 Claude Code 指向 LM Studio，环境变量这么设：

export ANTHROPIC_BASE_URL="http://localhost:1234/v1" export ANTHROPIC_AUTH_TOKEN="lm-studio" export ANTHROPIC_MODEL="qwen2.5-coder-7b-instruct"

设置好之后，新建终端启动 claude，理论上它能通过本地端口完成模型调用。但我要泼一盆冷水：本地模型的工具调用能力决定了 Agent Team 能不能真正跑起来。Claude Code 的架构严重依赖 function calling 来操作 Read、Write、Edit、Bash 这些工具。如果你的本地模型不支持或者支持得很差，子代理会频繁出现“调了个寂寞”的情况，既读不了文件也写不了代码。

我实测下来，7B 量级的本地模型处理简单问答还能忍，处理 Agent Team 这种多轮工具调用就明显吃力。如果你想认真用本地模型跑 Agent Team，至少准备 30B 以上的模型，并且把单次任务拆得更细，一次只让子代理做一件事，比让它并行处理多个目标要可靠得多。

5.3 不登录账号的使用边界与注意点

很多人在问“不登录 Claude 账号能不能用 Claude Code”。结论是能，但需要你自备可用的 API 端点。不登录官方账号，意味着你完全走环境变量指定的第三方或本地端点，Claude Code 的官方在线服务能力就不参与这次会话。

这种模式适合两类情况：一是你本身是模型服务商的重度用户，想用 Claude Code 这个界面来调自家的模型；二是做本地开发，不希望代码传到第三方服务，所有推理都在本机完成。但代价也很明显：官方订阅账号附带的模型调度、稳定性和某些专有能力会缺失，子代理的体验会打折扣。所以在团队生产项目里我一直坚持“本地模型可以试，第三方模型可以比，正式流程还是走官方账号”的策略。

6. Agent Team常见问题排查与优化技巧速查

6.1 安装和集成环节的典型报错

安装阶段大家问得最多的是这几个问题。

“执行 claude 命令提示找不到命令”多半是 npm 全局目录没进 PATH。解决办法是把npm config get prefix对应的bin目录加到环境变量里，或者重开终端。如果你用的 Windows 原生环境，还可以检查是否有其它命令冲突，干脆用 WSL2 能省掉很多麻烦。

“VSCode 插件里找不到 claude”和上面原因一样，VSCode 启动时没有继承你 shell 里的 PATH。要保证你用来启动 VSCode 的终端环境本身能跑通 claude 命令，再重启 VSCode 让它重新捕获环境变量。

“npm install 时报错安装失败”优先检查 Node 版本和网络源。Node 版本太低是最常见的，升到当前 LTS 基本能解决。安装源有问题就临时换镜像源，但记得装完之后把全局 registry 改回来，避免后续别的包也走错源。

6.2 子代理不生效与上下文协作问题

Agent Team 配置好后，最常遇到的第一个现象是“@ 不到 agent”。原因基本只有两个：agent 文件没有放在项目根目录的.claude/agents/下，或者你启动 claude 的目录不对。Claude Code 是按“当前运行目录”去找.claude的，你在子目录里运行它就找不到项目的代理人文件。解决办法是回到项目根目录重启 claude。

第二个现象是“子代理不按约束来，经常跑偏”。我排查过几次，问题基本都在 prompt 本身。你写“不要修改源码”，但紧接着又给了它 Write 和 Edit 工具，它在边界模糊的时候就会倾向动手。最好的方式是工具的“硬约束”和 prompt 的“软约束”双管齐下，能不给的工具坚决不给，别指望一句“你要谨慎”能兜底。

第三个现象是“agent 之间上下文互相看不见”。前面说过，解决方案是让每轮产出落到文件。我在项目里固定用 docs 下的 plan、notes、test-report 三个文档作为协作交接物，子代理阅后即清，只拿当前阶段需要的内容，整个协作立刻就顺了。

6.3 成本与性能的优化建议

Agent Team 的 token 消耗比单对话模式高，这是正常的，因为每个子代理都会读一遍相关文件。想控制成本，我做了三件事：

• 每个子代理按职责选择不同型号的模型，分析任务用便宜模型，代码生成用贵模型
• 在 CLAUDE.md 里写明“一次只读取必要文件，不要递归扫全仓库”
• 用.claudeignore排除日志、构建产物这类无关文件，避免子代理把无关内容也读进来

性能方面，如果你发现其中某个子代理特别慢，先看是不是模型并发限制的问题。多个子代理共用同一个模型时容易排队，可以试着给不同角色分配不同的模型名，或者错开调用时间，别一次把三个 agent 全塞进同一个任务里。

关于团队协作，再补充一句：如果你所在团队有飞书之类的 IM 工具，有人问“飞书能不能直接连接 Claude Code”的问题，我的回答是 Claude Code 本身没有飞书官方插件，通常需要把它封装成内部服务再通过机器人接口转发，这个工程化成本和 Agent Team 配置是两码事，不要混在一起搞。

最后聊点个人体会。用 Agent Team 最怕的不是模型能力不够，而是你觉得“多 Agent 就是万能”。我一开始贪多，一口气配了五六个角色，结果调度成本比直接单线程还高。后来收敛到“架构、编码、测试”三个角色，再加上清晰的产出物约定，效率反而上来了。给每个 agent 写系统提示的时候，多写几句“禁止做什么”，比写一大段“应该做什么”管用得多。这套东西不是零成本，但一旦跑顺，你面对大改动的心态会完全不一样。你可以先从一个最小配置开始，跑通一个任务后再慢慢加角色、加工具，找到适合自己项目的节奏。