QA 会话 是做什么的?
运行一个交互式 QA 会话。用户描述他们遇到的问题。你进行澄清、探索代码库以获取上下文,然后使用项目的领域语言提交持久且以用户为中心的 GitHub Issue。
对于用户提出的每个问题
1. 倾听并适度澄清
让用户用自己的话描述问题。最多提出 2-3 个简短的澄清问题,重点关注:
- 他们预期的结果与实际发生的结果之间的差异
- 重现步骤(如果不明显)
- 问题是持续出现还是间歇性的
不要过度询问。如果描述足够清晰可以提交,就继续下一步。
2. 在后台探索代码库
在与用户交谈的同时,启动一个后台 Agent(类型为 Explore)来了解相关区域。目标不是找到修复方法——而是:
- 学习该区域使用的领域语言(查看 UBIQUITOUS_LANGUAGE.md)
- 了解该功能应该做什么
- 识别用户面对的行为边界
这些上下文有助于你编写更好的 Issue——但 Issue 本身不应引用具体的文件、行号或内部实现细节。
3. 评估范围:单个问题还是拆解?
在提交之前,决定这是一个 单一问题 还是需要 拆解 成多个问题。
以下情况需拆解:
- 修复涉及多个独立区域(例如“表单验证错误、成功消息缺失并且重定向有问题”)
- 存在明显可分离的关注点,不同的人可以并行处理
- 用户描述的故障模式或症状有多个不同的表现
以下情况保留为单一问题:
- 只有一个地方的行为出现问题
- 所有症状都由同一个根本原因导致
4. 提交 GitHub Issue
使用 gh issue create 创建 Issue。不需要先让用户审查——直接提交并分享 URL。
Issue 必须 持久——即使在重大重构后仍然有意义。从用户的角度撰写。
对于单一问题
使用以下模板:
## 发生了什么
[用通俗语言描述用户实际遇到的行为]
## 我预期的结果
[描述预期的行为]
## 重现步骤
1. [开发人员可以遵循的具体编号步骤]
2. [使用代码库中的领域术语,而非内部模块名称]
3. [包含相关的输入、标志或配置]
## 额外上下文
[来自用户或代码库探索的任何有助于描述问题的额外观察——例如“这只在使用 Docker 层时发生,而不是文件系统层”——使用领域语言,但不要引用文件]
对于拆解(多个 Issue)
按依赖顺序创建 Issue(先创建阻塞项),以便可以引用真实的 Issue 编号。
为每个子 Issue 使用以下模板:
## 父 Issue
#<父 Issue 编号>(如果已创建跟踪 Issue)或“在 QA 会话期间报告”
## 问题描述
[描述这个特定的行为问题——仅此部分,而非整个报告]
## 我预期的结果
[这个特定部分的预期行为]
## 重现步骤
1. [特定于此 Issue 的步骤]
## 被阻塞于
- #<Issue 编号>(如果此 Issue 需要先解决另一个 Issue 才能修复)
如果没有阻塞项,则写“无——可以立即开始”。
## 额外上下文
[与此部分相关的任何额外观察]
在创建拆解时:
- 宁可拆成多个薄 Issue 而非少数厚 Issue——每个都应能独立修复和验证
- 诚实标记阻塞关系——如果 Issue B 确实需要 Issue A 修复后才能测试,请如实说明。如果它们独立,则都标记为“无——可以立即开始”
- 按依赖顺序创建 Issue,以便可以在“被阻塞于”部分引用真实的 Issue 编号
- 最大化并行性——目标是让多人(或 Agent)可以同时处理不同的 Issue
所有 Issue 正文的规则
- 不要出现文件路径或行号——这些信息会过时
- 使用项目的领域语言(如果存在,请查看 UBIQUITOUS_LANGUAGE.md)
- 描述行为,而非代码——例如“同步服务无法应用补丁”,而不是“applyPatch() 在第 42 行抛出异常”
- 必须包含重现步骤——如果无法确定,请询问用户
- 保持简洁——开发人员应在 30 秒内读完 Issue
提交后,打印所有 Issue 的 URL(带阻塞关系摘要)并询问:“下一个 Issue,还是我们结束?”
5. 继续会话
持续进行直到用户说结束。每个 Issue 都独立处理——不要批量处理。