Claude Code 项目实战

这套流程把 Claude Code 当作能操作工具的工程协作者：先建立事实，再计划和实现，最后用测试与审查证明结果。

配套阅读：入口与快速开始 · CLI · IDE 与远程入口

入口说明

下面的核心提示词以 CLI 为基线，也可以在已连接的 IDE 中使用。独立并行任务可使用 Background agent 或 Worktree；Remote Control、Chrome 和 Ultrareview 属于账号、网络或组织策略可能限制的入口，不作为新手默认路径。

实战总流程

1. 探索： 找入口、读现有模式、确认命令和 Git 状态。
2. 计划： 识别歧义、依赖、风险与测试方案。
3. 实现： 小步修改，控制文件和依赖范围。
4. 验证： 运行真实命令，区分新失败与已有失败。
5. 审查： 对照原始需求检查 diff、回归和安全问题。
6. 交付： 给出可复核摘要，不隐瞒未验证项。

复杂任务可以从 claude --permission-mode plan 开始，或在会话中切换到 /plan。

实战一：接手一个陌生仓库

启动：

cd /path/to/repo
claude --permission-mode plan

输入：

先不要修改文件。请调查这个仓库并给我一份接手说明：
1. 产品目标、技术栈和运行入口；
2. 主要模块、依赖方向和关键数据流；
3. 安装、开发、测试、构建命令，以及它们来自哪个文件；
4. 配置和环境变量从哪里加载，但不要读取或输出密钥值；
5. 当前 Git 状态、测试状况和最值得先确认的风险；
6. 仍无法从仓库判断的问题。

不要只总结 README。结论必须尽量引用具体文件。

然后执行 /init 生成 CLAUDE.md 草案。人工删除猜测，只保留团队愿意长期维护的命令和约束。

实战二：定位并修复 Bug

例子：搜索结果偶尔显示上一次关键词的数据。

修复搜索页的竞态问题：快速输入两个关键词时，较慢的旧请求可能覆盖新结果。

请严格按顺序：
1. 阅读搜索组件、请求封装、取消逻辑和现有测试；
2. 用测试或最小复现确认问题；
3. 解释事件时间线和根因；
4. 先添加能失败的回归测试；
5. 做最小修复，不更换请求库、不改服务端接口；
6. 验证快速输入、请求失败、清空关键词和组件卸载；
7. 运行相关测试、类型检查和 lint；
8. 最后审查 diff，说明修改、证据和剩余风险。

当根因不清楚时，及时收紧：

暂停修改。把目前内容分为“已验证事实”“仍是推测”“下一步最小实验”。
只有实验确认根因后才继续改生产代码。

这能避免模型围绕第一个猜测不断打补丁。

实战三：用计划模式开发功能

需求：导出当前筛选条件下的订单 CSV。

计划阶段

我们要给订单列表增加“导出 CSV”。

要求：
- 导出当前筛选和排序下的全部结果，而不只是当前页；
- 复用现有权限系统；
- 导出期间要有进度或禁用状态；
- 失败可重试，不能阻塞列表浏览；
- 文件名包含日期，但不包含用户隐私信息。

请先检查前后端现有能力、相似下载流程和测试方式。
列出需要确认的问题、推荐方案、修改文件、失败场景和验证计划。
现在不要实现。

计划阶段重点确认：

• 是前端生成还是服务端异步导出；
• 数据量、权限与审计要求；
• CSV 注入、编码和时区问题；
• 失败、重复点击和取消行为；
• 测试需要在哪一层覆盖。

实现阶段

按已确认方案实现。先完成最小纵向闭环，再补边界状态。

不要修改无关列表逻辑，不新增依赖，沿用现有下载和通知组件。
完成后运行相关前后端测试、类型检查、lint 和构建。
最后对照原始需求逐项验收，明确哪些是自动化验证、哪些需要人工验证。

实战四：用 worktree 隔离任务

Claude Code 可以为任务创建独立 Git worktree：

claude --worktree order-export

适合：

• 当前工作区已有未完成改动；
• 同时处理两个互不依赖的 Issue；
• 想隔离一次高风险实验；
• 需要并行代理但不希望改动互相覆盖。

进入后先让 Claude 报告 worktree 路径、分支和基线提交。结束前要求它运行测试、总结 diff，但是否提交、合并和删除 worktree 仍由你决定。

WARNING

worktree 只隔离工作目录和分支，不隔离数据库、端口、全局缓存、云账号或外部服务。并行测试使用独立端口和测试数据。

实战五：重构但保持行为

重构 packages/billing/src/calculateInvoice.ts，把折扣、税费和舍入拆成独立纯函数。

必须保持：
- 导出 API、参数和返回结构不变；
- 金额精度、舍入顺序和错误类型不变；
- 日志与指标字段不变；
- 不升级依赖，不修改调用方。

先列出现有可观察行为、边界值和测试缺口。
必要时先增加特征测试，再分小步重构；每步运行测试。
最后比较重构前后行为，并审查是否改变了运算顺序。

金融、权限、时间和并发代码尤其需要先固定现有行为。代码“更漂亮”不是完成标准。

实战六：让 Claude 做代码审查

交互会话中：

审查当前相对 main 的所有改动。

优先找：
- 会造成错误行为、数据损坏或权限绕过的问题；
- 并发、缓存、边界值和错误处理回归；
- 与需求不一致或缺失的测试。

