巧匠开发者速查手册
AI 命令行

用 Claude Code 走完一个真实的修 bug 流程

AI 编码助手不是"让它自动修"，而是一套有纪律的工作流。本文用一个真实项目的 bug 为例，演示从复现、加测试、定点修改到回归验证的完整闭环，并给出每一步该下发的指令。

作者：巧匠团队·8 分钟阅读·更新于 2026-09-06

先定纪律：改之前必须能复现

最常见的翻车是：用户提交一个问题，Claude 直接改了代码、给了个"看起来对"的修法，但根本没人验证过 bug 是否真实存在。修正心态的关键是让工具先"复现"——用最小输入把问题稳定逼出来，再谈修。

下发指令时把上下文和期望清晰说出来：什么环境、出错时的输入、期望 vs 实际。比自己心里想明白更重要。如果项目有测试框架，第一步就该让 Claude 写一个会失败的测试来捕获当前 bug 行为。

好提示的开头三要素：复现步骤、你在上面观察到的具体现象、系统的预期行为。三样越具体，越不会诞生"自动脑补"的错误修复。

# 给 Claude Code 的任务指令模板
"复现 [BUG]: 在当前分支先写一个测试，用输入 X 验证它如今失败（红）。
只写测试，不要改业务代码，跑通这个失败用例后再回来告诉我。"
# 期望看到：一个红测(失败测试) 作为 bug 的铁证

用测试"钉死"期望行为，再让代码通过它

有了复现的失败测试，修复就变成"让它变绿"的过程，而不是自由发挥。要求 Claude 在执行修复前先声明它的诊断（根因假设），再动手，这样你能在它做任何修改之前判断方向靠不靠谱。

然后下指令：只改必要的最小范围，逐个让相关测试通过，期间不引入新依赖、不改无关文件。跑完整测试套件确认全绿，保留这个失败测试作为回归护栏，防止未来重蹈覆辙。

关键点在于：让工具先给出诊断说明，而不是直接输出 patch。这样能区分"猜对了再修"和"盲目改到测试过为止"两种质量。

# 追加指令
"先给出根因诊断（一两句），再最小改动让测试变绿。
不要加新依赖，不要碰无关文件；完成后跑 npm test 回贴结果。"

改完不等于完成：代码审查与回归跑一遍

让 Claude 修改后，自己至少做一遍"逆向审查"：改的是什么？改动是否超出问题描述？有没有副作用与边界没覆盖？推荐用 Claude Code 的 git diff 能力让工具自述变更，再人工复核。

把完整测试套件与类型检查作为硬门槛（pnpm test、pnpm typecheck），如果项目有 linter，一并跑。随后要求 Claude 补充"为什么这样改"的变更说明，记录决策而非只堆代码。

一个真实流程里，审查往往能发现 AI 少处理的并发、判空或历史兼容问题，所以这一步不可省。

claude "用 git diff 列出本次所有改动，逐条解释作用；
跑 pnpm test 与 pnpm typecheck 并报告是否通过；
补充一行变更说明（为什么这样改，而非改了什么）。"

常见翻车：工具"改对"了却把别处改坏

AI 修复最危险的不是没修好，而是顺带把相邻逻辑改得面目全非。这往往源于指令范围不明确——只说"修这个 bug"，工具就自行扩大改动面。

应对办法是把范围写死：允许修改的文件/函数给白名单，禁止改动的东西明确列出，目标是"最小 diff"。审查 diff 时若出现无关重构、被删的可疑逻辑、格式大改，就要回退并限定范围重来。

同时保留它删改前的基线。用 version control 的 diff/back 或直接把原始文件复制成 .bak，让工具改坏了也有退路。

diff --git a/src/payment.js b/src/payment.js
# 审查要点：仅应为修复目标而变；出现无关重构/删除立即回退
# 隐藏改坏的退路
cp src/payment.js src/payment.js.bak   # 改动前手动留底

沉淀：把这次的根因和解法写进注释与文档

