企业官网建设流程全解析

上个月我把一个任务管理系统从零写到能跑通：后端是 FastAPI + SQLite，前端是 React + Vite，另外还要补测试、写 README、配 CI。一开始我就开着单个 Claude Code 会话让它从头盯到尾，结果到了第三天就卡得不行——不是它不会写，而是单条对话的上下文越滚越长，修改需求时它会记住太多旧细节，经常“过度尊重”早期方案，反而改不动。

后来我换成了 Claude Code 的多代理协作方式，一个主代理管调度，五个子代理分别负责架构、后端、前端、测试和代码审查，整个项目推进速度明显上了一个台阶。这篇文章我就把这段实战完整拆开，从为什么需要多代理、怎么配置子代理、到每个环节的提示词和踩坑记录都写出来，希望能给正在用 Claude Code 跑中型以上项目的朋友一些可复制的参考。

1. 整体思路拆解：单代理不够用才有的多代理

1.1 复杂项目的上下文压力是真实瓶颈

很多人第一次用 Claude Code 会觉得“这玩意儿真能写代码”，但项目一旦上了规模，问题就来了。单个会话处理一个 3000 行代码库、十几张数据表、几十个接口的时候，模型要同时记住用户需求、当前文件内容、过往对话结论和所有修改历史，上下文窗口再大也有撑不住的一天。哪怕 Claude Code 有 1M 的上下文版本，也不代表你可以无限往里塞信息——上下文越大，单次请求越贵，响应越慢，而且模型容易被早前的错误决定“锁死”。

我当时的体感特别明显：有一回只是想让前端代码换个状态管理库，结果它连着把后端的数据库连接配置也改了，原因就是在早前某次对话里它说过“统一用 localStorage”，后来这个上下文残留变成了错误决策的源头。说白了，单个聪明人扛所有事，和一支团队分工协作，复杂度一高，差距立刻拉开。

1.2 多代理方案选型：为什么选 Claude Code

市面上的 AI 编程工具里，能称得上“多代理协作”的并不多。Cursor 的 Agent 模式可以多文件操作，但本质还是一个代理在跑；GitHub Copilot Workspace 偏流程自动化，自由度没那么高。Claude Code 的做法更接近“主代理 + 子代理”的团队模型：主代理负责理解你的需求、拆解任务、调度资源，子代理各自拥有独立的上下文窗口和处理范围，干完活把结果交回来。

我选 Claude Code 的另一个原因是它的本地配置很轻：项目目录下一个 CLAUDE.md 就能定义项目约定，.claude/agents/下面放几个 Markdown 文件就能注册一批领域专家代理。不需要改 IDE、不需要额外搭服务、不需要写插件，纯文本配置，跟着项目走，换机器也能复现。这种“配置即代码”的思路，对长期维护非常友好。

1.3 架构设计：项目经理加领域专家

我把整个思路概括成一句话：主代理是项目经理，子代理是领域专家。主代理不会自己闷头写代码，它只负责接收需求、拆成子任务、分发给对应子代理、收结果、做集成。子代理每个人负责一块，比如后端代理专攻 API 和数据模型，前端代理只管组件和页面，测试代理盯着边界条件和回归用例。

这种设计有两个天然优势：第一，每个子代理的上下文是干净的，只包含自己职责范围内的信息，不会被其他模块的细节污染；第二，子代理之间通过文件系统交接，比如架构师把设计文档写进 docs/architecture.md，后端代理读取它来实现，前端代理读取同一份文档来定数据契约——文档成了团队之间的“接口”。这不是什么玄学，就是真实的团队协作方式被搬到了 AI 调度层。

2. Claude Code 多代理核心机制解析

2.1 主代理与子代理的分工关系

Claude Code 里的多代理是基于任务机制实现的。你可以粗暴理解成：你的对话对象是主代理，主代理内部有一个 Task 工具，当它觉得一件事适合交给专人处理时，就会拉起一个子代理，子代理带着明确的任务描述和独立上下文开始执行，结束后把结果摘要交回主代理，主代理再继续往下推进。

主代理不是被动的传话筒。它会根据你的需求决定哪个子代理上场，也会在子代理跑完后做集成检查。比如前端代理说“组件写完了”，主代理会检查 git diff、跑一次构建、发现问题再指派后端代理修复接口字段。这种来回调度的能力，才是多代理协作的核心价值——不是简单分房子，而是有人统筹。

