最近在项目里把 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 --ltsWindows 原生环境我之前也试过。网上有人报过“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.py600 多行里面数据库查询、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.pyHTTP 路由 ## 改动点 - 将 db 依赖从 service 中移到 storage 层 - 路由只负责解析参数不直接访问 db - 新增 tests/test_payment.py 覆盖核心业务流程 ## 风险 - 路由层引入循环依赖需要按依赖方向调整 import - 现有测试没有覆盖 db 回滚场景 ## 测试策略 - 用 fixture 管理数据库连接每个用例独立回滚拿到方案后我会先自己扫一眼确认没有明显方向错误然后继续主会话调用 codercoder 请按照 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 里维护几套配置配置名主要用途典型模型official日常主力官方订阅Sonnet / Opusdeepseek长上下文分析任务DeepSeek 系模型qwen中文理解与代码生成对照Qwen 系模型glm部分项目里的低价批量任务GLM 系模型local-lm-studio本地离线调试Qwen / Llama 本地量化模型实际切换时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_URLhttp://localhost:1234/v1 export ANTHROPIC_AUTH_TOKENlm-studio export ANTHROPIC_MODELqwen2.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 写系统提示的时候多写几句“禁止做什么”比写一大段“应该做什么”管用得多。这套东西不是零成本但一旦跑顺你面对大改动的心态会完全不一样。你可以先从一个最小配置开始跑通一个任务后再慢慢加角色、加工具找到适合自己项目的节奏。