qa-team

QA チーム: マルチエージェントコードレビュー

専門エージェントのチームが、現在のブランチの変更を実際のインシデントパターンに照らして独立にレビューします。その調査結果は、収束分析を含む単一のレポートに統合されます。

エージェントの独立性は極めて重要です。 各エージェントは、自身のペルソナ定義、そのフォーカス領域に関連するインシデントパターン、および diff のみを受け取ります。エージェントには、他のエージェントの存在、そのコードネーム、実行中のエージェント数、または収束分析が実行されることを伝えてはなりません。これにより、調査結果が完全に独立していることが保証されます。

ワークフロー

ステップ 1: diff の収集

ベースブランチを決定します。ユーザーが $ARGUMENTS を指定した場合は、それをベースブランチとして使用します。それ以外の場合は、デフォルトで master とします。

実行ディレクトリをリポジトリの外に作成し（セッションのスクラッチパッドまたは mktemp -d —— 決してリポジトリ内には作成しないでください）、そこにコンテキストを収集します:

RUN_DIR="$(mktemp -d "${TMPDIR:-/tmp}/qa-team-XXXXXX")"
mkdir -p "$RUN_DIR/personas" "$RUN_DIR/claimed"
git diff <base>...HEAD --name-only > "$RUN_DIR/files.txt"
git log <base>...HEAD --oneline > "$RUN_DIR/commits.txt"
git diff <base>...HEAD > "$RUN_DIR/diff.patch"

実行ディレクトリには、ペルソナキュー、claim スクリプト、および生成された起動スクリプト（ステップ 3）が格納されます。diff はビルドスクリプトによって共有エージェントプロンプトに埋め込まれ、モデルを経由しません（その理由はステップ 3 を参照してください）。diff.patch はディスク上に保持してください —— ビルドスクリプトがそれを読み取り、レビュー時にサイズ超過の diff はそれにフォールバックします。

変更がない場合は、ユーザーに通知して停止します。

ステップ 2: 変更されたファイルの分類

変更されたファイルを分類して、どのエージェントが関連するかを判断します:

ファイルパターン	関連するエージェント
*.py (マイグレーション)	database、reliability、compatibility
*.py (Django ビュー/API)	security、reliability、performance、data-integrity
*.py (Celery タスク)	reliability、performance、data-integrity
*.rs (Rust サービス)	security、performance、compatibility、reliability
*.tsx、*.ts (フロントエンド)	frontend、security、performance、copy
*.sql、ClickHouse クエリ	database、performance、data-integrity
Helm チャート、ArgoCD、k8s	compatibility、reliability
requirements*.txt、pyproject.toml、package.json	security、compatibility
SDK/拡張機能コード	compatibility、frontend、security、copy
ユーザー向け文字列を含むあらゆるファイル	copy
GitHub Actions ワークフロー	security

常に少なくとも 4 つの専門エージェントを実行します。ファイル分類に基づいて関連するエージェントが 4 つ未満の場合は、最も広く適用可能なもの（reliability、security、performance、compatibility）を追加して、少なくとも 4 つの専門エージェントがアクティブになるようにします。

ファイル分類に関係なく、常に両方のジェネラリストエージェント（generalist-a および generalist-b）を起動します。これらはすべての変更をレビューします。

ステップ 3: レビューエージェントを起動する（キャッシュ対応プロトコル）

このプロトコルが必要な理由: すべてのエージェントリクエストには、大きな固定プレフィックス（システムプロンプト、ツール、プロジェクトコンテキスト、ユーザープロンプト）が含まれており、これがプロンプトキャッシュされるのはプロンプトがエージェント間でバイト単位で同一である場合のみです。プロンプトキャッシュは厳密なプレフィックスベースです。プロンプト内のどこか1文字でも異なると、プレフィックス全体（数万トークン）がすべてのエージェントによって満額で再取り込みされます。そこから4つのルールが導かれます。

1. すべてのエージェントが同一のプロンプトを、完全な diff を含めてバイト単位で受け取ります。 同一のプロンプト内の diff は共有キャッシュされたプレフィックスの一部であるため、後続のエージェントはファイル読み取りツールの結果に対して書き込み価格を再支払いするのではなく、キャッシュ読み取り価格でそれを取り込みます。
2. 起動スクリプトは同梱のビルドツールによって生成され、オーケストレーターが手入力することはありません。 scripts/build_launch_scripts.js がプロンプト（diff を含む）を JSON エンコードして2つの Workflow スクリプトファイルに書き出すため、diff がモデルの出力トークンとして渡されることはなく、2つのスクリプトのプロンプトが1バイトのずれで食い違うこともありません。
3. エージェントごとの差異（ペルソナ）はプロンプトではなくツールの結果を介して渡されます。 各エージェントの最初のアクションは、アトミックにペルソナを割り当てる claim スクリプトを実行することです。ツールの結果は共有プレフィックスの後に来るため、キャッシュを壊しません。完了したエージェントへのフォローアップメッセージとしてペルソナを渡してはいけません。終了したエージェントを再開すると、そのリクエストがゼロから再構築され、キャッシュを完全に逃します。
4. 起動をずらします。 最初のレビュアーは単独で起動します。そのペルソナの claim が claimed/ に現れることが、最初のリクエストが完了し共有プレフィックスがキャッシュされたというシグナルです。その後になって初めて、残りのレビュアーが並行して起動し、それを読み取ります。同時にコールド起動すると、すべてのエージェントがプレフィックスを読み取るのではなく書き込むことになります（実測: 2つのエージェントを同時に起動すると、それぞれが約42kトークン全体を書き込みました）。

