不论用不用 AI，全栈项目最大的浪费是边写边想。 Day 15 学的 Plan 模式在这里第一次真正用上——先把架构、栈、范围画清楚， 让 Claude 知道这是个什么东西， 后面 6 小时的写码才不会原地打转。

今天的样例：Mini Task Tracker

麻雀虽小，五脏俱全：注册登录、增删任务、按标签筛选、按截止日排序、按状态归档。 这五条功能切片刚好覆盖全栈所有典型组件—— Auth、CRUD、Filter、Sort、State Transition。

技术栈一览

项目架构图

四条 AI-driven 全栈开发原则

Day 03 教你写 CLAUDE.md，那时它可能只有 20 行。 真实全栈项目里它应该是厚厚一份—— 告诉 Claude 项目是什么、技术栈是什么、规范是什么、 什么绝对不能做、出问题去哪里查。 项目级 CLAUDE.md 是你和 Claude 之间的项目契约。

四个必备章节

真实项目 CLAUDE.md 模板

# CLAUDE.md — Mini Task Tracker

## 项目说明
个人任务追踪 SaaS,后端 FastAPI + Postgres,前端 React 19 + Vite。
单租户、用户自己管理自己的 tasks/tags。**目前 MVP 阶段**,
不要引入复杂的多人协作 / 团队功能。

## 技术栈
- 后端: Python 3.12 + FastAPI 0.118 + SQLAlchemy 2.x + Pydantic v2 + Alembic
- 前端: React 19 + TypeScript 5.4 + Vite 6 + Tailwind v4 + TanStack Query
- 测试: pytest (后端) · Vitest + Playwright (前端)
- 部署: Dockerfile + Fly.io · CI 走 GitHub Actions

## 目录结构
- `backend/`  FastAPI 服务 + Alembic 迁移
- `frontend/` React app, 入口 src/main.tsx
- `infra/`    Dockerfile, fly.toml, deploy 脚本
- `.github/`  CI / CD workflow

## 编码规范
- Python: ruff + mypy --strict,所有函数必须有类型注解
- TS: tsc --noEmit + eslint,**不允许 any**,组件全用 function component
- 提交信息走 Conventional Commits: feat / fix / chore / docs
- 测试覆盖率 >= 80% — CI 卡线

## 常用命令(Make 风格)
- $ make dev          # 同时起前后端
- $ make test         # 跑全部测试
- $ make migrate      # 生成 + 应用迁移
- $ make lint-fix     # 自动修可修的
- $ make deploy       # fly deploy

## 禁忌(踩过的坑,别再踩)
- ❌ **不要在前端做 token 校验** — 一律走后端 middleware
- ❌ **不要用 raw SQL** — 走 SQLAlchemy ORM,迁移走 Alembic
- ❌ **不要把 .env 提交进 git** — 已 gitignore,看 .env.example
- ❌ **不要在 main 分支直接 push** — 走 PR
- ❌ **不要跳过测试合并** — CI 卡 80% 覆盖率

## 出问题去哪查
- 接口形态: 看 backend/openapi.json (CI 自动生成)
- 表结构: 用 db MCP 查 prod 副本(只读)
- 历史决策: docs/decisions/*.md (ADR 风格)

路径级规则（精准提示）

# .claude/rules/backend.md  ——  只在 backend/ 下生效

apply_to:
  - "backend/**/*.py"

## Backend 专属规则
- 所有路由文件放 `backend/routers/`,按资源分文件: tasks.py / tags.py / auth.py
- DB session 通过 FastAPI Depends 注入,**不要全局变量**
- 异常: 用 `HTTPException`,**不要 return error dict**
- 日志: `logging.getLogger(__name__)`,**不要用 print**

# .claude/rules/frontend.md  ——  只在 frontend/ 下生效

apply_to:
  - "frontend/src/**/*.tsx"
  - "frontend/src/**/*.ts"

## Frontend 专属规则
- 远端请求一律走 TanStack Query 的 useQuery / useMutation
- 表单用 React Hook Form + Zod
- 组件 props **必须**显式 Type,**不允许 React.FC**
- 样式只用 Tailwind class,**不写 inline style**

.claude/ 配置矩阵

