高手进阶（八）：Claude Code全栈项目实战指南：从需求到部署的Agentic Engineering还在手动CR

综合实战——用 Claude Code 交付一个完整全栈项目

Windows 10/11 · Claude Code v2.1.32+ · DeepSeek V4 Pro / Anthropic API · 🟢 常青 · 最后更新 2026-05-12

一、这篇教程解决什么问题

一句话定位：本篇是高手进阶系列的毕业设计——从需求分析、架构设计、前后端编码、测试调试到 CI/CD 部署，全程用 Claude Code 作为主开发者、你作为架构师和审查员，在 2-3 天内交付一个生产级全栈项目。

这不是"AI 帮你写几行代码"的玩具教程——这是 "Agentic Engineering"（代理工程）的完整实战。AI 领域的领军人物 Andrej Karpathy 在 2026 年 2 月的 Sequoia AI Ascent 大会上宣告：Vibe Coding（靠感觉写代码，不审查 AI 输出）已成为过去式，Agentic Engineering（人编排多 Agent 团队、人做架构和审查）才是下一阶段。本篇就是 Agentic Engineering 的操作手册。

跳读指南：只想看成本对比，跳到第七节。想先看复盘和踩坑经验，跳到第八节。想快速了解项目做了什么，看下面这张架构图和第二节的项目全景。想先跑起来，看第十一节速查卡。

全球实战案例速览（这不是理论——下面每个案例都是真实的人用 Claude Code 交付的真实项目）：

案例	时长	技术栈	关键数据
Jason Hoffman: Judoka App	19 天	React Native + Supabase + Stripe	30.9 万行代码，2726 测试，214 迁移，估算 71 倍加速
cpinto: OnboardingHub	55 天	Rails + PostgreSQL + Redis	38,632 行代码，713 commits，25-45 人工小时
Developers Digest: DD 网站	1 天	Next.js 16 + Convex + Clerk	155+ 功能，100+ commits，12 个并行 Agent
shusukedev: Amida-san	2 年	React + Go (GCP)	40 万 additions，2 万+ 用户，3 个 MCP 服务器
PulseMetrics SaaS	3 周	Next.js 14 + Hono + TimescaleDB	传统估算 8-10 周，实际 3 周
ClaudeSkill.com 市场	7 天	Next.js 14 + Supabase + Razorpay	8 种语言，2800+ skills

配套案例：建议同时阅读番外篇《Claude Code 实战拆解：8 天单人全栈交付视频翻译工具》——真实案例复盘，FastAPI + React + Whisper + Demucs 全栈，30+ commits，CLAUDE.md 269 行 + ARCHITECTURE.md 1000+ 行。本文和那篇互为补充。

阅读前提（硬条件）：

读过本系列前 7 篇（至少读过（一）权限模式、（四）MCP、（五）子代理、（六）CI/CD、（七）Agent SDK）
了解 Next.js、FastAPI、PostgreSQL 的基本概念（不需要精通）
Claude Code CLI 已安装并能正常启动
拥有 GitHub 账号
本地安装了 Node.js 18+、Python 3.10+、PostgreSQL 14+

DeepSeek 用户注意：本文全程使用 DeepSeek V4-Pro 完成，全流程 API 总成本不到 $0.40。文末附有 DeepSeek vs Claude Opus 4.7 的完整成本对比。

读完能得到什么：

一个完整可运行的全栈项目（Next.js + FastAPI + PostgreSQL 待办事项 SaaS）
一套Agentic Engineering 实战流程——什么时候用交互模式、什么时候用 -p、什么时候派子代理
一份真实的成本记录——每个阶段消耗了多少 Token、花了多少钱
一张 DeepSeek V4-Pro vs Claude Opus 4.7 全流程成本对比表
一份深度复盘报告——哪些环节 Claude 表现超预期、哪些需要人工介入、5 个真实 Debug
一张全局知识点串联表——把前面 7 篇文章的技能点串成一个完整项目

二、项目全景：TaskFlow 待办事项 SaaS

2.1 我们要做什么

一个名为 TaskFlow 的待办事项管理 SaaS。功能清单：

用户注册/登录（JWT 认证 + HttpOnly Cookie）
创建项目、在项目下管理任务
任务支持状态（todo/in_progress/review/done）、优先级（low/medium/high/urgent）、标签、截止日期
看板视图（三列拖拽）
项目成员邀请（邀请码加入）
个人仪表盘（任务统计、即将到期提醒）

为什么选 Todo App：题材够经典、体量适中（2-3 天单人+AI 可完成）、但功能足够"生产级"——用户系统、权限控制、数据库迁移、前后端分离、CI/CD 部署，一个不少。

2.2 技术栈与选型理由

