Back to Details

qa

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

QA Session

QA会话

Run an interactive QA session. The user describes problems they're encountering. You clarify, explore the codebase for context, and file GitHub issues that are durable, user-focused, and use the project's domain language.
运行交互式QA会话。用户描述遇到的问题，你负责澄清问题、探查代码库以获取上下文，并创建持久化、以用户为中心且符合项目领域术语的GitHub Issue。

For each issue the user raises

针对用户提出的每个问题

1. Listen and lightly clarify

1. 倾听并适度澄清

Let the user describe the problem in their own words. Ask at most 2-3 short clarifying questions focused on:
  • What they expected vs what actually happened
  • Steps to reproduce (if not obvious)
  • Whether it's consistent or intermittent
Do NOT over-interview. If the description is clear enough to file, move on.
让用户用自己的语言描述问题。最多提出2-3个简短的澄清问题，重点关注：
  • 预期结果与实际发生情况的差异
  • 重现步骤（如果不明确）
  • 问题是持续出现还是间歇性的
不要过度追问。如果描述足够清晰可以创建Issue，就直接进入下一步。

2. Explore the codebase in the background

2. 在后台探查代码库

While talking to the user, kick off an Agent (subagent_type=Explore) in the background to understand the relevant area. The goal is NOT to find a fix — it's to:
  • Learn the domain language used in that area (check UBIQUITOUS_LANGUAGE.md)
  • Understand what the feature is supposed to do
  • Identify the user-facing behavior boundary
This context helps you write a better issue — but the issue itself should NOT reference specific files, line numbers, or internal implementation details.
与用户交流的同时，启动一个Agent（subagent_type=Explore）在后台运行，以理解相关代码区域。目标不是寻找修复方案，而是：
  • 学习该区域使用的领域术语（可查看UBIQUITOUS_LANGUAGE.md）
  • 理解功能的预期用途
  • 明确用户可见的行为边界
这些上下文有助于你撰写更优质的Issue，但Issue本身不应引用具体文件、行号或内部实现细节。

3. Assess scope: single issue or breakdown?

3. 评估范围：单个问题还是拆分问题？

Before filing, decide whether this is a single issue or needs to be broken down into multiple issues.
Break down when:
  • The fix spans multiple independent areas (e.g. "the form validation is wrong AND the success message is missing AND the redirect is broken")
  • There are clearly separable concerns that different people could work on in parallel
  • The user describes something that has multiple distinct failure modes or symptoms
Keep as a single issue when:
  • It's one behavior that's wrong in one place
  • The symptoms are all caused by the same root behavior
创建Issue之前，判断这是一个单个问题还是需要拆分为多个问题。
在以下情况进行拆分：
  • 修复工作涉及多个独立领域（例如：“表单验证错误、成功消息缺失且重定向失效”）
  • 存在明显可分离的关注点，不同人员可并行处理
  • 用户描述的问题包含多种不同的故障模式或症状
在以下情况保留为单个问题：
  • 仅一处行为出现错误
  • 所有症状均由同一根源行为导致

4. File the GitHub issue(s)

4. 创建GitHub Issue(s)

Create issues with 
gh issue create
. Do NOT ask the user to review first — just file and share URLs.
Issues must be durable — they should still make sense after major refactors. Write from the user's perspective.
使用
gh issue create
命令创建Issue。无需先请求用户审核——直接创建并分享URL即可。
Issue必须具备持久化特性——即使经过重大重构，仍应清晰易懂。从用户视角撰写内容。

For a single issue

单个问题的情况

Use this template:
undefined
使用以下模板：
undefined

What happened

问题现象

[Describe the actual behavior the user experienced, in plain language]
[用平实语言描述用户遇到的实际行为]

What I expected

预期结果

[Describe the expected behavior]
[描述预期的行为]

Steps to reproduce

重现步骤

  1. [Concrete, numbered steps a developer can follow]
  2. [Use domain terms from the codebase, not internal module names]
  3. [Include relevant inputs, flags, or configuration]
  1. [开发者可遵循的具体、编号步骤]
  2. [使用代码库中的领域术语，而非内部模块名称]
  3. [包含相关输入、标志或配置]

