问题分类

调查报告的问题，找到其根本原因，并创建一个包含测试驱动开发修复计划的 GitHub 问题。这是一个尽量少交互的工作流程——尽量减少向用户提问。

流程

1. 捕获问题

从用户那里获取问题的简要描述。如果他们尚未提供，请只问一个问题：“您遇到的具体问题是什么？”

暂时不要追问更多问题。立即开始调查。

2. 探索和诊断

使用 Agent 工具，设置 subagent_type=Explore 来深入调查代码库。您的目标是找到：

• 哪里出现了 Bug（入口点、UI、API 响应）
• 涉及哪些代码路径（追踪流程）
• 为什么会失败（根本原因，而不仅仅是表象）
• 存在哪些相关代码（类似模式、测试、相邻模块）

查看：

• 相关的源文件及其依赖
• 现有的测试（测试了什么，缺少什么）
• 受影响文件的近期更改（相关文件上的 git log）
• 代码路径中的错误处理
• 代码库中其他位置能正常工作的类似模式

3. 确定修复方法

根据您的调查，确定：

• 修复根本原因所需的最小更改
• 受影响的模块/接口
• 需要通过测试验证哪些行为
• 这是回归问题、功能缺失还是设计缺陷

4. 设计测试驱动开发修复计划

创建一个具体、有序的红-绿循环列表。每个循环是一个垂直切片：

• 红：描述一个捕获了损坏/缺失行为的特定测试
• 绿：描述使该测试通过所需的最小代码更改

规则：

• 测试应通过公共接口验证行为，而非实现细节
• 一次一个测试，垂直切片（而不是先写所有测试，再写所有代码）
• 每个测试应能经受住内部重构
• 如有需要，包含最终的重构步骤
• 持久性：仅建议能经受住代码库剧变的修复。描述行为和契约，而非内部结构。测试断言的是可观察的结果（API 响应、UI 状态、用户可见效果），而非内部状态。好的建议读起来像规范；坏的建议读起来像差异对比。

5. 创建 GitHub 问题

使用 gh issue create 并按照以下模板创建 GitHub 问题。创建前无需让用户审阅——直接创建并分享 URL。

问题描述

清晰描述 Bug 或问题，包括：

• 发生了什么（实际行为）
• 应该发生什么（预期行为）
• 如何复现（如适用）

根本原因分析

描述您在调查中的发现：

• 涉及的代码路径
• 当前代码为何失败
• 任何促成因素

不要包含与当前代码布局耦合的具体文件路径、行号或实现细节。应描述模块、行为和契约。即使经过重大重构，该问题描述仍应保持有用。

测试驱动开发修复计划

一个编号的红-绿循环列表：

1. 红：编写一个测试，该测试[描述预期的行为]
   绿：[使其通过的最小更改]
2. 红：编写一个测试，该测试[描述下一个行为]
   绿：[使其通过的最小更改]

…

重构：[所有测试通过后所需的任何清理工作]

验收标准

• 标准 1
• 标准 2
• 所有新测试通过
• 现有测试仍然通过

创建问题后，打印问题 URL 和根本原因的一行摘要。