用 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 —— 每个功能的第一站

不做计划的编码是灾难。brainstorming skill 强制我回答三个问题：

1. 这个功能要解决什么问题？（而不是"我想加什么技术"）
2. 影响哪些现有模块？（而不是"新建一个文件就行"）
3. 有哪些边界情况？（而不是"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 强制先：

1. 收集完整错误信息（堆栈、日志、环境变量）
2. 定位最小复现条件
3. 对比"能工作"和"不能工作"的差异
4. 形成根因假设 → 验证假设 → 修复

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 个月。

---