mcpField
A
aif-qa-check

aif-qa-check

github.com/lee-toテスト・品質1.1k44 回インストール今日更新
リポジトリ

aif-qa-check について

aif-qa-check は、技術スタックやエージェント実行環境に依存せず、テストケースを人間主導または自動で実行し、結果を記録するスキルです。エージェントモードでは実行メモとブラウザー再生スクリプトを再利用し、回帰確認も行います。

主な機能

  1. 01人間主導と自動 QA
  2. 02qa-check.md への結果記録
  3. 03QA をまたいだコンテキスト再利用
  4. 04ブラウザーテスト再生による回帰確認
  5. 05複数の実行方法に対応

活用シーン

  1. 01人間がテストケースの結果を確認
  2. 02利用可能なツールでテストケースを実行
  3. 03修正後にブラウザー動作を再テスト

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/lee-to/ai-factory --skill aif-qa-check

インストール後、Claude Code で/aif-qa-checkを入力して読み込まれたか確認します。

同梱ファイルtemplates/QA-CHECK.md

詳細

QA チェック — テストケースの実行

/aif-qa が生成した test-cases.md アーティファクトを実行し、実行状況を qa-check.md に記録します。 エージェントモードでは、QA ルートの下に再利用可能な QA 実行メモリーも維持します。

  • agent-context.md — 今後の自動 QA 実行で再利用できる、整理済みの最新かつ機密性のないセットアップ情報
  • agent-history.md — 過去の実行から抽出した、追記専用の再利用可能な知見。実行ごとの監査ログではありません

ブラウザー／UI のテストケースでは、エージェントモードでブランチ固有の browser-replay/ ディレクトリに実行可能なリプレイスクリプトを保存します。後続の実行では、以前に合格したテストケースのスクリプトも含め、これらのスクリプトを最初に実行します。これにより、修正を再テストでき、ブラウザー自動化を再生成することなく、以前の動作を回帰テストの対象にできます。

このスキルはスタックやエージェントに依存しません。特定のフレームワーク、パッケージマネージャー、ブラウザーツール名、エージェントランタイムを前提としません。エージェントモードでは、各テストケースに適した利用可能な実行手段を使用します。ライブブラウザー自動化、CLI コマンド、プロジェクトのテストランナー、HTTP/API 呼び出し、データベースの安全な読み取りチェック、ファイル／ドキュメントの調査、その他の非破壊的な自動検証などが該当します。

モード

引数モード実行内容
human人間主導の QA一度にテストケースを 1 つだけ提示し、動作するかユーザーに確認して、その回答を記録します
agent自動エージェント QA最も適切な利用可能な機能を使ってテストケースを実行し、観測した結果を記録します

モードが指定されていない場合は、どちらのモードで実行するかユーザーに尋ねます。

ワークフロー

ステップ 0：設定の読み込み

最初に： .ai-factory/config.yaml が存在する場合は読み込み、以下を解決します。

  • パス： paths.description、paths.architecture、paths.qa（デフォルト：.ai-factory/qa）
  • 言語：
    • language.ui は AskUserQuestion のプロンプト、進捗メッセージ、要約、次のステップの案内に使用します
    • language.artifacts は保存される qa-check.md アーティファクトに使用します
    • language.technical_terms はアーティファクト内の、人が読む技術用語の表記スタイルに使用します
    • language.artifacts がない場合は、language.ui を使用します
    • 両方ともない場合は、en を使用します
  • Git： ブランチの解決には git.enabled を使用します

config.yaml が存在しない場合は、デフォルト値を使用します。

  • DESCRIPTION.md：.ai-factory/DESCRIPTION.md
  • ARCHITECTURE.md：.ai-factory/ARCHITECTURE.md
  • QA アーティファクト：.ai-factory/qa/
  • ui_language：en
  • artifact_language：en
  • technical_terms_policy：keep
  • Git の有効化：true

以下を保存します。

  • ui_language = language.ui || "en"
  • artifact_language = language.artifacts || language.ui || "en"
  • technical_terms_policy = language.technical_terms || "keep"
  • git_enabled = git.enabled（指定されている場合）、それ以外は true
  • qa_root = resolved paths.qa || ".ai-factory/qa/"
  • qa_agent_context_path = <qa_root>/agent-context.md
  • qa_agent_history_path = <qa_root>/agent-history.md

AskUserQuestion のプロンプト、ユーザーに表示する説明、ケースごとの要約、最終的な要約は、すべて ui_language で記述する必要があります。

保存する qa-check.md アーティファクトは、artifact_language で記述する必要があります。

テンプレートが定めるのは構成であり、言語ではありません。templates/QA-CHECK.md にある標準の英語テンプレートを使用します。artifact_language が en 以外の場合は、見出し、ラベル、ステータス文、作成するコメント、説明文を artifact_language に翻訳してから保存します。チェックボックスの構文、テストケース ID（TC-001）、コマンド、パス、設定キー、URL、セレクター、パッケージ名、API 名、ブランチ名、生のエラーメッセージはそのまま保持します。

artifact_language = ru の場合は、人が読む文章、見出し、ステータス、要約、およびエージェントが作成するコメントをロシア語で記述します。書き込む前に機密値を必ずマスキングし、それ以外のユーザーの表現は保持します。

アーティファクトを作成する際は、technical_terms_policy を適用します。

  • keep — より明確な場合は、browser、selector、viewport、endpoint、payload、regression、fixture などの一般的な技術用語をそのまま使用します
  • translate — 自然な訳語がある場合は、人が読む技術用語を翻訳します
  • mixed — 通常の文章中の用語は翻訳し、コード、インフラストラクチャ、エコシステムに関する用語はそのまま保持します
Step 0.1: プロジェクトコンテキストを読み込む

解決済みの説明パスが存在する場合は、そのファイルを読み込みます。

解決済みのアーキテクチャパスが存在する場合は、そのファイルを読み込みます。

.ai-factory/skill-context/aif-qa-check/SKILL.md を読み込みます。ファイルが存在する場合は必須です。このスキルに対するプロジェクトレベルの上書き設定として扱います。