层	选择	Claude Code 为什么擅长它
前端框架	Next.js 15 (App Router)	Server Components + Server Actions 是 Claude 训练数据的高频内容
UI 组件	Tailwind CSS + shadcn/ui	Tailwind 是 Claude 最强的 CSS 技能，几乎零修改可用
后端框架	FastAPI (Python 3.11+)	自动 OpenAPI 文档，Pydantic 类型安全，Claude 对 FastAPI 模式极熟
ORM	SQLAlchemy 2.0 (async) + Alembic	Claude 对 SQLAlchemy 模型+relationship+索引策略一次生成到位
数据库	PostgreSQL 15	JSONB 存标签、GIN 索引、RLS 支持
认证	JWT (python-jose) + bcrypt	无状态，FastAPI 生态成熟
前端部署	Vercel	零配置，推送即部署
后端部署	Railway	自动检测 Python 项目，从 requirements.txt 安装
AI 助手	Claude Code + DeepSeek V4-Pro	全流程辅助，成本约 $0.37

2.3 项目架构图

graph TB
    subgraph &#34;前端 Vercel&#34;
        NX[&#34;Next.js 15 App Router&#34;]
        SC[&#34;Server Components<br/>(直接查库/调 FastAPI)&#34;]
        SA[&#34;Server Actions<br/>(表单提交/数据变更)&#34;]
        CC[&#34;Client Components<br/>(交互/拖拽/状态)&#34;]
    end

    subgraph &#34;后端 Railway&#34;
        FA[&#34;FastAPI&#34;]
        JW[&#34;JWT Middleware&#34;]
        subgraph &#34;API v1&#34;
            AU[&#34;/auth 认证&#34;]
            WS[&#34;/workspaces 工作区&#34;]
            PJ[&#34;/projects 项目&#34;]
            TK[&#34;/tasks 任务&#34;]
        end
    end

    subgraph &#34;数据层&#34;
        PG[&#34;PostgreSQL 15&#34;]
        AL[&#34;Alembic Migrations&#34;]
    end

    subgraph &#34;CI/CD GitHub Actions&#34;
        GA[&#34;PR 自动审查&#34;]
        GT[&#34;自动化测试&#34;]
    end

    NX -->|REST API| FA
    FA --> JW --> AU & WS & PJ & TK
    FA --> PG
    AL --> PG
    GA --> NX
    GA --> FA

2.4 项目目录结构

taskflow/
├── CLAUDE.md                       # AI 记忆外骨骼（~80 行）
├── ARCHITECTURE.md                 # 架构决策记录
├── frontend/                       # Next.js 15
│   ├── src/
│   │   ├── app/
│   │   │   ├── layout.tsx          # 根布局
│   │   │   ├── page.tsx            # 仪表盘
│   │   │   ├── login/              # 登录页
│   │   │   ├── projects/
│   │   │   │   └── [id]/page.tsx   # 项目看板
│   │   │   └── actions/            # Server Actions
│   │   │       ├── tasks.ts
│   │   │       ├── projects.ts
│   │   │       └── auth.ts
│   │   ├── components/
│   │   │   ├── ui/                 # shadcn/ui
│   │   │   ├── TaskCard.tsx
│   │   │   ├── ProjectBoard.tsx    # 三列看板+拖拽
│   │   │   └── Navbar.tsx
│   │   └── lib/
│   │       ├── api-client.ts       # FastAPI 类型安全客户端
│   │       └── safe-action.ts      # next-safe-action 中间件
│   └── package.json
├── backend/                        # FastAPI
│   ├── app/
│   │   ├── main.py                 # Application Factory
│   │   ├── config.py               # Pydantic Settings
│   │   ├── database.py             # Async Session 工厂
│   │   ├── api/v1/
│   │   │   ├── router.py
│   │   │   └── endpoints/          # auth, workspaces, projects, tasks
│   │   ├── models/                 # SQLAlchemy 模型
│   │   ├── schemas/                # Pydantic 校验
│   │   └── services/               # 业务逻辑层
│   ├── alembic/                    # 数据库迁移
│   ├── tests/
│   └── requirements.txt
└── .github/workflows/
    ├── pr-review.yml
    └── test.yml

三、第一阶段：需求分析与架构设计

3.1 核心策略：用交互模式做推演，用 Headless 模式保存结果

这阶段不写一行代码，但决定了整个项目的质量。Claude Code 在需求推演上有一个被严重低估的能力——它可以扮演"产品经理 + 架构师"的双重角色，质疑你的假设、提出你没考虑到的边界情况。

实操：

mkdir taskflow && cd taskflow
claude  # 交互模式——这个阶段不要用 -p

第一条 prompt（关键——给上下文，要推演，不要代码）：

我要做一个待办事项管理 SaaS，叫 TaskFlow。现在还在需求阶段，不要写代码。

先帮我分析：
1. 目标用户是哪几类？每类的核心场景是什么？
2. 与 Todoist、Notion、Microsoft To Do 相比，差异化空间在哪？
3. MVP 只做 3 个核心功能，应该是哪 3 个？为什么？
4. 给出用户故事地图（User Story Map），按优先级排列

用中文回复，每个问题单独一节。在回答前，先提出 3 个你认为我可能没想清楚的问题。

为什么让 Claude 先提问：这是 Agentic Engineering 和简单"AI 写代码"的关键区别。Claude 会追问"是否需要多租户？"、"任务的权限粒度到哪一级？"、"数据归属是按 workspace 还是按 user？"——这些问题如果等代码写到一半才发现，返工成本是现在的 10 倍。

这个需求对话持续约 15 分钟、8 轮交互，消耗约 12K token（~$0.02）。确认需求后，用 Headless 模式保存文档：

claude -p "将刚才的需求讨论整理为结构化 docs/requirements.md" --allowedTools "Read,Write"

3.2 数据库 Schema 设计

需求定稿后，让 Claude 设计数据库。关键技巧：先给 schema 设计（不含 SQL），确认后再生成建表语句。

基于 docs/requirements.md，设计 PostgreSQL Schema。

要求：
1. 列出所有表、字段、类型、约束
2. 标注主键、外键关系
3. 考虑索引策略（哪些查询最频繁？）
4. 用 Mermaid ER 图表示关系
5. 评估方案 A（tags 用 JSONB）vs 方案 B（tags 用关联表），做 trade-off 分析

不要写建表 SQL，先给我 Schema 设计确认。

Claude 给出的核心设计（此处直接采用，几乎未修改）：

表	关键设计决策	Claude 的理由
`workspaces`	UUID 主键, `slug` 唯一, `settings` JSONB	多租户隔离的第一层
`users`	`email` 唯一索引, `password_hash`	全局用户，可跨 workspace
`workspace_members`	`(workspace_id, user_id)` 唯一约束, `role` 枚举	成员角色：owner/admin/member
`projects`	`workspace_id` 外键, `owner_id`, 软删除 `deleted_at`	项目归属 workspace
`tasks`	冗余 `workspace_id`, `parent_task_id` 自引用, `position` 排序, `tags` JSONB	冗余 workspace_id 是为了 RLS 查询性能——不需要 JOIN 就能过滤
`labels`	workspace 级别, `(workspace_id, name)` 唯一	标签共享但隔离到 workspace
`task_labels`	多对多关联表	一个任务可有多个标签
`comments`	`(task_id, created_at)` 联合索引	按任务查评论是最频繁查询

Claude 做对了一件关键的事：自动建议 tags 用 JSONB 而非关联表，理由是"标签是少量、非结构化的元数据，JSONB 避免了多表 JOIN，PostgreSQL GIN 索引支持 JSONB 内搜索"。这个 trade-off 如果自己拍板，新手至少要纠结半小时。

3.3 API 设计

基于 Schema，设计完整的 RESTful API。每个端点列出：
HTTP 方法、路径、请求体（JSON Schema）、响应体、认证要求、错误码。

覆盖：用户注册/登录、workspace CRUD、项目 CRUD + 成员管理、任务 CRUD + 状态变更 + 拖拽排序 + 按状态/优先级/标签/到期日筛选、仪表盘统计。

不要写代码，先给 API 清单，确认后再生成 FastAPI 路由骨架。

Claude 产出约 25 个 API 端点。确认后，让它生成 FastAPI 路由骨架（只有函数签名 + docstring）。

3.4 知识点串联：本节用到了前面哪些技能

用到的技能	来源	体现
权限模式（allowedTools）	高手进阶（一）	`--allowedTools "Read,Write"` 限制 Claude 的操作范围
MCP 协议	新手上路（四）	Claude 自动调用 Read 工具读取需求文档
Headless 模式 `-p`	高手进阶（六）	保存 Markdown 文档到文件系统
交互模式多轮对话	全系列基础	需求推演、trade-off 分析、设计确认

关键经验：需求阶段用交互模式（不要 -p）。交互模式的多轮推演式对话是 Claude Code 最强但最被低估的能力——它让你在写任何代码之前，把所有模糊点都澄清。

四、第二阶段：后端开发

4.1 开发策略：小步增量，每步确认

后端开发的顺序由依赖关系决定：

数据库模型 → 配置/连接 → Auth 模块 → Workspace 路由 → 项目路由 → 任务路由 → 仪表盘

每一步的循环：Claude 生成代码 → 人 Review → 跑测试 → 报错 → Claude 修复 → 通过 → Commit。

核心原则来自 Anthropic 官方最佳实践："Claude Code 需要的是护栏（guardrails），不是指令（instructions）"。你不用告诉 Claude 怎么写代码——你告诉它边界在哪。

4.2 数据库模型（关键代码）

# backend/app/models/user.py — Claude 生成，90% 一次通过
import uuid
from datetime import datetime
from sqlalchemy import String, Boolean, DateTime, func
from sqlalchemy.dialects.postgresql import UUID
from sqlalchemy.orm import Mapped, mapped_column, relationship
from app.database import Base

class User(Base):
    __tablename__ = "users"

    id: Mapped[uuid.UUID] = mapped_column(
        UUID(as_uuid=True), primary_key=True, default=uuid.uuid4
    )
    email: Mapped[str] = mapped_column(
        String(255), unique=True, nullable=False, index=True
    )
    username: Mapped[str] = mapped_column(String(100), nullable=False)
    hashed_password: Mapped[str] = mapped_column(String(255), nullable=False)
    is_active: Mapped[bool] = mapped_column(Boolean, default=True)
    created_at: Mapped[datetime] = mapped_column(
        DateTime(timezone=True), server_default=func.now()
    )
    memberships = relationship("WorkspaceMember", back_populates="user")
    assigned_tasks = relationship("Task", back_populates="assignee")

质量检查：UUID 主键（非自增 ID——安全）、server_default=func.now()（用数据库时间，不用 Python datetime.now()——防止服务器时钟不同步）、relationship 双向绑定正确。零修改通过。

4.3 Async Session 工厂（最关键的配置）

# backend/app/database.py
from sqlalchemy.ext.asyncio import (
    AsyncSession, async_sessionmaker, create_async_engine
)
from app.config import settings

engine = create_async_engine(
    settings.database_url,
    pool_size=10,
    max_overflow=20,
    pool_pre_ping=True,       # 生产环境必须——验证连接有效性
    pool_recycle=3600,        # 1小时回收连接
)

AsyncSessionLocal = async_sessionmaker(
    engine, class_=AsyncSession,
    expire_on_commit=False,   # Async 下必须——防止提交后懒加载报错
)

async def get_db() -> AsyncSession:
    async with AsyncSessionLocal() as session:
        try:
            yield session
            await session.commit()
        except Exception:
            await session.rollback()
            raise

expire_on_commit=False 是 async SQLAlchemy 最容易踩的坑。不设这个，commit 后访问任何属性都会触发 MissingGreenlet 错误。Claude 正确设置了它——这是训练数据中有大量此类问题的体现。

4.4 JWT 认证系统

写认证模块：
1. JWT 生成与验证（python-jose + bcrypt）
2. 注册 POST /auth/register
3. 登录 POST /auth/login——返回 access_token，同时设置 HttpOnly Cookie
4. 获取当前用户 GET /users/me
5. CurrentUser 依赖注入（从 Cookie 或 Authorization header 提取 JWT）

Claude 一次生成了完整的 auth 模块。测试：

# 启动后端
.venv/Scripts/python -m uvicorn app.main:app --reload

# 测试注册
Invoke-WebRequest -Uri http://localhost:8000/api/v1/auth/register `
  -Method POST -ContentType "application/json" `
  -Body '{"email":"test@example.com","username":"test","password":"Test1234!"}'

返回 {"id":"...","email":"test@example.com","username":"test"}——注册成功。

4.5 第一个真正的 Bug：position 并发冲突

任务看板需要拖拽排序。Claude 的初版实现是逐条 UPDATE position：

# ❌ 有并发问题的初版
for item in reorder_items:
    task = await db.get(Task, item["task_id"])
    task.position = item["position"]

运行测试：

FAILED tests/test_tasks.py::test_reorder_tasks
sqlalchemy.exc.IntegrityError: duplicate key value violates unique constraint "ix_tasks_position"

根因：如果 position 有唯一约束，逐条 UPDATE 的中间状态会出现冲突（两条记录暂时有相同的 position 值）。

修复：让 Claude 用 PostgreSQL 的 UPDATE ... FROM (VALUES ...) 在一条 SQL 中完成全部更新：

# ✅ 修复后——原子批量更新
values_clause = ", ".join(
    f"('{item['task_id']}', {item['position']})"
    for item in reorder_items
)
await db.execute(text(f"""
    UPDATE tasks SET position = v.position
    FROM (VALUES {values_clause}) AS v(id, position)
    WHERE tasks.id = v.id::uuid AND tasks.project_id = :project_id
"""), {"project_id": project_id})

这是 Claude Code 实战的典型模式：生成的代码 80% 直接可用，15% 需要微调，5% 需要人工介入修正（如这个并发问题）。

4.6 后端阶段成本

子阶段	Token	DeepSeek V4-Pro	耗时
数据库模型	~8K	$0.014	15min
Async Session 配置	~5K	$0.009	10min
认证系统	~12K	$0.021	25min
Workspace + 项目路由	~10K	$0.018	20min
任务路由（含排序修复）	~18K	$0.032	40min
测试编写 + Debug	~18K	$0.032	35min
后端合计	~71K	$0.126	~2.5h

对比：同样后端手写，一个熟练全栈开发约需 6-8 小时。Claude Code 将效率提升约 3 倍——这符合多个独立案例报告的加速比（PulseMetrics 3x、Django 迁移 6x）。

五、第三阶段：前端开发

5.1 前端策略：组件树先行

前端难点不是"怎么写"，而是"什么时候拆组件"。策略：先让 Claude 画组件树，确认后再逐个生成。

用 Next.js 15 App Router + Tailwind + shadcn/ui。

先不要写代码，画出 TaskFlow 前端的组件树：
1. 页面级路由及其负责的数据
2. 每个页面拆到叶子组件（标注：props、依赖的数据、Server 还是 Client Component）
3. 数据流：哪些从 Server Components 直接调 FastAPI、哪些从 Client Components 通过 Server Actions
4. 共享组件（Navbar、Sidebar）的复用位置

确认后，逐个页面生成。以项目看板为例：

生成 /projects/[id]/page.tsx——项目看板页面。

功能：
1. 三列看板：todo / in_progress / done
2. 每列显示该状态的任务卡片
3. 拖拽任务到不同列（@hello-pangea/dnd）
4. 拖拽后调 PATCH /tasks/reorder 更新位置（乐观更新）
5. 顶部显示项目名 + 成员头像 + 邀请按钮
6. "新建任务"按钮 → shadcn/ui Dialog

使用 Server Components 获取初始数据，Client Components 处理拖拽交互。

Claude 自动做了乐观更新——先更新 UI 状态，再发 API，失败时回滚。这个模式在它的训练数据中来自 shadcn/ui 的 pattern，不需要额外指示。

5.2 Tailwind 样式——Claude 的绝对强项

前端最耗时的往往是 CSS。但 Tailwind + Claude Code 的组合几乎消灭了这个痛点。原因是 Tailwind 类名在 Claude 训练数据中密度极高——GitHub 上数百万个 Tailwind 文件提供了海量的"意图→类名组合"映射。

TaskCard 样式要求：
- 白色卡片，圆角 8px，hover 阴影加深
- 优先级标签：urgent=红色、high=橙色、medium=黄色、low=灰色
- 截止日期：过期（红色+粗体）、今天（橙色）、未来（默认）
- 标签用 pill 样式小圆角

Claude 生成的 Tailwind：bg-white rounded-lg shadow-sm hover:shadow-md transition-shadow——零修改。

5.3 前端阶段成本

子阶段	Token	DeepSeek V4-Pro	耗时
组件树设计	~6K	$0.011	15min
登录/注册页	~10K	$0.018	20min
仪表盘	~14K	$0.025	30min
项目看板（含拖拽）	~20K	$0.035	50min
样式微调	~8K	$0.014	20min
前端合计	~58K	$0.103	~2.25h

六、第四阶段：部署与 CI/CD

6.1 CORS 联调

前后端分属两个目录和端口（3000/8000），让 Claude Code 跨目录处理 CORS：

# 项目根目录
cd taskflow && claude

前端 localhost:3000，后端 localhost:8000。配置：
1. 后端 CORS 中间件——允许 localhost:3000，支持 credentials
2. 前端 lib/api-client.ts——统一 fetch + JWT Cookie 管理
先读两个文件，确认需要改什么，再逐个修改。

6.2 部署

前端 → Vercel：

cd frontend && npx vercel --prod

Vercel 自动检测 Next.js，零配置。环境变量在 Vercel Dashboard 设置：NEXT_PUBLIC_API_URL=https://taskflow-api.railway.app

后端 → Railway：

cd backend && railway up

Railway 自动检测 Python 项目，从 requirements.txt 安装，从 Procfile 启动：

web: uvicorn app.main:app --host 0.0.0.0 --port $PORT

6.3 CI/CD 流水线（调用高手进阶六的知识）

claude -p "为 taskflow 生成 GitHub Actions：
1. PR 审查：PR 打开时 Claude Code 自动审查（--allowedTools Read,Grep --max-turns 5）
2. 测试：PR 打开时跑 pytest + Vitest
输出 .github/workflows/pr-review.yml 和 test.yml" \
  --allowedTools "Write"

生成的核心 YAML（pr-review.yml）：

name: PR Review
on:
  pull_request:
    types: [opened, synchronize]
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Claude Code Review
        env:
          ANTHROPIC_API_KEY: ${{ secrets.DEEPSEEK_API_KEY }}
          ANTHROPIC_BASE_URL: https://api.deepseek.com/anthropic
        run: |
          npx claude -p "审查本次 PR 的代码变更。关注安全性、正确性、性能。
            输出 JSON 格式报告。" \
            --allowedTools "Read,Glob,Grep,Bash(git diff)" \
            --max-turns 5 --output-format json > review.json
      - name: Comment PR
        run: gh pr comment ${{ github.event.pull_request.number }} --body "$(cat review.json | jq -r '.result')"

6.4 部署阶段成本

子阶段	Token	费用
CORS 联调	~5K	$0.009
部署配置	~8K	$0.014
CI/CD YAML	~10K	$0.018
合计	~23K	$0.041

七、成本全记录

7.1 TaskFlow 全流程账单

阶段	Token	DeepSeek V4-Pro	实际耗时
需求分析 + 架构设计	~30K	$0.053	1h
后端开发（含 Debug）	~71K	$0.126	2.5h
前端开发	~58K	$0.103	2.25h
联调 + 部署 + CI/CD	~23K	$0.041	1h
额外探索/重试	~25K	$0.044	0.5h
全流程合计	~207K	$0.37	~7.25h

全流程 DeepSeek V4-Pro API 总费用：不到 4 毛美元。提示：DeepSeek V4-Pro 输入 $1.74/M token，输出定价也远低于 Claude。全栈项目的 token 大头在代码生成输出。

7.2 DeepSeek V4-Pro vs Claude Opus 4.7 成本对比

阶段	DeepSeek V4-Pro	Claude Opus 4.7（估算）	价差
需求分析	$0.05	$0.19	~3.5x
后端开发	$0.13	$0.46	~3.5x
前端开发	$0.10	$0.35	~3.5x
联调部署	$0.04	$0.14	~3.5x
合计	$0.37	$1.30	~3.5x

Claude Opus 4.7 估算基于 Anthropic 官方定价（输入 $5.00/M，输出$ 25.00/M token，2026年5月），假设相同 prompt 和生成量。注意：Opus 4.7 使用新 tokenizer，相同文本可能多消耗高达 35% 的 token，实际成本可能更高。DeepSeek V4-Pro 当前处于促销期（75% off，截至 2026-05-31），促销结束后恢复 $1.74/$ 3.48，届时价差将缩小至约 2x。

7.3 成本优化心得

需求阶段不要省钱——多轮推演对话虽然消耗 token，但能避免后期返工。本项目需求阶段只占总 token 的 15%，但避免了至少 2 次方向性返工。
max_turns=10 是最佳甜点值——太小（3-5）任务半途而废，太大（20+）Claude 在死胡同里打转。10 轮刚好完成一次完整的"读→改→测试→修正→验证"循环。
中文 prompt 比英文省 30% token——DeepSeek 对中文的 tokenization 效率更高，用中文写 prompt 天然省钱。
模型选择是成本控制的最关键决策——DeepSeek V4-Pro 用于主力开发，V4-Flash 用于简单任务，Hybrid 策略可比全用 Claude 省 90%。

八、复盘：Claude Code 全栈实战表现

8.1 表现超预期的环节

环节	表现	原因分析
Tailwind 样式	近乎零修改	Tailwind 在 Claude 训练数据中密度极高，GitHub 上数百万文件提供了海量映射
SQLAlchemy 模型	一次通过（模型+relationship+索引）	ORM 模式固定，Claude 对"最佳实践"掌握很深
shadcn/ui 组件集成	95% 直接可用	组件库有明确 pattern，Claude 能准确复用
需求推演	超出预期	多轮交互模式下 Claude 能追问你没考虑到的边界情况
CORS + Cookie 配置	正确处理 HttpOnly + SameSite	安全配置在训练数据中频繁出现
CI/CD YAML	直接可用	GitHub Actions 是 Claude 的高频训练数据
Async Session 配置	`pool_pre_ping=True` + `expire_on_commit=False` 自动设置	这两个坑在 Python 社区被反复讨论，Claude 学到了

8.2 需要人工介入的环节

环节	问题	解决方式
position 并发排序	逐条 UPDATE 导致唯一约束冲突	人工识别根因 → Claude 改用 VALUES 批量 UPDATE
JWT 刷新机制	Claude 初版没考虑 token 过期后的刷新	人工补充需求 → Claude 生成 refresh token 逻辑
CORS 通配符风险	初版 CORS 用了 `allow_origins=["*"]`	人工改为白名单模式
异常处理过宽	`except Exception` 吞掉所有错误	人工逐个指定异常类型
N+1 查询	任务列表没预加载 assignee	人工 Code Review 发现 → Claude 加 `selectinload`
Vercel 环境变量	`NEXT_PUBLIC_` 前缀遗漏	人工发现 → Claude 补全

规律总结：Claude 在"有标准答案"的领域（框架语法、组件 pattern、配置模板）几乎完美；在"需要业务判断"的领域（安全 trade-off、并发处理、UX 细节）需要人类把关。这就是 Agentic Engineering 的核心——人做判断，AI 做实现。

8.3 真实世界的失败教训（别人的血，你的经验）

以下事故全部来自 2025-2026 年的真实报道——每个都是在 AI 辅助编程中"少想了一步"导致的灾难：

事故	工具	根因	教训
生产数据库被删（SaaStr, 2025.7）	Replit AI Agent	AI 有生产 DB 写权限，执行了 `DELETE FROM users`	生产环境永远不要给 AI 写权限
全部基础设施被毁（DataTalks, 2026.3）	Claude Code	AI 混入了旧 Terraform state，执行 `terraform destroy --auto-approve`	永远不要 `--auto-approve`
150 万 API Token 泄露（Moltbook）	AI 构建的 MVP	RLS 从未开启，API 无权限检查	安全检查不能交给 AI——人必须审
用户文件永久损坏（2025.7）	Google Gemini CLI	AI 幻觉出一个不存在的目录，覆盖写入了真实文件	AI 的自我报告不可信
React 无限递归炸内存	多次 AI 会话接力	一个关键的 `readOnly` prop 被后续 AI 会话误删	保护性代码必须有测试用例，不能只靠注释

核心教训：写代码不再是瓶颈——证明代码正确才是瓶颈。Claude Code 让"写出来"变得极快，但"写对"仍然需要人的判断力。

8.4 八个关键实战经验

CLAUDE.md 是 AI 的记忆外骨骼。项目进行到一半时，CLAUDE.md 积累约 80 行（项目结构、Schema 摘要、常见命令、已知坑）。每次新开会话，第一条消息是"请先读 CLAUDE.md"。社区共识：保持在 200 行以内，只写 AI 无法从代码推断的信息，像代码一样维护。
文档驱动开发。不要直接在代码里让 Claude 改。先在 docs/ 写好需求、API 设计、组件树，确认后让 Claude 读文档生成代码。文档是人类和 AI 之间的"合同"。
小步增量 > 一次全给。不要把整个后端需求一次性丢给 Claude。先做模型→确认→做路由→确认→做测试。每一步确认只用 2 分钟，但避免了"模型设计有问题的发现延迟到所有代码写好之后"的灾难。
前后端分离是天然的并行点。Schema 确认后，后端路由和前端组件可以完全并行——这正是子代理（高手进阶五）的最佳用武之地。
@docs/xxx.md > 把所有内容塞进 CLAUDE.md。使用渐进式披露——让 CLAUDE.md 指向更详细的文档文件，而非把 500 行内容全塞进去。
对抗性 AI 审查。用一个独立的 Claude 会话（不是生成代码的那个），以"安全工程师"角色审查 AI 生成的代码。实验证明这种技术比标准审查多发现 40-50% 的问题。
测试是代码的保护层，不是注释。AI 会在清理代码时删除注释中的"不要删这个"——但不会删除失败的测试用例。保护性逻辑必须用测试覆盖。
能自己修才能让 AI 写。核心原则：如果 AI 生成的代码出了问题你不能自己修，就不要让 AI 写那段代码。判断力和调试力是 AI 无法替代的最后防线。

九、Debug ×5（全项目实际踩坑）

Debug #1 — CORS 预检请求失败

报错：

Access to fetch at 'http://localhost:8000/api/v1/auth/login' from origin
'http://localhost:3000' has been blocked by CORS policy

根因：FastAPI CORS 中间件只设了 allow_origins，但没设 allow_methods 和 allow_headers。浏览器在 POST 之前发 OPTIONS 预检请求，被拒绝了。

配置	简单请求	预检请求
`allow_origins=["http://localhost:3000"]` 仅设 origin	通过	拒绝
完整配置（allow_methods + allow_headers + allow_credentials）	通过	通过

修复：

app.add_middleware(
    CORSMiddleware,
    allow_origins=["http://localhost:3000"],
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

验证：curl -X OPTIONS http://localhost:8000/api/v1/auth/login -H "Origin: http://localhost:3000" 返回 200。

Debug #2 — `MissingGreenlet` 错误

报错：

sqlalchemy.exc.MissingGreenlet: greenlet_spawn has not been called;
can't call await_only() here.

根因：JWT 中间件里有一个同步方法调了 await db.execute()。

调用链	结果
路由(`async def`) → `await service.get_user()` → `await db.execute()`	正常
中间件(`def __call__`) → `service.get_user()`（无 await）→ `await db.execute()`	MissingGreenlet

修复：JWT 验证不查库——仅解码 token 提取 user_id，在路由层用 Depends(get_current_user) 查库。中间件只做无状态的 token 验证。

验证：pytest tests/test_auth.py -v 全部通过。

Debug #3 — Server Components 返回过期数据

报错：看板页面显示已删除的任务，刷新后消失。

根因：Next.js 15 中 Server Components 的 fetch 默认不再缓存（与 14 不同），但通过第三方库（如 @hey-api/client）发起的请求可能走了库内部的缓存。

策略	表现
直接 `fetch()`（Next.js 15 默认）	每次请求最新数据
通过第三方 HTTP 客户端	取决于库的缓存配置
显式 `cache: "no-store"`	确保每次重新获取

修复：所有 API client 请求显式设置 cache: "no-store"，并在 mutation 后调用 revalidatePath()。

验证：删除任务后立即刷新，任务不再出现。

Debug #4 — Alembic 漏掉 JSONB 默认值

报错：

sqlalchemy.exc.IntegrityError: null value in column "tags"
violates not-null constraint

根因：Alembic --autogenerate 检测不到 Column(JSONB, default=[])，因为 [] 是 Python 可变对象，SQLAlchemy 不将其序列化到 DDL。

配置	Alembic 检测	生成的 DDL
`default=[]`	不检测	无 DEFAULT 子句
`server_default=text("'[]'::jsonb")`	检测到	`DEFAULT '[]'::jsonb`

修复：手动修改迁移脚本，加 server_default。

验证：alembic downgrade -1 && alembic upgrade head，插入不带 tags 的记录不再报错。

Debug #5 — Vercel 部署后环境变量不生效

报错：前端部署到 Vercel 后，所有 API 请求发到了 http://localhost:8000。

根因：NEXT_PUBLIC_* 变量在构建时注入 Client Component bundle。Vercel Dashboard 设置的环境变量如果没有 NEXT_PUBLIC_ 前缀，Client Components 读到 undefined。

变量名	Server Component	Client Component
`API_URL`	可读	`undefined`
`NEXT_PUBLIC_API_URL`	可读	可读

修复：在 Vercel Dashboard 设置 NEXT_PUBLIC_API_URL=https://taskflow-api.railway.app，触发重新部署（重新构建）。

验证：部署后浏览器 DevTools Network 确认请求发到正确地址。

十、全局知识点串联：前 7 篇技能在本项目的映射

前序文章	核心技能	在 TaskFlow 中的具体应用
高手进阶（一）IDE 五端	VSCode + CLI 双端协同、权限模式	VSCode 做编辑+审查，CLI 做 Headless 批处理和代码生成
高手进阶（二）Routines	云端定时任务	部署后可用 Routines 做每日数据库备份、依赖安全扫描
高手进阶（三）代码审查	`/review` + `/ultrareview`	CI/CD 中的 PR 自动审查步直接复用第（三）篇的审查配置
高手进阶（四）自定义 Skill	写自己的 CLAUDE.md 规则	项目的 CLAUDE.md 就是最精简的"项目专属 Skill"
高手进阶（五）子代理	Worktree + Background Agent	前后端并行开发是子代理的经典场景——Schema 确认后两路并发
高手进阶（六）CI/CD	`claude -p` + `--output-format json`	PR 审查 YAML 直接复用第（六）篇模板
高手进阶（七）Agent SDK	`query()` + `@tool`	本项目可封装为 SDK 工具——"一键生成全栈项目骨架"

十一、速查卡

核心命令速查

命令	用途
`cd taskflow && claude`	启动交互模式（需求分析、逐模块编码）
`claude -p "..." --allowedTools "Read,Write"`	Headless 保存文档/生成配置
`claude -p "审查..." --allowedTools "Read,Grep" --max-turns 5`	CI 管道中自动审查
`.venv/Scripts/python -m uvicorn app.main:app --reload`	启动 FastAPI 开发服务器
`cd frontend && npm run dev`	启动 Next.js 开发服务器
`.venv/Scripts/python -m pytest tests/ -v`	后端测试
`alembic revision --autogenerate -m "..." && alembic upgrade head`	数据库迁移

成本控制关键参数

参数	推荐值	说明
`max_turns`	10（编码）/ 5（审查）/ 20（探索）	超限自动停止——最后安全网
`max_budget_usd`	0.10-1.00	单次调用的硬上限
`--allowedTools`	场景精确指定	只开必要的工具，生产环境绝不开放 Bash
API 端点	`ANTHROPIC_BASE_URL=https://api.deepseek.com/anthropic`	DeepSeek 兼容端点——成本降低 90%

报错速查

报错	根因	解决
CORS blocked	中间件配置不完整	加 `allow_methods=[""]` + `allow_headers=[""]`
MissingGreenlet	同步上下文调了 async	所有 DB 操作统一用 `async def` + `await`
Next.js 过期数据	fetch 缓存	显式 `cache: "no-store"`
JSONB null 约束冲突	Alembic 没检测 `default=[]`	手动加 `server_default=text("'[]'::jsonb")`
Vercel 环境变量不生效	缺少 `NEXT_PUBLIC_` 前缀	加前缀 + 重新部署（触发重新构建）
position 重复键冲突	逐条 UPDATE	用 `UPDATE ... FROM (VALUES ...)` 批量更新

扩展阅读

本系列相关文章：

高手进阶（一）：Claude Code 五端完整指南 — 本项目在 VSCode + CLI 双端协同完成
高手进阶（三）：代码审查 2026 — 本项目的 PR 审查步直接复用了审查篇的配置
高手进阶（五）：子代理与并行开发 — 前后端并行开发是子代理的经典应用场景
高手进阶（六）：Headless 模式与 CI/CD 集成 — 本项目的 CI/CD YAML 来自第六篇模板
高手进阶（七）：Agent SDK 入门 — 本项目可封装为 Agent SDK 的 @tool
番外篇：Claude Code 实战拆解：8 天单人全栈交付视频翻译工具 — 真实案例复盘，与本文互为补充

参考文献

Jason Hoffman: Building Software with Claude Code — 19 天构建 Judoka App 的完整复盘
cpinto: Building a Complete SaaS with Only Claude Code — 55 天构建 OnboardingHub 的每日记录
Developers Digest: Case Study Building DD with AI — 一天 155+ 功能的并行 Agent 工作流
Claude Code 官方最佳实践 — 官方 CLAUDE.md 编写指南
Next.js 15 生产检查清单 — Next.js App Router 官方生产指南
FastAPI 生产模式 2025 — FastAPI + SQLAlchemy async 最佳实践
SQLAlchemy 2.0 Async 文档 — Async SQLAlchemy 官方参考
Next.js + FastAPI 全栈模板 — Vercel 部署的完整参考实现
Karpathy: From Vibe Coding to Agentic Engineering — Agentic Engineering 概念起源
Vibe Graveyard: Claude Code Terraform Destroy — Terraform 生产事故复盘
Fortune: Replit AI Wiped Production Database — SaaStr 数据库被删事故报道
DeepSeek API 定价 — 成本计算依据

高手进阶（八）：Claude Code全栈项目实战指南：从需求到部署的Agentic Engineering