ce-dogfood-beta

Dogfood（ベータ）

QA エンジニアとして、アクティブなブランチをエンドツーエンドで実地検証します。すべての変更を把握し、実際のユーザーと同じように実ブラウザーで各変更をテストし、問題があれば自律的に修正して、ブランチが本当にリリース可能な状態になるまで続けます。

これは差分の範囲に限定した検証であり、アプリ全体の探索ではありません。main と比較して、このブランチで追加または変更されたものをテストします。（アプリ全体の探索的 QA には、代わりに dogfood スキルを使用してください。）

ブラウザー自動化には agent-browser のみを使用する

このワークフローでは、agent-browser CLI のみを使用してブラウザーを操作します。Chrome MCP ツール（mcp__claude-in-chrome__*）、ブラウザー MCP 統合、その他の組み込みブラウザー制御ツールは使用しないでください。プラットフォームにブラウザーを操作する方法が複数ある場合は、必ず agent-browser を選択してください。直接バイナリーを使用し、npx agent-browser は使用しないでください（直接バイナリーは高速な Rust クライアントを使用します）。

前提条件

• 起動可能なローカル開発サーバー（bin/dev、rails server、npm run dev など）。

• agent-browser がインストール済みであること。次のコマンドで確認します。

  command -v agent-browser >/dev/null 2>&1 && echo "Ready" || echo "NOT INSTALLED"
  

  インストールされていない場合は、ce-setup スキルを実行して最新のインストールコマンドを確認し、agent-browser をインストールしてから再開してください。インストールせずに続行しないでください。

Compound-Engineering スキルの再利用

ce-dogfood-beta はオーケストレーターです。動作を独自に再構築するより、既存の CE スキルに委任することを優先してください。

条件	スキル	理由
フェーズ 0 の分離	ce-worktree	メインのチェックアウトをクリーンな状態に保つため、隔離されたワークツリーで dogfood を実行します。
agent-browser がない	ce-setup	最新の agent-browser インストールコマンドを提示します。
失敗の根本原因が明確でない	ce-debug	当てずっぽうで試すのではなく、体系的に根本原因を分析します。
各修正のコミット	ce-commit	一貫性があり、適切な範囲に絞ったコミットメッセージを作成します。
バグから再利用可能な教訓が得られた	ce-compound	チームの知識を蓄積できるよう、学びを記録します。

ce-test-browser のポート検出と開発サーバー起動の仕組みを再利用し、独自に作り直さないでください（フェーズ 3 を参照）。

ワークフロー

0. Scope        Pick the branch, get onto it (offer worktree), never touch main
1. Analyze      Diff branch vs main, understand every change
2. Map+Matrix   Map user flows as Mermaid flowcharts, then derive the test matrix as a task list
3. Serve        Detect port, start dev server, open agent-browser
4. Execute      Work the matrix one item at a time with agent-browser
5. Fix loop     On failure: fix -> add regression test -> commit -> continue
6. Report       Write durable doc to docs/dogfood-reports/ (flows, matrix, fixes, learnings, verdict)

フェーズ 0：対象範囲を確認し、正しいブランチに移動する

$ARGUMENTS を解析します。PR 番号、ブランチ名、または空欄（現在のブランチを使用）を指定できます。--port PORT がある場合は取り除きます。

1. 対象ブランチを解決します。
   • PR 番号： gh pr checkout <number> を実行します（先に既存のワークツリーがないか確認してください）。
   • ブランチ名： そのブランチにチェックアウトします（先に既存のワークツリーがないか確認してください）。
   • 空欄： 現在のブランチを使用します。
