1. 一个需求做完之后我才意识到验收才是真正的深水区用 Claude Code 写代码这件事我算是比较早开始折腾的那批人。从最早在终端里敲claude命令到后来在 VS Code 里配好插件、调通中文启动器再到把常用开发工具的配置摸了个遍整个过程踩的坑不算少但真正让我停下来反思的不是某次 prompt 写崩了导致输出一塌糊涂也不是 TypeScript 类型报错满屏飘红而是一个看起来特别普通的需求做完之后我盯着git diff的输出发呆的那半个小时。那个需求本身不复杂给一个已有的 Vue Spring Boot 项目加一个数据导出功能前端加个按钮后端加个接口中间涉及 TypeScript 类型定义、接口参数校验、文件流处理这几块。我用 Claude Code 分了三轮对话把代码生成完每一轮的 prompt 都写得挺细把项目结构、技术栈、命名规范、错误处理要求都交代清楚了。生成出来的代码乍一看没什么问题TypeScript 编译通过接口能调通前端按钮点了也能下载文件。但当我准备提交的时候习惯性地跑了一下git diff --check发现了一堆行尾空格和几处缩进不一致再仔细看 diff 内容发现生成的代码里有一个隐藏的逻辑问题导出文件的文件名在并发请求下会互相覆盖。这个问题不是 prompt 能解决的。prompt 写得再好AI 生成代码时也不会主动帮你考虑并发场景下的文件名冲突它只会按照你描述的功能点去实现。而验收环节恰恰是发现这类问题的唯一机会。我后来跟几个同样在用 Claude Code 的朋友聊发现大家都有类似的感受写 prompt 的时候觉得自己已经把需求说得很清楚了生成代码的时候也觉得挺顺利但到了验收这一步才发现真正考验人的地方在这里。你得知道要看什么、怎么查、哪些地方容易出问题这些东西没有任何一个 prompt 能替你完成。这篇文章就是想把我在这个过程中积累的验收经验整理出来。不管你是刚接触 Claude Code 的新手还是已经用它写过不少代码的老手验收这一关都绕不过去。我会从验收的整体思路讲起然后拆解具体环节的操作要点再分享一些实际排查问题的技巧最后给出一套可以直接抄作业的验收清单。文章里涉及的技术栈主要是 TypeScript、Vue、Spring Boot 这一套但验收的思路是通用的换成其他语言和框架也一样适用。2. 验收思路的整体设计与拆解2.1 为什么验收比 prompt 更难写 prompt 的时候你面对的是一个相对确定的问题你知道自己要什么只需要把它描述清楚。哪怕描述得不够精确大不了多试几轮调整措辞补充上下文总能逼近你想要的结果。但验收面对的是一个已经生成出来的、看起来能跑的代码块你要做的是判断它到底对不对、好不好、能不能上生产。这个判断过程没有标准答案也没有即时反馈全靠你自己的经验和技术判断力。我总结下来验收之所以难主要有三个原因。第一是信息不对称AI 生成代码的速度太快了你还没来得及完全理解它写了什么它就已经把几百行代码铺在你面前了。你需要在短时间内消化这些代码的逻辑找出其中可能存在的问题这对注意力和技术功底都是考验。第二是盲区效应AI 生成代码时往往会遵循一些常见的模式这些模式在大多数情况下没问题但在特定场景下可能就是坑。比如前面提到的文件名冲突就是一个典型的盲区。第三是验收标准模糊什么叫“验收通过”编译通过算吗接口能调通算吗还是说要做完整的边界测试、并发测试、异常测试很多人在这一步没有明确的标准导致验收流于形式。2.2 验收的核心原则从“能跑”到“敢上”我把验收分成三个层次对应三种不同的标准。第一个层次是功能验收核心问题是“代码能不能实现需求描述的功能”。这个层次的验收相对简单跑一遍主流程看看输入输出是否符合预期就行。第二个层次是质量验收核心问题是“代码写得好不好”。这个层次要看代码风格是否统一、命名是否规范、有没有明显的坏味道、类型定义是否完整、错误处理是否到位。第三个层次是风险验收核心问题是“代码有没有可能出问题”。这个层次要考察边界条件、并发场景、异常输入、资源泄漏、安全漏洞等。很多人在用 Claude Code 的时候验收只停留在第一个层次觉得功能跑通了就完事了。但真正让你半夜被叫起来修 bug 的往往是第二和第三个层次的问题。我的建议是不管需求多小验收至少要做到第二个层次如果涉及核心业务逻辑或者对外接口第三个层次也不能省。2.3 验收流程的设计分阶段、有重点验收不是一次性动作而是一个分阶段的过程。我的做法是把它拆成四个阶段每个阶段有明确的重点和产出。第一个阶段是代码通读。在跑任何测试之前先把git diff的输出完整看一遍。这个阶段的目标是建立对代码的整体认知改了哪些文件、新增了哪些函数、修改了哪些逻辑、有没有引入新的依赖。通读的时候不要纠结细节重点看结构和流程。第二个阶段是静态检查。利用工具做自动化检查包括 TypeScript 编译、ESLint 检查、git diff --check检查行尾空格和冲突标记、依赖安全检查等。这个阶段的目标是用工具把明显的问题筛出来减少人工检查的负担。第三个阶段是功能验证。跑主流程验证功能是否符合需求。这个阶段要覆盖正常路径和常见的异常路径比如空输入、超长输入、非法参数等。第四个阶段是深度审查。针对核心逻辑做重点审查包括并发场景、边界条件、错误处理、日志输出、性能影响等。这个阶段最耗时但也最能发现真正有价值的问题。这四个阶段的顺序不是固定的可以根据需求复杂度调整。但不管怎么调代码通读和静态检查这两步不能省它们是后续验收的基础。3. 核心细节解析与实操要点3.1 代码通读怎么看 diff 才不遗漏关键信息git diff是验收的第一手材料但很多人看 diff 的方式不对。常见的问题是只看新增的行忽略删除和修改的行或者只看自己关心的文件跳过其他文件。这两种做法都容易漏掉问题。我的做法是分三步看 diff。第一步是看文件列表用git diff --stat先看哪些文件被改了、每个文件改了多少行。这一步能帮你快速判断改动的范围是否合理。比如你只让 AI 加一个导出功能结果它改了十几个文件那就要警惕了可能它顺手重构了一些不该动的东西。第二步是看结构性改动重点关注新增或删除的函数、类、接口定义。这些改动往往影响面比较大需要仔细审查。我一般会用git diff --function-context来看这个参数会把改动所在的完整函数上下文都显示出来比默认的 diff 输出更容易理解。第三步是逐行看细节重点关注条件判断、循环边界、错误处理、类型转换这几类容易出问题的地方。看的时候可以配合git diff --check来检查行尾空格和冲突标记这个命令的输出很简洁有问题的行会直接标出来。提示看 diff 的时候建议关掉编辑器的自动格式化功能否则你看到的 diff 可能和实际提交的内容不一致容易误判。3.2 静态检查用工具把低级问题挡在门外静态检查是验收中性价比最高的环节因为工具能帮你自动发现很多低级问题省下大量人工检查的时间。我常用的静态检查工具和命令有这么几个。TypeScript 项目首先要跑tsc --noEmit这个命令只做类型检查不生成输出文件速度比完整编译快很多。如果项目用的是 Vue还要跑vue-tsc --noEmit因为 Vue 单文件组件里的类型检查需要专门的工具支持。这两个命令能发现类型不匹配、属性不存在、参数个数不对等问题是 TypeScript 项目验收的必做项。代码风格检查用 ESLint跑eslint --ext .ts,.vue src就行。如果项目配置了 Prettier再跑一下prettier --check检查格式。这两个工具能发现命名不规范、缩进不一致、缺少分号、使用了被禁用的 API 等问题。虽然这些问题不影响功能但会影响代码的可维护性验收时不能放过。git diff --check这个命令容易被忽略但它能发现行尾空格、冲突标记、制表符和空格混用等问题。这些问题在代码合并时可能引发冲突或者在某些工具链下导致解析错误。我一般把它作为提交前的最后一道检查。依赖安全检查用npm audit或者yarn audit能发现依赖包中的已知漏洞。如果项目用了锁文件还要检查锁文件是否被意外修改因为锁文件的改动可能导致依赖版本不一致。检查项命令检查内容建议频率类型检查tsc --noEmit类型不匹配、属性不存在每次验收Vue 类型检查vue-tsc --noEmit单文件组件类型问题每次验收代码风格eslint --ext .ts,.vue src命名、缩进、API 使用每次验收格式检查prettier --check代码格式一致性每次验收diff 检查git diff --check行尾空格、冲突标记每次提交前依赖安全npm audit依赖包漏洞每周或发版前3.3 功能验证主流程和异常路径都要覆盖功能验证的核心是“跑一遍”但怎么跑有讲究。我的做法是先跑主流程再跑异常路径最后跑边界条件。主流程就是需求描述的正常使用场景。比如导出功能主流程就是打开页面、点击导出按钮、选择导出范围、等待文件生成、下载文件、打开文件检查内容。这个流程要完整走一遍每一步都要确认结果符合预期。跑主流程的时候要注意观察控制台输出和网络请求看看有没有报错或者警告。异常路径是主流程之外的可能情况。还是以导出功能为例异常路径包括没有选择导出范围就点导出、导出过程中取消操作、导出数据量特别大、导出过程中网络中断、后端接口返回错误等。这些场景不一定会发生但一旦发生代码的行为是否符合预期就是验收要确认的。边界条件是最容易出问题的地方。比如导出功能边界条件包括导出数据为空、导出数据只有一条、导出数据量达到系统上限、导出字段包含特殊字符、导出文件名包含非法字符等。这些场景在主流程中不会出现但实际使用中一定会遇到。注意功能验证不要只在自己的开发环境跑有条件的话要在测试环境或者类生产环境跑一遍。开发环境和生产环境的差异比如数据库版本、中间件配置、网络策略可能导致完全不同的行为。3.4 深度审查重点盯住容易出问题的几类代码深度审查是最考验技术功底的环节也是最容易发现高价值问题的环节。我一般会重点审查以下几类代码。并发相关的代码。AI 生成代码时很少主动考虑并发场景所以凡是涉及共享资源、文件操作、数据库写入、缓存更新的地方都要仔细检查。比如前面提到的文件名冲突就是并发场景下的典型问题。检查的时候要问自己如果两个请求同时到达这段代码的行为是什么有没有加锁锁的粒度是否合适有没有死锁风险错误处理相关的代码。AI 生成的错误处理往往比较粗糙要么是简单的 try-catch 包一切要么是直接抛出异常不做处理。审查的时候要看错误是否被正确捕获捕获后是否做了合理的处理错误信息是否足够定位问题有没有吞掉异常的情况有没有在 catch 块里做可能再次抛出异常的操作类型定义相关的代码。TypeScript 的类型系统很强大但 AI 生成的类型定义经常不够精确。审查的时候要看有没有用any绕过类型检查接口定义是否完整可选属性和必选属性是否合理泛型参数是否正确类型断言是否安全资源管理相关的代码。涉及文件流、数据库连接、网络请求的地方要检查资源是否正确释放。比如文件流有没有在 finally 块里关闭数据库连接有没有归还连接池网络请求有没有设置超时这些细节在功能测试中不一定暴露但在高负载下可能引发严重问题。4. 实操过程与核心环节实现4.1 验收前的准备工作在开始验收之前有几件事要先做好否则验收过程会很不顺畅。第一件事是确认代码状态。用git status确认当前工作区没有未提交的改动用git log --oneline -5看一下最近的提交记录确认你验收的是正确的代码版本。如果 AI 是在多个对话轮次中生成的代码还要确认这些改动是否都已经合并到当前分支。第二件事是准备好验收环境。包括安装好项目依赖npm install或yarn install、启动必要的后端服务、准备好测试数据、打开浏览器开发者工具。如果项目有自动化测试先跑一遍测试套件看看有没有现成的测试用例可以复用。第三件事是明确验收标准。在开始之前把这次验收要检查的点列一个清单包括功能点、质量要求、风险点。这个清单可以基于需求文档、代码改动范围、历史问题记录来制定。有了清单验收过程会更有针对性不容易遗漏。4.2 代码通读的实操记录我以那个导出功能为例记录一下代码通读的实际过程。首先跑git diff --stat输出显示改了 8 个文件新增 320 行删除 45 行。文件包括前端的一个 Vue 组件、一个 TypeScript 类型定义文件、一个 API 请求封装文件后端的一个 Controller、一个 Service、一个工具类、一个配置文件、一个测试文件。改动范围基本合理没有意外的文件被修改。然后跑git diff --function-context重点看新增的函数。前端新增了一个handleExport方法负责收集导出参数、调用 API、处理响应。后端新增了一个exportData方法负责查询数据、生成文件、返回文件流。工具类里新增了一个generateFileName方法负责生成导出文件名。看到generateFileName的时候我停下来仔细看了一下实现。代码是这样的function generateFileName(prefix: string): string { const timestamp Date.now(); return ${prefix}_${timestamp}.xlsx; }这个实现用时间戳来保证文件名唯一看起来没问题。但仔细一想如果两个请求在同一毫秒内到达生成的文件名就会相同。虽然这种情况概率很低但在高并发场景下是可能发生的。这就是一个典型的并发盲区。4.3 静态检查的实操记录静态检查我按顺序跑了几个命令记录如下。tsc --noEmit跑完没有报错说明类型定义基本正确。但我注意到类型定义文件里有一个接口用了anyinterface ExportParams { dateRange: [string, string]; fields: string[]; filter: any; }这个any虽然不影响编译但会让类型检查失去意义。我后来把它改成了具体的类型定义。eslint --ext .ts,.vue src跑完报了 3 个警告都是关于未使用的变量。这些变量是 AI 生成代码时留下的虽然不影响功能但应该清理掉。git diff --check跑完报了几处行尾空格集中在后端 Service 文件里。这些空格在代码合并时可能引发冲突需要清理。npm audit跑完报了一个中危漏洞是某个间接依赖的版本问题。这个漏洞不影响当前功能但发版前应该处理。4.4 功能验证的实操记录功能验证我按主流程、异常路径、边界条件的顺序跑了一遍。主流程跑下来基本正常但发现一个小问题导出文件的内容里日期字段的格式和页面上显示的不一致。页面上显示的是2024-01-15导出文件里是2024/01/15。这个问题不影响功能但会影响用户体验需要统一格式。异常路径测试中我发现当导出数据量为零时后端返回了一个空文件前端没有做任何提示。用户点击导出后下载了一个空文件不知道是操作失败还是数据为空。这个体验不好应该加一个提示。边界条件测试中我构造了一个包含特殊字符的导出字段发现导出的 Excel 文件在打开时提示格式错误。排查后发现是字段值里包含了 Excel 不支持的字符需要在导出前做转义处理。4.5 深度审查的实操记录深度审查我重点看了并发、错误处理、类型定义、资源管理这几块。并发方面除了前面提到的文件名冲突我还发现后端查询数据时没有做分页如果数据量特别大可能导致内存溢出。这个问题的修复方案是加一个导出上限超过上限时提示用户缩小导出范围。错误处理方面后端 Service 里的异常处理比较粗糙所有的异常都被包装成了一个通用的错误信息丢失了原始的错误细节。这会导致排查问题时缺少线索。我后来改成了按异常类型分别处理保留原始错误信息。类型定义方面除了前面提到的any我还发现前端 API 请求的响应类型定义不完整缺少了一些可选字段。这会导致 TypeScript 在某些场景下无法正确推断类型。资源管理方面后端生成文件时用了FileOutputStream但没有在 finally 块里关闭。虽然 Java 的垃圾回收最终会释放资源但在高并发场景下可能导致文件句柄耗尽。我后来改成了 try-with-resources 写法。5. 常见问题与排查技巧实录5.1 验收中遇到的典型问题在用 Claude Code 写代码并验收的过程中我遇到过不少典型问题这里整理几个有代表性的。问题一生成的代码能跑但不符合项目规范。AI 生成代码时会遵循通用的最佳实践但不一定符合你项目的特定规范。比如你项目里规定所有 API 请求都要经过统一的拦截器但 AI 生成的代码直接用了fetch。这类问题在功能测试中不会暴露但会在代码审查时被挑出来。问题二生成的代码有隐藏的逻辑错误。这类问题最危险因为代码看起来能跑主流程也正常但在特定场景下会出错。比如前面提到的文件名冲突、日期格式不一致、特殊字符未转义都属于这一类。问题三生成的代码引入了不必要的依赖。AI 有时候会为了实现一个简单的功能引入一个第三方库而这个库可能和项目现有的依赖冲突或者增加了打包体积。验收时要检查package.json的改动确认新增的依赖是否必要。问题四生成的代码修改了不该修改的文件。AI 在生成代码时可能会顺手重构一些它认为可以优化的地方这些改动可能超出你的需求范围引入不必要的风险。验收时要仔细看 diff确认所有改动都在预期范围内。问题五生成的代码缺少必要的注释和文档。AI 生成的代码往往注释很少对于复杂的逻辑缺少注释会增加后续维护的难度。验收时要检查关键逻辑是否有注释公共 API 是否有文档。5.2 排查技巧速查表问题类型排查方法常用命令/工具类型问题跑类型检查tsc --noEmit、vue-tsc --noEmit风格问题跑 lint 和 format 检查eslint、prettier --check格式问题检查 diffgit diff --check依赖问题检查依赖树和漏洞npm ls、npm audit并发问题代码审查 压力测试人工审查、ab、wrk边界问题构造边界输入测试手工测试、单元测试资源问题代码审查 监控人工审查、lsof、jstack性能问题性能测试 profilingab、wrk、Chrome DevTools5.3 独家避坑技巧技巧一让 AI 自己写验收清单。在生成代码之后可以再给 AI 一个 prompt让它根据需求描述和生成的代码列出一份验收清单。这个清单不一定完整但可以作为你验收的起点帮你发现一些容易忽略的点。技巧二用git diff的--word-diff模式看细节改动。默认的 diff 是按行显示的对于只改了几个字符的行看起来不够直观。用git diff --word-diff可以按词显示改动更容易发现细微的变化。技巧三验收时开两个窗口一个看代码一个跑测试。这样可以边看代码边验证发现问题可以立即确认不用来回切换。技巧四把验收中发现的问题记录下来形成自己的检查清单。每次验收后把发现的问题和排查方法记录下来下次验收时对照检查。积累一段时间后你会有一套自己的验收方法论。技巧五对于核心逻辑让 AI 生成单元测试。AI 生成单元测试的能力还不错可以让它针对核心逻辑生成测试用例然后你审查这些用例是否覆盖了关键场景。这比手工测试效率高很多。提示验收过程中发现的问题不要直接让 AI 重新生成整个代码块而是针对具体问题让 AI 修改。重新生成可能引入新的问题而且会让你之前的验收工作白费。6. 一套可以直接抄作业的验收清单6.1 提交前的必做检查每次用 Claude Code 生成代码后提交前至少要做以下检查跑git diff --stat确认改动范围合理跑git diff --check确认没有行尾空格和冲突标记跑tsc --noEmit或vue-tsc --noEmit确认类型检查通过跑eslint和prettier --check确认代码风格一致跑npm audit确认没有新增的高危漏洞通读一遍 diff确认所有改动都在预期范围内跑一遍主流程确认功能正常检查关键逻辑是否有注释公共 API 是否有文档6.2 核心逻辑的深度检查项对于涉及核心业务逻辑的代码还要额外做以下检查并发场景是否有共享资源竞争是否需要加锁边界条件空输入、超长输入、非法输入是否处理错误处理异常是否被正确捕获和处理错误信息是否足够定位问题资源管理文件流、数据库连接、网络请求是否及时释放性能影响是否有全表扫描、N1 查询、大内存分配安全风险是否有 SQL 注入、XSS、CSRF、敏感信息泄露日志输出关键操作是否有日志日志级别是否合理配置管理新增的配置项是否有默认值是否在文档中说明6.3 验收记录模板我一般会用下面这个模板记录每次验收的结果方便后续追溯和复盘。## 验收记录 - 需求描述 - 生成工具Claude Code - 改动范围X 个文件新增 X 行删除 X 行 - 验收时间 ### 静态检查结果 - 类型检查通过 / 失败问题描述 - 风格检查通过 / 失败问题描述 - diff 检查通过 / 失败问题描述 - 依赖检查通过 / 失败问题描述 ### 功能验证结果 - 主流程通过 / 失败问题描述 - 异常路径通过 / 失败问题描述 - 边界条件通过 / 失败问题描述 ### 深度审查结果 - 并发问题 - 错误处理 - 类型定义 - 资源管理 - 性能影响 - 安全风险 ### 待修复问题 1. 2. 3. ### 验收结论 - [ ] 通过可以提交 - [ ] 有条件通过需修复上述问题后提交 - [ ] 不通过需要重新生成或大幅修改这套清单和模板是我在实际项目中反复用过的不敢说覆盖了所有场景但至少能帮你把大部分常见问题挡在提交之前。验收这件事没有捷径做得多了自然就有感觉了。我现在的习惯是不管需求多小提交前至少把静态检查和主流程跑一遍这两个步骤花不了多少时间但能避免很多低级问题流到代码仓库里。