来源：Claude Code 官方文档 · Claude Code What's New · Community Reports | 整理时间：2026-05-14
概述
很多开发者对 Claude Code 的第一印象是"能写代码的聊天工具"。但实际上，Claude Code 最强的地方是用 Agent 的方式完成有边界的真实开发任务——不是让它从零写一个完整应用，而是让它在一个已有代码库中完成可验证、可回滚的工作。
本文记录三种实战模式：重构迁移、新功能开发、多 Agent 协作排障。每种模式都附带具体的 CLAUDE.md 配置、提示词模板和效果评估。
模式一：代码重构与迁移
场景
将一个 Express + CommonJS 的 API 服务迁移到 Fastify + ES Modules。约 40 个路由文件，涉及中间件、测试和配置。
CLAUDE.md 配置
# 项目约定
## 技术栈
- Runtime: Node.js 20+
- 语言: TypeScript (strict mode)
- 框架: 正在从 Express 迁移到 Fastify
- 测试: Vitest
- 包管理: pnpm
## 迁移规则
- 先迁移路由文件，再迁移中间件
- 每个 PR 只迁移一个模块（路由 + 对应测试）
- 必须保持所有现有测试通过
- import 路径必须用 .js 扩展名（ESM 要求）
## 测试命令
- pnpm test — 运行所有测试
- pnpm test -- --watch — 监听模式
- pnpm test -- src/routes/auth.test.ts — 运行单个测试
## Git 规则
- 不要 force push
- 每个模块迁移单独 commit
- commit message 格式: refactor(migrate): {module name} to Fastify
工作流
# Step 1: 先让 Claude 理解当前架构
claude
> 分析 src/routes/ 目录的结构，列出所有路由模块和它们的依赖关系
# Step 2: 选一个模块开始迁移
> 把 src/routes/auth.ts 从 Express 迁移到 Fastify
> 保持所有测试通过，不要改变 API 行为
# Step 3: 验证
> 运行 pnpm test 确认测试通过
# Step 4: 继续
> 迁移 src/routes/users.ts，同样的方式
效果
| 维度 | 结果 |
|---|---|
| 单模块迁移时间 | 5-15 分钟（人工通常需要 30-60 分钟） |
| 测试通过率 | 首次迁移约 80% 直接通过，20% 需要一次修正 |
| 可回滚性 | 每个 commit 对应一个模块，git revert 即可 |
| 关键成功因素 | CLAUDE.md 中的迁移规则和测试命令 |
经验总结
- CLAUDE.md 是关键：写清楚迁移规则、测试命令、文件结构，Claude Code 的输出质量会显著提高
- 分步执行：不要一次让 Claude 迁移所有文件，按模块逐步推进
- Plan Mode 先分析：先用
claude --permission-mode plan了解全貌，再切换到执行模式
模式二：新功能开发
场景
为一个已有的 Astro 静态站点添加暗色模式、搜索功能和 i18n 支持。
提示词模板
# 约束优先的提示方式
1. 项目使用 Astro 6 + 纯 CSS（无框架）
2. 当前 CSS 变量定义在 src/styles/global.css
3. 测试命令: npm run build && npm run validate
4. 不要引入新的 npm 依赖
5. 暗色模式用 CSS custom properties + prefers-color-scheme
6. 搜索用客户端 JS 实现，不需要后端
任务: 为站点添加暗色模式切换。要求:
- 跟随系统偏好，用户可以手动切换
- 切换按钮放在导航栏右侧
- 所有页面都需要支持
- 运行 npm run build 确认没有报错
效果
| 维度 | 结果 |
|---|---|
| 暗色模式实现 | 15 分钟完成，包含 CSS 变量 + JS 切换 + localStorage 持久化 |
| 代码质量 | 符合项目现有模式，不需要额外重构 |
| 测试 | build 通过，但需要手动检查视觉效果 |
| 关键成功因素 | 约束写在前面，技术栈和限制条件明确 |
模式三：多 Agent 协作排障
场景
一个权限系统出现间歇性 bug：部分用户在并发操作时权限检查失败。
Agent 分工
# Agent 1: 调查 Agent（只读模式）
claude --permission-mode plan
> 分析 src/auth/ 和 src/middleware/ 目录的权限检查逻辑
> 找出可能导致并发场景下权限检查失败的原因
> 重点关注：缓存失效、竞态条件、session 管理
# Agent 2: 实现 Agent（受限工具）
claude --allowedTools "Read,Edit,Bash(npm test)"
> 根据 Agent 1 的分析，修复 src/auth/permission-cache.ts 中的竞态条件
> 添加互斥锁保护缓存刷新操作
> 确保所有权限相关测试通过
# Agent 3: 验证 Agent
claude -p "运行所有权限相关测试（npm test -- --grep auth）
分析测试结果，如果测试失败，给出具体的失败原因和修复建议"
效果
| 维度 | 结果 |
|---|---|
| 排障时间 | 从人工通常需要 2-4 小时降到 20-30 分钟 |
| 修复准确度 | Agent 1 的分析指向了正确方向（缓存竞态） |
| 回归风险 | Agent 3 验证通过，人工 review 后合并 |
| 关键成功因素 | Agent 分工明确——调查不修改、修改先验证 |
三种模式对比
| 维度 | 重构迁移 | 新功能开发 | 多 Agent 排障 |
|---|---|---|---|
| 复杂度 | 中高 | 中 | 高 |
| CLAUDE.md 重要度 | 极高 | 高 | 中 |
| 推荐权限模式 | default | default | plan + 受限 |
| 人工介入频率 | 每个模块 review 一次 | 完成后 review | 调查后决策点 |
| 典型时间节省 | 50-60% | 40-50% | 70-80% |
通用最佳实践
CLAUDE.md 必备要素
- 技术栈声明：语言、框架、包管理器
- 测试命令：Claude Code 需要知道怎么验证
- 项目结构：关键目录和文件的用途
- 编码规范：命名、风格、import 规则
- Git 规则：commit 格式、分支策略、禁止操作
提示词模式
# 好的提示词结构
1. 先给约束（技术栈、规则、限制）
2. 再给上下文（相关文件、当前状态）
3. 最后给任务（具体做什么、怎么验证）
# 避免
- "帮我写个网站"（太模糊）
- "重构所有代码"（太宽泛）
- "修复这个 bug"（没有给出足够上下文）
安全护栏
- 不要给不受限制的 Bash 权限：用
--allowedTools限制范围 - 重要操作前用 Plan Mode：先看 Claude 的分析，再决定是否执行
- 每个任务单独 commit：方便
git revert回滚 - CI 先行：让 Claude 先跑测试，再 review 代码