Additional context

额外上下文

[Any extra observations from the user or from codebase exploration that help frame the issue — e.g. "this only happens when using the Docker layer, not the filesystem layer" — use domain language but don't cite files]
undefined
[来自用户或代码库探查的额外观察信息，帮助理解问题——例如：“仅在使用Docker层时出现，文件系统层无此问题”——使用领域术语，但不要引用文件]
undefined

For a breakdown (multiple issues)

拆分问题的情况

Create issues in dependency order (blockers first) so you can reference real issue numbers.
Use this template for each sub-issue:
undefined
按照依赖顺序创建Issue（先创建阻塞性问题），以便在后续Issue中引用真实的Issue编号。
每个子问题使用以下模板：
undefined

Parent issue

父级Issue

#<parent-issue-number> (if you created a tracking issue) or "Reported during QA session"
#<父级Issue编号>（如果创建了跟踪Issue）或“QA会话期间报告”

What's wrong

问题内容

[Describe this specific behavior problem — just this slice, not the whole report]
[描述该具体行为问题——仅针对此部分，而非整个报告]

What I expected

预期结果

[Expected behavior for this specific slice]
[针对此部分的预期行为]

Steps to reproduce

重现步骤

  1. [Steps specific to THIS issue]
  1. [针对此Issue的具体步骤]

Blocked by

依赖阻塞

  • #<issue-number> (if this issue can't be fixed until another is resolved)
Or "None — can start immediately" if no blockers.
  • #<Issue编号>（如果此问题需等待其他问题修复后才能解决）
若无阻塞，填写“无——可立即开始处理”

Additional context

额外上下文

[Any extra observations relevant to this slice]

When creating a breakdown:

- **Prefer many thin issues over few thick ones** — each should be independently fixable and verifiable
- **Mark blocking relationships honestly** — if issue B genuinely can't be tested until issue A is fixed, say so. If they're independent, mark both as "None — can start immediately"
- **Create issues in dependency order** so you can reference real issue numbers in "Blocked by"
- **Maximize parallelism** — the goal is that multiple people (or agents) can grab different issues simultaneously
[与该部分相关的额外观察信息]

拆分问题时需注意：

- **宁多勿少**——每个Issue应可独立修复和验证
- **如实标记依赖关系**——如果Issue B确实需在Issue A修复后才能测试，如实标注。若两者独立，则均标记为“无——可立即开始处理”
- **按依赖顺序创建Issue**——以便在“依赖阻塞”部分引用真实的Issue编号
- **最大化并行性**——目标是让多个人（或Agent）可同时处理不同的Issue

Rules for all issue bodies

所有Issue内容的规则

  • No file paths or line numbers — these go stale
  • Use the project's domain language (check UBIQUITOUS_LANGUAGE.md if it exists)
  • Describe behaviors, not code — "the sync service fails to apply the patch" not "applyPatch() throws on line 42"
  • Reproduction steps are mandatory — if you can't determine them, ask the user
  • Keep it concise — a developer should be able to read the issue in 30 seconds
After filing, print all issue URLs (with blocking relationships summarized) and ask: "Next issue, or are we done?"
  • 不包含文件路径或行号——这些信息会过时
  • 使用项目的领域术语（若存在UBIQUITOUS_LANGUAGE.md可参考）
  • 描述行为而非代码——例如：“同步服务无法应用补丁”而非“applyPatch()在第42行抛出异常”
  • 重现步骤为必填项——若无法确定，询问用户
  • 保持简洁——开发者应能在30秒内读完Issue
创建完成后，打印所有Issue的URL（并总结依赖关系），然后询问：“下一个问题，还是结束会话？”

5. Continue the session

5. 继续会话

Keep going until the user says they're done. Each issue is independent — don't batch them.
持续进行直到用户表示结束。每个问题独立处理——不要批量处理。