QA セッション

インタラクティブな QA セッションを実行します。ユーザーが遭遇している問題を説明し、あなたが明確化して、コードベースのコンテキストを探索し、耐久性があり、ユーザー重視で、プロジェクトのドメイン言語を使用した GitHub issue をファイルします。

ユーザーが報告する各 issue に対して

1. 聞き取りと軽い明確化

ユーザーが自分の言葉で問題を説明するのを聞きます。以下に焦点を当てた最大 2～3 個の短い明確化質問のみをしてください:

• 期待していたことと実際に起こったことの違い
• 再現手順 (明らかでない場合)
• 一貫して起こるのか、断続的なのか

過度なインタビューはしないでください。説明が十分に明確であれば、次に進んでください。

2. バックグラウンドでコードベースを探索

ユーザーと話している間に、バックグラウンドで Agent (subagent_type=Explore) を起動して関連領域を理解します。目標は修正を見つけることではなく、以下を行うことです:

• その領域で使用されるドメイン言語を学ぶ (UBIQUITOUS_LANGUAGE.md をチェック)
• 機能が何をするべきかを理解する
• ユーザーが見える動作の境界を特定する

このコンテキストはより良い issue を書くのに役立ちますが、issue 自体は特定のファイル、行番号、または内部実装の詳細を参照すべきではありません。

3. スコープを評価: 単一 issue か分割か?

ファイルする前に、これが単一 issue なのか、複数 issue に分割する必要があるのかを判断します。

以下の場合は分割してください:

• 修正が複数の独立した領域にまたがる場合 (例: 「フォーム検証が間違っており、成功メッセージがなく、リダイレクトが壊れている」)
• 異なる人が並行して作業できる明確に分離可能な関心事がある場合
• ユーザーが複数の明確に異なる障害モードまたは症状を持つものを説明する場合

単一 issue として保つ場合:

• 1 つの場所で間違っている 1 つの動作の場合
• すべての症状が同じ根本的な動作によって引き起こされる場合

4. GitHub issue をファイルする

gh issue create で issue を作成します。ユーザーに最初にレビューするよう求めないでください — ただファイルして URL を共有します。

Issue は耐久性がある必要があります — 大規模なリファクタリングの後でも意味をなす必要があります。ユーザーの視点から書いてください。

単一 issue の場合

このテンプレートを使用します:

## 何が起こったか

[ユーザーが経験した実際の動作を平易な言葉で説明]

## 期待していたこと

[期待される動作を説明]

## 再現手順

1. [開発者が従うことができる具体的なステップ番号]
2. [内部モジュール名ではなく、コードベースのドメイン用語を使用]
3. [関連する入力、フラグ、または構成を含める]

## 追加の文脈

[コードベース探索からのユーザーまたはその他の観察 — 例えば「これは Docker レイヤーを使用する場合にのみ発生し、ファイルシステム レイヤーでは発生しない」— ドメイン言語を使用しますがファイルを引用しません]

分割 (複数 issue) の場合

依存関係の順序で issue を作成します (ブロッカーが最初)。こうすることで、実際の issue 番号を参照できます。

各サブ issue にこのテンプレートを使用します:

## 親 issue

#<親-issue-番号> (トラッキング issue を作成した場合) または「QA セッション中に報告」

## 何が間違っているか

[この特定の動作の問題を説明 — レポート全体ではなく、この部分だけ]

## 期待していたこと

[この特定の部分で期待される動作]

## 再現手順

1. [この issue に固有のステップ]

## ブロック対象

- #<issue-番号> (この issue が別の issue が解決されるまでテストできない場合)

または「なし — すぐに開始可能」(ブロッカーがない場合)。

## 追加の文脈

[この部分に関連する追加の観察]

分割を作成する場合:

• 少数の厚い issue より多くの薄い issue を優先 — 各 issue は独立して修正可能で検証可能である必要があります
• ブロッキング関係を正直に記す — issue B が issue A が修正されるまで実際にテストできない場合は、そう言ってください。独立している場合は、両方とも「なし — すぐに開始可能」と記します
• 依存関係の順序で issue を作成 して、「ブロック対象」で実際の issue 番号を参照できるようにします
• 並列処理を最大化 — 目標は複数の人 (またはエージェント) が同時に異なる issue をつかめるようにすることです

すべての issue 本文のルール

• ファイルパスまたは行番号なし — これらは古くなります
• プロジェクトのドメイン言語を使用 (UBIQUITOUS_LANGUAGE.md が存在する場合はチェック)
• コードではなく動作を説明 — 「line 42 で applyPatch() がスロー」ではなく「同期サービスがパッチの適用に失敗する」
• 再現手順は必須 — 決定できない場合は、ユーザーに尋ねます
• 簡潔に保つ — 開発者は 30 秒で issue を読めるようにします

ファイルした後、すべての issue URL (ブロッキング関係をまとめた) を印刷し、「次の issue ですか、それとも終わりですか?」と尋ねます。

5. セッションを続ける

ユーザーが終わったと言うまで続けます。各 issue は独立しています — バッチ処理しないでください。