<paths.qa>/agent-context.md が存在する場合は読み込みます。将来の自動実行で再利用できる、ユーザー承認済みの QA 実行コンテキストとして扱います。内容には、安定した環境クラス、標準的なローカル／ステージング URL、ログインルート、テストアカウントのロール、許可された機密性のないユーザー名、必須のシードデータパターン、安定したセレクター、フィールド識別子、既知のリダイレクト、起動時の前提条件、安全なコマンドパターン、再利用可能なテストフィルターの規則、環境に関するメモ、サービスの起動手順が含まれます。

<paths.qa>/agent-history.md が存在する場合は読み込みます。過去の /aif-qa-check 実行から得られた、追記専用の QA 横断メモリーとして扱います。ユーザーに質問したり、自動実行を試みたりする前に、同じ障害に対する再利用可能な過去の回答がないか検索し、スキルが避けられるはずのミスを繰り返さないようにします。

agent-context.md と agent-history.md は、paths.qa 配下のすべての QA セットで共通です。特定の QA 計画のログにしてはなりません。ブランチ名、ブランチスラッグ、QA 対象パス、現在の artifact_dir、TC-* の対応関係、実行ごとの集計件数、コマンドの全実行履歴、単一実行のアサーション数、単発のファイル確認、番号付きの QA フォルダー名など計画固有のラベルを記録してはなりません。これらの詳細は <paths.qa>/<branch-slug>/qa-check.md にのみ記録します。

将来の無関係な QA 実行にも役立つ可能性が高い情報のみを、agent-context.md または agent-history.md に反映します。具体的な一度限りの実行情報よりも、安定したパターンを優先します。例：Laravel backend checks use php artisan test --filter=<TestClass> は再利用可能です。一方、05-profile-formula-recommendations ran ProfileReaderTest with 4 tests / 13 assertions は実行固有の情報であり、qa-check.md に記録します。

プロジェクト全体に当てはまる場合を除き、機能や範囲に関するグローバルな否定的主張は決して記録しません。ある QA 計画だけから導かれた結論を、browser automation is not required、browser URL is not used、all QA is backend/CLI、these cases are backend-test/cli/file-docs のような表現で agent-context.md または agent-history.md に記録しないでください。代わりにブランチ固有の情報として qa-check.md に記録するか、For backend-only QA cases, browser automation is not required; browser/UI cases still require Browser or Playwright MCP のような、再利用可能な条件付きルールとして表現します。

どちらのファイルもシークレットの情報源として扱ってはなりません。いずれかのファイルにパスワード、トークン、Cookie、認証ヘッダー、ワンタイムコード、その他のシークレットらしき値が含まれている場合は、その値を実行に使用せず、次回ファイルを書き換えたり追記したりする際に削除します。

Step 0.2: 引数を解析してブランチを解決する

$ARGUMENTS を解析します。

  1. モードを検出します。最初の単語が human または agent に一致する場合は、その単語をモードとして検出し、引数から削除します。
  2. ブランチを検出します。残りのテキストがある場合は、それをブランチラベルとします。
  3. モードが指定されていない場合は、ui_language で実行モードを尋ねます。
    • 人間主導の QA
    • 自動エージェント QA

作業ブランチを解決します。

If git_enabled = false or the repository is not a git work tree:
  If branch was provided in arguments → use it as the resolved branch label
  Otherwise → set resolved_branch = "manual"
If git_enabled = true and the repository is a git work tree:
  If branch was provided in arguments → use it as the resolved branch
  Otherwise → run: git branch --show-current

以下を保存します。

  • resolved_branch
  • artifact_dir = <resolved paths.qa>/<branch-slug>
  • test_cases_path = <artifact_dir>/test-cases.md
  • qa_check_path = <artifact_dir>/qa-check.md
  • browser_replay_dir = <artifact_dir>/browser-replay

/aif-qa とまったく同じアルゴリズムで branch-slug を計算します。

  1. [A-Za-z0-9._-] に含まれない文字をすべて - に置き換え、連続する - をひとつにまとめ、先頭と末尾の - を削除します。空になった場合は branch を使用します。その後、safe_slug を先頭から ASCII 文字で 40 文字に切り詰める必要があります。正規化後の safe_slug に含まれる文字は [A-Za-z0-9._-] のみなので、バイト長と文字数は同じです。
  2. git hash-object --stdin <<< "<resolved_branch>" を実行し、先頭の 8 桁の 16 進数を hash8 とします。
  3. 結合します。branch-slug = "<safe_slug>-<hash8>"。
Step 1: QA 入力を確認する

<artifact_dir>/test-cases.md が存在するか確認します。 存在しない場合は停止し、ui_language で次のどちらを実行するかユーザーに確認します。

  1. 先に /aif-qa test-cases <resolved_branch> を実行する
  2. キャンセルする

test-cases.md を読み込みます。テストケースを ID（TC-001、TC-002 など）、タイトル、優先度、種類、記載がある場合は実行環境、前提条件、手順、期待される結果、テストデータごとに抽出します。記載順を維持します。

qa-check.md を作成または変更する前に、ソースバインディングのメタデータを計算します。

  • source_digest — git hash-object --no-filters <test_cases_path> が利用可能な場合はそれを使用し、そうでない場合はファイルの正確な内容を git hash-object --stdin に渡して、test-cases.md 全体の決定論的なダイジェストを計算します。
  • case_digests — 抽出した各 TC-NNN について、タイトル、優先度、種類、前提条件、手順、期待される結果、テストデータを含む、そのケースの標準ブロックから決定論的なケースごとのダイジェストを計算します。
  • tested_revision — git_enabled = true で、リポジトリが git 作業ツリーの場合は、git rev-parse HEAD を実行し、解決されたコミット SHA を記録します。
  • worktree_digest — git_enabled = true で、リポジトリが git 作業ツリーの場合は、現在の作業ツリー状態の決定論的なダイジェストを記録します。これにより、ローカル変更をコミットした後でなければ、変更のある作業ツリーに対する QA 結果を再利用できなくなります。
  • manual_build_id — git_enabled = false、またはリポジトリが git 作業ツリーではない場合は、結果を作成または再開する前に、明示的なビルド／バージョン識別子をユーザーに尋ねます。空の識別子は受け付けません。
  • replay_script_digests — 既存の標準 <browser_replay_dir>/TC-NNN.js ごとに、利用可能な場合は git hash-object --no-filters <path> を使用し、そうでない場合は別の安定した SHA-1／SHA-256 ダイジェストを使用して、ファイルの正確な内容をハッシュ化します。これにより、QA が管理するリプレイファイルは worktree_digest から除外されるものの、実際に実行された自動化スクリプトにエビデンスを紐付けます。

