第三章：Claude Code 项目开发全流程实战

第三章：项目开发全流程实战

← 上一章：Claude Code 概述 | 返回目录 | 下一章：软件开发方法论 →

---

3. 项目开发全流程实战

以 Finance 项目为例，展示 Claude Code 在软件开发各阶段的实际应用。

Finance 项目简介

项目定位：家庭理财管理系统，用于追踪资产、负债、支出和投资，支持多币种和多家庭成员。

核心功能：

1. 资产负债管理：

   • 多种资产和负债类型管理
   • 时序数据模型：每笔资产/负债的历史变化都保留记录
   • 基础 CRUD 操作和列表展示

2. 支出管理：

   • 分层支出分类（大类 + 小类）
   • 月度批量录入，显示历史数据作为参考
   • 三级钻取分析（大类 → 小类 → 月度趋势）

3. 多币种支持：

   • 支持多种主流货币
   • 实时汇率获取（集成外部 API）
   • 所有金额存储原币种 + USD 等值

4. 数据可视化：

   • 资产负债趋势图
   • 支出分析和三级钻取
   • 净资产变化曲线

技术复杂性：

• 后端复杂度：

  • 时序数据建模（资产/负债的历史记录管理）
  • 多币种转换逻辑（存储过程 + Java Service 层分工）
  • 跨表关联查询（资产、负债、支出、汇率）
  • RESTful API 设计（30+ 接口）

• 前端复杂度：

  • 33 个 Vue 组件，复杂的表单交互
  • 多种数据可视化（Chart.js 集成）
  • 响应式设计（移动端适配）

• 数据库复杂度：

  • 25 张表，包含时序数据、多币种、软删除
  • 存储过程用于复杂聚合计算
  • 数据迁移脚本管理

开发历程：

• 阶段 1：资产负债表管理（核心功能）
• 阶段 2：资产负债分析（趋势图、净资产计算）
• 阶段 3：支出管理（分类、录入、查询）
• 阶段 4：支出分析（三级钻取、预算功能）
• 阶段 5：投资管理和分析（已完成）

这种渐进式功能扩展是使用 Claude Code 的最佳实践：先完成最核心的功能，验证架构可行性，再逐步添加新功能。

应用界面展示：

Dashboard 界面展示了资产负债总览、趋势分析以及多维度数据可视化

3.1 初始化阶段：搭建项目骨架

传统方式 vs. Claude Code

传统方式（约 2-4 小时）：

1. 创建 Spring Boot 项目（Spring Initializr）
2. 配置 Maven/Gradle
3. 创建包结构（controller/service/repository）
4. 配置数据库连接（application.yml）
5. 创建 Vue 项目（vue create）
6. 配置路由、状态管理、API 客户端
7. 设置 Dockerfile 和 k8s 配置

Claude Code 方式（推荐）（20 分钟）：

$ claude

You: 创建一个全栈财务管理系统，参考我之前的 match project（tennis match 管理）的技术栈和目录结构。

**首个核心功能**：资产负债表管理
- 资产和负债类型管理
- 时序数据模型：记录每笔资产/负债的历史变化
- 基础 CRUD 操作和列表展示

为什么这样做：

1. 参照已有项目：固定技术选型，避免 AI 选择不一致的框架
2. 明确目录架构：确保项目结构清晰，方便后续扩展
3. 专注核心功能：先完成最重要的资产负债管理，验证架构
4. 渐进式扩展：功能迭代顺序清晰（管理 → 分析 → 扩展）

实际效果：

• ✅ 生成了完整的目录结构
• ✅ 配置了 Spring Security、JPA、CORS
• ✅ 创建了基础实体（User、Family）和对应的 CRUD
• ✅ 前端路由、Axios 配置、Tailwind 主题
• ❌ 需要手动调整数据库连接字符串（AI 用了默认值）

关键学习：

1. 让 AI 生成 80%，人工完善 20% - 初始化阶段，AI 能快速搭建标准架构
2. 提供明确的技术栈 - 模糊需求会导致 AI 选择过时或不匹配的技术
3. 先生成再调整 - 不要期望一次性完美，快速迭代更高效

优化实践：CLAUDE.md 的萌芽

初始化完成后，我创建了第一版 CLAUDE.md：

# Finance App - Claude Code Guide

## Stack
Java 17 + Spring Boot 3.2 + Vue 3 + MySQL 8.0

## Critical Rules
- **ALWAYS use Maven wrapper** - `./mvnw` instead of `mvn`
- **NEVER commit backend/.env** - Contains DB credentials

为什么这么早就写 CLAUDE.md？

