qa

QA セッション

対話形式の QA セッションを実施します。ユーザーが遭遇している問題について説明します。確認のために質問し、コードベースを調べて状況を把握し、長期にわたって通用し、ユーザー視点に立ち、プロジェクトのドメイン用語を使った GitHub イシューを作成します。

ユーザーが問題を提起するたびに

1. 話を聞き、必要に応じて簡単に確認する

まずはユーザー自身の言葉で問題を説明してもらいます。次の点に絞って、短い確認質問を最大 2～3 個します。

• 期待していたことと、実際に起きたこと
• 再現手順（明らかでない場合）
• 常に起きるのか、ときどき起きるのか

質問しすぎないでください。イシューを作成できる程度に説明が明確なら、そのまま次に進みます。

2. 背景でコードベースを調べる

ユーザーと話している間に、関連する領域を把握するため、バックグラウンドで Agent（subagent_type=Explore）を起動します。目的は修正方法を見つけることではなく、次の点を把握することです。

• その領域で使われているドメイン用語（UBIQUITOUS_LANGUAGE.md を確認する）
• その機能が本来どのように動作するか
• ユーザーが実際に体験する動作の境界

この情報を使って、より良いイシューを作成します。ただし、イシュー本文では特定のファイル、行番号、内部実装の詳細に言及しないでください。

3. 範囲を判断する：単一のイシューか、分割が必要か？

作成前に、これは単一のイシューでよいか、複数のイシューに分割する必要があるかを判断します。

次の場合は分割します。

• 修正が複数の独立した領域にまたがる（例：「フォームの検証が誤っている」「成功メッセージが表示されない」「リダイレクトが機能しない」）
• 明確に切り分けられる懸念事項があり、それぞれを別の人が並行して作業できる
• ユーザーが、複数の異なる障害モードや症状を説明している

次の場合は単一のイシューにまとめます。

• 1 か所の 1 つの動作が誤っている
• すべての症状が同じ根本的な動作に起因する

4. GitHub イシューを作成する

gh issue create を使ってイシューを作成します。ユーザーに事前確認を求めず、そのまま作成して URL を共有してください。

イシューは長期にわたって通用するものにします。大規模なリファクタリングの後でも内容が通じるように、ユーザーの視点から記述してください。

単一のイシューの場合

次のテンプレートを使います。

## 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]

## 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]

分割する場合（複数のイシュー）

ブロッカーを先にして、依存関係の順にイシューを作成し、実際のイシュー番号を参照できるようにします。

各サブイシューには次のテンプレートを使います。

## Parent issue

#<parent-issue-number> (if you created a tracking issue) or "Reported during QA session"

## 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]

## Blocked by

- #<issue-number> (if this issue can't be fixed until another is resolved)

Or "None — can start immediately" if no blockers.

## Additional context

[Any extra observations relevant to this slice]

分割して作成する場合：

• 少数の大きなイシューより、数多くの小さなイシューを優先する — それぞれを独立して修正・検証できるようにします
• ブロック関係を正確に示す — イシュー B がイシュー A の修正までテストできない場合は、その旨を記載します。独立している場合は、両方に「なし — すぐに着手可能」と記載します
• 依存関係の順にイシューを作成する — 「ブロックされているイシュー」に実際のイシュー番号を記載できるようにします
• 並行作業を最大限にする — 複数の人やエージェントが、それぞれ異なるイシューに同時に取り組めることを目指します

すべてのイシュー本文に適用するルール

• ファイルパスや行番号は記載しない — いずれ古くなるためです
• プロジェクトのドメイン用語を使う（UBIQUITOUS_LANGUAGE.md がある場合は確認する）
• コードではなく動作を説明する — 「同期サービスがパッチの適用に失敗する」と記述し、「applyPatch() が 42 行目で例外をスローする」とは記述しません
• 再現手順は必須 — 特定できない場合は、ユーザーに質問します
• 簡潔にする — 開発者が 30 秒で読める内容にします

作成後、すべてのイシュー URL を表示し（ブロック関係の要約も添えて）、次のように尋ねます。「次のイシューに進みますか？それとも、これで終了しますか？」

5. セッションを続ける

ユーザーが終了を伝えるまで続けます。各イシューは個別に扱い、まとめて処理しないでください。