ケースごとのダイジェスト入力は、正確に次のとおり標準化します。

  1. ケースの TC-NNN 識別子を含む行から、次の TC-NNN ブロックの直前の行、またはファイル末尾までの生の Markdown ブロックを抽出します。
  2. CRLF または CR の改行コードを LF に正規化します。
  3. 各行末のスペースとタブを削除します。
  4. 抽出したブロックの先頭と末尾にある空行を削除します。
  5. 元のフィールド順、箇条書き記号、インデント、内部の空行、Markdown の句読点、その他すべての空白を保持します。フィールドの並べ替え、空白の圧縮、箇条書きの書き換えは行いません。
  6. ハッシュ化する前に、正規化したブロックを生のブロック境界で囲みます。BEGIN TC-NNN\n<normalized block>\nEND TC-NNN\n
  7. 利用可能な場合は git hash-object --stdin を使用し、そうでない場合は別の安定した SHA-1／SHA-256 ダイジェストを使用して、囲んだブロックをハッシュ化します。

git が有効で、git 作業ツリーが存在する場合は、worktree_digest を正確に次の手順で計算します。

  1. git status --porcelain=v1 --untracked-files=all を取得します。
  2. git diff --binary HEAD -- を取得します。
  3. ステータス、差分、未追跡ファイルのダイジェスト入力から、qa_check_path と browser_replay_dir 配下のすべてのファイルを除外します。QA が管理する結果／リプレイの成果物によって、それ自体の結果が古くならないようにします。test_cases_path は除外しません。ソースの変更も source_digest で追跡されます。
  4. porcelain ステータスに記載されている残りの未追跡ファイルごとに、読み取り可能であれば git hash-object --no-filters <path> を使用して、UNTRACKED <path> <content-digest> を追加します。
  5. 結合した入力の改行コードを LF に正規化し、git hash-object --stdin でハッシュ化します。
  6. フィルタリング後の作業ツリー入力がクリーンな場合は、標準文字列 clean\n のダイジェストを記録します。

mode = agent の場合は、qa-check.md を作成または変更する前に Step 1.1 を実行します。このゲート中は、既存の qa-check.md を読み取り専用で確認してもかまいません。 qa-check.md が存在する場合は読み込み、保存済みのバインディングメタデータを現在のバインディングメタデータと比較したうえで、既存のステータスから再開します。

  • tested_revision が変更されている場合、以前のすべての結果を Stale にしてチェックを外し、以前のコメント／証拠は履歴情報として保持し、再テストを必須とします。古い pass／fail／block ステータスは現在の結果として数えません。
  • worktree_digest が変更されている場合、以前のすべての結果を Stale にしてチェックを外し、以前のコメント／証拠は履歴情報として保持し、再テストを必須とします。古い pass／fail／block ステータスは現在の結果として数えません。
  • manual_build_id が変更されている場合は、tested_revision が変更された場合と同様に扱います。
  • source_digest が変更されている場合は、case_digests を比較します。ケースごとのダイジェストが変更されておらず、テスト対象リビジョン／手動ビルド ID とワークツリーのダイジェストも変更されていないケースに限り、現在のステータスを保持します。
  • 既存のケースのダイジェストが変更されている場合、そのケースを Stale にしてチェックを外し、再テストを必須とします。
  • 新しいケースが追加された場合は、チェックなしの Pending として追加します。
  • 以前のケースが test-cases.md に存在しなくなった場合は、履歴エントリを Stale として残すか、成果物の言語で「Stale / Removed Cases」セクションに移動します。現在のケースとして数えてはなりません。
  • ユーザーがそのケースの再テストを明示的に選択しない限り、以前の pass／fail コメントを上書きしてはなりません。
  • 正規のリプレイファイルの実際の内容ダイジェストが、そのケースに記録された Script digest と異なる場合、そのケースを Stale にし、以前のリプレイメタデータ／証拠を保持して、変更されたスクリプトの証明実行を必須とします。従来のスクリプトダイジェストまたはターゲットフィンガープリントのメタデータがない場合は、一致しているのではなく、スクリプトが未証明であることを意味します。
  • リビジョン、ワークツリー、または手動ビルドの古さだけでは、ブラウザーリプレイスクリプトは無効になりません。スクリプトに埋め込まれたケースダイジェスト、埋め込まれたターゲットフィンガープリント、実際のスクリプトダイジェストが、現在のケース、承認済みターゲット、以前に記録されたスクリプトダイジェストと一致している限り、再利用できます。

qa-check.md が存在しない場合は、抽出したテストケースとソースバインディングメタデータを使用して、templates/QA-CHECK.md から作成します。すべてのケースはチェックなしの Pending とします。

ステップ 1.1：エージェントモードの機能と安全性の事前確認

