Claude Code全栈实战：从空白目录到可部署应用

npm install -g @anthropic-ai/claude-code

claude --version
# 预期输出: claude-code/x.x.x (具体版本号)

graph LR
    A["Sequential<br/>顺序模式<br/>🔵 手动控制"] --> B["Operator<br/>操作员模式<br/>🟡 半自动"]
    B --> C["Split & Merge<br/>拆分合并<br/>🟠 并行处理"]
    C --> D["Agent Teams<br/>团队模式<br/>🔴 多Agent协作"]
    D --> E["Headless<br/>无头模式<br/>⚫ 全自动"]

    style A fill:#4a90d9,color:#fff
    style B fill:#f5a623,color:#fff
    style C fill:#e67e22,color:#fff
    style D fill:#e74c3c,color:#fff
    style E fill:#2c3e50,color:#fff

# 创建项目目录
mkdir taskflow-app && cd taskflow-app

# 初始化Git仓库（Claude Code对Git有深度集成）
git init

# 启动Claude Code
claude

> /init

# CLAUDE.md（/init 自动生成的基础版本）

## 项目概述
TaskFlow - 一个任务管理全栈应用

## 技术栈
- 后端: Node.js + Express + TypeScript
- 前端: React + Vite + TypeScript
- 数据库: SQLite（开发阶段）
- 测试: Vitest

## 开发规范
- 使用TypeScript严格模式
- 遵循RESTful API设计原则
- 提交信息使用Conventional Commits格式
- 代码必须有对应的测试

## 项目结构

## 构建与运行命令
- 安装依赖: `npm install`
- 启动后端: `cd server && npm run dev`
- 启动前端: `cd client && npm run dev`
- 运行测试: `npm test`
- 构建生产版本: `npm run build`

> 请帮我完善CLAUDE.md，这是一个任务管理应用，包含以下功能：
> - 用户注册和登录
> - 任务的CRUD操作
> - 任务分类和标签
> - 简单的看板视图
> 
> 后端用Express + SQLite，前端用React。
> 代码风格遵循Airbnb规范，使用pnpm作为包管理器。

> 进入计划模式。我要搭建一个任务管理全栈应用，请帮我设计项目结构、
> API路由设计和数据库表结构。用SQLite作为数据库，不需要ORM。

flowchart TD
    A["用户描述需求"] --> B["Claude Code<br/>进入Plan模式"]
    B --> C["输出技术方案"]
    C --> D{"用户审查"}
    D -->|"满意"| E["退出Plan模式<br/>开始实施"]
    D -->|"需要调整"| F["用户反馈修改意见"]
    F --> B

    style A fill:#4a90d9,color:#fff
    style E fill:#27ae60,color:#fff

> 请根据刚才的计划，搭建完整的项目骨架。包括：
> 1. server/ 目录：Express应用、路由、数据库初始化脚本
> 2. client/ 目录：React + Vite 应用
> 3. 根目录：package.json、tsconfig.json、.gitignore
> 4. 每个目录都需要独立的package.json
> 
> 先创建文件结构和配置文件，不要写具体业务逻辑。

taskflow-app/
├── CLAUDE.md
├── .gitignore
├── package.json              # 根monorepo配置
├── server/
│   ├── package.json
│   ├── tsconfig.json
│   ├── src/
│   │   ├── index.ts          # 入口文件
│   │   ├── routes/           # 路由定义
│   │   ├── middleware/       # 中间件
│   │   └── db/               # 数据库相关
│   └── tests/
├── client/
│   ├── package.json
│   ├── tsconfig.json
│   ├── vite.config.ts
│   ├── index.html
│   └── src/
│       ├── App.tsx
│       ├── main.tsx
│       ├── components/
│       ├── pages/
│       └── api/
└── shared/                   # 前后端共享类型
    └── types.ts

> 安装所有依赖，确保项目能正常启动

# 根目录
pnpm install

# 后端
cd server && ppm add express cors better-sqlite3
pnpm add -D typescript @types/express @types/cors @types/better-sqlite3 vitest

# 前端
cd client && pnpm add react react-dom react-router-dom
pnpm add -D @vitejs/plugin-react vite typescript vitest

> 现在实现第一个功能模块：任务的CRUD API。
> 
> 需要实现：
> - POST   /api/tasks     创建任务
> - GET    /api/tasks     获取任务列表
> - GET    /api/tasks/:id 获取单个任务
> - PUT    /api/tasks/:id 更新任务
> - DELETE /api/tasks/:id 删除任务
> 
> 数据库使用SQLite，创建tasks表。包含测试。

