qa

QA セッション

対話形式の QA セッションを実施します。ユーザーが直面している問題を説明します。内容を明確にし、コードベースを調べて背景を把握し、長く役立ち、ユーザー中心で、プロジェクトのドメイン用語を使った GitHub の Issue を作成します。

ユーザーが問題を報告するたびに

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

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

• 期待した動作と実際に起きた動作
• 再現手順（明らかでない場合）
• 毎回起きるのか、断続的に起きるのか

質問を重ねすぎないでください。Issue を作成するのに十分な説明があれば、次に進みます。

2. バックグラウンドでコードベースを調べる

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

• その領域で使われているドメイン用語（GLOSSARY.md を確認）
• その機能がどのように動作する想定なのか
• ユーザーから見える動作の境界

この背景情報はより適切な Issue の作成に役立ちますが、Issue 自体には特定のファイル、行番号、内部実装の詳細を記載しないでください。

3. 対応範囲を判断する：単一の Issue か、分割が必要か

作成前に、これは単一の Issueで対応するものか、複数の Issue に分割する必要があるかを判断します。

次の場合は分割します。

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

次の場合は単一の Issue にまとめます。

• 1 つの箇所で 1 つの動作に問題がある
• すべての症状が同じ根本的な動作に起因している

4. GitHub の Issue を作成する

gh issue create を使って Issue を作成します。ユーザーに事前確認を求めず、そのまま作成して URL を共有します。

Issue は長く役立つ内容にしてください。大規模なリファクタリング後も意味が通じるようにし、ユーザーの視点から記述します。

単一の Issue の場合

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

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

分割する場合（複数の Issue）

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

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

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

分割する場合：

• 少数の大きな Issue より、個別に対応できる小さな Issue を優先する — それぞれ単独で修正と検証ができるようにします
• ブロック関係を正確に示す — Issue B の検証に Issue A の修正が本当に必要なら、その旨を記載します。互いに独立している場合は、どちらも「なし — すぐに着手可能」とします
• 依存関係の順に Issue を作成する — 「Blocked by」に実際の Issue 番号を記載できるようにします
• 並行作業を最大化する — 複数の担当者やエージェントがそれぞれ異なる Issue に同時に取り組めるようにします

すべての Issue 本文に適用するルール

• ファイルパスや行番号は記載しない — すぐに古くなります
• プロジェクトのドメイン用語を使う（GLOSSARY.md があれば確認）
• コードではなく動作を説明する — 「パッチを適用できない」ではなく「同期サービスがパッチを適用できない」
• 再現手順は必須 — 特定できない場合はユーザーに尋ねます
• 簡潔にまとめる — 開発者が 30 秒で読める内容にします

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

5. セッションを続ける

ユーザーが終了すると言うまで続けます。各 Issue は独立して扱い、まとめて処理しないでください。