| name | qa |
| description | 运行交互式 QA session:用户通过对话报告 bugs 或 issues,agent 随后创建 GitHub issues;同时在后台探索 codebase,获取上下文和 domain language。适用于用户希望报告 bugs、开展 QA、通过对话创建 issues,或提到“QA session”的场景。 |
QA Session
运行一场交互式 QA session。用户描述遇到的问题;你负责澄清、探索 codebase 以获取上下文,并创建经得住时间和重构、以用户为中心、使用项目 domain language 的 GitHub issues。
对用户提出的每个 issue
1. 倾听并进行少量澄清
让用户用自己的话描述问题。最多提出 2–3 个简短澄清问题,重点关注:
- 预期结果与实际结果
- 复现步骤(尚不清楚时)
- 问题稳定发生还是偶尔发生
不要过度访谈。现有描述已经足以创建 issue 时,直接继续。
2. 在后台探索 codebase
与用户对话的同时,在后台启动一个 Agent(subagent_type=Explore),理解相关区域。探索的目标是补足以下上下文:
- 学习该区域使用的 domain language(检查
UBIQUITOUS_LANGUAGE.md)
- 理解该功能原本应有的行为
- 找出用户可观察的 behavior boundary
这些上下文有助于写出更好的 issue;issue 正文中不得引用具体文件、行号或内部实现细节。
3. 评估范围:单个 issue 还是需要拆分?
创建前,判断当前问题应作为单个 issue,还是拆成多个 issues。
出现以下情况时拆分:
- 修复跨越多个互相独立的区域(例如“form validation 错误、success message 缺失、redirect 失效”)
- 存在可以由不同人员并行处理的独立关注点
- 用户描述了多种彼此独立的 failure modes 或 symptoms
出现以下情况时保留为单个 issue:
- 某处只有一个 behavior 出错
- 全部 symptoms 来自同一个根本 behavior
4. 创建 GitHub issue(s)
使用 gh issue create 创建 issues。无需先请用户审阅;直接创建并分享 URLs。
Issues 必须具有持久性,即使 codebase 经历大规模重构,内容仍然成立。使用用户视角进行描述。
单个 issue
使用以下模板:
## 发生了什么
[用直白语言描述用户实际遇到的行为]
## 预期行为
[描述期望发生的行为]
## 复现步骤
1. [开发者可以照着执行的具体编号步骤]
2. [使用 codebase 中的 domain terms,不要使用内部 module names]
3. [包含相关 inputs、flags 或 configuration]
## 补充上下文
[来自用户或 codebase 探索的额外观察,用于帮助界定问题。例如:“仅使用 Docker layer 时发生,filesystem layer 不会发生。”使用 domain language,不要引用文件]
拆分为多个 issues
按依赖顺序创建 issues(blockers 优先),以便引用真实 issue numbers。
每个 sub-issue 使用以下模板:
## Parent issue
#<parent-issue-number>(创建了 tracking issue 时)或“Reported during QA session”
## 问题
[描述这一项具体 behavior 问题,只写当前 slice,不要重述完整报告]
## 预期行为
[当前 slice 的期望行为]
## 复现步骤
1. [只与当前 issue 相关的步骤]
## Blocked by
- #<issue-number>(当前 issue 必须等待另一项解决时)
没有 blockers 时填写“None — can start immediately”。
## 补充上下文
[只与当前 slice 相关的额外观察]
拆分时:
- 优先创建多个薄 issue,少建厚 issue——每一项都应能够独立修复和验证
- 如实标记 blocking relationships——issue B 确实必须等到 issue A 修复后才能测试时,明确写出;相互独立时,两项都标记为 “None — can start immediately”
- 按依赖顺序创建 issues,确保 “Blocked by” 能够引用真实 issue numbers
- 尽量提高并行度——让多个人或 agents 可以同时领取不同 issues
所有 issue 正文都必须遵守的规则
- 不写文件路径和行号——它们会过时
- 使用项目的 domain language(存在
UBIQUITOUS_LANGUAGE.md 时先检查)
- 描述 behaviors,不描述 code——写“sync service 无法应用 patch”,不要写“
applyPatch() 在第 42 行抛错”
- 复现步骤不可缺少——无法确定时向用户询问
- 保持简洁——开发者应能在 30 秒内读完
创建后,输出所有 issue URLs,概述 blocking relationships,并询问:“下一个 issue,还是已经完成?”
5. 继续 session
持续进行,直到用户表示结束。每个 issue 独立处理,不要批量积压后再统一创建。