Claude wants to edit server/src/db/schema.ts [Allow? y/n]
Claude wants to run: pnpm --filter server test [Allow? y/n]

> 运行后端测试，确认所有API测试通过。如果有错误请修复。

cd server && pnpm test

# 预期成功输出：
# ✓ POST /api/tasks - 创建任务
# ✓ GET /api/tasks - 获取任务列表
# ✓ GET /api/tasks/:id - 获取单个任务
# ✓ PUT /api/tasks/:id - 更新任务
# ✓ DELETE /api/tasks/:id - 删除任务
# 
# Tests  5 passed (5)
# Time   1.2s

# 测试失败示例：
# ✗ POST /api/tasks - 创建任务
#   → Expected status 201, received 500
#   → Error: Cannot read property 'title' of undefined
# 
# Claude Code自动分析：
# "问题出在请求体解析中间件未正确配置。
#  我需要添加 express.json() 中间件。"

> 请查看当前的代码变更，生成合适的commit message并提交。

# Claude Code生成的commit：
feat(server): implement task CRUD API with SQLite

- Add database schema and initialization script
- Implement RESTful endpoints for tasks
- Add input validation middleware
- Include comprehensive test suite (5 tests)

Co-Authored-By: Claude <[email protected]>

> 现在实现前端。创建一个简单的任务列表页面，包含：
> 1. 显示所有任务的列表
> 2. 添加新任务的表单
> 3. 标记任务完成/未完成的切换
> 4. 删除任务的按钮
> 
> 使用React Hook管理状态，不需要引入状态管理库。
> 样式使用CSS Modules。

> 前后端需要联调。请确保：
> 1. 后端添加CORS中间件
> 2. 前端API调用指向正确的后端地址
> 3. Vite配置代理到后端的3001端口
> 4. 两个服务能同时启动

// client/vite.config.ts
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

export default defineConfig({
  plugins: [react()],
  server: {
    port: 5173,
    proxy: {
      '/api': {
        target: 'http://localhost:3001',
        changeOrigin: true,
      },
    },
  },
})

> 创建feature/task-tags分支，实现任务标签功能。

git checkout -b feature/task-tags
# 然后开始实现标签功能...

> 审查当前分支相对于main分支的所有变更。关注：
> - 潜在的bug
> - 性能问题
> - 安全隐患
> - 代码风格一致性
> 
> 输出审查报告和改进建议。

## 代码审查报告

### 严重问题 (2)
1. [安全] server/src/routes/tasks.ts:45
   - SQL注入风险：直接拼接用户输入
   - 建议：使用参数化查询

2. [Bug] client/src/api/tasks.ts:23
   - 未处理网络错误，可能导致页面崩溃
   - 建议：添加try-catch和错误状态

### 改进建议 (3)
1. [性能] 任务列表缺少分页，数据量大时性能下降
2. [风格] 部分文件缺少错误类型定义
3. [可维护] API基础URL应提取为环境变量

> 将feature/task-tags合并到main。如果有冲突请帮我解决。

gitgraph
    commit id: "init"
    commit id: "feat: CRUD API"
    branch feature/task-tags
    checkout feature/task-tags
    commit id: "feat: tag model"
    commit id: "feat: tag API"
    commit id: "test: tag tests"
    checkout main
    commit id: "feat: frontend list"
    merge feature/task-tags id: "merge: task tags"
    commit id: "chore: update CLAUDE.md"

> 分析当前代码的测试覆盖率，为缺少测试的模块补充测试。
> 重点关注API端点和关键业务逻辑。

cd server && pnpm test -- --coverage

# 输出：
# File            | % Stmts | % Branch | % Funcs | % Lines
# ----------------|---------|----------|---------|--------
# All files       |   72.3% |    65.1% |   80.0% |  71.8%
#  routes/tasks.ts|   95.0% |    88.9% |  100.0% |  95.0%
#  routes/tags.ts |   45.0% |    30.0% |   60.0% |  43.5%  ← 需要补充
#  middleware/    |   60.0% |    50.0% |   75.0% |  58.3%  ← 需要补充

> 用Vitest + fetch API为整个应用写端到端集成测试。
> 测试场景：创建任务 → 添加标签 → 筛选 → 完成任务 → 删除任务

