Claude Code 真实工作流：从单文件改动到跨仓库重构

过去 6 周我每周用 Claude Code 写 30+ 小时代码，覆盖 4 个仓库、3 种语言。 这篇是我把混乱的「啥都让它干」收敛成 12 个稳定模式之后的总结，附 5 个我学会不该让它干的事。

TL;DR

• 把 Claude Code 当工程师，不是当 IDE——给它任务上下文与验收标准，而不是手把手指令。
• 项目根放一份 CLAUDE.md，是 1 小时投资换长期 ROI 最高的一件事。
• 大改用 Plan mode + worktree，小改直接 dispatch；中间地带用 TaskCreate 拆分。
• 它不擅长的：陌生数据库 schema 推断、性能瓶颈定位、UI 视觉判断。
• 实测：纯熟后我 PR 速度提了 2.4×、bug 修复速度提了 3.1×、平均代码 review 评分不降。

1. 我的项目级 Claude Code 配置

每个仓库根目录都放一个 CLAUDE.md。不是什么都写——而是写「**它读不出来的东西**」：

# CLAUDE.md (~/projects/foo/)

## Stack 速览
- Next.js 15 (App Router) + Tailwind 3 + Postgres (Supabase)
- 包管理用 pnpm（不要用 npm，会打架 lockfile）
- 测试框架是 Vitest，**不是** Jest

## 这个仓库的反共识做法
- 我们故意不用 ESLint，靠 type 系统 + Biome 替代
- DB 迁移文件手写，不用 Prisma migrate（历史遗留）
- React 组件不强求 server / client 分离，按需加 'use client'

## 你（Claude）应该避免做的事
- 不要在没有 type 的接口上随便加 `any`，用 `unknown` + narrow
- 不要写 README 风格注释（"// fetch user from DB"）
- Bash 命令尽量先 dry-run（migration / 删除类操作）

## 我常用 sub-agent
- `Explore` 用来在陌生区域找定义
- `Plan` 用来在动多文件之前对齐方案

2. 12 个高 ROI 模式

按使用频率从高到低排，前 4 个占了我 80% 的真实使用场景。

P1 · 单文件局部改 — 直接 dispatch

最高频。比如「在这个 React 组件里加个 loading state」「这条 SQL 加个索引提示」。

# 直接说，别铺垫
src/components/UserList.tsx 加一个 isLoading
状态，渲染 Skeleton。骨架屏组件用现有的 <Skeleton>。

关键：给文件路径 + 现有的组件名 + 验收标准。不要写「请你...能否...或许...」。

P2 · Plan-then-execute — 动 3 个以上文件先对齐

但凡跨 3 个文件，先让它出方案我再点头。我用一个固定 prompt 模板：

目标：把全局 useUser hook 替换成 React Query。
约束：
1. 不动 SSR 入口
2. 错误处理接现有 toast 系统
3. 不破坏 e2e 测试

先给我一个 plan，列出：
- 要改哪些文件
- 新增什么依赖（必须用 pnpm）
- 哪些是 risky 改动需要我盯
- 测试怎么验

我看完点头你再开干。

我曾经省略 plan 步骤，结果 Claude 删了我自己写的一个看起来「冗余」的 retry 包装——其实它处理着一个 race condition。从此凡跨 3 文件必先 plan。

P3 · 测试先行修 bug

修 bug 时倒过来：先让它写一个失败的测试，复现 bug，**然后**让它修。

bug: /api/orders/[id] 在 id 含空格时返回 500，期望 400。

第一步：在 src/api/orders/__tests__/ 写一个失败的 test 复现这个。
跑 `pnpm test orders` 确认 RED。
然后再修。修完 GREEN 才算完。

P4 · 探索陌生代码库 — Explore subagent

接手别人写的 ~100k 行老代码。我会先派 Explore 子 agent 出一份地图：

Explore：这个仓库做什么？给我：
1. 顶层 architecture（最多 8 个模块）
2. 主要数据流（请求进来到落库）
3. 历史复杂度高的文件 top 5
4. 看着像「大家都怕动的地方」是哪几块

不要写代码，只输出 markdown 报告，控制在 600 字内。

P5 · 大重构开 worktree

要做 2+ 天的重构（比如换 ORM、升级 Node），开 git worktree。 Claude Code 在隔离 worktree 里跑，不会污染主分支，搞砸了 rm -rf 整个 worktree 即可。

git worktree add ../foo-orm-rewrite refactor/drizzle
cd ../foo-orm-rewrite
claude  # 在这里开新会话

P6 · PR review — 用 review skill

我有个 review skill（slash command），专跑「假设这是别人的 PR，挑刺」：

/review
聚焦：
- 性能 hotspot
- 边界条件 / 空值处理
- 是否破坏了现有公共 API
- 命名是否一致（参考 src/lib/naming.md）

输出 markdown 报告，按严重度排序。不要客气。

P7 · 跨仓库批量改名 / 升级 SDK

多个仓库一起改，不要在一个会话里轮流跑——并行起多个 Claude Code 实例，每个仓库一个。 共用一份 prompt：

目标：把 @anthropic-ai/sdk 从 0.32 升到 0.40。
变更：
- messages.create 入参 system 不再支持 string，改为 [{type:"text", text:...}]
- thinking 配置位置变化（看官方迁移指南）

每个仓库的步骤：
1. 升包，跑 typecheck
2. 修编译错误
3. 跑测试
4. 写 commit 信息：chore(deps): bump anthropic sdk 0.32 -> 0.40

P8 · 自定义 skill 把高频 prompt 沉淀下来

我把每天会用 3+ 次的 prompt 都做成 skill，放在 ~/.claude/skills/。 例子：/changelog（自动从 git log 写 PR 描述）、/sql-review（贴 SQL 让它挑性能问题）。

skill 比每次重复粘贴 prompt 强在两点：一是版本化（你迭代它），二是上下文隔离（不污染主对话）。

3. 5 个不该用 Claude Code 的场景

1. 性能瓶颈定位——它会过早做改动，不会先 profile。 先自己 perf / flamegraph 拿到数据，再让它改。
2. UI 视觉走查——它看不到截图（除非你贴），所以「这个按钮看起来怎么样」 这种问题它给的反馈基本无效。
3. 陌生 DB schema 推断——它会幻觉表结构。先 \\d table_name 自己确认，再让它写 SQL。
4. 风险高的破坏操作——rm -rf、force push、生产 migration。 一律自己手敲，否则踩坑无回头。
5. 2+ 步连续的 high-stake 决策——比如选数据库、选支付方案。 它能列优劣，但**判断**这一步留给你。

4. 真实成本与时间收益

过去 6 周（2026-03-19 至 2026-04-30）我的实际数据：

换算成 ROI：账单多了 \$84/月，但省了大约 28 小时/月。如果你单价 > \$3/小时，回报为正。 对工程师就是稳赚——但对 hobbyist 算清楚。

5. 上手 checklist

1. 装 Claude Code CLI（npm i -g @anthropic-ai/claude-code）
2. 在你最常工作的仓库根目录写一份 CLAUDE.md，照本文 §1 模板
3. 把你最高频的 3 个 prompt 做成 ~/.claude/skills/
4. 下次跨 3+ 文件改动时，强制走 P2（Plan-then-execute）
5. 2 周后回来读这篇，对照看哪些模式你没用上