• ✅ 避免 AI 在后续会话中"忘记"技术选型
• ✅ 记录第一天就遇到的问题（如 mvn vs ./mvnw）
• ✅ 为后续的 /clear + /catchup 工作流打基础

---

3.2 需求阶段：从模糊想法到精确规格

我的需求工作流（防止 AI 过度设计）

第一步：高层需求

You: 我要做支出管理功能，先不要实现，帮我拆解需求。

**核心需求**：
- 支出分类管理（大类 + 小类）
- 月度批量录入
- 多币种支持

**我特别关注**：
- 数据录入效率（一个表单完成所有小类）
- 历史数据参考（显示最近3个月）

第二步：审查 AI 拆解的需求

Claude 会返回详细需求列表，通常有过度设计的趋势：

Claude: 以下是拆解的需求：
1. 支出分类管理
   - 大类增删改查
   - 小类增删改查
   - 分类层级管理（大类 → 小类）
2. 月度录入
   - 批量录入表单
   - 历史数据展示（最近3个月）
   - 自动保存草稿 ❌（过度设计）
   - 模板功能（复制上月数据）❌（暂不需要）
3. 多币种
   - 7种货币支持
   - 实时汇率获取
   - 汇率历史记录 ❌（第二阶段）
4. 数据验证
   - 唯一性约束
   - 金额范围校验 ❌（不必要）
...

我的回复：

You: 需求3.3（汇率历史记录）、2.2（自动保存草稿）、2.3（模板功能）、4.2（金额范围校验）先不做。
保留核心功能：分类管理、批量录入、多币种、基本验证。

为什么要这样做：

• ✅ 防止范围蔓延：AI 倾向于添加"有用但非必要"的功能
• ✅ 快速迭代：先做最小可用版本（MVP），后续根据实际需要扩展
• ✅ 降低复杂度：避免第一版就引入过多功能导致实现时间拉长

---

3.3 设计阶段：架构决策与 AI 的边界

需求明确后，进入设计阶段。这是人类主导、AI 辅助的阶段。

Planning Mode：系统化设计流程

对于复杂功能（如支出管理的三级钻取分析），我会使用 Planning Mode 进行系统化设计：

$ claude --plan

You: 实现支出分析的三级钻取功能，请给出详细设计方案，包括：

1. **数据模型设计**
2. **后端 API 设计**
3. **前端 UI Mock**
4. **测试用例设计**

**功能需求**：
- 饼图显示大类占比
- 点击大类 → 该大类的小类饼图
- 点击小类 → 该小类的月度柱状图

**UI 参考**：
- 第一个功能：从简单开始，纯白背景 + 基础图表
- 后续功能：参照已实现的 AssetAnalysisView.vue 的风格
  （保证用户体验一致性）

Claude 生成的计划（plan.md）：

# Expense Analysis Three-Level Drill-Down - Design Plan

## 1. 数据模型设计
- 使用现有表，无需新增字段
- 关键字段审查（amount_usd, period, is_deleted）

## 2. 后端 API 设计
- GET /api/expenses/analysis/category-summary
- GET /api/expenses/analysis/subcategory/{categoryId}
- GET /api/expenses/analysis/monthly/{subcategoryId}

## 3. 前端 UI Mock
- 参照 AssetAnalysisView.vue 的卡片布局
- 饼图显示大类占比
- 点击钻取到小类和月度趋势

## 4. 测试用例
- 数据准确性验证
- 跨货币聚合测试
- 钻取状态管理测试

我的审查重点：

1. 数据模型：仔细审阅每个字段，确认必要性
   • ✅ 无需新增表或字段
   • ✅ 使用现有 amount_usd 做聚合
2. UI Mock：确保与已有界面一致
   • ✅ 参照 AssetAnalysisView.vue 的卡片风格
   • ✅ 使用相同的配色方案和布局
3. API 设计：检查命名和参数是否合理
   • ✅ RESTful 风格一致
   • ✅ 参数简洁明了

通过后：

You: 数据模型和 API 设计都OK，开始实现。
参考 AssetAnalysisView.vue 的样式，保持 UI 一致性。

Planning Mode 的价值：

• ✅ 数据模型审查：避免后期数据库迁移成本
• ✅ UI 一致性：参照已有组件，保证体验
• ✅ 对齐预期 - 在写代码前确认方案
• ✅ 发现遗漏 - AI 可能想到你没考虑的边界情况
• ⚠️ 不要过度规划 - 简单功能（<3 文件）直接开干

---

架构权衡：人类决策 + AI 提供选项

AI 很难独立做好架构权衡，我的两个实践方法：