重要 — エージェントの独立性: 各エージェントは完全に分離されて動作する必要があります。共有プロンプトまたはペルソナファイルのいずれにも、以下のいずれも含めてはいけません。

• 他のエージェントの名前、コードネーム、説明
• 起動されるエージェントの数
• 収束分析が実行されること
• 他のレビュアーが同じコードを見ていること
• レビュアーの「チーム」への言及

各エージェントは、自分が唯一のレビュアーであると信じます。これにより、完全に独立した発見が保証されます。（ディスク上のペルソナキューには必然的に他のペルソナが含まれますが、共有プロンプトがエージェントによる実行ディレクトリの検査を禁じているため、実際には独立性が保たれます。）

3a. ペルソナファイルを書き込む

選択したエージェントごとに1つのファイルを $RUN_DIR/personas/ に書き込み、claim の順序が決定的になるように数値プレフィックスを付けます（01-generalist-a.md、02-generalist-b.md、03-security.md、04-database.md、...）。ジェネラリストが最初に来るのは、彼らがすべてのレビューで実行されるためです。したがって、レビュアー1 — 共有キャッシュを温めるエージェント — は、diff がどのスペシャリストを選択するかに関係なく、常に同じペルソナになります。ペルソナファイルの数は、起動するレビュアーの数と一致しなければなりません。ビルドスクリプトはこのディレクトリから起動数を導出します。

各スペシャリスト（security、database、reliability、performance、frontend、compatibility、data-integrity、copy）について、ファイルには以下が含まれます。

Your assigned review focus: {FOCUS_AREA}

