问题排查
调查报告的问题,找到其根本原因,并创建一个包含TDD修复计划的GitHub Issue。这是一个基本无需干预的工作流——尽量减少向用户提问。
流程
1. 捕获问题
从用户那里获取问题的简要描述。如果他们还没有提供,请只问一个问题:“你看到了什么问题?”
暂不提问后续问题。立即开始调查。
2. 探索与诊断
使用Agent工具(subagent_type=Explore)深入调查代码库。你的目标是找到:
- Bug在哪里表现(入口点、UI、API响应)
- 涉及哪些代码路径(跟踪流程)
- 为什么失败(根本原因,而不仅仅是症状)
- 存在哪些相关代码(相似模式、测试、相邻模块)
查看:
- 相关的源文件及其依赖
- 现有的测试(测试了什么、缺少什么)
- 对受影响文件的最近更改(相关文件上的
git log) - 代码路径中的错误处理
- 代码库其他能正常工作的地方的相似模式
3. 确定修复方法
基于你的调查,确定:
- 修复根本原因所需的最小更改
- 哪些模块/接口受到影响
- 需要通过测试验证哪些行为
- 这是回归、缺失功能还是设计缺陷
4. 设计TDD修复计划
创建具体有序的RED-GREEN循环列表。每个循环是一个垂直切片:
- RED:描述一个捕捉破坏/缺失行为的特定测试
- GREEN:描述使该测试通过的最小代码更改
规则:
- 测试通过公共接口验证行为,而非实现细节
- 一次一个测试,垂直切片(非先所有测试,再所有代码)
- 每个测试应在内部重构后依然有效
- 如果需要,包含最终的重构步骤
- 持久性:仅建议能在重大代码库变更后依然成立的修复。描述行为和契约,而非内部结构。测试断言可观察到的结果(API响应、UI状态、用户可见的效果),而非内部状态。好的建议读起来像一份规范;差的建议读起来像一份差异。
5. 创建GitHub Issue
使用gh issue create并附带以下模板创建GitHub Issue。不要要求用户在创建前审查——直接创建并分享URL。
问题
对Bug或问题的清晰描述,包括:
- 实际发生了什么(实际行为)
- 应该发生什么(期望行为)
- 如何复现(如果适用)
根本原因分析
描述你在调查中发现的内容:
- 涉及的代码路径
- 当前代码为何失败
- 任何促成因素
不要包含特定的文件路径、行号或与当前代码布局耦合的实现细节。而是描述模块、行为和契约。即使在重大重构后,该Issue也应保持有用。
TDD修复计划
RED-GREEN循环的编号列表:
-
RED:编写测试 [描述期望的行为] GREEN:[使其通过的最小更改]
-
RED:编写测试 [描述下一个行为] GREEN:[使其通过的最小更改]
...
REFACTOR:[所有测试通过后需要的任何清理工作]
验收标准
- 标准1
- 标准2
- 所有新测试通过
- 现有测试仍然通过
创建Issue后,打印Issue URL和一行摘要说明根本原因。