第 20 章 · 综合实战项目

本章目标：综合运用前 19 章所学，从零搭建一个全栈 Todo 应用——完整走通需求分析、CLAUDE.md 编写、MCP 工具接入、Skill 封装、Hooks 自动化和部署验证的完整工作流。

20.1 项目规划与 CLAUDE.md

首先初始化项目并编写 CLAUDE.md——这是整个工作流的基础：

mkdir todo-app && cd todo-app
git init
npm create vite@latest . -- --template react-ts

# CLAUDE.md

## 项目概述
全栈 Todo 应用：React + TypeScript 前端，Express + SQLite 后端。

## 技术栈
- 前端: React 18, TypeScript, Tailwind CSS
- 后端: Express, better-sqlite3
- 测试: Vitest (前端), Jest (后端)
- 包管理: pnpm

## 硬性约束
- 所有 API 路由使用 /api/v1/ 前缀
- 数据库操作必须通过 repository 层
- 每个功能必须有对应测试

## 验证命令
- 前端测试: pnpm test:front
- 后端测试: pnpm test:back
- 类型检查: pnpm typecheck
- 完整验证: pnpm check

20.2 需求→设计→编码

启动 Claude Code 并按阶段推进：

claude

> 我要做一个 Todo 应用。请先阅读 CLAUDE.md 了解约束，
  然后在 docs/plan.md 中写出功能列表和实现计划。

Claude 会生成结构化的计划文档。审查确认后逐步执行：

> 按照 plan.md 的第一个功能（创建任务）开始实现，
  先写后端 API 和数据库层，再写前端组件和测试。

20.3 接入 MCP 工具

为 Claude 配置文件系统和数据库工具：

// .claude/mcp.json
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "."]
    },
    "sqlite": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-sqlite", "--db-path", "./data/todo.db"]
    }
  }
}

配置后 Claude 可以直接查询数据库状态来调试问题。

20.4 Skills 与 Hooks 自动化

封装重复操作为 Skill，用 Hooks 自动化质量检查：

<!-- .claude/skills/deploy/SKILL.md -->
---
name: deploy-check
description: 部署前检查：运行所有测试、类型检查和构建，全部通过后才允许部署。
---

## 步骤
1. 运行 pnpm check（包含 lint + typecheck + 全部测试）
2. 运行 pnpm build 确认构建成功
3. 如果任何步骤失败，报告错误并停止
4. 全部通过后输出"✅ 部署检查通过"

// .claude/settings.json — Hooks
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "command": "pnpm lint --fix --quiet"
      }
    ]
  }
}

每次 Claude 编辑文件后自动执行 lint 修复。

20.5 验证与部署

完成开发后，让 Claude 执行完整的部署流程：

> 使用 deploy-check skill 进行部署前检查。
  全部通过后帮我生成 Dockerfile 和 docker-compose.yml。

Claude 会：

1. 加载 deploy-check Skill；
2. 逐项执行检查命令；
3. 根据项目结构生成 Docker 配置；
4. 提交代码并打 tag。

本章小结

• CLAUDE.md 是整个工作流的基石——先写约束再写代码；
• MCP 工具让 Claude 能直接查询数据库等外部资源；
• Skill 封装可复用的多步操作，Hooks 自动化质量保障；
• 完整工作流：需求 → 计划 → 编码 → 测试 → 部署。

🧪 随堂测验

点击你认为正确的选项。答错时会展示正确答案与原因解析。

1. 在综合实战中，为什么要在写代码之前先创建 CLAUDE.md？

2. 在实战项目中，MCP sqlite 服务器的价值是什么？

3. deploy-check Skill 与 PostToolUse Hook 的分工是？

4. 实战工作流的正确顺序是？

🛠️ 动手实践

1. 为你自己的项目编写一份 CLAUDE.md，至少包含技术栈、约束和验证命令三个部分。
2. 配置一个 PostToolUse Hook，在每次文件编辑后自动运行格式化。
3. 将你团队常用的部署检查流程封装为一个 Skill。

🎉 恭喜完成核心实战！继续阅读第 21 章了解近期新特性。