## Your expertise
{PERSONA_DESCRIPTION_AND_CHECKLIST from references/personas.md — this agent's section only}

## Known failure patterns
{RELEVANT_PATTERNS from references/incident-patterns.md — only patterns matching
this agent's focus area. Omit this entire section for the copy persona.}

常に両方のジェネラリストペルソナを含めます。ジェネラリスト A（新鮮な目を持つシニアエンジニア）:

Your assigned review focus: general correctness and safety

You are a senior software engineer reviewing this code change for the first time.
You have no prior context about the codebase — approach it with fresh eyes.

Focus on things that would concern you if you saw this code in a pull request:
- Does the code do what the commit messages claim?
- Are there obvious bugs, logic errors, or edge cases?
- Is error handling adequate? What happens when things fail?
- Are there race conditions or concurrency issues?
- Is the code readable and maintainable?
- Are there any "that looks wrong" moments?

Do NOT focus on style, formatting, or minor nits. Focus on correctness and safety.
This focus has no formal checklist — omit the Checklist Coverage section from your review.

ジェネラリスト B（敵対的テスター）:

Your assigned review focus: breakability

You are a QA engineer who tries to break things. Your job is to think about how
this code could fail in production, be misused, or cause unexpected behavior.

Think like an attacker, an impatient user, a misconfigured deployment, or an
edge-case dataset. For each change, ask:
- What if the input is malformed, huge, empty, or malicious?
- What if the external service is slow, down, or returns garbage?
- What if two requests hit this code at the same time?
- What if this runs against a database with millions of rows?
- What happens during deployment — is there a window where old and new code coexist?
- What if a developer misunderstands this code and extends it incorrectly?

Do NOT focus on style or readability. Focus on breakability.
This focus has no formal checklist — omit the Checklist Coverage section from your review.

3b. claim スクリプトをインストールし、起動スクリプトをビルドする

どちらもこのスキルの scripts/ ディレクトリにあります。claim スクリプトを run ディレクトリにコピーし、run ディレクトリの内容から 2 つの Workflow 起動スクリプトをビルドします:

SKILL_DIR="<this skill's base directory>"
cp "$SKILL_DIR/scripts/claim_persona.sh" "$RUN_DIR/"
node "$SKILL_DIR/scripts/build_launch_scripts.js" "$RUN_DIR"

claim_persona.sh は、呼び出し元ごとに次の未 claim のペルソナをアトミックに割り当てます（mv はアトミックなので、並行するエージェントはそれぞれ異なるペルソナを獲得します）。build_launch_scripts.js は、共有レビュープロンプト — claim 指示、変更されたファイル、コミットメッセージ、および完全な diff（diff が約 200 KB を超える場合はディスクから読み取る指示）— を JSON エンコードして $RUN_DIR/launch_first.js と $RUN_DIR/launch_rest.js に書き込み、ペルソナ数から並列ファンアウトのサイズを決定します。プロンプトのテキスト自体はビルドスクリプト内にあります。生成されたファイルを再入力したり編集したりしないでください。

3c. 2 段階で起動する

1. Workflow ツールを {scriptPath: "$RUN_DIR/launch_first.js"} で呼び出します。これはレビュアー 1 だけをバックグラウンドで起動します。

2. レビュアー 1 のペルソナ claim をポーリングします — これはその最初のリクエストが完了した（約 15 秒後）ことと、共有プレフィックス（diff を含む）がキャッシュされたことのシグナルです:

   timeout 120 bash -c 'until [ -n "$(ls -A '"$RUN_DIR"'/claimed)" ]; do sleep 1; done'
   

   最初のワークフロー実行が完了するのを待たないでください — レビュアー 1 は残りが起動している間もレビューを続けるため、この短いウォームアップ期間を除いてすべてのレビュアーが並行して実行されます。ポーリングがタイムアウトした場合は、まず launch_first の実行がエラーになったかどうかを確認し、その後続行して、実行がキャッシュなしで進んだことを最終レポートに記載してください — キャッシュミスはコストがかかるだけで正確性には影響しませんが、原因を特定できるようにしておくべきです。

3. Workflow ツールを {scriptPath: "$RUN_DIR/launch_rest.js"} で呼び出します。これは残りのレビュアーを並列で起動し、それぞれがレビュアー 1 が書き込んだキャッシュ済みプレフィックスを読み取ります。

4. 両方のワークフロー実行は、完了時に { reviews: [...] } を返します — ステップ 4 のために両方を収集します。失敗したレビュアーは明示的な REVIEWER FAILED: ... センチネルエントリとして現れ、レビューが黙って欠落することはありません。

5. 統合する前に照合してください: personas/ が空であり、収集されたレビューの数（センチネルを含む）がペルソナ数と一致していなければなりません。不一致の場合は、不完全なカバレッジを完全なレビューとして提示するのではなく、未 claim または未レビューのペルソナをレポートに記載してください — あるいは残りに対して単一のエージェントを再起動してください。（既知の制限: claim は冪等ではありません — claim を再実行したエージェントは 2 つ目のペルソナを消費し、後続のレビュアーを飢えさせます。この照合ステップがそれを検出します。）

レポートが書かれた後、ベストエフォートで run ディレクトリをクリーンアップします（rm -rf "$RUN_DIR"）— これには完全な diff がディスク上に含まれており、それ以上の用途はありません。

フォールバック: Workflow ツールが利用できない場合は、Agent ツールでエージェントを直接起動し、diff を埋め込む代わりに run ディレクトリのファイルを参照する単一の共有プロンプトを使用します（Read $RUN_DIR/diff.patch など — diff を N 回手入力するコストはキャッシュで節約できる分より高くつきます）。最初のエージェントを起動し、上記と同じ claimed/ のポーリングを実行してから、残りを 1 つのメッセージで並列に起動します。

Step 4: レポートを統合する

すべてのエージェントが完了したら、その調査結果を 1 つの統合レポートにまとめます。

4a. 収束分析

複数のエージェントが同じファイルや懸念事項を指摘したかどうかを確認します。収束した調査結果（2 つ以上のエージェントによって独立に特定されたもの）は信頼性が高く、要約で強調する必要があります。

4b. リスクスコアリング

総合リスクスコアを計算します:

• CRITICAL: いずれかのエージェントがリスクレベル CRITICAL を返した -> 総合 CRITICAL
• HIGH: 2 つ以上のエージェントがリスクレベル HIGH を返した、または 1 つの HIGH + 2 つの MEDIUM エージェント -> 総合 HIGH
• MEDIUM: 1 つのエージェントがリスクレベル HIGH を返した、または 3 つ以上のエージェントがリスクレベル MEDIUM を返した -> 総合 MEDIUM
• LOW: エージェントのリスクレベルが LOW/NONE のみ -> 総合 LOW

4c. 判定

全体的なリスクを判定にマッピングします:

• ✅ APPROVE — 全体的に LOW リスク、対応が必要な指摘なし
• 💬 APPROVE WITH NITS — MEDIUM リスク、マージを妨げない軽微な提案
• ⚠️ REQUEST CHANGES — HIGH リスク、マージ前に必要な具体的な修正
• 🚫 BLOCKED — CRITICAL リスク、ブロックすべきセキュリティ/データの問題を検出

4d. 最終レポートの形式

Write ツールを使用してリポジトリルートの QAREPORT.md にレポートを書き込み、 その後、判定と主要な指摘を簡潔にまとめてユーザーに提示します。

レポートは視覚的な構成のために絵文字を使用し、長い散文の段落は避ける MUST があります。 すべてを scannable に保ちます — 表、チェックリスト、短い箇条書きを使用してください。

# 🔍 QA Team Review Report

| Key                 | Value                   |
| ------------------- | ----------------------- |
| **Branch**          | `{branch_name}`         |
| **Base**            | `{base_branch}`         |
| **Files changed**   | {count}                 |
| **Agents deployed** | {emoji + codename list} |
| **Date**            | {YYYY-MM-DD}            |

---

## 📋 Summary

{2-4 bullet points: what was changed and why. No long paragraphs.}

### Key findings

- {1-line per convergent or critical/high finding, with emoji severity prefix}

---

## 🏁 Verdict

> {emoji} **{APPROVE / APPROVE WITH NITS / REQUEST CHANGES / BLOCKED}**

{1-2 sentences explaining the verdict. Reference the top blocking items if not approving.}

---

## 👥 Agent summaries

| Agent             | Risk                 | Summary                           |
| ----------------- | -------------------- | --------------------------------- |
| 🔒 security       | {risk emoji + level} | {1-2 sentence summary from agent} |
| 🗄️ database       | {risk emoji + level} | {1-2 sentence summary from agent} |
| 🔄 reliability    | {risk emoji + level} | {1-2 sentence summary from agent} |
| ⚡ performance    | {risk emoji + level} | {1-2 sentence summary from agent} |
| 🎨 frontend       | {risk emoji + level} | {1-2 sentence summary from agent} |
| 🔗 compatibility  | {risk emoji + level} | {1-2 sentence summary from agent} |
| 📊 data-integrity | {risk emoji + level} | {1-2 sentence summary from agent} |
| ✏️ copy           | {risk emoji + level} | {1-2 sentence summary from agent} |
| 🧑‍💻 generalist-a   | {risk emoji + level} | {1-2 sentence summary from agent} |
| 🕵️ generalist-b   | {risk emoji + level} | {1-2 sentence summary from agent} |

(Only include rows for agents that were deployed.)

**Note:** ✏️ copy findings are always non-blocking nits. 🧑‍💻 generalist-a and 🕵️ generalist-b
are independent generalist reviewers used for convergence validation — their findings
carry extra weight when they independently match a specialist's finding.

Risk emojis: 🔴 CRITICAL, 🟠 HIGH, 🟡 MEDIUM, 🟢 LOW, ⚪ NONE

---

## 📝 Findings

Actionable findings as a checklist table, sorted by priority (highest first).

Each row is a checklist item. The `Status` column starts as `⬜ Open`.
Use convergence markers when 2+ agents flagged the same issue.

| #   | Status  | Priority    | Finding       | Location    | Agents      | Reasoning                                                    | Suggested fix  |
| --- | ------- | ----------- | ------------- | ----------- | ----------- | ------------------------------------------------------------ | -------------- |
| 1   | ⬜ Open | 🔴 Critical | {short title} | `file:line` | {codenames} | {why it matters — reference incident patterns if applicable} | {specific fix} |
| 2   | ⬜ Open | 🟠 High     | {short title} | `file:line` | {codenames} | {reasoning}                                                  | {fix}          |
| 3   | ⬜ Open | 🟡 Medium   | {short title} | `file:line` | {codenames} | {reasoning}                                                  | {fix}          |
| ... | ...     | ...         | ...           | ...         | ...         | ...                                                          | ...            |
| N   | ⬜ Open | 🟢 Low      | {short title} | `file:line` | {codenames} | {reasoning}                                                  | {fix}          |

Priority mapping:

- 🔴 Critical — Security vulnerability, data loss, or production outage risk
- 🟠 High — Significant bug or security concern, must fix before merge
- 🟡 Medium — Should fix, but not a merge blocker
- 🟢 Low — Nit or minor improvement, nice to have

Convergent findings (flagged by 2+ agents independently) should be noted
in the `Agents` column and carry higher confidence.

参照ファイル

ペルソナ定義

• references/personas.md -- スペシャリストエージェント向けの完全なペルソナの説明、コンテキスト、レビューチェックリスト（ジェネラリストには使用されません — そのペルソナファイルはステップ 3a でインラインに定義されます）

インシデントパターン

• references/incident-patterns.md -- 本番インシデントから合成された障害パターン。スペシャリストエージェントのレビューを実際の障害モードに即して行うために使用されます（ジェネラリストには使用されません）