Claude Code 实战心得：从零构建企业级 Agent 平台的 30 天
用 Claude Code 驱动一个 7 服务、6 万行 Java + Vue 的全栈项目，是什么体验？本文总结我在 wagent 项目中深度使用 Claude Code 的心得，并剖析 CC 的架构设计与主/子 Agent 协作原理。
一、项目背景：wagent — 企业多租户 Agent 平台
wagent 是一个面向企业的多用户智能体平台，技术栈：
- 后端：Java 19 + Spring Boot 3.3 + MyBatis-Plus + PostgreSQL 16 (pgvector) + Redis 7
- 前端：Vue 3 + TypeScript + Vite + Element Plus + Pinia
- 服务拆分：7 个微服务（gateway、auth、agent、skill、mcp、knowledge、frontend）
- 核心能力：多 LLM 路由、SSE 流式对话、Skill 引擎、MCP 协议网关、RAG 知识库
整个开发过程历时约 30 天，经历了 6 个 Phase，从 MVP 到完整的 RAG 管道，全部由 Claude Code 驱动实现。
二、Claude Code 架构概览
要理解如何高效使用 CC，先要理解它的架构。Claude Code 不是一个简单的"代码补全"工具——它是一套完整的 AI 软件工程系统。
┌─────────────────────────────────────────────────────────┐ │ Claude Code System │ ├─────────────────────────────────────────────────────────┤ │ System Prompt (行为准则) │ │ ├─ 角色定义、安全边界、代码规范 │ │ ├─ 工具使用策略（何时用哪个工具） │ │ └─ 交互风格（简洁、不冗余） │ ├─────────────────────────────────────────────────────────┤ │ Tool Layer (工具层) │ │ ├─ 读写工具: Read / Write / Edit / Glob / Grep │ │ ├─ 执行工具: Bash / PowerShell │ │ ├─ 代理工具: Agent (子Agent调度) │ │ ├─ 规划工具: EnterPlanMode / ExitPlanMode │ │ ├─ 任务工具: TaskCreate / TaskUpdate / TaskList │ │ └─ 通知工具: PushNotification / Monitor │ ├─────────────────────────────────────────────────────────┤ │ Memory System (记忆系统) │ │ ├─ project: 项目背景、阶段、架构决策 │ │ ├─ user: 用户角色、偏好、知识背景 │ │ ├─ feedback: 用户反馈、行为纠正、已验证模式 │ │ └─ reference: 外部系统指针（数据库、监控面板等） │ ├─────────────────────────────────────────────────────────┤ │ Skill System (技能系统) │ │ ├─ 流程技能: brainstorming / debugging / TDD │ │ ├─ 执行技能: executing-plans / subagent-driven-dev │ │ └─ 工具技能: git-worktrees / verification │ ├─────────────────────────────────────────────────────────┤ │ Hook System (钩子系统) │ │ ├─ SessionStart: 会话启动时触发 │ │ ├─ PreToolUse: 工具调用前拦截 │ │ └─ PostToolUse: 工具调用后处理 │ └─────────────────────────────────────────────────────────┘2.1 System Prompt —— 隐形的"架构师守则"
System Prompt 不是一段普通的提示词，而是约 3000 行的行为规范文档。它定义了：
| 维度 | 约束内容 |
|---|---|
| 安全 | 禁止 destructive git 操作、敏感文件提交、命令注入 |
| 代码质量 | 不写冗余注释、不过度抽象、不引入无意义的错误处理 |
| 沟通风格 | 简洁、不主动总结、不滥用 emoji |
| 工具选择 | Edit 优于 Write、Grep 优于 grep、Agent 用于复杂探索 |
这套规范让 CC 输出的代码始终保持在"刚好够用"的水平线——不多一行废话，不少一个关键步骤。
2.2 记忆系统 —— 跨会话的"项目大脑"
Memory 是 CC 最被低估的特性。在 wagent 项目中，我维护了：
project_wagent.md：记录了 6 个 Phase 的完成状态、服务端口、JDK 版本陷阱（PATH 上是 JDK 8 但项目用 JDK 19）reference_tools.md：PostgreSQL 客户端路径、Maven 路径- 各种 feedback 记忆：用户偏好、已验证的开发模式
关键价值：每次新会话启动，CC 自动加载这些记忆，不需要重新解释项目结构。60 天跨几十个会话，从未出现过"不知道项目在做什么"的情况。
2.3 Skill 系统 —— 可加载的"专业技能包"
Skill 是 CC 的可插拔能力模块。每个 Skill 本质上是一份专业工作流指令，加载后会覆盖/增强 CC 的默认行为：
用户消息 → Skill 匹配检查 → 加载 Skill 指令 → 执行专业化工作流 → 输出结果wagent 项目中高频使用的 Skill：
| Skill | 使用场景 | 价值 |
|---|---|---|
brainstorming | 每个 Feature 开始前 | 强制需求澄清，避免自嗨式编码 |
writing-plans | 多步骤任务 | 生成可审查的实施方案 |
executing-plans | 执行阶段 | 分步执行 + review checkpoints |
systematic-debugging | Bug 修复 | 禁止盲目试错，先定位根因 |
verification-before-completion | 完成前 | 强制运行验证，不一厢情愿说"done" |
subagent-driven-development | 并行任务 | 将独立任务分派给子 Agent |
三、主 Agent 与子 Agent 协作原理
这是 CC 架构中最精妙的部分，也是大规模项目的生产力倍增器。
3.1 单 Agent 的局限
传统 AI 编程助手只有一个"Agent"——它既要做需求分析，又要写代码，还要查文档、调试、验证。在 wagent 这样 7 服务 60+ 文件的项目中，这导致：
- 上下文窗口被污染：读 3 个大文件后，之前的分析结果被挤出窗口
- 串行效率低：读文件 → 理解 → 编辑 → 读下一个文件，全程单线程
- 决策疲劳：一个 Agent 要切换多种思维模式
3.2 CC 的解决方案：Agent 工具 + 专业化子 Agent
CC 通过Agent工具实现了主从 Agent 协作架构：
┌──────────────┐ │ 用户指令 │ └──────┬───────┘ │ ┌──────▼───────┐ │ 主 Agent │ │ (编排者) │ │ │ │ • 理解需求 │ │ • 制定计划 │ │ • 分解任务 │ │ • 调度子Agent │ │ • 合成结果 │ └──┬───┬───┬──┘ │ │ │ ┌────────────┘ │ └────────────┐ │ │ │ ┌───────▼──────┐ ┌──────▼──────┐ ┌──────▼──────┐ │ Explore Agent │ │ Plan Agent │ │General Agent│ │ (探索者) │ │ (规划者) │ │ (执行者) │ │ │ │ │ │ │ │ • 代码库搜索 │ │ • 架构设计 │ │ • 写代码 │ │ • 依赖分析 │ │ • 方案对比 │ │ • 调试 │ │ • 模式识别 │ │ • 文件定位 │ │ • 运行测试 │ └──────────────┘ └─────────────┘ └─────────────┘3.3 三种子 Agent 类型
Explore Agent（探索者）
- 用途：在代码库中搜索、理解现有模式
- 特点：只读操作，快速返回结果
- wagent 实例：探索 7 个微服务的 API 路由模式，SearchService 的 pgvector 混合搜索实现
Plan Agent（规划者）
- 用途：设计实现方案，评估架构决策
- 特点：输出结构化计划，供主 Agent 审查
- wagent 实例：Phase 6 RAG 知识库的方案设计——chunking 策略选择、pgvector 索引优化、异步 ingestion 管道设计
General-Purpose Agent（通用执行者）
- 用途：执行具体的代码编写、调试、测试任务
- 特点：全工具可用，可隔离执行
- wagent 实例：实现 OpenAIProvider、SkillBuilderService、JWT 认证过滤器
3.4 隔离模式：Worktree
子 Agent 可以通过isolation: "worktree"在独立的 git worktree 中运行：
主工作区 (master) ├── .claude/worktrees/ │ ├── feature-skill-builder/ ← Agent A 隔离工作区 │ └── fix-jwt-filter/ ← Agent B 隔离工作区这解决了 AI 编程中的经典问题：多个并行任务互不干扰。一个 Agent 在 feature 分支上大胆重构，不会污染另一个在修 bug 的 Agent。
3.5 实际协作流程（以 wagent Skill Builder 为例）
这是 wagent 中最典型的"主-子 Agent 协作"案例：
Step 1: 主Agent 接收指令 "给 skill 服务添加 builder 功能" Step 2: 主Agent 调用 brainstorming skill 澄清需求：builder 做什么？输入输出？和现有 SkillManager 的关系？ Step 3: 主Agent 启动 2 个 Explore Agent（并行） Agent A: 探索 wagent-skill 现有 API 模式 Agent B: 探索 wagent-frontend SkillManager.vue 组件结构 Step 4: 主Agent 合成探索结果，启动 Plan Agent Plan Agent: 设计方案 - 后端: SkillBuilderController + SkillBuilderService - 前端: SkillBuilderDrawer 组件 - 数据库: skill_draft 表 - 路由: gateway 添加 /api/v1/skill/builder/** Step 5: 主Agent 审查方案，进入 Plan Mode 获取用户确认 Step 6: 主Agent 启动 3 个子 Agent（并行） Agent 1 (worktree): 实现后端 SkillBuilderService + Controller Agent 2 (worktree): 实现前端 SkillBuilderDrawer.vue Agent 3: 更新 gateway 路由配置 Step 7: 主Agent 集成结果 合并 worktree 变更 → 解决冲突 → 验证编译 → 端到端测试这个过程在 30 分钟内完成了原本需要 1-2 天的工作。
3.6 关键协作原则
| 原则 | 说明 |
|---|---|
| 主 Agent 从不写代码 | 主 Agent 只做理解、规划、调度、合成——真正写代码的是子 Agent |
| 子 Agent 无上下文 | 每个子 Agent 从干净上下文启动，必须自包含地传达任务 |
| 并行优先 | 独立任务必须在一条消息中同时启动，而不是串行等待 |
| 验证后信任 | 子 Agent 返回的结果必须经过主 Agent 验证（代码审查、编译检查） |
四、Skill 实战：wagent 项目中的 6 个关键工作流
4.1 Brainstorming —— 每个功能的第一站
不做计划的编码是灾难。brainstormingskill 强制我回答三个问题：
- 这个功能要解决什么问题？（而不是"我想加什么技术"）
- 影响哪些现有模块？（而不是"新建一个文件就行"）
- 有哪些边界情况？（而不是"happy path 能跑就行"）
在 Phase 6 RAG 知识库中，brainstorming 帮助确定了 pgvector 的 cosine + tsvector 混合搜索策略，避免了后来可能需要推倒重来的纯向量搜索方案。
4.2 Writing Plans —— 把想法变成可审查的方案
writing-plans输出的不是"要做什么"的列表，而是：
- 具体改哪个文件，改什么方法 - 新文件放在哪个包下，遵循什么命名规范 - 测试策略：单元测试覆盖什么，集成测试覆盖什么 - 风险点：哪些改动可能影响现有功能4.3 Subagent-Driven Development —— 并行执行
wagent 是 7 个微服务，很多事情可以并行：
| 并行场景 | 并行度 |
|---|---|
| 同时修改 3 个微服务的 API | 3 个 Agent |
| 前后端同时开发 | 2 个 Agent |
| explore + plan + implement | 串并行混合 |
4.4 Verification Before Completion —— 证据而非断言
这个 skill 定了一条铁律：声称"完成"之前，必须运行验证命令并展示实际输出。
在 wagent 项目中无数次避免了"代码写完了但服务起不来"的情况——最典型的例子就是 JDK 版本问题：系统默认是 JDK 8，但项目用 JDK 19 编译，启动验证时立刻发现 JNI 错误并修正。
4.5 Systematic Debugging —— 禁止试错
传统调试的毛病：看到错误 → 猜一个原因 → 改代码 → 还不 work → 再猜。systematic-debugging强制先：
- 收集完整错误信息（堆栈、日志、环境变量）
- 定位最小复现条件
- 对比"能工作"和"不能工作"的差异
- 形成根因假设 → 验证假设 → 修复
Java 8 vs Java 19 的问题如果用试错法可能需要反复重启很多次，但用系统调试法一次就定位了：对比 auth 服务（脚本启动，正常）和 agent 服务（手动启动，崩溃）的启动方式差异 → 发现 PATH 中的 Java 版本不同 → 修复。
4.6 Git Worktrees —— 隔离实验
在实现 Skill Builder 时，需要同时：
- 修改 wagent-agent 的 SkillApiClient
- 新增 wagent-skill 的 SkillBuilderController
- 新增前端 SkillBuilderDrawer.vue
三个 worktree 并行，互不影响，最后一次性合并。这比在单一工作区反复 stash/pop 高效得多。
五、CC 使用心得：5 条实践经验
5.1 "先计划，后代码"是效率的乘法器
我最大的教训：不要看到任务就写代码。在 Phase 4 MCP 网关时，我一开始直接写实现，结果 stdio transport 的实现方向错了——因为我不了解 JSON-RPC 的 notification vs request 区别。重来后遵循brainstorming → plan → implement流程，只用了原来的 1/3 时间。
5.2 善用子 Agent 做"脏活累活"
Explore Agent 是最好的研究员。wagent 项目有 5 个后端模块 + 1 个前端项目，手动搜索"API 用了什么命名模式"需要翻 20 个 Controller 文件。一个 Explore Agent 2 分钟搞定，返回一份结构化的 API 模式报告。
5.3 Memory 要持续维护
Memory 不是"设完就不管"。每个 Phase 完成后，我都会更新project_wagent.md的"Current Phase"和完成状态。正确的记忆让 CC 在下次会话直接进入工作状态，错误的记忆比没有记忆更糟（会误导决策）。
5.4 相信 Agent 的判断，但验证结果
CC 有时候会过度自信。它在实现 JwtAuthFilter 时，自动添加了一个"优雅降级"逻辑——当 JWT 解析失败时不返回 401 而是放行。这在安全上完全错误。子 Agent 输出的代码必须先审查，再合并——这就是为什么requesting-code-review和verification-before-completion是两个独立的 skill。
5.5 "简洁"是一种约束力
CC 的 System Prompt 要求代码"刚好够用，不多写"。这听起来是极简主义执念，但在大型项目中价值巨大：
- wagent-agent 的
ReActEngine.java如果没有这个约束，可能会被各种"以防万一"的 try-catch 和注释淹没 - 最终产出的代码干净、可读、可维护——像一个有经验的工程师写的，而不是 AI 堆砌的
六、总结
Claude Code 不是一个"帮你写得更快"的工具——它是一个软件工程的 AI 操作系统。它通过：
- 记忆系统解决跨会话上下文丢失
- Skill 系统将最佳实践编码为可复用的工作流
- 主/子 Agent 协作实现真正的并行开发
- Worktree 隔离保证并行任务互不干扰
- 验证驱动防止 AI 的自欺欺人
wagent 这个 7 服务、60+ 文件、覆盖 LLM 路由/Skill 引擎/MCP 协议/RAG 管道的企业级项目，在 Claude Code 的驱动下，从零到完整可用只用了约 30 天——这在传统开发模式下需要 3-4 人的团队 3-6 个月。