Claude Code 结对编程实战指南：让 AI 加速开发但不失控

Claude Code 结对编程不是把键盘完全交给 AI。更稳定的做法是：人负责目标、边界、验收标准，Claude Code 负责阅读代码库、提出计划、生成小范围改动、运行检查并整理评审材料。

官方 Claude Code overview 把 Claude Code 描述为可以读取代码库、编辑文件、运行命令并接入开发工具的 agentic coding tool，也就是能主动执行开发任务的编码代理。能力越强，越需要清楚的边界。如果提示词只写“帮我改好”，它可能很快写出代码，也可能很快偏离需求。

这篇文章适合作为 Claude Code 入门指南 之后的实践篇。下面的流程来自日常修 bug、补测试、准备 PR 的实际工作模式，重点不是炫技，而是让新手也能复制。

先分清人和 Claude Code 的职责

开始之前，先约定谁做决定。Claude Code 可以快速搜索文件和修改代码，但产品意图、安全边界、是否可以合并，仍然应该由人来判断。

环节	人负责	Claude Code 负责
目标	说明要改什么，以及不改什么	找到可能相关的文件和路径
调研	指定阅读范围	阅读源码、测试、diff 和日志
实现	控制改动大小和风险	生成小而清晰的代码差异
验证	定义通过或失败的信号	运行测试、lint、build 或截图检查
评审	判断是否能合并	列出风险、遗漏测试和替代方案

这样做后，Claude Code 更像一位执行力很强的搭档，而不是无人监督的外包。对初学者来说，也更容易学习：先从一个 bug、一个测试文件、一个组件开始，不要一上来就重写整块功能。

前 10 分钟先整理环境

准备工作比提示词更重要。Claude Code best practices 强调两点：给 Claude 可执行的验证方式，并把探索、计划、实现和检查拆开。实际使用时，我会先做三件事。

第一，使用独立分支或 worktree，不直接在 main 上工作。第二，写一个短的 CLAUDE.md。官方 memory documentation 说明，CLAUDE.md 会在会话开始时作为持久指令被读取。第三，把项目里的验证命令告诉 Claude。

# CLAUDE.md

## Project rules
- Before editing, summarize the files you plan to inspect.
- Prefer small diffs and explain risky changes before applying them.
- After code edits, run `npm run lint` and the narrowest relevant test.
- Do not read `.env*` files or change deployment settings without approval.

## Common commands
- `npm run lint`
- `npm run test`
- `npm run build`

CLAUDE.md 不要写成百科全书。它越长，关键规则越容易被淹没。重复使用的流程可以考虑做成 Skills，只在需要时加载，避免每次会话都占用上下文。

核心循环：探索、计划、实现、验证

不要一开始就让 Claude Code “直接实现”。更可靠的循环如下。

flowchart LR
  A[说明目标] --> B[探索相关文件]
  B --> C[确认计划]
  C --> D[小步修改]
  D --> E[运行检查并看 diff]
  E --> F{是否通过}
  F -- 否 --> C
  F -- 是 --> G[整理 PR 摘要]

第一条提示词可以简短，但必须包含目标、范围、禁止事项和验证方式。

目标: 修复登录后个人资料页出现 500 的问题。
范围: 先检查 `src/auth` 和 `src/pages/profile`。
禁止: 不要改变认证策略，不要改数据库 schema，不要读取 `.env` 文件。
流程: 先读相关文件，列出 3 个可能原因，编辑前给出计划。
验证: 运行现有认证测试和 `npm run lint`。

如果 Claude 给出的计划太大，就继续收窄。

计划方向可以，但先只写复现测试。
确认测试失败后，再修改生产代码。
生产代码每次只建议一个文件的改动。

这就是 TDD，也就是测试驱动开发的实际用法：先让失败变得可见，再修复它。Claude Code 如果必须先证明 bug 存在，就更容易被审查。

一个可以直接运行的小例子

练习时不要先动真实业务代码。下面的 pair-check.test.ts 是一个小规则：根据改动风险决定 Claude Code 的工作模式。它可以直接用 Vitest 运行。

import { describe, expect, it } from "vitest";

type ClaudeMode = "direct" | "plan-first" | "human-review";

