前几个月接了个某遗留系统的维护单子代码是几年前从外包手里传下来的ES5 风格、函数动辄两三百行、几乎没有测试。接手后我做的第一件事不是读代码而是把 Claude Code 拉进终端让它先帮我梳理项目结构、识别高风险模块再逐步做重构和补测试。整个过程用下来我的感受是这是一款把“结对编程”真正落到日常命令行里的工具不是那种只能聊天、建议、给片段的助手而是能直接读文件、改代码、执行命令、看报错结果的完整工作流协作者。这篇内容我把几个真实做过的场景整理出来包括遗留代码重构、自动化补单元测试、运行时故障排查以及团队协作里的权限控制和规则沉淀每个环节都附上了提示词写法、操作流程、遇到过的问题和对应的处理方式。无论你是刚接触这类编程协作者还是已经用过一些 AI 辅助工具应该都能在里面找到能直接抄作业的部分。1. 项目背景与整体设计思路1.1 这个实战项目要解决什么问题先说背景。我手上的项目是某业务系统里最核心的订单处理模块技术栈是 Node.js Express MySQL后端的核心服务函数是几段历史遗留代码没有单元测试没有 lint甚至没有像样的注释。维护成本极高。当时主要有三个诉求把几个超长函数拆成短函数降低后续改动的心理负担给工具模块和核心业务模块补上基本的单元测试缓解“谁都不敢改”的问题排查一个偶发性的运行时异常日志里能看到堆栈但无法稳定复现这些事如果全部人工做按我的经验大概需要两周左右而且过程极其无聊。用 Claude Code 的目标是把大部分机械劳动拆出去比如生成测试骨架、做代码逻辑拆解、给出重构方案我保留决策权和最终审查权。这相当于从“自己动手干”变成了“带了个实习生但这位实习生执行力很强、不会累、也不会抱怨”。1.2 为什么选择 Claude Code 而不是其他方案当时我也对比过几种方式直接让通用 AI 助手生成代码再粘贴、用带 AI 能力的现代编辑器、用专门的代码补全插件。最终选择 Claude Code 的主要原因是它把“理解项目上下文”和“执行操作”这两件事统一了起来。通用聊天助手的问题在于没有项目上下文。你每次给它粘贴一段代码它只能基于这段代码回答改动后不会主动提醒你会不会影响其他调用方。而 Claude Code 可以直接查看整个目录的文件列表阅读多个相关源文件自己 grep 关键词甚至可以读取测试配置、打包脚本。它给出的方案不是凭空产生的是基于对项目当前状态的真实把握。另外它一个非常关键的能力是能直接修改文件。你可以让它重构某个函数它会自己打开文件、定位需要修改的位置、生成 diff然后在你的确认下写入。这和“让 AI 生成代码、你手动复制粘贴”是两种完全不同的工作方式前者保持了你对改动的全程感知可以在每个步骤拦截质量问题后者很容易出现粘贴位置错误或者遗漏调用方的问题。1.3 整体推进路线我的推进路线分四步让 AI 先通读项目生成模块清单和依赖关系建立对代码库的整体认知针对高风险文件让它逐个输出“当前逻辑梳理 修改风险评估”确认无误后再动刀重构完成后立刻让 AI 补测试用例用覆盖率工具验证把测试不必填的分支告诉它让它自己补漏把排查故障时用到的 prompt 和 AI 的权限配置沉淀到项目文档里让团队其他人也能复用这条路线并不复杂但每一步都踩过一些坑后面我会详细展开。2. 环境准备与基础配置2.1 安装与身份认证安装本身不复杂在终端里执行 npm 全局安装命令即可。装完后先做身份认证有两种方式如果你有对应服务的订阅账号可以让它走登录流程如果通过 API 方式调用则需导出 API Key 环境变量需要注意一点API Key 方式通常按 token 用量计费代码块输出、长文件读取都会产生较多消耗。如果只是个人日常开发订阅方案可能更划算。如果要在团队内大规模使用建议先做一段时间的用量观察再决定采用哪种方案。安装完成后在任意项目目录下输入命令就能启动交互界面。它会先扫描当前目录读取文件结构然后等你提出指令。2.2 给 AI 建立项目记忆CLAUDE.md 文件这是我在几天的使用中认为最重要的一个环节。Claude Code 支持读取项目根目录下的 CLAUDE.md 文件把它当作长期记忆和项目约束来对待。在你开启会话后它会自动读取这个文件并把相关内容作为上下文的一部分。第一次使用时我完全没有这个概念结果每次让 AI 给代码补测试它都会自动生成它自己偏好的测试框架风格。我明确告诉过项目用的是某测试框架但它还是会写错导入路径和断言风格。后来我建了 CLAUDE.md在里面写清楚技术栈和关键依赖版本测试命令和覆盖率检查命令代码风格约定比如使用单引号、尾部分号可省略、2 空格缩进禁止 AI 直接触碰的目录或文件提交信息格式约定写完之后的效果是立竿见影的。AI 生成的代码风格明显与项目更贴合不需要每次在 prompt 里反复强调。这个文件对团队协作尤其重要等于把团队的代码规范“翻译”成了 AI 也能遵循的规则。2.3 权限模型先想清楚让 AI 动什么Claude Code 的权限模型是我特别看重的一部分。它默认的策略是在执行可能产生外部影响的命令之前会先询问你是否允许。比如写文件、运行测试、安装依赖、执行 git 操作都需要得到明确授权。有一个命令行参数可以跳过所有权限确认但这非常危险。我测试过一次在沙盒目录里运行没问题但在正式项目里也这样跑的话AI 可能会自作主张修改掉你没有预期到的文件甚至运行一些不该运行的脚本来试图满足你的需求。我的做法是保持默认的交互式授权。每次 AI 想改文件都会弹出对应的路径和改动摘要我可以选择接受、拒绝或者修改意见。这虽然多了一点确认成本但换来了对每次改动的透明感知在重构场景下这是非常关键的安全保障。2.4 与编辑器的联动方式Claude Code 是一个终端工具但它和现代编辑器的联动体验也做得挺顺。直接把编辑器自带的终端切换到项目目录然后运行命令就行。AI 修改文件后编辑器会自动检测到文件变化并更新缓冲区基本不需要手动切换到 AI 的终端和编辑器窗口之间来回操作。如果是纯命令行环境它也会生成 diff 让你确认我自己在服务器上调试时觉得这个过程挺顺畅不会因为看不到文件内容变化而盲目信任它的修改。3. 实战一遗留代码可控重构3.1 任务拆分与提示词设计重构老代码最忌讳一上来就说“帮我重构这段代码”。原因在于 AI 在没有充分理解代码逻辑的情况下动手很可能会改变原有的行为带来隐蔽的回归问题。我用的提示词分三个步骤。第一步让它通读文件并总结逻辑请阅读 src/handlers/orderHandler.js 这个文件用中文梳理每个导出的函数分别做什么依赖哪些外部模块内部有哪些分支和副作用输出格式用列表。这一步的价值在于确认 AI 是否真的理解了代码。如果它总结得颠三倒四说明上下文不够或者需要换一种提示方式如果总结准确就可以放心进入下一步。第二步让它输出重构方案在不改变外部行为的前提下分析 orderCreate 函数当前的复杂度列出它可以拆分成哪些独立函数每个新函数的职责和输入输出并标注哪些地方属于高风险改动需要保持原样。注意这里强调“不改变外部行为”“高风险改动需要保持原样”这些约束性词汇会显著影响 AI 的输出倾向更稳妥。第三步才是让它动手改并且改成“只输出 diff不要直接写文件”的方式。你可以提出让 AI 直接改文件但我是通过先让它给 diff 的方式做了一层额外的确认。改完后看 diff 总比它直接静默修改文件要安全得多。3.2 让 AI 先出方案再动手的收益这次重构里最有收获的地方不是 AI 直接生成的代码而是“先出方案再动手”这个流程。AI 输出的重构方案里提到了一个我之前没有注意到的点原函数里有一段看起来无害的参数兜底逻辑但一旦抽成独立函数调用方就可以绕过兜底直接传空值导致后续逻辑崩溃。这不是 AI 的代码写得有多聪明而是它把整条调用链读了一遍之后给出的提醒确实触及了盲区。换作人工做重构这种问题通常要到测试阶段才会暴露而 AI 在方案阶段就把它标了出来。那次重构的改动涉及一个约三百行的函数AI 最终给出了五个新函数每个职责都相对单一。整个过程我确认了两次 diff加上补了一次手动回归用了大概四十分钟。放在平时我应该需要一下午。3.3 重构后的检查清单重构完成后我建议无论如何都要做这几步验证先用 lint 工具检查新代码风格是否合规CLAUDE.md 里的规则是否被严格遵守跑一遍已有的自动化测试确认没有破坏原有行为如果测试覆盖不完整至少把修改涉及的函数手动跑一遍用例检查是否有多余的 import 和未使用的变量这是 AI 重构时常会留下的垃圾我经历过一次比较惨痛的教训让 AI 重构一个函数它改了函数签名把参数从对象改成了具体值。函数内部确实简洁了但调用方全部用的是旧参数测试一跑五个模块报错。那个场景让我从此养成习惯——要求 AI 修改完成后必须自己跑一遍相关测试而不是让你自己去排查。# 让 AI 自己执行测试 运行当前项目的测试命令 npm run test如果有失败用例请分析原因并给出修复建议。这个提示词会触发它自己动手运行命令读取报错信息定位问题然后再提出修复方案。相当于让 AI 对自己的改动负责到底。4. 实战二自动化补单元测试4.1 分析覆盖率缺口第二个高频场景是补测试。项目里原本测试覆盖率只有不到 20%要人工补齐是件很枯燥的事。选择 Claude Code 来做的好处是它可以先读取源文件再设计覆盖面更完整的用例。我先让 AI 分析覆盖率请分析 src/utils/dateUtil.js 的代码路径列出当前可能存在分支但没有被测试覆盖的场景重点关注边界条件、异常分支和默认值。AI 读取函数后会按“输入类别”整理测试场景比如正常输入空字符串非法日期闰年/非闰年时间边界值未定义参数返回值的格式校验把这些场景列清楚后再让它生成测试代码就顺理成章了。4.2 生成测试用例与代码我一般会在 prompt 里明确指定测试框架、断言库风格、mock 方式和文件位置否则它可能自己发挥。比如基于上述测试场景用 Vitest 写测试用例放在 tests/utils/dateUtil.test.js使用 describe/it/expect 的结构mock 掉 Date.now 相关调用保持测试文件风格与现有 tests/utils/base.test.js 一致。指定风格后生成的代码基本可以直接用不需要自我调整太多。它还会自动补充每个用例的标题描述这比人工写还认真一些。有一点要注意不要让 AI 生成“保姆级”的重复断言。有时候它会给每个函数写五六个几乎一样只是参数不同的用例实际上价值很低。我会在 prompt 里加一句话“优先覆盖不同的分支路径避免重复输入下的冗余用例”。它一般能理解把注意力放在分支差异上。4.3 让 AI 自己补漏引入覆盖率工具后AI 补测试有一个天然的优势它可以用命令直接看到覆盖率报告然后精准补缺。我用的方式很简单——让它先跑覆盖率再根据报告补充执行 npm run test -- --coverage 查看当前测试覆盖情况找出低于 80% 的分支补充对应的测试用例使 utils 目录下文件的覆盖率提升到 90% 以上。实测下来它会自己分析哪些行没被覆盖哪些分支判断条件只测了一个方向然后逐一补测试用例。这个过程在纯人工环境下非常费时间AI 做起来却很快关键是它会从覆盖率报告出发而不是靠感觉猜测。不过也有一点需要人工把关AI 追求覆盖率时会出现“为了凑覆盖而写用例”的问题。比如一个函数内部有三个 if它可能会写三个用例分别命中每个 if但从未组合过两个 if 同时成立的场景。覆盖率数字确实上去了但实际的组合分支仍然是盲区。这种情况下我会追加一句“重点补多条件组合场景”它一般能调整策略。5. 实战三运行时故障排查5.1 定位可疑代码路径偶发性的运行时错误是最烦人的一种问题。它不固定复现日志里有堆栈但堆栈指向的代码段看起来完全合理。我遇到的那个 500 错误就是日志显示某个对象属性为 undefined但调用它的业务逻辑看起来已经被前面的 if 判空保护了。我把堆栈和可疑代码片段一起喂给 AI让它做交叉分析。提示词大概是这是线上日志中的堆栈信息指向 src/services/paymentService.js 第 128 行附近报错是 Cannot read properties of undefined。请先阅读整个函数分析哪些调用路径可能导致 targetAccount 为 undefined列出可能性从高到低排序并标出用于验证的关键日志或测试用例。AI 给出的分析比我想象得更系统。它没有只盯着报错那一行而是顺着调用往上找梳理了数据来源、前置判断逻辑、异步竞态几种可能并且区分了“理论上可能但实际概率低”和“代码路径上确实存在漏洞”两个层面。5.2 结合版本历史做回归判断保留多年的代码里也有值得留意的做法我让它把git log也拉进来对照。提示词是查看最近十次针对 paymentService 的提交记录分析哪次改动可能与 undefined 错误相关重点关注删除判空逻辑、调整对象字段名、改变异步顺序的提交。AI 读版本历史后指出了一个被我忽略的细节最近一次重构把原来在函数开头统一判空的逻辑删掉了改为在具体使用点逐段判断但中间有一段异步回调里的使用点当时没有补上判空。这几乎完美解释了为什么错误是偶发的那条异步回调只在特定网络环境下才会触发。这个发现让我很感慨。版本历史的分析人工也能做但需要一条条去翻 commit工作量大且容易漏。AI 帮我节省了很多时间去直接锁定可疑提交。5.3 验证 AI 的推测这里必须提醒AI 给出的所有推测都只能作为线索不能直接当作最终结论。在线上环境直接按照 AI 的建议改代码是不可取的。我的做法是让 AI 生成一段用于验证的临时日志代码先在生产日志里观察触发条件确认错误确实来源于它预测的路径再正式提交修复代码。这种做法让整个修复过程非常清晰先通过日志确认触发条件再在本地构造对应场景跑测试复现问题确认复现成功后再让 AI 生成修复方案修复后跑一遍已有用例再补一条针对该异步路径的回归用例这个流程走下来修复的把握会大很多。它也真正体现了工具的价值不是帮你拿主意而是帮你把“拿主意”之前的证据链铺得更完整。6. 团队协作与工作流沉淀6.1 用 CLAUDE.md 固化项目规则Claude Code 在团队场景下的表现很大程度取决于你如何定义规则。如果每个人按各自的习惯给 AI 下指令生成的代码风格会非常混乱。我的建议是把 CLAUDE.md 当作团队契约来维护。我目前维护的 CLAUDE.md 包含这些内容项目简介和架构说明目录结构和各模块职责代码风格与格式要求测试覆盖率基线禁止 AI 操作的文件列表要求 AI 在修改后运行哪些命令提交信息格式模板这样团队成员只要在各自的分支里使用 Claude CodeAI 展示出来的输出风格和遵守规则的自觉性就是一致的。6.2 快速提示词模板库团队协作中重复劳动最多的场景是提示词的编写。为了解决这个问题我把常用的提示词整理成模板统一放在团队文档库里比如代码逻辑梳理模板测试用例补充模板重构方案设计模板故障堆栈分析模板依赖升级影响分析模板每个模板都写清楚适用的场景、关键指令和注意事项。新加入的同事不需要自己摸索写提示词的方式直接套模板就能得到相对稳定的输出。我现在看到“让 AI 分析代码”这类事时第一反应已经不是自己打字了而是从模板库里找对应的一份替换里面提到具体文件名然后跑起来。这让整个团队的 AI 使用成本大幅降低。6.3 AI 参与的代码审查机制AI 自动生成的代码必须纳入人工审查流程。我把 Claude Code 的使用方式设置为“只能改本地的 feature 分支”不允许直接在主干分支上进行修改。AI 完成修改后我会先跑它自行生成的测试再看 diff确认无误后推送到远端并提交 MR让另一位同事做最终审查。这里我给团队的约定是AI 可以写代码、跑测试、分析堆栈AI 不能推送远程分支不能合并代码不能执行与部署相关的操作所有 AI 生成的代码必须经过至少一位真人 reviewMR 描述里需要标注哪些内容由 AI 生成方便 reviewer 重点关注这套机制运行下来团队里没有出现“AI 改出的问题没人发现”的情况。反而 AI 生成的代码一般结构更规范给 review 节省了不少时间。7. 常见问题与排查技巧实录7.1 高频问题速查表用了一段时间我和团队遇到的各种问题也不算少。我把它整理成一张速查表希望对正要上手的你也有些参考价值。问题现象可能原因处理方式AI 修改了与任务无关的文件没在 prompt 里限定范围在 prompt 中明确“只修改 xxx 文件”并在它请求操作时逐一确认AI 生成的测试代码风格与项目不符未在 CLAUDE.md 中说明测试框架在 CLAUDE.md 中补充测试框架、命名规则和命令反馈说无法找到某个函数项目文件过大导致上下文缺失手动打开相关文件再提问或调整 AI 权限让它可以自行读取修改循环多次未结束提示目标过于模糊给定明确验收标准例如覆盖率阈值或测试用例数运行长命令中途超时命令执行超时限制拆分命令为小步骤或者直接让 AI 只输出命令然后你自己跑AI 给出看起来很有道理但实际是错误代码它缺少日志或运行反馈让它直接运行测试或 lint把报错结果作为下一次输入的上下文反复修改同一段代码但问题没解决prompt 中没有体现前一次修改失败的原因主动告知 AI 前次修改失败的具体原因要求它规避上下文过长导致模型回答开始变得碎片化多轮的长期记忆容量限制使用对话压缩指令精简历史或拆分任务为不同会话这张表里最常出现的是第一条。尤其是初次使用时AI 很容易在改完目标文件后“顺手”调整其他相关文件它觉得这是一种优化但对项目来说这可能是破坏性操作。所以我现在养成了一个习惯每次让 AI 改代码前明确写出“只允许修改 src/handlers/orderHandler.js其他任何文件不要动”。这个限制写在 prompt 开头基本上 AI 就会老实很多。7.2 一些实用的小技巧还有一些零散的小技巧不一定能写进固定的教程里但实际用起来很顺第一个是让 AI 在修改前先自己执行一遍相关搜索。我用过“先搜索项目内所有引用该函数的地方列出列表后再修改”这种 prompt效果特别好。因为在这个过程中AI 生成的修改方案会自动把调用方一起考虑进去我在 review 时也能更清晰地看到影响范围。第二个是测试驱动的修改方式。让 AI 先为某个 bug 写一个失败用例再让它修代码使用例通过。这种方式看着略为绕路但对于需要严谨验证的场景非常合适既保证了修改有效性又保证了回归防护。第三个是利用对话压缩功能。AI 对话时间久了上下文占用会很高回答质量可能明显下降。遇到这种情况我会让它先压缩对话而不是直接开新会话。压缩之后AI 仍然记得项目背景和之前做过的关键决定回答质量会明显回升。最后的体会前面说的基本都是具体操作最后聊一点我对这类工具的整体感受。过去我对 AI 编程助手的态度一直比较谨慎总担心引入它会让代码质量变得更难把控。但 Claude Code 的权限确认机制、项目记忆文件、命令执行能力组合起来之后我的体验发生了改变。它更像一个执行力很强、但需要明确指令和边界感的协作伙伴你让它做什么、做到什么程度、允许触碰哪些文件它都会尽量执行好。负责兜底和决策的部分仍然压在真人身上只是那些重复性的读代码、写测试、查日志的过程被大幅压缩了。如果你准备在自己的项目里尝试我的建议是先从一个低风险模块起步把 CLAUDE.md 和权限确认流程跑通再逐步扩大使用范围。这样既能感受到效率提升也不至于让风险失控。另外分享一个小技巧给 AI 的任务别太省字。把背景、目标、边界条件、验收标准写清楚它的表现会有巨大提升。这和你带一个新人做任务是一个道理——你交代得越清楚对方就越少出意想不到的岔子。哪怕多写一两行字也比后面花十分钟排查它自作主张引入的问题要划算得多。