# 项目根目录结构(完整版)
project/
├── CLAUDE.md                  # 项目契约(80 行)
├── .claude/
│   ├── settings.json          # 团队共享设置
│   ├── settings.local.json    # 个人覆盖(gitignored)
│   ├── .mcp.json              # db / github MCP 配置
│   ├── rules/
│   │   ├── backend.md         # 后端规则
│   │   ├── frontend.md        # 前端规则
│   │   └── migrations.md      # Alembic 规则
│   ├── skills/
│   │   ├── new-endpoint.md    # 新增一个 API 端点(含测试)
│   │   ├── new-component.md   # 新增一个 React 组件
│   │   └── ship.md            # 构建 + 部署 + 跑 smoke
│   ├── agents/
│   │   ├── tester.md          # 专门写测试的子代理
│   │   └── reviewer.md        # 专门做 code review 的子代理
│   └── hooks/
│       └── post-edit.sh       # 编辑后自动 lint + 跑相关测试
├── backend/                   # Python 后端
├── frontend/                  # React 前端
└── infra/                     # Dockerfile + fly.toml

地基打好后，七步 build pipeline 走完一轮，一个能跑的 MVP 就出来了。 关键不是每一步会用什么命令——而是每一步用对模式： 何时 Plan、何时 TDD、何时让 Subagent 接手。

7 步 Build Pipeline

阶段 A · 脚手架（Plan → 落地）

# Step 1 — 用 plan 模式让 Claude 先给方案,不要直接动手
> /plan

> 帮我搭一个 mini task tracker 的脚手架:
  · monorepo: backend/(FastAPI + Alembic) · frontend/(Vite+TS) · infra/
  · Makefile: dev/test/migrate/deploy 四个目标
  · .gitignore · .env.example · pre-commit hook
  · 不要写业务代码 — 只搭骨架,所有路由先返 501

# Claude 会回一份 plan(目录 + 关键文件清单),用户确认后才执行
> 通过,执行

# Step 2 — 验证脚手架能跑
$ make dev
# backend 起在 :8000, frontend 起在 :5173 — 都返 hello / 501,即 OK

阶段 B · DB 模型与迁移

> 在 backend/models/ 下建三张表:
  · users(id, email, hashed_password, created_at)
  · tasks(id, user_id FK, title, description, due_date, status, created_at)
  · tags(id, name) + tasks_tags 多对多关联表
  生成对应 SQLAlchemy 2.x 风格 model + 一份 Alembic 初始迁移

$ make migrate    # Claude 已经写好,你只需跑一下
INFO  Running upgrade -> 7f3a2b — initial schema

阶段 C · API 端点（TDD 循环）

# 关键: 一次开一个端点,先测试再实现 — 走 Day 6 的 TDD 模式
> 用 TDD 模式实现 POST /tasks:
  1. 先在 backend/tests/test_tasks.py 写 5 个测试:
     - 未登录 401
     - title 为空 422
     - 正常创建 201 返 task obj
     - status 默认为 "open"
     - due_date 必须未来
  2. 跑测试确认全部失败
  3. 在 backend/routers/tasks.py 实现端点直到全过

# Claude 的执行轨迹(简化):
[Edit] backend/tests/test_tasks.py     # 写测试
[Bash] pytest backend/tests/test_tasks.py
5 failed — expected, no impl yet

[Edit] backend/routers/tasks.py        # 写实现
[Edit] backend/schemas/task.py         # Pydantic schema
[Bash] pytest backend/tests/test_tasks.py
5 passed in 0.42s ✓

[Hook · post-edit] ruff check backend/  # 自动 lint
[Hook · post-edit] mypy backend/        # 自动类型检查

阶段 D · 前端（Subagent 并行）

# 前端有 5 个页面 + ~12 个组件 — 用 Subagent 并行铺开
> 派出三个 subagent 并行做:
  · agent A: frontend/src/api/ 从 backend/openapi.json 生成 TS 类型 + fetch client
  · agent B: frontend/src/components/ 建 TaskCard / TaskList / FilterBar 三个基础组件
  · agent C: frontend/src/pages/ 建 LoginPage / TasksPage / 路由配置

  agent A 完成后 agent B/C 才能用类型,所以 A 串行,B/C 并行

# 实际跑下来:
[Agent A] 完成 — 3 min · 生成 api/client.ts (147 行) + types.ts (89 行)
[Agent B] 进行中 ... 完成 — 8 min · TaskCard.tsx + TaskList.tsx + FilterBar.tsx
[Agent C] 进行中 ... 完成 — 6 min · LoginPage.tsx + TasksPage.tsx + router.tsx

$ cd frontend && npm run dev
UI 已经能登录 → 看 task 列表 → 新建 task,~17 min 完成

代码能跑只是开始。能跑得稳、能上线、能被监控才算 ship。 这一阶段把三层测试矩阵补齐、Dockerfile 写好、GitHub Actions 接通—— 之后每次 PR 都自动跑全套校验，绿了才能 merge。

三层测试矩阵

Dockerfile · 多阶段构建