エージェントモードはユーザーのみが実行できます（disable-model-invocation: true）。ライブブラウザー操作、シェルコマンド、ローカルサービスの呼び出し、その他、無視できない副作用を伴うチェックを実行する可能性があるためです。 エージェントモードでケースを実行したり、qa-check.md を作成したりする前に、次の手順を行います。

  1. 現在のランタイムツールから、利用可能な実行機能を検出します。
    • シェル／CLI コマンドの実行
    • シェル経由で利用できるプロジェクトのテストランナーとビルドツール
    • アプリ内 Browser または Playwright MCP によるライブブラウザー自動化
    • 既存のプロジェクトツールまたは安全なシェルコマンドで実行できる HTTP／API チェック
    • Read／Grep／Glob によるファイル、ドキュメント、リポジトリの調査
  2. 各テストケースを、必要な証拠の種類に基づいて分類します。分類は browser-ui、cli、backend-test、api、file-docs、database-read、hybrid、human、unknown のいずれかです。ケースに Execution surface: フィールドが明示されている場合は、ケースの記述が明らかに矛盾していない限り、その指定を使います。指定を上書きした場合は agent-history.md に記録します。
  3. 各ケースについて、具体的な証拠を得られる最も侵襲性の低い機能を選択します。ブラウザー／UI で観察できるケース、および期待される結果がウェブページの描画内容に依存するハイブリッドケースでは、ブラウザー自動化が必須です。ブラウザー／UI のケースを CLI コマンド、単体テスト、静的調査、バックエンドチェックで代用してはいけません。これらは補足証拠としてのみ記録できます。
  4. ブラウザー自動化が必要な場合は、利用可能であればアプリ内 Browser 機能を優先します。アプリ内 Browser が利用できない場合は、Playwright MCP を使用します。
    • 再生スクリプトがある場合は、保存済みの Playwright 互換 page スクリプトを実行できるブラウザー機能を優先します。
  5. ブラウザー／UI ケースでライブブラウザー自動化が必要なのに、アプリ内 Browser も Playwright MCP も利用できない場合は、そのケースのみ未チェックのままにし、ステータスを Blocked に設定します。ui_language でライブブラウザー機能を有効にするようユーザーに依頼し、このブロッカーを <paths.qa>/agent-history.md に追記します。CLI、テスト、API、ファイル／ドキュメントのチェックで検証できる他のケースは続行します。
  6. 対象 URL、サービスの起動コマンド、テストコマンド、環境を判断するために、<paths.qa>/agent-context.md、<paths.qa>/agent-history.md、test-cases.md、change-summary.md、プロジェクトのドキュメント、現在のブラウザー状態、リポジトリ内のスクリプトを確認します。
  7. ブラウザー／UI ケースで認証または特定のユーザー状態が必要な場合は、ケースをブロックする前にブラウザーテスト用の識別情報を解決します。
    • まず、agent-context.md、agent-history.md、テストデータ、シーダー／ファクトリー／フィクスチャ、ドキュメント、安全に読み取り可能なローカルデータベースの情報、既存のテストユーザーを調べ、該当する非機密のテスト用識別情報を探します。
    • 環境が明らかに local、test、または破棄可能な development であり、リポジトリのツールで合成テストユーザー／状態を安全に作成またはシードできる場合は、ケースに必要な最小限の破棄可能なフィクスチャを作成します。フィクスチャの識別子とセットアップコマンド／証拠を qa-check.md に記録します。
    • フィクスチャの作成にパスワード、ロール、テナント、ワークスペース、フィーチャーフラグ、シードコマンド、または不明確なセットアップ判断が必要な場合は、ブロックする前にユーザーに確認します。既存のテストアカウントを提供するか、破棄可能なフィクスチャの作成を許可するかを尋ねます。
    • ユーザーが local または test 環境用の破棄可能なテスト認証情報を提供または作成を許可した場合は、この実行で使用します。再利用可能なテスト専用認証情報であり、安全に保存できるとユーザーが明示した場合に限り、認証情報を agent-context.md に保存します。それ以外の場合は、ユーザー名／ロールとシークレットの取得場所のみを保存します。
    • 本番環境の認証情報、個人用認証情報、Cookie、セッショントークン、ワンタイムコード、共有シークレットを agent-context.md または agent-history.md に保存してはいけません。
  8. ユーザーが提供できる前提条件が不足している場合は、ブロックする前にユーザーに確認します。
    • アプリケーション URL またはログイン URL
    • テストアカウントのロールまたは非機密のユーザー名
    • 認証情報を漏らさずに取得する方法
    • 破棄可能なローカル／テスト用ブラウザーフィクスチャを作成する権限と、希望する初期状態
    • 必要な起動状態、シードデータ、フィーチャーフラグ、テナント、組織、またはワークスペース
    • 不明確なログイン方法または認証プロバイダー
    • 続行に必要な安定したセレクター、フィールド識別子、またはページルート
    • 続行に必要な正確なプロジェクトコマンド、テストフィルター、サービス起動コマンド、または安全な API エンドポイント
  9. 再利用可能で機密性のない回答は、今後の QA セットにも役立つ一般的な内容である場合に限り、ただちに <paths.qa>/agent-context.md に保存します。再利用可能な教訓となる回答の要約は、該当する場合に限り、機密情報を除いて <paths.qa>/agent-history.md に追記します。それ以外は、ブランチ固有の qa-check.md の証拠／コメントにのみ記録します。
  10. 該当する場合は URL も含めて対象環境を特定し、環境クラスを local、development、staging、test、production、unknown のいずれかで推定して表示します。ブラウザーの対象については、次の手順を行います。
  • 解決した対象 URL から、ユーザー情報、クエリ、フラグメントを取り除き、スキーム、ホスト、ポート、デプロイ時のベースパスを維持したうえで、オリジンルート以外では末尾のスラッシュを取り除き、normalized_base_url を導出します。
  • 利用可能な場合は git hash-object --stdin を使い、正確な正規入力 AIF TARGET\n<environment_class>\n<normalized_base_url>\n から target_fingerprint を計算します。利用できない場合は、別の安定した SHA-1／SHA-256 ダイジェストを使用します。
  • 環境クラスと target_fingerprint を qa-check.md に記録します。別の対象フィンガープリントで作成された再生スクリプトを、現在の対象に一致するものとして扱ってはいけません。
  1. production または unknown の対象に対して、明示的なユーザーの承認を実行直前に得ずに、ブラウザー操作、API 書き込み、副作用のある CLI コマンド、データベース書き込み、破壊的コマンド、決済、権限変更、メール送信、通知、データエクスポート、またはその他の外部副作用を伴う操作を実行してはいけません。承認の判断と対象クラスを qa-check.md に記録します。再利用可能な複数の QA に共通するポリシーまたは承認に関する繰り返しの教訓となる場合に限り、agent-history.md にも追記します。将来の実行に適用される広範な本番環境の承認を保存してはいけません。
  2. 各ケースと実行予定のコマンドについて、破壊的、不可逆、決済、権限変更、メール送信、通知、データエクスポート、データベース変更、サービス再起動、デプロイ、ファイルシステムの削除、その他の外部副作用のリスクを確認します。そのようなケースを実行する前に、ケースごとに明示的な承認を得る必要があります。
  3. 読み取り専用かつテスト範囲に限定されたコマンドを優先します。ユーザーデータを削除する rm、git reset、git checkout --、データベースのリセット、共有環境へのマイグレーション、デプロイコマンド、クリーンアップコマンドなどの破壊的なシェルコマンドは、ユーザーがその操作を明示的に承認しない限り実行してはいけません。
  4. 承認が拒否された場合、または不明確な場合は、ケースを未チェックのままにし、ステータスを Blocked に設定して、危険な操作を実行せずにブロッカーを qa-check.md に記載します。この判断が再利用可能な複数 QA に共通する教訓となる場合に限り、agent-history.md に追記します。単一ケース固有の拒否は追記しません。 エージェントのコメント／証拠、および人間が入力したすべてのコメント／証拠では、必ず秘匿処理を行ってください。
  • 認証情報、Cookie、認証値、セッショントークン、API キー、ベアラートークン、ベーシック認証の値、ワンタイムコード、個人的な秘密情報を秘匿してください。
  • token、access_token、refresh_token、id_token、code、secret、password、passwd、pwd、auth、key、api_key、session、sid、jwt などの機密性の高い URL パラメーターを秘匿してください。
  • コメントまたは証拠を qa-check.md に書き込む前に、秘匿した値を [REDACTED] に置き換えてください。
  • 生のブラウザーストレージ、Cookie、リクエストヘッダー、認証ヘッダー、またはトークンを含む URL を成果物に貼り付けないでください。