2.2 通过 .claude/agents 自定义领域代理

自定义子代理是所有配置里最关键的一环。在项目根目录创建.claude/agents/目录，里面每个 Markdown 文件代表一个代理，文件名就是代理标识。文件开头用 YAML front matter 声明元信息，正文写系统提示词。

我的后端代理配置大概长这样：

--- name: backend-developer description: 负责后端接口设计、数据模型、数据库迁移和业务逻辑实现。当需要处理 /app 目录下的 Python 代码时使用。 tools: Read, Edit, Write, Bash, Grep, Glob model: sonnet --- 你是本项目的后端开发专家。技术栈是 FastAPI + SQLite + SQLAlchemy。 你只能修改 app/ 目录下的文件，如果有需求涉及其他目录，不要直接改，而是写一份说明文件放到 docs/notes/ 下面。 在开始实现前，必须先读取 docs/architecture.md，严格遵循其中的接口契约。 完成一个功能后，运行 pytest tests/test_backend.py 验证，确认通过后再汇报。

这里有三个点值得强调：

• description 是注册索引。主代理会根据描述里的关键词决定谁上场，所以描述要写清楚“负责什么”“什么场景用”，别写虚的。
• tools 字段限制权限。这是我最看重的一处，给前端代理只配 Read、Write、Edit 这类文件工具，不配 Bash，它就不会自作主张改后端代码。
• model 字段可以单独指定。简单任务用 haiku 省钱，复杂逻辑用 opus 求稳，主代理还是用默认的 sonnet 做调度，成本可控。

2.3 代理之间的协作与信息交接

多个子代理不是同时在同一个上下文里聊天，它们之间靠两样东西协作：文件系统和 git。

文件系统的逻辑是：上游代理把产出写到约定好的路径，下游代理开工前先读那份文件。比如架构代理产出docs/architecture.md，里面定义了GET /api/tasks的请求响应结构；后端代理实现时照着这个文件写路由；前端代理开发列表页时也读这个文件，直接按接口字段渲染。这样三个人（三个 AI）不会各自为政，因为大家参考的是同一份“合同”。

git 的作用是留痕和容错。每个子代理动手前我会要求它先git stash或确认当前工作区干净，干完一个阶段提交一次。万一某个代理改坏了东西，直接git checkout回滚就行。后来我在 prompt 里统一加了一句话：“每次修改必须用 git diff 复核自己的改动，提交信息写明改动范围”——这句话帮我省掉了大量返工。

3. 实操环境准备：从零搭建 Claude Code 多代理工作台

3.1 安装 Claude Code 与桌面版

新机器上装 Claude Code 很简单，前提是你已经有 Node.js 环境，建议版本 18 以上。装完验证一下版本：

node -v npm install -g @anthropic-ai/claude-code claude --version

如果你更习惯图形界面，可以下载桌面版。桌面版和 CLI 共用同一套配置，我更喜欢 CLI，因为它能直接嵌在终端里配合 Vim、Tmux 使用，而且脚本化方便。卸载也比较干净，npm uninstall -g @anthropic-ai/claude-code即可。

首次启动会有认证流程：订阅用户可以直接 OAuth 登录，或者用 API key 方式设置环境变量。我建议在 shell 配置文件里单独建一段，方便以后切模型时改：

export ANTHROPIC_API_KEY="你的key" # 或使用兼容第三方模型时 export ANTHROPIC_BASE_URL="https://你的端点" export ANTHROPIC_AUTH_TOKEN="你的token"

关于可用区域，Claude Code 的服务支持范围以官方文档为准。如果启动时出现区域支持的提示，应当去官方渠道确认当前支持情况，通过正规方式获取服务。网上的旁门左道既不稳定也容易埋雷，没必要冒这个险。

3.2 在 VSCode 中配置 Claude Code 扩展

用 VSCode 的话，装官方扩展后在侧边栏就能打开对话面板，选中代码右键发送给 Claude Code，改动会直接标注在编辑器里。我的习惯是：CLI 跑长任务，扩展面板处理短问题——选中一段报错信息，按快捷键问它是怎么回事，比来回切窗口快得多。