修复闭环的最后一步不是提交，而是沉淀。让 Claude 在代码的关键位置加一句"为什么这里要这样"的注释（说明坑，而非复述代码），并在项目 docs 或 issue 里记录根因、触发条件、解决方式。

这一步的价值在于：下次有人或 AI 再遇到相似问题时，能直接读到历史决策，而不是重新踩同样的坑。它把一次临时修复转化为可复用知识，也是区分"救火"和"治理"的分水岭。

若修复涉及公共约定（如参数校验、边界处理），建议顺手更新 CONTRIBUTING 或 README 的对应小节，让规范与代码一致演进。

// 修复痕记实例（注释里写"为什么"，而非复述做了什么）
// 此前 dateStr 允许为空导致 endDate 非法，parse 前必须判空
// 根因见 docs/bugfix/2026-09-outdated-enddate.md
claude "在这个修复处加注释说明 出发原因，并把根因记录到 docs 对应文件。"

官方参考来源

下方为命令对应的官方权威文档，供你核对最新用法与深入查阅。

更多指南

Git 事故恢复实战：提交写错、推错分支、误删分支怎么救日常协作里最慌的时刻往往是「完蛋，提交/分支搞错了」。本文按真实事故场景给出可立即照做的恢复命令，并讲清每条命令的安全边界。Docker 镜像瘦身实战：从 1.2GB 压到 120MB 的 5 步镜像越大，拉取越慢、攻击面越广、存储越贵。本文给出可立即落地的 5 步瘦身法，每一步都附可复用的 Dockerfile 片段与验证命令。Nginx 报 502 Bad Gateway？按这 5 步定位502 不是 Nginx 本身挂了，而是它作为网关从上游（后端/代理）收到了无效响应。本文按「进程→配置→超时→资源→日志」的顺序给出最短排查路径。Linux 磁盘写满排查：df、du、lsof 三板斧定位真凶No space left on device 不代表可以随便删文件。本文给出从文件系统水位、目录逐层下钻到「已删除但仍被占用」的完整定位路径，并给出不会误伤数据的安全清理顺序。Linux CPU 100% 排查：从 top 到线程栈的最短路径CPU 打满时「重启解决一切」是最贵的选择。本文给出一条可复用的定位路径：分清消耗类型、锁定线程、拿到它在执行的代码，再对症处理——Java、Python、Go 场景各有对应工具。MySQL 慢查询优化实战：慢日志、EXPLAIN 与索引三板斧「数据库慢」通常只是几条 SQL 慢。本文给出一套可复用流程：用慢日志圈出最贵的查询、用 EXPLAIN 看清执行计划、判断是否值得建索引，并点名最常见的索引失效写法。Redis 变慢排查手册：大 key、阻塞命令与内存淘汰Redis 是单线程处理命令的，一个阻塞点就能拖慢整个实例。本文按「内存水位 → 大 key → 阻塞命令 → 淘汰与持久化」的顺序给出排障路径，每步附可直接执行的命令。Kubernetes CrashLoopBackOff 排查：5 步定位容器反复重启CrashLoopBackOff 不是一种错误，而是「容器起来就崩、K8s 退避重试」的结果状态。本文按退出码 → 上次崩溃日志 → 探针 → 资源 → 依赖的顺序给出最短排查路径。SSH 免密登录配置与排错：从 ssh-keygen 到 Permission denied免密登录的核心只有一句话：公钥放进远端 authorized_keys。但配不通时卡人的往往是权限位、家目录与 SELinux 这三个隐形关卡。本文给出完整配置路径与逐级排错法。Python 虚拟环境实战：venv 创建、依赖锁定与跨平台坑「在我机器上能跑」大多源于环境混用。本文用标准库 venv 搭建干净流程：创建、激活、依赖固定与复现，并点名 Windows 激活、版本漂移、跨平台依赖这三类高频坑。VSCode 远程开发实战：Remote-SSH 配置与连接排错本地机器弱、代码在内网服务器、GPU 在远端——Remote-SSH 让编辑器跑在本地、代码与终端跑在远端，体验如本地。本文覆盖安装连接、免密配置、常见连接故障与体验优化。Bash 脚本防坑实战：set -euo pipefail 与 trap 让脚本真正可信多数 Bash 脚本「跑完了」不代表「跑对了」：命令失败不退出、变量为空不报错、管道掩盖上游崩溃。本文用一套可直接套用的骨架（set -euo pipefail + trap + 引号纪律）根治这些静默失败。YAML 排坑实战：类型推断、缩进与多行字符串的静默炸弹YAML「看着对、跑起来错」的坑几乎都来自三处：标量被自动转类型、缩进层级错位、多行字符串语义不清。本文把高频暗雷逐个拆开，给出判别方法与工具链。HTTP 缓存实战：Cache-Control 与 ETag 的正确配法缓存配错只有两种结局：用户看不到新版，或回源流量打爆源站。本文讲清强缓存与协商缓存的分工、指纹资源与 HTML 的策略分治，并给出可直接用的 Nginx 配置与验证命令。Git 合并与变基冲突实战：读懂冲突标记并分场景解决面向日常频繁分支协作的开发者，用可复现的冲突案例讲清 <<<<<<< ======= >>>>>>> 标记怎么读，以及合并、变基、重命名冲突各自怎么处理。用 git bisect 二分定位引入 Bug 的提交适用于“凭感觉找提交太慢、checkout 试错费时”的老手与新人都能用的二分排查法：设定 good/bad、跑校验脚本把判定自动化。Git 子模块（submodule）管理与常见坑为你讲清何时该用 submodule、何时该用其他方案，以及 clone 后子模块空目录、分支漂移、嵌套等高频坑的标准解法。用 git worktree 并行开发多个分支与任务面向需要同时盯多个分支、频繁切换又担心 stash 乱套的开发者，教你一个干净工作目录对应一个任务的并行开发法。docker compose 多服务联调与启动排错讲清依赖启动顺序、环境变量、端口冲突、容器间网络名解析等联调硬伤，并给出可执行的 yaml 与排错命令。Kubernetes HPA 水平自动扩缩容配置与验证面向已会用 Deployment 但没配过自动扩缩容的工程师：从装 metrics-server、写 HPA 到压测验证副本数真的膨胀。Dockerfile 安全加固：收窄攻击面，非 root 运行与只读文件系统为维护基础镜像与把服务容器化的开发者提供一套可落地的加固清单：非 root、只读根文件系统、免特权、分层与镜像扫描。JavaScript 错误处理实践：从 try/catch 到全局兜底与重试写给中后端与全栈 JS 工程师的方法清单：同步/异步错误怎么接、Promise 的 unhandledrejection、兜底与指数退避重试怎么写。Python 打包与依赖锁定：从 pyproject.toml 到发布 PyPI面向把脚本落地成可发布包的 Python 工程：用 pyproject.toml 管理元信息、venv 隔离、锁定文件复现环境、twine 发布到 PyPI。Linux 内存耗尽与 OOM 定位：从 dmesg 到个大概率失控进程服务器说没内存时它往往没说真话，本文教你用 free、/proc/meminfo、cgroup 和 dmesg 一层层逼近真正吃满内存的进程，并把不再需要被 OOM kill 的配置填平。Linux 网络排查手册：连通性、丢包、延迟与 DNS 一次讲透从 ping 不通到慢如爬行、再到域名偶尔解析失败，本文按"链路层→IP→传输→应用"的顺序给出每层该用什么命令、看什么字段，并附随手可跑的对照实验。systemd 服务启动失败排查：从 status 到依赖与时序死锁看出 systemctl is-failed 只是第一步，本文把失败分成"启动器直接报错、进程秒退、依赖未就绪、端口迟迟不监听"四类，并给出每一类对应的日志入口与修复手法。Linux 文件权限与 sudo 实战：chmod/DACL/setuid 及提权边界从位权限到 ACL 再到 setuid 的存在意义，本文讲清"读写执行到底是怎么算的、特殊位什么时候帮倒忙、sudo 别再无脑 ALL"，并给出一套误操作前的安全姿势。Nginx 反向代理实战：location 优先级、proxy_pass 与上游均衡一次配对代理配错十有八九是 location 匹配顺序和 / 结尾的坑，本文把最常写错的几种配置逐条校正，并带你用一个后端 Node 服务实拼一个含负载均衡的反向代理。HTTPS 证书申请与 Let's Encrypt 自动续期：从签发到 cron 兜底手动申请证书不难，难的是让它在过期前自动续上，本文用 certbot 走通 webroot 与 HTTP-01 校验、配置在 80 端口上的自动续期，并配套两份"漏了也没事"的兜底机制。用 curl 调试 REST API 全流程：方法、头、鉴权、上传与诊断curl 是多数 API 排障的第一现场，本文从"看清一次请求到底发了什么"讲起，覆盖 GET/POST、Query 与 Body、Bearer/JWT 鉴权、Multipart 上传，并教你把响应时间与状态码一并读出来。MySQL 逻辑备份与恢复：mysqldump、导入提速与误删救回mysqldump 导出不难，难的是导出的是否可恢复、恢复是否够快、误删之后是否救得回，本文讲清一致性选项、单事务隔离、导入加速参数，以及一套靠 binlog 补救的误删流程。PostgreSQL 慢查询定位与参数调优：从 explain 到 shared_buffers慢查询三板斧是"先找出来、再解释计划、后调参数"，本文讲怎么开慢日志、读懂 EXPLAIN 的 Seq Scan vs Index Scan，以及 buffer pool 与并发等最省事的几组核心参数。缓存穿透、击穿与雪崩：三种 Redis 故障的识别与防护线上接口突然变慢、数据库被打挂，多半是缓存的三类故障在作祟。本文用真实日志现象教你区分穿透/击穿/雪崩，并给出互斥锁、空值缓存、热点永不过期等可落地的防护方案。MySQL 索引设计与 EXPLAIN 分析：从小余量到慢查询清零表上索引越加越多，慢查询却不见减少，多半是索引没设计到位。本文从实际业务 SQL 出发，讲复合索引顺序、覆盖索引、索引失效场景，并用 EXPLAIN 逐段解析，把执行计划读明白。tmux 会话管理与复用：SSH 断开也不中断的远程开发SSH 一断，跑了一半的编译、正在编辑的代码以及十几个窗口全部前功尽弃。本文教你用 tmux 的命名会话、分离/复用、窗口与窗格划分，做到断网重连后一切原样继续。VSCode 断点调试上手：从 launch.json 到鼠标停在变量上比起到处 console.log，断点调试能让你停下来看到函数调用栈、每一步的变量值。本文从改 launch.json 开始，带你把 Node/前端项目的调试跑起来，并讲清边栏、watch 与条件断点的用法。环境变量与 .env 配置管理：12 因素之外的实务细节密钥放代码里、环境变量在不同环境间漂移、.env 被提交进 git——这类隐患几乎每个项目都会踩。本文按 12 因素原则讲清楚优先级、注入方式，以及如何安全地管理本地与 CI 的配置。Prettier 与 ESLint 协作：格式化与代码规范落地不打架Prettier 管格式化、ESLint 管代码质量，但两者规则重叠时容易互斥，pre-commit 跑起来鸡飞狗跳。本文讲清怎么划分职责、如何关闭冲突规则、以及统一配置并在 CI 强制生效。面向编码智能体的提示词工程：把 Claude Code / Codex 调教成可靠协作者让编码智能体一次写对的秘诀不在模型，而在指令质量。本文讲清楚上下文约束、最小修改原则、测试优先与代码审查提示的写法，教你写出高可复现、少幻觉的编码提示词。
← 返回指南列表