2. main／master での実行は拒否します。 解決したブランチが trunk の場合は、停止してユーザーに伝えてください。dogfood の対象となる差分がありません。
3. 分離実行を提案します。 メインのチェックアウトに変更を加えずに済むよう、git ワークツリーで実行するかどうかを尋ねます（プラットフォームのブロッキング質問ツールを使用）。実行する場合は ce-worktree に引き継ぎ、実行しない場合は現在の場所で続行します。
4. 前回の実行を再開します。 docs/dogfood-reports/*-<branch-slug>-dogfood.md に既存のレポートがないか確認します。未完了のシナリオがあるレポートが見つかった場合は、そこから再開するか、新しく始めるかを尋ねます。再開するには、レポートのマトリクスからタスクリストを復元し（Pass／Fixed／Skipped は完了のまま、Pending／Blocked／進行中は残りの作業として扱います）、そこから続けてください。

再開可能性（いつでも中断して戻れます）

このワークフローは、中断して再開できるように設計されています。次の2つの状態によって、安全に再開できます。

• タスクリスト（TaskCreate/TaskUpdate）は、最新のToDoリストです。マトリックスのシナリオごとにタスクを1つ作成します。着手時にin_progressにし、実際に合格した場合にのみcompletedにします。
• docs/dogfood-reports/<YYYY-MM-DD>-<branch-slug>-dogfood.mdにあるレポートドキュメントは、セッションをまたいで保持される永続的なチェックポイントです。**マトリックスができたらすぐに（フェーズ2の終わりに）作成し、すべてのシナリオをPendingとして記載します。**また、最後にまとめて更新するのではなく、各シナリオの判定後と各修正のコミット後に、随時更新してください。

タスクはセッションごとにリセットされますが、レポートドキュメントはディスク上に残るため、再開時の正本はレポートです。後からの実行やチームメイトが正確に作業を引き継げるよう、常に両者の内容を一致させてください。

フェーズ1：変更を分析する

mainとの差分全体を取得して読みます。

git diff --name-only main...HEAD     # what changed
git diff main...HEAD                 # how it changed

すべての変更について、機能の追加、動作の変更、新しいルート／ビュー／コンポーネント、データフローへの影響を含め、頭の中でモデルを組み立てます。ユーザーに見える動作を生み出す変更を記録します。マトリックスで網羅すべきなのは、それらの変更です。

**プロダクトのペルソナとビジョンに基づいて考えてください。**実際のユーザーの視点からフローを評価できるよう、ペルソナとビジョンに関する情報を探します。「動作するか」だけでは不十分です。次の順に確認してください。STRATEGY.md（「Who it's for」セクションに主要なペルソナと、そのユーザーが達成したいことが記載されています）、VISION.md、ペルソナに関するドキュメント（例：docs/personas/、PERSONAS.md）。主要なペルソナを1～3人選び、それぞれが重視することを記録します。該当する情報がない場合は、プロダクトと差分から妥当な主要ペルソナを推定し、その旨をレポートに記載します。

フェーズ2：フローを把握してから、マトリックスを作成する

ページの一覧をすぐに作り始めないでください。まず、差分が影響するユーザーフローを把握し、その後でマトリックスを導き出します。フローモデルなしで作成したマトリックスでは、ページを個別にテストすることになり、ユーザーの一連の体験を見落とします。たとえば、メールは「送信」されても、間違ったスレッドに表示されるかもしれません。

2a. ユーザーフローを把握する（必須）

ユーザーに見える変更ごとに、一連の操作を開始から終了までたどり、図にします。テストを始める前に、ユーザーフローを明確にしてレビューできるよう、各フローを**Mermaidのflowchart**として表現してください。開始地点、各ユーザー操作、分岐点（成功／入力検証エラー／空の状態／権限拒否）、副作用（メール、ジョブ、通知）、実際の終了状態を含めます。

メールの例：「メールが送信される」だけでは不十分です。適切な受信者に届きますか？ユーザーがリンクをクリックしたとき、アプリは正しいメッセージに移動して、そこまでスクロールしますか？内容に問題はありませんか？フロー全体がプロダクトのビジョンやUXに沿っていますか？フローチャートには、メール送信で終わらせず、クリック後の操作と遷移先も含めてください。

flowchart TD
    A[User opens /threads] --> B[Clicks 'Reply']
    B --> C{Form valid?}
    C -->|No| D[Inline validation error shown]
    C -->|Yes| E[Reply saved]
    E --> F[Notification email sent to thread participants]
    E --> G[UI scrolls to new reply, focus on it]
    F --> H[Recipient clicks email link]
    H --> I{Lands on correct thread + scrolls to the reply?}

明確に異なるユーザーフローごとに、フローチャートを1つ作成します。正常系と分岐点（エラー、空の状態、境界条件、権限）を網羅してください。これらの図は、フローの理解そのものです。マトリックスの骨格となり、最終レポートに含めます。

2b. フローからマトリックスを導き出す

各フローチャートをたどり、すべてのノードと分岐から1つ以上のテストシナリオを作成します。references/test-matrix-taxonomy.mdを読み、各観点（ユーザーフロー、機能の確認、ユーザー体験の確認、エッジケース／エラー／空の状態、アクセシビリティ、レスポンシブ対応）の全項目を確認してください。機能面（「動作するか」）と体験面（「使い心地が適切で、プロダクトに沿っているか」）の両方を網羅します。

変更されたファイルを具体的なルートに対応付けます（ビュー -> そのページ、コンポーネント -> そのコンポーネントを表示するページ、レイアウト -> すべてのページ、スタイルシート -> 主要ページでのビジュアルリグレッションテスト）。それらのルートを、検証に使用するフローに割り当てます。

マトリックスをタスクリストとして登録します（TaskCreate）。シナリオごとにタスクを1つ作成し、進捗を追跡して、抜け漏れを防ぎます。タスクはファイル別ではなく、フローチャートに沿ってフローごとに並べます。

フェーズ 3：ポートを検出して開発サーバーを起動する

ポートを決定します（優先順位：明示的な --port > コンテキスト内のプロジェクト指示に明示されたポート > package.json の dev スクリプト > .env* の PORT= > デフォルトの 3000）。すでにサーバーがリッスンしている場合はそれを再利用します。そうでない場合は、プロジェクトの開発コマンドをバックグラウンドで起動し、ポートが利用可能になるまで待ちます。これは ce-test-browser が使用するものと同じ仕組みです。フェーズ 5〜6 のロジックに従ってください。

agent-browser open "http://localhost:${PORT}"
agent-browser snapshot -i

フェーズ 4：マトリックスを実行する

タスクリストの項目を一つずつ進めます。シナリオごとにタスクを in_progress にしてから、次の手順を実行します。

1. テスト内容を記録する（ジャーニーと期待される結果）。

2. agent-browser で操作する — 移動し、操作可能な参照用にスナップショットを取得し、クリック、入力、送信を行い、実際の終了状態までジャーニーをたどります。

   agent-browser open "http://localhost:${PORT}/<route>"
   agent-browser snapshot -i
   agent-browser click @e1
   agent-browser fill @e2 "value"
   agent-browser screenshot <scenario>.png
   agent-browser errors      # check console/page errors
   

3. 正確性と体験の両方を評価する：データが正しいか、遷移先が適切か、コンテンツが妥当か、コンソールエラーがないか、そしてプロダクトに合った体験かを確認します。

4. 各ペルソナの視点でたどる。主要な各ペルソナ（フェーズ 1 より）の視点からジャーニーを頭の中で再実行し、どこで小さな使いづらさを感じるか考えます。小さな使いづらさとは、機能テストには失敗しないものの、体験を損なう摩擦のことです。たとえば、分かりにくいラベル、余分なクリック、予想外の画面遷移、遅く感じるステップ、フィードバックの不足、そのペルソナの考え方に合わない文言などです。シナリオは機能的には Pass でも、小さな使いづらさが残ることがあります。それぞれの使いづらさと、それを感じるペルソナ、深刻度を記録します。

5. 記録する：合格／不合格と、小さな使いづらさがあれば具体的な内容を記録します。本当に合格した場合に限り、タスクを completed にします（小さな使いづらさは記録し、ブロッカーにはしません。重大なものはフェーズ 5 で修正し、残りはレポートに記載します）。

外部とのやり取りを含むフロー（OAuth、実際のメール配信、決済、SMS）はヘッドレスでは完全に実行できません。その箇所で一時停止してユーザーに確認を依頼し、その後続行します。

フェーズ 5：修正ループ（自律実行）

シナリオが失敗した場合は、修正して、その修正を検証します。ただし、まず修正を自律的に行うか、人間の判断に委ねるべきかを決めます。

コードに手を加える前に、修正の規模を判断します。 変更が小さく、内容を十分理解でき、リスクが低い場合は自動修正します。たとえば、明白な正解がある明確なバグで、少数のファイルに収まり、スキーマ、アーキテクチャ、プロダクト上のトレードオフを伴わない変更です。変更が大規模または曖昧な場合は、自動修正しないでください。アーキテクチャやスキーマの判断が必要な場合、プロダクトの動作や UX の意図を変える場合、多数のファイルにまたがる場合、妥当な解決策が複数ある場合、または「正しい」答えが明確だと自信を持てない場合が該当します。重大な判断を自律的に強行するより、エスカレーションするほうが適切です。

自律的に修正する場合：

1. 根本原因を調査します。原因が明白でない場合は ce-debug を使用します。
2. コードを修正します。
3. 自動回帰テストを追加します。修正前は失敗し、修正後は成功するテストにより、バグの再発を防ぎます。
4. 明確なメッセージを付けて修正をコミットします（ce-commit を使用）。コミットごとに、論理的にまとまった修正を一つだけ含めます。
5. ブラウザーで失敗したシナリオを再実行して、合格することを確認してからマトリックスの続きに進みます。
6. 再利用できる教訓が得られた場合は、ce-compound で記録します。

自律的に行うには変更が大きすぎる場合： 実装しないでください。レポートの人間による判断が必要な項目セクションに、問題の内容、自律的に修正するのが安全でない理由、考えられる選択肢（トレードオフを含む）、推奨案を記録します。マトリックスではそのシナリオを Blocked (human decision) とし、残りの作業を続けます。マトリックスの項目を解消するためだけに、大規模で不可逆な変更やプロダクトを変える変更を行ってはいけません。

すべてのタスクが completed または明示的に Blocked (human decision) になるまで、反復を続けます。修正によって影響を受けた可能性のある項目は再テストし、隣接するジャーニーでのリグレッションに注意してください。

フェーズ 6：レポート成果物を作成する

レポート文書はフェーズ 2 の最後に作成され、その後、段階的に更新されています（再開可能性を参照）。マトリックスがすべて緑色になったとき（または残りの項目がすべて明示的にブロックされているとき）は、テスト対象のリポジトリ内の docs/dogfood-reports/<YYYY-MM-DD>-<branch-slug>-dogfood.md にレポートを仕上げて、ファイルパスを添えて短い要約をチャットに共有してください。

計画やブレインストーミングをテンプレートから作成するのと同じように、references/dogfood-report-template.md をひな形として使用してください。完成した成果物には、次の内容を含める必要があります。

1. 差分の概要 — ブランチと main の間で変更された内容。
2. ペルソナ — 評価対象とした主要なペルソナと、その出典（STRATEGY.md／VISION.md／推定）。
3. テストしたフロー — フェーズ 2a の Mermaid フローチャート。ユーザーの行程を記録として残します。
4. テストマトリックスと結果 — すべてのシナリオについて、テスト内容、合否、見つかった問題、適用した修正、コミット SHA。
5. 修正した内容 — 各バグの根本原因、修正、追加した回帰テスト、コミット。
6. ペルソナ別の小さな不便 — 見つかった体験上の摩擦、それを感じるペルソナ、深刻度、修正済みか先送りか。
7. 人間が判断すべき事項 — 自律的に修正するには大きすぎる問題について、何が壊れているのか、エスカレーションした理由、トレードオフを含む選択肢、および推奨案。
8. 学び — 今後に活かせる再利用可能な教訓（重要なものは ce-compound に共有してください）。
9. 最終ステータス — 準備状況の判定に加え、ブロック中の項目や人間による確認が必要な事項。

ドキュメント内では絶対パスではなく、リポジトリ相対パスを使用してください。これにより、ドキュメントの移植性を保てます。