扩展有个容易忽略的配置项是“信任工作区”。首次打开项目时 VSCode 会问是否信任，选信任后 Claude Code 才能读写目录。还有人在扩展里找不到安装目录，其实是配置路径问题，在扩展设置里搜 “claude-code.path” 指定 CLI 的绝对路径即可。

3.3 初始化项目级 CLAUDE.md 与 agents 目录

项目跑起来之前，先把“团队规矩”立好。CLAUDE.md 是项目的全局记忆文件，主代理每次会话都会加载它。我的文件里会写这几类内容：

• 项目简介和技术栈
• 目录结构说明
• 编码规范（命名、缩进、commit 格式）
• 所有代理的工作边界和协作流程
• 常用命令（测试、构建、运行）

写完 CLAUDE.md，接着创建 agents 目录：

mkdir -p .claude/agents touch .claude/agents/backend-developer.md touch .claude/agents/frontend-developer.md touch .claude/agents/tester.md touch .claude/agents/reviewer.md

一个容易踩的坑：agents 文件里如果写了绝对路径，换机器就废了。我全部用项目相对路径，比如app/models.py，配合 CLAUDE.md 里的目录说明，才能保证子代理在任意环境下都找得到文件。

4. 实战案例：三模块 Web 项目多代理协作全流程

4.1 项目目标与角色分配

拿我那个任务管理系统当例子，目标很朴素：能建项目、能指派任务、能看统计。技术栈是 FastAPI + React + SQLite，不引太多依赖，但功能要完整。

我拆了五个代理：

这里有个经验：架构代理一定要最先跑。没有架构文档就并行开发，两个代理各写各的，最后接口对不上是必然的。宁可多花二十分钟让架构代理把接口表列清楚，后面能省半天。

4.2 执行流程与关键节点实录

第一步，我给主代理下了总命令：

初始化项目。先让 architect 产出一份架构文档，要求包含：数据表结构、REST API 列表、每个接口的请求响应样例、前后端目录约定。文档写到 docs/architecture.md，完成后汇报给我。

主代理自动调用 architect 后，大约一分钟就产出了五页文档。我快速扫了一遍，接口契约、字段命名都合理，就批准进入下一步。

第二步，让后端和前端并行开工。我给主代理的命令长这样：

backend-developer 根据 docs/architecture.md 实现全部后端，要求先建模型再写路由，完成后运行 app 启动脚本自测。 frontend-developer 同样基于 architecture.md 开发前端页面，读取其中的接口定义，把 API 客户端层先用 mock 数据写好。 两者先提交各自改动。

注意我把“根据同一份架构文档”写进了命令里。两个代理虽然同时跑，但参照物一致，所以没有出现鸡同鸭讲的情况。大约十几分钟后，后端代理提交了数据模型和 12 个接口的实现；前端代理完成了登录页、任务列表和统计页的骨架，mock 数据先跑通。

第三步是集成验证。前端代理把 mock 数据换成真实 API 调用，后端代理配合修正了几处字段命名问题。这里第一次暴露了协作问题：前端代理按文档把create_time渲染成createdAt，而后端返回的字段是create_time，两个代理各按各的习惯写，测试代理一跑就报错。

处理方式很简单：让主代理下达裁决，统一使用 snake_case 作为前后端字段格式，同时修改文档、后端返回、前端解析三层代码。改完后测试代理接手，先写 20 个用例覆盖核心接口和页面流程，再跑到全绿为止。最后 reviewer 代理做代码审查，在docs/review.md里列了十几条优化建议，涉及空指针防御、SQL 索引、前端组件拆分等。

4.3 多代理协作的经验细节

整个流程跑下来，有几个细节很值得单独说。

一是给子代理的 prompt 应该模板化。我每次都会按“目标、输入文件、输出路径、约束、验收标准”五个要素写，例如：

目标是实现任务列表接口。输入文件是 docs/architecture.md，里面有两个相关接口定义。输出到 app/routers/tasks.py。约束：只能改 app/routers 和 app/models 目录下的文件，确认前必须运行 pytest。验收标准：GET /api/tasks 返回示例中的字段，字段命名 snake_case。

二是并行任务要确认安全性。两个代理同时写文件时，最好事先讲清楚文件边界。我把前后端的目录边界在 CLAUDE.md 里写死，并明确“backend-developer 不得触碰 src/ 目录，frontend-developer 不得触碰 app/ 目录”，这样才敢放心让它们并行跑。