方法1：从现有系统中提炼架构原则

当项目第一个功能稳定后，我会总结架构设计原则并写入 CLAUDE.md：

## Architecture Principles

**Time-Series Data**:
- Asset/Liability: NEVER update existing records, always INSERT new ones
- Reason: Historical tracking requirement

**Multi-Currency**:
- Store original currency + converted USD amount
- Use ExchangeRateService for all conversions
- Reason: Audit trail + performance

...

为什么重要：

• 新功能自动遵循已定原则
• 避免 AI 对相似功能采用不同架构
• 降低长期重构成本

方法2：小功能试验 + 多选项对比

对于不确定的架构决策（如复杂逻辑放在哪一层），我会让 Claude 提供多个选项：

You: 年度财务汇总逻辑很复杂（跨表关联、币种转换、时间范围过滤），给我3个实现方案：
1. MySQL 存储过程
2. Java Service 层计算
3. 前端实时计算

对每个方案分析性能、可维护性、测试难度。

先不实现，只给方案对比。

Claude 的回复：

方案	性能	可维护性	测试难度	适用场景
存储过程	⭐⭐⭐⭐⭐	⭐⭐	⭐⭐	数据量大、查询频繁
Java Service	⭐⭐⭐	⭐⭐⭐⭐	⭐⭐⭐⭐	逻辑复杂、需单元测试
前端计算	⭐	⭐⭐⭐	⭐⭐⭐	数据量小、实时交互

我的决策过程：

1. 选择方案 1（存储过程）+ 方案 2（Java Service）各实现一个小功能
2. 对比实际效果：
   • 存储过程：查询时间从 3s 降到 0.5s
   • Java Service：单元测试覆盖率高，但慢
3. 最终方案：混合使用
   • 跨表聚合 → 存储过程
   • 币种转换 + 业务逻辑 → Java Service
   • 前端只做展示

固化决策到 CLAUDE.md：

**Complex Aggregation**:
- Use MySQL stored procedures for cross-table aggregation
- Java Service layer handles business logic + currency conversion
- Frontend: presentation only

为什么这样做：

• ✅ 小功能试验成本低（1-2小时）
• ✅ 实际对比比理论分析更可靠
• ✅ 一旦定型，后续功能保持一致

---

3.4 实现阶段：高效协作与自动化

这是 Claude Code 最能发挥价值的阶段。

基于 Plan 的跨层实现

因为我在设计阶段已经做好了 Plan（包括数据模型、API、UI Mock），实现阶段必然涉及跨层修改。Claude Code 的优势在于：

• ✅ 代码规范：生成的代码符合项目规范
• ✅ 跨层一致性：API 返回格式与前端期望匹配
• ✅ 自动联调：大多数情况下无需手动调整即可运行

任务：增加"支出预算"功能（已完成 Plan 设计）

Plan 输出（设计阶段已确定）：

• 数据库：expense_budgets 表
• 后端：BudgetService、BudgetController
• 前端：BudgetManagementView.vue
• API：GET/POST/PUT/DELETE /api/budgets

实现顺序（我的标准流程）：

1. 数据库先行：创建表和迁移脚本
2. 后端实现：Service → Controller → 单元测试
3. 前端实现：组件 → API 调用 → 集成测试

传统方式：

1. 写后端（1-2 小时）
2. 测试 API（30 分钟）
3. 写前端（1-2 小时）
4. 联调（30 分钟）
5. 写数据库脚本（30 分钟）

Claude Code 实现流程（遵循我的标准顺序）：

第一步：数据库

• 创建迁移脚本，执行 /mysql-exec 创建表
• ✅ 数据库就绪

第二步：后端实现 + 测试

• 生成 Entity、Repository、Service、Controller
• 写单元测试并运行 ./mvnw test
• 自动修复测试中发现的问题
• ✅ 测试通过

第三步：前端实现

• 创建 Vue 组件，参照已有风格
• API 调用自动匹配后端格式
• ✅ 前后端联调成功

为什么这个顺序高效：

1. 数据库先行：避免后端多次修改表结构
2. 后端完全测试：确保逻辑正确再做前端
3. 前端直接集成：API 已验证，前端实现快速

关键观察：

• Claude 会自主运行测试并修复错误（前提是项目有测试）
• 跨层一致性好：API 返回格式与前端期望自动匹配
• 遵循已有代码风格：前端参照 ExpenseManagementView.vue，样式一致

Skills 的威力 - 自动化工作流

问题：每次数据库修改后需要手动操作（写脚本、复制密码、执行、检查）