> 配置生产构建流程：
> 1. 后端编译为JavaScript
> 2. 前端构建为静态文件
> 3. Express服务前端静态文件（生产模式）
> 4. 创建启动脚本

// 根目录 package.json
{
  "scripts": {
    "build": "pnpm --filter server build && pnpm --filter client build",
    "start": "node server/dist/index.js",
    "dev": "concurrently \"pnpm --filter server dev\" \"pnpm --filter client dev\""
  }
}

> 添加环境变量支持：
> - DATABASE_PATH：数据库文件路径
> - PORT：服务端口
> - NODE_ENV：运行环境
> 创建 .env.example 文件作为模板

> 为这个应用创建Dockerfile和docker-compose.yml。
> 多阶段构建，最终镜像使用Alpine Linux。

# Dockerfile（Claude Code生成）
FROM node:20-alpine AS builder
WORKDIR /app
COPY package.json pnpm-lock.yaml ./
RUN corepack enable && pnpm install --frozen-lockfile
COPY . .
RUN pnpm run build

FROM node:20-alpine AS runner
WORKDIR /app
COPY --from=builder /app/server/dist ./dist
COPY --from=builder /app/client/dist ./public
COPY --from=builder /app/package.json ./
RUN corepack enable && pnpm install --prod --frozen-lockfile
EXPOSE 3001
CMD ["node", "dist/index.js"]

flowchart TB
    subgraph Phase1["阶段一：初始化（15分钟）"]
        A1["mkdir taskflow-app"] --> A2["git init"]
        A2 --> A3["claude 启动"]
        A3 --> A4["/init 生成CLAUDE.md"]
        A4 --> A5["完善项目配置"]
    end

    subgraph Phase2["阶段二：架构设计（10分钟）"]
        B1["Plan模式讨论架构"] --> B2["确定技术栈"]
        B2 --> B3["设计API路由"]
        B3 --> B4["设计数据库表"]
        B4 --> B5["审查并确认方案"]
    end

    subgraph Phase3["阶段三：骨架搭建（10分钟）"]
        C1["生成项目目录结构"] --> C2["创建配置文件"]
        C2 --> C3["安装依赖"]
        C3 --> C4["验证项目能启动"]
        C4 --> C5["Git初始提交"]
    end

    subgraph Phase4["阶段四：功能迭代（每个功能15-20分钟）"]
        D1["描述功能需求"] --> D2["Claude实现代码"]
        D2 --> D3["运行测试"]
        D3 --> D4{"测试通过？"}
        D4 -->|"是"| D5["审查变更"]
        D4 -->|"否"| D6["Claude自动修复"]
        D6 --> D3
        D5 --> D7["Git提交"]
        D7 --> D8["下一个功能"]
    end

    subgraph Phase5["阶段五：质量与部署（15分钟）"]
        E1["代码审查"] --> E2["补充测试"]
        E2 --> E3["生产构建配置"]
        E3 --> E4["Docker化"]
        E4 --> E5["部署就绪"]
    end

    Phase1 --> Phase2 --> Phase3 --> Phase4 --> Phase5

    style Phase1 fill:#3498db,color:#fff
    style Phase2 fill:#2ecc71,color:#fff
    style Phase3 fill:#f39c12,color:#fff
    style Phase4 fill:#e74c3c,color:#fff
    style Phase5 fill:#9b59b6,color:#fff

❌ "帮我写个登录功能"
✅ "实现用户登录功能：
   - POST /api/auth/login 端点
   - 接受 {email, password} 请求体
   - 返回JWT token
   - 密码用bcrypt加密存储
   - 添加单元测试和集成测试"

> 实现任务标签功能的数据库部分  ← 先做数据层
> （验证后）
> 实现标签的API端点              ← 再做API层
> （验证后）
> 实现标签的前端展示              ← 最后做展示层

> /plan 我想添加WebSocket实时通知功能，请先设计方案

# 1. 项目初始化
mkdir my-project && cd my-project
git init
claude
> /init

# 2. 架构规划
> 进入计划模式。描述需求和技术栈...

# 3. 骨架搭建
> 根据计划创建项目结构...

# 4. 功能迭代（重复以下步骤）
> 实现[具体功能]...
> 运行测试确认通过
> 查看变更并提交

# 5. 上下文管理（在对话过长时）
> /compact

# 6. 代码审查
> 审查所有变更，输出审查报告

# 7. 生产构建
> 配置生产构建和部署