ステップ 2：人間によるモード

保留中または選択されたテストケースを、一度に必ず 1 件だけ実行してください。

各ケースについて：

  1. そのテストケースのタイトル、優先度、事前条件、手順、テストデータ、期待結果のみを表示してください。
  2. ui_language でケースごとの短い要約を含めてください。
  3. 要約の質問は必ず「これをテストして、動作するかどうか答えてください」という意味にしてください。ui_language = ru の場合は、次の文をそのまま使用してください：Протестируйте и ответьте работает или нет
  4. ユーザーに結果を尋ねてください：
    • 動作する／完了
    • 動作しない／失敗
    • ここで停止
  5. ユーザーが動作すると答えた場合、そのケースを qa-check.md で確認済み（[x]）にし、ステータスを Passed に設定して、現在のモードを human として追加してください。
  6. ユーザーが失敗したと答えた場合、チェックボックスは未チェック（[ ]）のままにし、ステータスを Failed に設定して理由を尋ね、機密値の必須の秘匿処理を除き、ユーザーの表現を保ったまま説明をコメントとして記録してください。
  7. 進捗がコンテキストのリセット後も保持されるよう、各ケースの後に qa-check.md を保存してください。

現在のケースに結果が出るか、ユーザーが停止するまでは、次のテストケースを表示しないでください。

ステップ 3：エージェントモード

エージェントモードでは、各ケースに適した具体的な証拠を必ず提示してください。証拠によってケースの手順と期待結果を直接確認できる場合は、ブラウザーの実行結果、CLI 出力、自動テストの出力、API レスポンス、バックエンドコマンドの結果、データベースの安全な読み取り結果、ファイル／ドキュメントの調査結果のいずれも、ケースを合格とするのに十分な場合があります。

内部の決定論的な不変条件は、自動チェックとして扱わなければなりません。サービスメソッドの呼び出し、キャッシュの状態、マテリアライズされた行、配列の完全一致、生のデータベース値、数式の出力、CLI の内部動作など、人間が直接確認できない動作を含むケースは、適切に backend-test、cli、api、または database-read として分類してください。まず、その不変条件をすでにカバーしているテストやコマンドを探してください。該当するテストが見つかり、合格した場合は、対応する TC-* ケースを Passed とし、テストクラス／名前、コマンド／フィルター、終了ステータス、アサーション／結果の概要を証拠として記録してください。1 回のテスト実行で複数の TC-* ケースをカバーできる場合は、カバーされるすべてのケースで同じ証拠を再利用し、「Supporting Automated Checks」に共有実行の概要を記載してもかまいません。適切な自動テストが存在しない場合は、Missing automated test coverage for backend invariant などのブロッカーを記載してケースを Blocked のままにしてください。内部配列や生のデータベース値を手動で確認するようユーザーに求めないでください。

テスト対象を特定してください：

  • agent-context.md、agent-history.md、test-cases.md、change-summary.md、プロジェクトのドキュメント、または現在のブラウザー状態から URL が明確に特定できる場合は、それを使用してください。
  • リポジトリのスクリプト、テストファイル、パッケージマニフェスト、Makefile、フレームワークのコマンド、またはドキュメントから、CLI／バックエンド／API／ドキュメントのケースに安全なコマンドやテストフィルターが明確に特定できる場合は、それを使用してください。
  • URL、コマンド、起動時の状態、認証情報の保存場所、テストフィルター、または必要なフィクスチャが明確でない場合は、不足している情報をユーザーに尋ね、その後、再利用可能な機密性のない情報のみを agent-context.md に保存してください。
  • 認証情報、URL、コマンド、フィクスチャ、環境に関する前提を捏造しないでください。
  • ステップ 1.1 で確認した対象環境と権限を使用してください。別のホストにリダイレクトされた場合、またはより機密性の高い環境に移る場合は、再確認してください。
ブラウザー再生の契約

