18.5 代码审查与端到端测试

面向经管学生、研究者与从业者的 AI 智能体设计教材

代码审查与端到端测试

代码写完不等于做完。开发阶段的子代理通过了双阶段审查，但整个系统能否从头到尾跑通，还需要完整验证。verification-before-completion Skill 的核心原则只有一条：没有验证证据，不能声称完成。以下五个维度构成验收标准：

维度	验证内容	通过标准
单元测试	npm test 或 pytest	全部通过，无跳过
类型检查	npx tsc --noEmit	零错误
数据导入	导入样例 PDF/Excel	索引成功，记录数匹配
检索问答	发送测试查询	返回相关结果
前端渲染	浏览器访问首页	无控制台报错

前两项是静态检查，后三项是功能验证。五项全部通过，项目才算可交付。

当所有开发任务结束后，先做代码审查，再触发验证。

代码审查

验证之前，用 requesting-code-review 做一轮整体代码审查。审查基于 plan 文件和 git diff，按 Critical / Important / Minor 三级分类问题：

▶ Claude Code

所有模块开发完了，先做一轮代码审查。/requesting-code-review

审查子代理会对照计划文件逐条检查变更范围，确认没有遗漏或多余的改动。Critical 级别问题必须修复后才能进入验证；Minor 级别可以标记为后续优化。

审查通过后，启动完整验证：

▶ Claude Code

代码审查通过了，帮我做一轮完整验证。/verification-before-completion

Claude Code 依次执行清单中每一项，汇报通过或失败状态。任何一项未通过，流程就不能结束。

端到端测试

后端 API 通过了不代表用户能正常使用。前端渲染、交互逻辑、网络请求都可能出问题。Claude Code 通过 Playwright MCP 打开真实浏览器，模拟用户操作流程：

▶ Claude Code

用浏览器打开 http://localhost:3000，测试以下流程：
1. 在搜索框输入"宁德时代产能"，检查返回结果
2. 点击筛选按钮，选择"研报"类型
3. 点击任意结果，查看详情页
发现问题直接修复。

Playwright 逐步执行操作，检查页面状态和控制台日志。遇到 JavaScript 错误或网络请求失败（4xx/5xx），自动记录并定位原因。测试截图保存在项目目录中，供人工复核。

调试链条

端到端测试发现问题后，需要一套系统化的排查流程。systematic-debugging 提供四阶段根因调查：根因定位 → 模式分析 → 假设验证 → 修复实施。核心铁律：未找到根因不得提出修复方案。

以一个常见场景为例：Playwright 测试发现搜索结果为空，但后端 API 单元测试全部通过。

▶ Claude Code

搜索功能不返回结果，但单元测试是通过的。帮我排查问题出在哪里。/systematic-debugging

Claude Code 按 systematic-debugging 流程逐步排查：

1. 复现：直接调用 /api/search?q=宁德时代，确认 API 返回空数组
2. 假设：API 本身正常但索引为空——检查向量数据库中的文档数量
3. 定位：发现文档解析模块将 .xlsx 文件当作 .csv 处理，解析失败但没有报错
4. 修复：修正文件类型判断逻辑，重新导入文档
5. 回归：重新运行完整验证清单，确认搜索返回预期结果

每轮修复后都要跑完整验证——不能只验证出问题的那一项，因为修 A 可能影响 B。

常见验证陷阱

两种做法会让验证形同虚设：

• 只跑部分测试：跳过慢测试或”不相关”的测试，遗漏的往往就是出问题的那个
• 看到绿色就以为通过：命令执行了不代表测试通过了，必须确认输出中没有 FAIL 或 ERROR

verification-before-completion 要求每次验证都提供完整的命令输出作为证据。

验证全部通过后，项目的交付物自然形成，不需要事后补写：

• 可运行的 Web 应用：金融知识库，支持入库、检索、生成
• 设计文档：brainstorming 阶段的产出
• 实施计划：writing-plans 阶段的产出
• 测试报告：test-driven-development + verification 阶段的产出
• Git 提交历史：每个任务一次原子提交，变更可追溯

按流程推进时，文档和代码自然同步产出。设计文档在需求阶段就已生成，测试报告在验证阶段自动产出——交付时只需确认清单，不需要额外整理。