# infra/Dockerfile — 一个镜像同时打包前后端,前端构建产物给 FastAPI static 服务
FROM node:22-alpine AS frontend
WORKDIR /app/frontend
COPY frontend/package*.json ./
RUN npm ci
COPY frontend/ ./
RUN npm run build      # 出 dist/

FROM python:3.12-slim
WORKDIR /app
COPY backend/requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY backend/ ./backend/
COPY --from=frontend /app/frontend/dist ./backend/static
ENV PORT=8080
CMD ["uvicorn", "backend.main:app", "--host", "0.0.0.0", "--port", "8080"]

GitHub Actions CI

# .github/workflows/ci.yml — PR 卡线,绿了才能合
name: CI
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with: { python-version: "3.12" }
      - uses: actions/setup-node@v4
        with: { node-version: "22" }

      - run: pip install -r backend/requirements.txt
      - run: cd frontend && npm ci

      - run: ruff check backend/                 # lint py
      - run: cd frontend && npm run lint        # lint ts
      - run: mypy backend/ --strict              # 类型
      - run: pytest --cov=backend --cov-fail-under=80
      - run: cd frontend && npm test
      - run: cd frontend && npx playwright test # E2E

  deploy:
    needs: test
    if: github.ref == "refs/heads/main"
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: superfly/flyctl-actions/setup-flyctl@master
      - run: flyctl deploy --remote-only
        env:
          FLY_API_TOKEN: ${{ secrets.FLY_API_TOKEN }}

上线后的 Smoke Test

# 部署完别走人 — 跑 5 个最关键的健康检查
$ URL=https://task-tracker.fly.dev

$ curl -sf $URL/healthz                    # 1. 进程活
$ curl -sf $URL/api/version | jq .commit   # 2. 部署的是最新 commit
$ curl -sf $URL/api/docs > /dev/null       # 3. OpenAPI 可访问
$ curl -sf -o /dev/null -w "%{http_code}\n" $URL/  # 4. 首页 200
$ npx playwright test e2e/smoke.spec.ts \
       --config=playwright.prod.config.ts      # 5. 关键用户路径

上面四节是动作，这一节是编排—— Hooks / Skills / MCP / Subagent 不是孤立工具,而是协奏曲。 看一个真实场景: 你接到一张 ticket，到 PR 合并、自动部署、Slack 通知, Claude Code 怎么在每一步串起 Day 10–14 学过的能力。

编排全景图

四件套各自的位置

真实 Ticket 全流程实录

# 假设 ticket #42: "tasks 列表需要支持按 due_date 排序"

> 读 GitHub issue #42 的描述,然后给我一份实施方案# MCP · github
[mcp_github] 读到了 issue: "用户希望按截止日升降序排,默认升序"

> /plan — 这个需求要改哪些文件?需要新加测试吗?# PLAN
[Plan] 1. backend/routers/tasks.py 加 order_by 参数
       2. backend/tests/test_tasks.py 加 4 个排序测试
       3. frontend/src/components/FilterBar.tsx 加排序下拉
       4. frontend/e2e/sort.spec.ts 加一条 E2E

> 通过,执行                                              # 进入实现
[Subagent A] 改后端 + 测试 ...
[Subagent B] 改前端 + 组件 ...
[Hook · post-edit] 自动跑相关测试 ✓
[Hook · post-edit] ruff fmt + mypy ✓

> /pr — 起 PR,标题 "feat(tasks): support order_by"# SKILL
[git] 已创建分支 feat/tasks-order-by · push · 开 PR #87

> 派 reviewer subagent 审一下                            # SUBAGENT
[Reviewer] 发现 1 处: missing index hint — 建议加 db index on (user_id, due_date)
> 同意,加上,重新跑 CI

[CI · GitHub Actions] All checks passed ✓ — 你点 merge
[Deploy] fly deploy — 上线 1m12s
[mcp_slack] 已发 #team-eng: "✅ #42 上线 / PR #87 / commit abc1234"

不实际跑一遍,前面所有内容都只是读过而已。 下面四个 Lab 按 BUILD pipeline 切片,任挑一个项目跟着做—— 技术栈不必和样例一样,关键是体会编排。

1. 7 步 build pipeline 中,哪些步骤必须走 Plan 模式?哪些可以直接 Edit?给出理由。
2. 项目级 CLAUDE.md 的四个必备章节是什么?为什么"禁忌"通常比"规范"更重要?
3. "API 先于 UI" 的开发顺序背后的具体原因是什么?反过来会发生什么?
4. 列出 4 件套(Hooks / Skills / MCP / Subagent)在一个典型 ticket 全流程里各自的具体使用场景。
5. CI 通过 ≠ 可以合并。给出至少 3 件 CI 检测不到、但 PR review 必须人工把关的事。