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跑完没有报错，说明类型定义基本正确。但我注意到类型定义文件里有一个接口用了any：
interface 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 |
| 格式问题 | 检查 diff | git diff --check |
| 依赖问题 | 检查依赖树和漏洞 | npm ls、npm audit |
| 并发问题 | 代码审查 + 压力测试 | 人工审查、ab、wrk |
| 边界问题 | 构造边界输入测试 | 手工测试、单元测试 |
| 资源问题 | 代码审查 + 监控 | 人工审查、lsof、jstack |
| 性能问题 | 性能测试 + profiling | ab、wrk、Chrome DevTools |
5.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 核心逻辑的深度检查项
对于涉及核心业务逻辑的代码，还要额外做以下检查：
- 并发场景：是否有共享资源竞争？是否需要加锁？
- 边界条件：空输入、超长输入、非法输入是否处理？
- 错误处理：异常是否被正确捕获和处理？错误信息是否足够定位问题？
- 资源管理：文件流、数据库连接、网络请求是否及时释放？
- 性能影响：是否有全表扫描、N+1 查询、大内存分配？
- 安全风险：是否有 SQL 注入、XSS、CSRF、敏感信息泄露？
- 日志输出：关键操作是否有日志？日志级别是否合理？
- 配置管理：新增的配置项是否有默认值？是否在文档中说明？
6.3 验收记录模板
我一般会用下面这个模板记录每次验收的结果，方便后续追溯和复盘。
## 验收记录 - 需求描述： - 生成工具：Claude Code - 改动范围：X 个文件，新增 X 行，删除 X 行 - 验收时间： ### 静态检查结果 - 类型检查：通过 / 失败（问题描述） - 风格检查：通过 / 失败（问题描述） - diff 检查：通过 / 失败（问题描述） - 依赖检查：通过 / 失败（问题描述） ### 功能验证结果 - 主流程：通过 / 失败（问题描述） - 异常路径：通过 / 失败（问题描述） - 边界条件：通过 / 失败（问题描述） ### 深度审查结果 - 并发问题： - 错误处理： - 类型定义： - 资源管理： - 性能影响： - 安全风险： ### 待修复问题 1. 2. 3. ### 验收结论 - [ ] 通过，可以提交 - [ ] 有条件通过，需修复上述问题后提交 - [ ] 不通过，需要重新生成或大幅修改这套清单和模板是我在实际项目中反复用过的，不敢说覆盖了所有场景，但至少能帮你把大部分常见问题挡在提交之前。验收这件事没有捷径，做得多了，自然就有感觉了。我现在的习惯是，不管需求多小，提交前至少把静态检查和主流程跑一遍，这两个步骤花不了多少时间，但能避免很多低级问题流到代码仓库里。