すべての browser-ui ケース、およびブラウザーの手順を含むすべての hybrid ケースについて：

  1. <browser_replay_dir>/TC-NNN.js を正規のリプレイ成果物として使用します。失敗したケースを個別に再実行できるよう、1 ファイルにつき 1 ケースにしてください。
  2. ブラウザーのコード実行機能で受け付けられる形式である、最小限の Playwright 互換の async (page) => { ... } 式を記述します。import、テストフレームワーク、fixture、生成したラッパー、プロジェクトの依存関係を追加しないでください。ナビゲーション、安定したセレクター、入力／操作、そして不一致時に例外をスローする明示的なアサーションを含めてください。
  3. すべての正規スクリプトの先頭に、次のメタデータ行をこのとおりに記述し、その後に async 式を続けます。
    • // aif-case-digest: <case_digest>
    • // aif-target-fingerprint: <target_fingerprint> 絶対的な対象 URL を保存する代わりに、ナビゲーションには引用符で囲んだプレースホルダー "AIF_BASE_URL" を使用してください。実行の直前に、保存済みファイルは変更せず、メモリ上でこの引用符付きプレースホルダーを、正しく JSON エンコードされた normalized_base_url に置き換えてください。パスワード、トークン、Cookie、認証情報、ワンタイムコード、個人の秘密情報、トークンを含む URL をスクリプトに記録しないでください。すでに認証済みのブラウザーセッションを再利用するか、許可された実行時の仕組みを通じて秘密情報を取得してください。
  4. リプレイが matching とみなされるのは、3 つすべてのバインディングが一致する場合のみです。埋め込まれた case_digest、埋め込まれた target_fingerprint、および qa-check.md に記録された最新の proof と実際の script_digest が一致している必要があります。リプレイのたびに、この 3 つすべてを確認してください。対象が一致しない場合は、現在表示されている許可済みの対象が確認され、スクリプトが明示的に再バインドされるまで実行を必ず停止してください。再バインドによってスクリプトダイジェストが変わるため、新たな proof 実行が必要です。
  5. 機械的に明確なケースでは、初回実行の前に、スクリプトが存在しないか古くなっている場合、そのスクリプトを作成してください。script_digest を計算して 1 回実行し、その初回実行を proof 実行として使用します。新規または更新済みのスクリプトを自動的に 2 回実行しないでください。
    • 手動のブラウザー操作で動作の詳細を明確にする必要があり、観察した実行後に保存済みスクリプトが変更された場合は、新しいスクリプトを Unproven として記録してください。すぐに再実行しないでください。
    • 未証明のスクリプトまたは変更されたスクリプトは、明記された前提条件が明示的に復元または確認された後にのみ実行できます。ケースが作成、送信、メッセージ送信、削除、権限／設定の変更、またはその他の外部副作用を引き起こす可能性がある場合は、再実行であることを明示した新たなケースごとの許可を取得してください。クリーンアップ／リセット操作にも同じ安全規則と許可要件が適用されます。
    • Script digest は、その正確なファイル内容が実行された後にのみ、現在のエビデンスのバインディングとして記録してください。未証明のファイルでは Script digest: n/a のままにし、Proof status: Unproven を設定してください。proof 実行が完了するまで、計算した候補ダイジェストをコメント／エビデンスに記録してください。
  6. 修復、再バインド、または明確化された動作の反映のために既存の正規スクリプトを変更する前に、古いスクリプトダイジェストを計算し、<browser_replay_dir>/history/TC-NNN-<old_script_digest>.js にそのまま保存してください。アーカイブしたパス、古いダイジェスト、最初のエラーを qa-check.md に記録してください。履歴ファイルを自動実行しないでください。
  7. プロダクトのリグレッションを隠さず、リプレイの失敗を分類してください。
    • 構文エラーまたはブラウザー実行エラー → 自動化の欠陥です。アーカイブして修正し、script_digest を再計算したうえで、上記の前提条件／副作用に関する規則に従って新たな proof 実行を必須とします。
    • セレクターが見つからない場合 → まず元のスクリプトと最初のブラウザーエラー／状態を保存してください。同じ意味の要素と期待される動作が現在も存在し、変更されたのがセレクターの仕組みだけであることを具体的なブラウザーエビデンスで証明できる場合に限り、ロケーターを修正してください。その証明を記録してください。それ以外の場合はケースを Failed とし、単に似ている要素を選んだり、見つからない手順を迂回したりしないでください。
    • スクリプトがアサーションまで到達し、観察された動作が異なる場合 → ケースを Failed としてください。これは回帰／修正のエビデンスであり、スクリプトを再生成する理由ではありません。
  8. リビジョン、worktree、または手動ビルドに変更があった後の実行では、以前に成功または失敗したケースも含め、現在一致しているすべてのブラウザースクリプトをリプレイしてください。機能／安全性の事前確認とケースごとの副作用許可は、各リプレイに引き続き適用されます。安全で、かつサポートされている場合は、セットアップとツール呼び出しを減らすため、状態を変更しないスクリプトを 1 つのブラウザーセッションまたはバッチで実行してください。
  9. ケースの Browser replay および Evidence フィールドに、正規パス、ケースダイジェスト、スクリプトダイジェスト、対象フィンガープリント、proof ステータス、実行機能、結果を記録してください。Proven は、正確なスクリプト内容が実行されたことを意味し、プロダクトの結果が成功したことを意味するものではありません。
  10. 利用可能なアプリ内ブラウザーが個別の操作のみをサポートしている場合は、保存済みスクリプトを正確な操作／アサーションプログラムとして読み、その操作を通じてリプレイしてください。Playwright MCP がファイル本文を直接実行できる場合は、直接実行を優先してください。実行方法が変わったというだけの理由で、既知の手順を再生成しないでください。
  11. リプレイを回帰テストのベースラインとして扱いますが、唯一のブラウザーチェックとはしないでください。リプレイ後、具体的な変更リスクに基づいて、範囲を限定した探索的な確認が妥当か判断してください。
  • 変更が共有 UI、レイアウト、ナビゲーション、認証、権限、状態遷移、またはその他の横断的なフローに影響する場合、バグの原因や修正の挙動が不確かなままの場合、アプリケーションの挙動が変わったために一致するリプレイの修復が必要だった場合、またはリプレイで想定外の関連挙動が見つかった場合は、実施してください。
  • 修正が狭い範囲に限定されており、一致するリプレイが変更された挙動を直接検証し、隣接する高リスクの経路に影響せず、リプレイが成功した場合は、省略してください。
  • 実施する場合は、直接影響する隣接ルート、状態、または境界入力のみを確認してください。範囲を限定しないブラウジングを開始したり、動作しているリプレイ手順を再生成したりしないでください。
  • Browser exploration: Ran または Browser exploration: Skipped、その理由、範囲、機密情報を除いた簡潔な所見を qa-check.md に記録してください。
  • 新たな所見を、暗黙のうちに元となるテストケースにしないでください。所見を qa-check.md に記録し、/aif-qa test-cases を通じて追加することを推奨してください。新たなケースのリプレイスクリプトは、そのケースに TC-NNN が割り当てられてから作成してください。 未処理または選択済みの各ケースについて：
  1. ケースの分類に基づいて実行する環境を選択します。
    • browser-ui：まず、該当する保存済みブラウザーリプレイを実行します。ケース、対象、またはスクリプトダイジェストが一致しないか、リプレイが存在しない場合に限り、作成するか、一致するものがないことを確認します。その後、Browser または Playwright MCP で移動し、UI 手順を実行します。
    • cli：該当するプロジェクトコマンドを実行し、終了コードと出力を確認します。
    • backend-test：まず、既存の関連テストコマンドまたはテストフィルターのうち、対象を最も絞ったものを見つけて実行します。確信を得るために必要な場合に限り、対象範囲を広げます。自動テストの合格は、そのケースの有効な合格証拠です。
    • api：適切に応じて、既存のプロジェクトツール、安全なローカルコマンド、またはブラウザー／ネットワーク機能を通じてエンドポイントを呼び出します。
    • file-docs：Read/Grep/Glob で生成ファイル、ドキュメント、設定、またはリポジトリの内容を調べ、必要に応じてプロジェクトの検証コマンドも実行します。
    • database-read：ユーザーがテスト専用環境での変更を明示的に許可している場合を除き、安全な読み取り専用の確認のみを使用します。
    • hybrid：必要な環境を組み合わせ、それぞれの証拠の種類を記録します。
  2. 選択した環境に応じて明らかな操作方法だけを調整し、記載どおりにテスト手順を実行します。
  3. 認証情報の不足、ブラウザーフィクスチャの不足、サービスの利用不可、設定の不明確さ、移動のブロック、セレクター情報の不足、フィールドの対応関係の曖昧さ、不明なルート、不明なコマンド、フィクスチャの不足、またはテストフィルターの不明確さが原因で実行が滞った場合は、まず agent-context.md と agent-history.md を調べます。ブラウザー／UI の認証やユーザー状態に関する不足については、ブロックする前に、Step 1.1 に記載された安全なローカル／テスト用フィクスチャの発見または作成を試します。答えやフィクスチャが既に用意されていない場合は、ケースをブロック済みとしてマークする前に、不足している情報または許可だけをユーザーに正確に尋ねます。
  4. ユーザーから利用可能な機密性のない情報が提供された場合は、同じ実行内でケースを続行します。将来の QA でも有用な、長期的に役立つ情報は agent-context.md を更新し、今後の QA セットでも再発する可能性が高い場合に限り、解決した障害を agent-history.md に追記します。ケース固有の詳細は qa-check.md に記録します。
  5. ユーザーが不足情報を提供できない場合、サービスが利用できないままの場合、許可が拒否された場合、必要な機能が利用できない場合、または副作用のリスクが解決されないままの場合は、チェックボックスを未チェック（[ ]）のままにし、ステータスを Blocked に設定して、ブロッカーを記載します。
  6. 観測された結果を期待される結果と比較します。
  7. 観測された動作が一致する場合は、ケースにチェックを付け（[x]）、ステータスを Passed に設定し、個人情報などを除いた簡潔な証拠を追加します。証拠には、ブラウザーでの観察結果、コマンドと終了ステータス、テスト名と結果、API 応答の要約、ファイルパスと一致した条件、またはその他の具体的な観察結果を記載できます。
  8. 観測された動作が一致しない場合は、チェックボックスを未チェック（[ ]）のままにし、ステータスを Failed に設定して、観測された動作と期待される動作を比較した、個人情報などを除く具体的な問題コメントを記載します。
  9. 各ケースの実行後に qa-check.md を保存します。

