tamnguyendinh/Anvien

（必須）Codex の場合: QA でプラグインを使用する場合

• ブラウザ - アプリ内ブラウザを制御
• Chrome - ユーザーの実際の Chrome ブラウザを制御
• Computer Use - QA でブラウザ外での実際のアプリ操作が必要な場合に Windows アプリやインストール済みアーティファクトを制御
• Playwright: ブラウザ操作、コントロールスイープ、スクリーンショット、動画、トレース、レポートの自動化アームとして使用

（必須）Claude またはその他のエージェントの場合:

• そのエージェント/ランタイムが公開する同等のブラウザ、Chrome/セッション、またはコンピュータ制御機能、またはその環境で利用可能な Playwright 類似機能を使用する。

Anvien を用いた QA ランタイムレビュー

このスキルを使用して、ユーザーの視点から実際のランタイム動作を検証します。QA は修正を行わない役割です: 検査、実行、記録、分類、報告を行います。QA 中に製品コード、テスト、仕様、フィクスチャ、生成ファイルを修正してはなりません。

Anvien は QA のための発見ツールです。ルート、マウントサーフェス、ハンドラ、API、ストア、権限、ソースファイル、データフローをマッピングするのに役立ちます。ユーザーがサーフェスに到達できる、コントロールをクリックできる、正しい状態を確認できる、フローを完了できることを証明するものではありません。ランタイム証拠が QA の判定源です。

鉄則

• QA はコードを修正してはなりません。バグ、ブロッカー、摩擦、テストのギャップ、および提案される修正の方向のみを報告してください。
• ランタイム動作が QA の真実の源です。コードの存在、テスト、スクリーンショット、またはグラフ出力だけでは合格/不合格を証明できません。
• スクリーンショットの証拠が必須です。
• テストはすでに正しい動作を検証します。テストは期待される動作を定義するものではなく、間違った UX を正当化してはなりません。
• 間違ったテストは発見事項です。間違った動作をエンコードしたグリーンテストは QA の証明にはなりません。
• ステップをスキップしないでください。スコープ内のすべてのフローステップは同様に重要です。
• スコープ内のすべてのサーフェス、アクション、状態、データパス、ブロッカーには、明示的な判定またはスコープ外のマークが必要です。
• 不完全なインベントリまたはアクション台帳は、QA が不完全であることを意味します。
• ブロッカーが下流の検証を妨げる場合、下流スコープは合格ではなく「ブロック済み」となります。
• 最終的な可視 QA の場合、ユーザーが開くのと同じ方法で、実際の構築済みウェブサイト、ランタイム、または生成されたアプリアーティファクトを、ユーザーの物理 PC 上の可視ブラウザまたはアプリウィンドウで開いてください。ヘッドレス、非表示、ソースのみ、テストのみ、またはスクリーンショットのみの実行では、最終的な可視 QA を承認できません。
• QA は、実際の公式に構築されたアプリケーション（実際の Electron アーティファクトまたはリリースバイナリ）で実行する必要があります。
• すべてのアクション（ボタンのクリック、データの入力、状態の変更）は、screenshots/ ディレクトリに順次保存された明確な PNG スクリーンショットをキャプチャする必要があります。
• キャプチャされた各画像/ビジュアルアーティファクトを目視検査して、UI および動作上の欠陥を検出します。コード内のアサーションや生成された .json/.md サマリファイルのみに依存しないでください。
• 各インタラクションの実際のスクリーンショット証拠セットが不足している QA レポートを受け入れてはなりません。

期待される動作の源泉

利用可能な最初の該当権威を、以下の順序で使用してください:

1. ユーザーの明示的な QA スコープと修正禁止指示。
2. AGENTS.md などのリポジトリルール。
3. アクティブな実行計画、QA 計画、または SPEC ファミリー。
4. 最終的な可視 QA が要求された場合、または計画にスコープがある場合の可視ブラウザ計画。
5. このスキルの QA プロトコル。
6. 以下のカバレッジモデル、インベントリ要件、およびコントロール/状態プロトコル。
7. マッピングサポートとしての Anvien グラフ証拠のみ。
8. 検証証拠としての自動テストのみ。

権威が競合する場合は、競合を明記し、より上位の権威に従ってください。テストの期待値を使用して、実際の必要な製品動作を無効にしてはなりません。

QA における Anvien の使用

スコープの見逃しを防ぎ、データフローを理解するために Anvien を使用してください。ランタイム相互作用の代わりとして Anvien を使用しないでください。

グラフベースの Anvien 作業の前に、以下を実行してください:

anvien analyze --force

便利な Anvien の選択肢:

QA の必要性	使用法
ルート、ページ、コンポーネント、動作、またはリスク所有者を見つける	anvien query "<概念>" --repo <リポジトリ>
動作の候補ファイルを見つける	anvien query files "<概念>" --repo <リポジトリ>
1つのファイルを深く検査する	anvien file-detail <パス> --repo <リポジトリ> --json
ルートハンドラとコンシューマを検査する	anvien api route-map [ルート] --repo <リポジトリ>
コンシューマに対するレスポンス形状のずれを検査する	anvien api shape-check [ルート] --repo <リポジトリ>
ツール/IPC パスを検査する	anvien api tool-map [ツール] --repo <リポジトリ>
提案された修正方向のソース所有権を特定する	anvien impact file <パス> --repo <リポジトリ> --direction upstream または anvien impact symbol "<シンボル>" --repo <リポジトリ> --direction upstream
Anvien が古いか不完全に見える場合にグラフ証拠を監査する	anvien graph-health summary --repo <リポジトリ> --json

Anvien の証拠をスコープマッピング証拠として記録:

• ルート/ページの候補
• マウントされたエントリの候補
• アクション/ハンドラ/API の候補
• データソース/ストア/API/DB の候補
• 権限/コンテキストゲートの候補
• 提案された修正方向の可能性のあるソースファイル

Anvien が発見したからといって、何かを合格とマークしないでください。合格/不合格にはランタイム証拠が必要です。

コアワークフロー

1. 事前準備 → ビルド、ランタイム、ブラウザ（→ references/runtime-and-build-rules.md を読む）
2. インベントリ → サーフェス、コントロール、状態（→ references/coverage-model.md を読む）
3. 自動化 → スクリーンショット、コントロールスイープ（→ references/automation-and-evidence-capture.md を読む）
4. データフロー → 真実の源を追跡（→ references/data-flow-and-source-of-truth.md を読む）
5. ロケール → i18n がスコープ内の場合（→ references/i18n-and-locale.md を読む）
6. 証拠 → 収集、ブロッカーの分類（→ references/evidence-and-blockers.md を読む）
7. レポート → 発見事項、判定、引き継ぎ（→ references/reporting.md を読む）

クイック決定木

• ビルド、ランタイム、またはブラウザを準備していますか？ → references/runtime-and-build-rules.md
• コントロールスイープを実行中、またはスクリーンショットをキャプチャ中ですか？ → references/automation-and-evidence-capture.md
• インベントリの作成中、または状態マトリックスを確認中ですか？ → references/coverage-model.md
• データフローまたは DB 読み返しをトレース中ですか？ → references/data-flow-and-source-of-truth.md
• スコープに i18n / ローカライゼーションが含まれていますか？ → references/i18n-and-locale.md
• 証拠を記録中、またはブロッカーを処理中ですか？ → references/evidence-and-blockers.md
• レポートを作成中、または発見事項を分類中ですか？ → references/reporting.md

レッドフラグ

以下の場合、停止、報告、またはスコープの再設定を行ってください:

• QA がコードの修正を始める。
• QA が合格/不合格の証明として Anvien、ソースコード、またはテストを使用する。
• QA が最終的な可視 QA でヘッドレス/非表示ブラウザのみを実行する。
• QA がインベントリをスキップする。
• QA がスコープ内フローのステップをスキップする。
• QA がハッピーパスのみをクリックする。
• QA が無効、no-op、拒否、空、エラー、古い、またはブロックされた状態を無視する。
• QA が偽のアプリ/商用データを実際の本番状態であるかのように使用する。
• QA が DB バックの動作について DB/ソースの読み返しを無視する。
• QA がスコープ内である場合にロケール/セッション/権限の変更を無視する。
• QA が上流ブロッカーの後に下流スコープを合格として報告する。

リファレンスインデックス

ニーズ	ファイル
ビルド、ランタイム、可視ブラウザ/アプリのルール	references/runtime-and-build-rules.md
スクリーンショットキャプチャ、コントロールスイープ	references/automation-and-evidence-capture.md
インベントリ、判定、フローステップ、状態マトリックス	references/coverage-model.md
データトレース、DB、真実の源	references/data-flow-and-source-of-truth.md
i18n / ロケールスコープ	references/i18n-and-locale.md
証拠ソース、テスト、ブロッカーの伝播	references/evidence-and-blockers.md
発見事項の分類、レポートテンプレート、引き継ぎ	references/reporting.md