export function decideClaudeMode(input: {
  changedFiles: number;
  touchesSecrets: boolean;
  hasReliableTests: boolean;
}): ClaudeMode {
  if (input.touchesSecrets) return "human-review";
  if (input.changedFiles > 3) return "plan-first";
  if (!input.hasReliableTests) return "plan-first";
  return "direct";
}

describe("decideClaudeMode", () => {
  it("allows direct work for small, well-tested changes", () => {
    expect(
      decideClaudeMode({
        changedFiles: 1,
        touchesSecrets: false,
        hasReliableTests: true,
      }),
    ).toBe("direct");
  });

  it("requires a plan for broad changes", () => {
    expect(
      decideClaudeMode({
        changedFiles: 5,
        touchesSecrets: false,
        hasReliableTests: true,
      }),
    ).toBe("plan-first");
  });

  it("requires human review for secret-related work", () => {
    expect(
      decideClaudeMode({
        changedFiles: 1,
        touchesSecrets: true,
        hasReliableTests: true,
      }),
    ).toBe("human-review");
  });
});

npm install -D vitest typescript
npx vitest run pair-check.test.ts

接着可以要求 Claude Code 增加一条规则，例如“涉及 billing 时必须 human-review”。让它先加测试、运行失败、再实现、再运行测试。这个练习很小，但训练的是同一套能力：把任务变成可验证的小步骤。

真实项目里的 4 个常见用例

第一个用例是给现有功能加一个小条件，例如“免费用户隐藏 CSV 导出”。这类任务会涉及 UI、权限和测试，但不需要重写产品结构。

第二个用例是 bug 调查。把错误信息、复现步骤和期望行为一起给 Claude。官方 Common workflows 也建议提供复现命令和 stack trace，让 Claude 从根因开始查，而不是凭感觉猜。

第三个用例是补测试。先让 Claude 阅读已有测试风格，再要求它覆盖成功、无权限、非法输入、空数据等场景。想系统化推进时，可以结合 testing strategies guide。

第四个用例是 PR 前自查。让 Claude 阅读 git diff，优先检查安全、兼容性、测试缺口和命名问题。GitHub 的 pull request review documentation 说明了评论、批准和要求修改如何帮助团队守住质量。Claude Code 更适合做预审，而不是替代人类评审。

具体坑点和规避方式

坑点	会发生什么	更好的做法
只说“优化一下”	混入需求外重构	写清范围、非目标和验收条件
diff 太大	评审困难，bug 容易藏进去	一个任务一个 diff，先看计划
没有验证命令	代码看似完成但无法确认	要求测试、lint、build 或截图
CLAUDE.md 太长	关键规则被忽略	把流程拆到 Skills
权限放太宽	可能触碰秘密信息或生产操作	用权限和 hooks 限制

最隐蔽的问题是审批疲劳。如果每一步都要点确认，人很快会机械地批准；如果几乎全部允许，错误提示词就可能越界。实用原则是：可逆工作给高信任，不可逆工作给高摩擦。权限配置可参考 approval and sandbox guide。

把会话变成可评审的 PR

团队使用时，不要让信息只留在聊天里。结束前让 Claude Code 整理 PR 说明。

请把这个 diff 整理成 PR 描述。
包括:
- 为什么要改
- 主要修改文件
- 已执行的验证命令和结果
- 评审者需要重点看的风险
- 本次刻意没有修改的范围

Claude 可以写初稿，但最终文字应由人编辑。尤其是安全、支付、隐私、数据删除相关改动，不要把 AI 的“没有问题”当作证据。证据是 diff、测试输出、日志和评审讨论。

实际试用后的结论

Masa 在一个小型 Next.js 修复中使用这套流程时，评审时间比直接说“实现这个”更短。原因不是 Claude 写出了完美代码，而是第一条提示词限制了文件范围、写明了禁止事项，并要求留下 lint 和测试结果。另一方面，测试薄弱的 UI 改动仍然需要人工目视确认。结论很现实：Claude Code 结对编程不是把责任交给 AI，而是设计清楚哪些责任可以交给 AI。

下一次使用时，从今天的一个小任务开始，按探索、计划、实现、验证四步执行。如果团队需要统一提示词、评审标准和落地训练，可以查看 ClaudeCodeLab training。