最終的な要約の前に、実行ごとの詳細な証拠をルートレベルのメモリではなく qa-check.md に記録します。これには、現在のブランチ／QA 対象、実行したコマンド、終了コード、アサーション数、裏付けとなるファイルの確認結果、ケースの対応関係、要約件数、今回限りのブロッカーが含まれます。

qa-check.md を書き込んだ後は、再利用可能な QA 共通の学びのみを抽出します。

  • 発見した事実が長期的に有用で、今後の QA セットでも役立つ可能性が高い場合は、<paths.qa>/agent-context.md を更新します。
  • ブロッカー、セレクター、コマンドのパターン、テストフィルターの規則、API エンドポイントのパターン、ルート、設定に関するメモ、または許可に関する判断が、現在の QA セット以降も再発する可能性が高い場合に限り、<paths.qa>/agent-history.md に追記します。
  • 新たに再利用できる学びがない成功実行では、agent-history.md に何も追記しなくてもかまいません。
  • 実行の全記録、ブランチ／QA 対象、実行ごとの要約件数、正確なアサーション総数、または現在の QA 計画のラベルを agent-history.md に追記してはなりません。 <paths.qa>/agent-context.md は簡潔かつ最新の状態に保ち、一度限りの所見よりも安定した事実を優先してください。生のパスワード、トークン、Cookie、認可ヘッダー、ワンタイムコード、個人の機微情報、トークンを含む URL、ブランチ名、QA 対象パス、実行の概要は記載しないでください。

アクティブな実行環境でスクリーンショットやブラウザーの状態を確認できる場合は、それらを使用してください。ただし、テストの合格にスクリーンショットを必須としないでください。

Step 4：最終サマリー

停止または終了した後、ui_language で以下を報告してください。

  • テストケースの合計数
  • 合格数
  • 失敗数
  • ブロック数
  • 未実行数
  • qa-check.md のパス
  • ブラウザースクリプトを作成または実行した場合は、browser-replay/ のパス
  • エージェントモードを実行した場合、または不足している実行コンテキストを求めた場合は、agent-context.md と agent-history.md のパス
  • 次に推奨するアクション

mode = agent で、現在のケースが1件以上 Blocked の場合は、終了前に人が確認できるブロック中のケースと、自動化のみで確認できるブロック中のケースに分けてください。

  • 実行対象が human、browser-ui、人が確認できる手順を含む hybrid、または unknown のブロック中のケースに限り、人が確認しながら続行する方法を提案してください。
  • 自動テストのカバレッジ不足、コマンドやテストフィルターの不足、サービスの利用不可、その他の技術的な自動化前提条件が原因でブロックされている backend-test、cli、api、file-docs、database-read のケースについては、人が確認しながら続行する方法を提案しないでください。それらのケースについては、適切な自動チェックを追加または実行すること、あるいは不足しているコマンド／フィクスチャ／コンテキストを提供することを推奨してください。
  • 人が確認できるブロック中のケースが1件以上ある場合は、該当するケースを人が確認しながら今すぐ実行するか、ui_language でユーザーに確認してください。
  • ユーザーが同意した場合は、同じ実行内で Step 2 に進み、該当するブロック中のケースのみを対象にしてください。既存のエージェントによるブロッカーのコメントはコンテキストとして残し、人による結果／コメントを同じケースに追記してください。
  • ユーザーが同意しない場合、または中止した場合は、それらのケースを未チェックのまま Blocked にしてください。
  • 引き継ぎに関する判断と、解決したブロック中のケースを qa-check.md に記録してください。引き継ぎによってQA全体に再利用可能な教訓が得られた場合に限り、agent-history.md に追記してください。