三是主代理的最终集成检查不能省。子代理各自交付只能说明局部正常，主代理最后要拉通跑一次构建、测试和启动，确认所有模块合在一起没问题，才算真正的完成。我让它把最终版本的启动命令和测试结果写进 README，作为交付物的一部分。

5. 常见问题排查与避坑实录

5.1 连接、鉴权与可用性提示

我遇到过最频繁的报错是启动时提示无法连接服务，日志里有个大写的连接失败字样。这类问题的排查顺序我基本固定：先看 API key 是否过期、有无余额；再看网络是否能正常访问目标服务；最后确认当前所在区域是否在官方支持范围内。前后端代码本身很少是这个问题的根源，别急着改代码，先查环境。

排查时记住一个原则：凡是涉及区域可用性的，去官方文档看支持列表，正规渠道解决。我在网上见过不少所谓的“配置技巧”，要么是改 hosts，要么是套中间层，都不安全也不稳定，项目跑在不可控的环境里，随时可能出问题，到时候查 bug 都无从下手。

5.2 子代理误改文件与超时

子代理误改文件是最常见的协作事故。表现是：你让前端代理改按钮样式，结果它把 package.json 里的依赖版本也升了。要防住这个，权限控制比口头约束更可靠。在 agents 文件里限定 tools，比如前端代理不配 Bash，它就执行不了 npm install；再把 CLAUDE.md 写清楚“谁可以动哪些目录”，让主代理分配任务时就有边界意识。

如果子代理执行超时，大概率是任务拆得太粗。不要让它“写一个完整模块”，拆成“先建表结构”“再写 CRUD 接口”“最后补分页逻辑”，每个任务控制在十分钟内能完成的粒度。我试过把一个接口加全套测试的大任务直接丢给 tester，十分钟后超时，换成只写 test_cases 的部分，很快跑完。

5.3 上下文膨胀与成本优化

多代理解决了上下文污染问题，但主代理的上下文还是会随时间增长。我用了两个办法：一是频繁开新会话，每个阶段完成后git commit，然后/clear开新的主会话，让 CLAUDE.md 和 agents 文件承担“长期记忆”的职责；二是开启 prompt caching，环境变量里设置缓存标志，一小时内的重复前缀会被缓存，多代理反复读取同一份 CLAUDE.md 时能省不少 token。

关于 1M 上下文，我的看法是：那是留给大型仓库扫描的场景，不是让你在单次对话里无限堆料的。真正专业的做法是把仓库信息拆成索引文件，按需读取，而不是全量塞进上下文。

5.4 想用第三方模型和模型切换

多代理机制对模型选择是透明的。如果你有兼容 Anthropic API 的第三方模型供应商，可以通过环境变量把模型端点指过去。官方接口方式大概是设置ANTHROPIC_BASE_URL和ANTHROPIC_AUTH_TOKEN，然后在配置里指定模型名。像我试过把部分简单子代理指向 DeepSeek 的模型，效果也能接受，尤其在成本敏感的阶段。

项目里如果有多个模型配置需要来回切，可以自己写一行切换脚本或者用现成的切换工具。但工具只能帮你在几个预设配置之间切换，真正的多代理调度逻辑还是在 Claude Code 内部完成的，换模型不影响子代理分工。我实际体验下来，复杂推理任务用更强的模型，简单任务用轻量模型，整体成本能压到只用高性能模型的四分之一。

6. 写在最后的实操体会

多代理协作真正带来的最大收益，不是“多个 AI 同时干活”带来的速度感，而是上下文隔离带来的稳定性。每个子代理只面对自己那一亩三分地，不会被其他模块的旧决定影响，主代理则用文档和契约把这些独立的碎片粘成整体。这个思路往大里说，跟真实团队的管理方式一模一样：定清楚边界，写清楚接口，让每个人专注自己的活。

如果你打算在下一个项目里尝试这套流程，我的建议是先从小处练手：拿一个两三个模块的项目，定义两三个代理，跑通一个完整阶段，观察子代理之间是怎么交接的。别一上来就搭七八个代理，调度复杂度会掩盖所有收益。等你真正体会到“文档即契约、边界即效率”这两个原则之后，再慢慢加角色、加并行任务，这条路的空间比你想的要大得多。