每个发现必须说明严重程度、具体文件位置、触发条件和影响。
不要报告纯风格偏好；如果没有可验证问题，明确说没有发现。

非交互审查已暂存 diff：

git diff --cached | claude -p \
  --no-session-persistence --safe-mode --tools "" \
  -- "审查这份 diff，只报告可验证的 Bug、安全问题和缺失测试，按严重程度排序"

输入前先确认 diff 不含密钥、PII、客户数据或内部地址。这里禁用了工具并不保存会话，只审查标准输入；只有 diff 可能缺少调用方和项目约束。高风险审查应在可信仓库内使用 plan 模式和受限 Read/Glob/Grep 工具读取上下文。

实战七：前端视觉与交互验证

完成页面后启动本地服务，并验证桌面 1440×900 与移动端 390×844。

覆盖：
- 正常、加载、空数据、错误、禁用和长文本状态；
- 键盘导航、焦点、表单错误与按钮反馈；
- 控制台错误、失败请求和资源加载；
- 文字溢出、元素遮挡、横向滚动和布局跳动。

请用真实页面和截图验证，不要只根据组件代码推断。
修复发现的问题后重复检查，并在最终结果中列出视口和状态。

没有可用浏览器或测试账号时，让 Claude 明确列出未完成的人工验收项。

实战八：非交互和脚本

claude -p 执行一次任务并退出，适合管道、报告和 CI。

生成仓库摘要：

claude -p --no-session-persistence --permission-mode plan \
  --tools "Read,Glob,Grep" \
  -- "概括仓库架构、关键命令和三个主要风险；引用文件路径，不修改文件"

分析测试输出：

npm test 2>&1 | claude -p \
  --no-session-persistence --safe-mode --tools "" \
  -- "分析失败测试，找出最早根因，区分实现问题与环境问题，并给出最小修复建议"

管道前先对测试输出脱敏。即使禁用工具，日志正文仍会发送到当前模型 endpoint；--no-session-persistence 只是不保存本地会话，不改变 provider 的数据政策。

输出 JSON：

claude -p --output-format json --no-session-persistence \
  --permission-mode plan \
  --tools "Read,Glob,Grep" \
  -- "检查仓库并返回架构摘要和风险列表，不修改文件" \
  > report.json

要求结构化字段：

claude -p --output-format json \
  --no-session-persistence \
  --permission-mode plan \
  --tools "Read,Glob,Grep" \
  --json-schema '{"type":"object","properties":{"summary":{"type":"string"},"risks":{"type":"array","items":{"type":"string"}}},"required":["summary","risks"]}' \
  -- "分析当前仓库，不修改文件" > report.json

自动修改时明确工具和权限边界：

claude -p \
  --no-session-persistence \
  --permission-mode acceptEdits \
  --tools "Read,Edit,Bash" \
  --allowedTools "Read,Edit,Bash(npm run lint),Bash(npm test *)" \
  --disallowedTools "Bash(git push *),Bash(npm publish *)" \
  -- "修复当前 lint 错误，只修改直接相关文件，然后重新运行 lint 和相关测试"

自动化安全

显式 -p 或 stdout 非 TTY 都会跳过工作区信任对话，只在预先固定并审查过的可信目录中运行。Print 模式会静默忽略无效 settings，CI 应在运行前单独校验配置。不要把 --dangerously-skip-permissions 当成默认选项；更稳妥的做法是容器隔离、只读仓库权限、用 --tools 限制工具面、精确 allow/deny 和短期凭据。

实战九：把重复流程做成技能

当同一套步骤已经稳定重复三次以上，可以考虑项目技能，例如 .claude/skills/release-check/SKILL.md：

---
name: release-check
description: 发布前检查版本、变更记录、测试和构建产物。
---

1. 读取当前版本和自上个标签以来的提交。
2. 检查 CHANGELOG 是否覆盖用户可见变更。
3. 运行项目规定的 lint、测试和构建。
4. 检查仓库是否包含密钥、调试日志或意外产物。
5. 输出通过项、阻塞项和对应证据，不执行发布。

技能负责可复用流程，CLAUDE.md 负责项目事实和约束。不要在两处复制一大段相同内容。

失败时怎样纠偏

直接使用这些短指令：

停下。不要继续修改，先用 git diff 说明你已经改了什么以及为什么超出原范围。

回到最近一个测试通过的状态。不要丢弃我原有的未提交改动；先区分哪些修改是你本轮产生的。

你还没有证据支持这个根因。设计一个最小实验来证实或否定它，暂时不要改生产代码。

这个错误来自环境。保留原始错误，说明缺少的前提，并继续完成不依赖该前提的检查。

纠偏要指出“哪条事实或边界错了”，比泛泛说“再仔细一点”有效。

交付前检查清单

• Claude 是否在正确仓库和分支工作。
• 当前 diff 是否只有需求相关改动。
• 原始问题是否真实复现，修复后是否再次验证。
• 测试、类型检查、lint 和构建是否确实运行。
• 是否用跳过测试、删断言或扩大超时掩盖失败。
• 是否读取、输出或提交了敏感信息。
• 是否区分自动验证、人工验证与未验证项。
• 最终摘要是否包含改动、证据和剩余风险。

官方资料

• Claude Code 常见工作流
• 交互模式
• CLI 参考
• 子代理
• 技能
• Hooks
• 沙箱