失敗したケースがある場合、次に推奨するアクションは、問題を修正して /aif-qa-check <mode> <resolved_branch> を再実行することです。

エージェントモードの実行後も人が確認できるケースがブロックされたままで、ユーザーが人による確認モードで続行しなかった場合、次に推奨するアクションは、該当するケースに対して /aif-qa-check human <resolved_branch> を実行するか、不足している実行コンテキストを提供することです。自動化のみで確認できるケースがブロックされたままの場合は、代わりに必要な自動テスト、コマンド、フィクスチャ、サービス、またはコンテキストを追加または実行することを推奨してください。具体的な観察結果がない限り、ブロックされたケースを製品の不具合とみなさないでください。

成果物の管理と設定ポリシー

  • 主な管理対象：<paths.qa>/<branch-slug>/qa-check.md、正規の <paths.qa>/<branch-slug>/browser-replay/TC-NNN.js、保持された <paths.qa>/<branch-slug>/browser-replay/history/*.js、<paths.qa>/agent-context.md、<paths.qa>/agent-history.md。
  • 読み取りポリシー：QA のコンテキストとして、<paths.qa>/<branch-slug>/change-summary.md、test-plan.md、test-cases.md、<paths.qa>/agent-context.md、<paths.qa>/agent-history.md を読み取ってかまいません。
  • 書き込みポリシー：永続的な書き込みは、qa-check.md、ブランチ固有の browser-replay/TC-NNN.js と browser-replay/history/*.js、agent-context.md、agent-history.md に限定します。test-cases.md、test-plan.md、change-summary.md、config.yaml は書き換えないでください。
  • 設定ポリシー：設定を考慮しますが、読み取り専用です。paths.description、paths.architecture、paths.qa、language.ui、language.artifacts、language.technical_terms、git.enabled を読み取り、config.yaml には書き込みません。

重要なルール

  1. test-cases.md がなければ実行してはなりません。
  2. 人間モードでは、一度に表示するケースは1つだけにしてください。
  3. 人間モードでは、そのケースが問題なく動作するかユーザーに確認してください。
  4. 書き込む前に機密値を必ずマスキングすることを除き、失敗に関するユーザーのコメントの文言を保持してください。
  5. エージェントモードでは、そのケースに適した実行環境から得た具体的な証拠なしに、ケースを合格と判定してはなりません。
  6. ライブブラウザー自動化を利用できないことだけを理由に、ブラウザー以外のケースをブロックしてはなりません。
  7. 決定論的な内部／バックエンド／CLI／API／データベースの不変条件に関するケースは自動チェックとして分類し、自動テストの不足を補う代替手段として人手によるQAに回してはなりません。
  8. 現在の結果を、tested_revision と worktree_digest、または manual_build_id に加え、source_digest と case_digests に紐付けてください。
  9. テスト対象のリビジョン、ワークツリーのダイジェスト、手動ビルドID、ソース全体のダイジェスト、またはケースごとのダイジェストが変更された場合、古い結果を stale としてマークしてください。
  10. 本番環境／不明な対象、および破壊的または外部に副作用を及ぼすケースでは、明示的な許可を必須としてください。
  11. コメントや証拠を書き込む前に、認証情報、Cookie、認証値、トークン、機密性の高いURLパラメーターを必ずマスキングしてください。
  12. ケースごとに進捗を保存してください。
  13. 自動実行の前、およびセットアップ情報をユーザーに尋ねる前に、agent-context.md と agent-history.md を読み、過去の回答を再利用してください。
  14. URL、認証情報、ログイン経路、フィールド識別子、セットアップ状態、セレクター、コマンド、テストフィルター、フィクスチャ、または同様の回復可能な情報が不足している場合、エージェントモードのケースをブロックする前に、ユーザーから提供可能な実行コンテキストの不足分をユーザーに尋ねてください。
  15. ブラウザー／UIのケースでログイン認証情報やユーザー状態が不足している場合、再利用可能なコンテキスト、既存のフィクスチャ、シーダー／ファクトリー、ドキュメント、安全なローカル／テストデータを検索し、環境がローカル／テスト環境でツールが利用可能なら安全で破棄可能なフィクスチャの作成を試みるか、ユーザーに認証情報、フィクスチャのセットアップ、または破棄可能なフィクスチャを作成する許可を求めるまでは、そのケースをブロックしてはなりません。
  16. 再利用可能なテスト専用認証情報を agent-context.md に保存するのは、ユーザーから明示的な許可を得た後に限ってください。本番環境の認証情報、個人の認証情報、Cookie、セッショントークン、ワンタイムコード、共有秘密情報は絶対に保存してはなりません。
  17. 再利用可能で機密性のないQA横断的な回答、および判明した安定した実行情報のみを agent-context.md に書き込んでください。繰り返し利用できる学びやブロッカーパターンが見つかった場合に限り、agent-history.md に追記してください。
  18. エージェント実行を終了する時点で、人間が検証可能な Blocked ケースが残っている場合、エージェントモードでブロックされた対象ケースを人間モードで続行するかどうかをユーザーに確認してください。
  19. ブラウザー／UI自動化は、ケース、対象、コンテンツに紐付けた browser-replay/TC-NNN.js スクリプトとして保存し、新しいブラウザー操作を生成する前に、該当するスクリプトを実行してください。
  20. リビジョン、ワークツリー、または手動ビルドに変更があった場合、以前合格したブラウザーケースの該当スクリプトを再実行し、リグレッションを確認してください。
  21. リプレイ成果物だけを目的として、ブラウザーテストの依存関係やランナーを追加してはなりません。
  22. リプレイ後に、証拠に基づいてブラウザー探索の要否を判断し、その判断を記録してください。リプレイはベースラインであり、具体的な変更リスクの兆候がある場合に範囲を限定して行う探索の代わりにはなりません。
  23. 新規または更新されたリプレイを自動で再実行してはなりません。再実行には、前提条件の復元と検証、および外部への副作用に関する改めての許可が必要です。
  24. セレクターが見つからない場合は、ロケーターの仕組みだけが変更されたことを示す具体的な証拠がない限り、製品のリグレッションの可能性として扱ってください。修正前の元のスクリプトとエラーは保持してください。
  25. リプレイ前に case_digest、target_fingerprint、script_digest を検証してください。また、スクリプトの変更後または対象の再バインド後には、証明のための実行を必須としてください。

コメント

Markdown 対応