解决方案：创建 /mysql-exec Skill，自动加载凭据并执行 SQL

效果：

# 之前：5 步手动操作
# 现在：1 条命令
$ /mysql-exec database/add_budget_table.sql
✓ Executed successfully

Skills vs. 手动命令的对比：

场景	手动命令	Skill
时间成本	2-3 分钟	10 秒
密码泄露风险	高（history）	低（封装）
可重复性	需记住命令	一致性保证
AI 可用性	需指导	自动调用

我的其他 Skills：

• /setup-java - 配置 Java 17 + 加载环境变量（每次会话必用）
• /git-commit-push - 暂存、提交、推送的原子操作（符合 Conventional Commits）
• /docker-build-push - 多架构镜像构建（amd64/arm64）

CLAUDE.md 的实现阶段演进

随着开发深入，CLAUDE.md 增加了实现层面的约束：

## Backend Development

**NEVER modify JPA entities without checking existing records**
**ALWAYS use TimeService.getCurrentTimestamp()**

## Frontend Development

**ALWAYS use Composition API** - No Options API
**NEVER hardcode colors** - Use CSS variables

...

为什么这些规则重要？

• TimeService 规则：避免了一次严重 Bug（时区不一致导致数据混乱）
• JPA 规则：防止 AI 直接修改实体导致数据丢失
• Composition API：保持代码风格一致性

---

3.5 测试阶段：迭代式质量保证

我的测试工作流：

1. 单元测试：实现阶段的一部分

   • 后端 Service 层代码生成后，立即生成单元测试
   • 运行 ./mvnw test 验证逻辑正确性

2. 手动使用测试：发现问题和改进体验

   • 完成多层实现（数据库 + 后端 + 前端）后，先自己使用
   • 发现 Bug → 修改 → 重新测试
   • 没有 Bug → 尝试改进使用体验 → 回到设计与实现

3. 多次迭代：直到功能固化

   • 重复"使用 → 发现问题 → 改进"的循环
   • 直到功能稳定、体验满意

4. 集成测试：提交前的最后检查

   • 功能固化后，生成集成测试用例
   • 确保端到端流程无误
   • 只有集成测试全部通过，才提交代码

这种方式与传统 TDD（先写测试再写代码）不同，更适合 AI 辅助开发的快速迭代模式。

单元测试自动生成

任务：为 ExchangeRateService 写单元测试

Claude 自动生成测试代码，覆盖主要场景（缓存、转换、批量操作）

结果：

• ✅ 覆盖率 85%+
• ✅ 发现了一个 Bug：负数金额未校验
• ❌ 外部 API mock 过于复杂，需要人工简化

集成测试与 Hook 验证

挑战：防止 AI 在测试未通过时提交代码

解决方案：创建 Pre-Commit Hook (.claude/hooks/pre-tool-use.sh)，在提交前强制验证测试通过

Hook 的价值：

• ✅ 强制验证 - AI 无法跳过测试
• ✅ 自我纠正 - AI 会读取 hook 输出并修复问题
• ⚠️ 不要过度使用 - 太多 hook 会让 AI "困惑"

---

3.6 部署阶段：Docker 容器化

我目前的部署策略：

• Docker 镜像构建（backend + frontend）
• Docker Compose 本地编排
• GitHub Actions 自动构建和推送到 Docker Hub

（Kubernetes 部署暂未实施，计划未来引入）

Docker容器化

Claude 生成了完整的 Docker 配置：

• Backend Dockerfile：多阶段构建（Maven 构建 + JRE 运行）
• Frontend Dockerfile：Vue 构建 + Nginx 伺服
• docker-compose.yml：MySQL + 后端 + 前端的完整编排

评价：

• ✅ 多阶段构建减小镜像体积
• ✅ 本地开发方便
• ✅ 环境变量管理清晰

GitHub Actions 自动构建

Claude 生成了完整的 GitHub Actions 工作流，实现：

• Push to master 时：测试 → 构建 → 推送到 Docker Hub
• Pull Request 时：仅运行测试

实际使用效果：

• ✅ 自动化 CI/CD 流程完整
• ✅ 同时推送 latest 和 commit SHA 两个标签

/docker-build-push Skill

为了简化本地构建，创建了 /docker-build-push Skill，支持多架构镜像构建（amd64/arm64）

效果：

# 之前：多条复杂命令
# 现在：一条命令完成
$ /docker-build-push
✓ Building backend (amd64, arm64)...
✓ Building frontend (amd64, arm64)...
✓ Pushed to Docker Hub

---

← 上一章：Claude Code 概述 | 返回目录 | 下一章：软件开发方法论 →