qa-expert

QA エキスパート

AAA テスト構造と OWASP セキュリティカテゴリを使用して、テストケース、実行状況の追跡、バグ報告、QA の引き継ぎを設定します。

このスキルを使用する場面

次の場合にこのスキルを使用します。

• 新規または既存のプロジェクトに QA インフラストラクチャを設定するとき
• 標準化されたテストケースを作成するとき（AAA パターンへの準拠）
• 進捗を追跡しながら包括的なテスト計画を実行するとき
• セキュリティテスト（OWASP Top 10）を実施するとき
• 適切な重大度分類（P0-P4）でバグを報告するとき
• QA レポート（日次サマリー、週次進捗）を作成するとき
• 品質指標（合格率、カバレッジ、ゲート）を算出するとき
• サードパーティチームへの引き継ぎに向けて QA ドキュメントを準備するとき
• LLM による自律的なテスト実行を可能にするとき

クイックスタート

1 つのコマンドで初期化：

uv run "<qa-expert-dir>/scripts/init_qa_project.py" "<project-name>" "<project-root>"

作成されるもの：

• ディレクトリ構造（tests/docs/、tests/e2e/、tests/fixtures/）
• 追跡用 CSV（TEST-EXECUTION-TRACKING.csv、BUG-TRACKING-TEMPLATE.csv）
• ドキュメントテンプレート（BASELINE-METRICS.md、WEEKLY-PROGRESS-REPORT.md）
• 自律実行用のマスター QA プロンプト
• 準備手順と生成されたファイルへのリンクを記載した README

出力先ディレクトリはプロジェクトのルートであり、スクリプトによって tests/ が追加されます。新しい保存先を使用してください。初期化によってテンプレートファイルが上書きされます。実行前に、CSV のサンプル行を置き換え、テスト仕様を記述し、プロジェクトのテストハーネスを設定してください。<qa-expert-dir> は、対象プロジェクトではなく、読み込まれたこのスキルのディレクトリを基準に解決してください。

自律実行の場合：準備、範囲を限定した実行、中断からの復旧について、マスタープロンプトに従ってください。初期化で作成されるのはテンプレートであり、テストの実行やスケジューラーのインストールは行われません。

主な機能

1. QA プロジェクトの初期化

QA ディレクトリとテンプレートを初期化します。

uv run "<qa-expert-dir>/scripts/init_qa_project.py" "<project-name>" "<project-root>"

ディレクトリ構造、追跡用 CSV、ドキュメントテンプレート、自律実行用のマスタープロンプトが作成されます。

使用場面：QA を一から始めるとき、または構造化された QA プロセスに移行するとき。

2. テストケースの作成

AAA パターン（Arrange-Act-Assert）に従って、標準化された再現可能なテストケースを作成します。

1. テンプレートを読みます：assets/templates/TEST-CASE-TEMPLATE.md
2. 次の構造に従います：前提条件（Arrange）→ テスト手順（Act）→ 期待結果（Assert）
3. 優先度を割り当てます：P0（ブロッカー）→ P4（低）
4. エッジケースと潜在的なバグを含めます

テストケースの形式：TC-[CATEGORY]-[NUMBER]（例：TC-CLI-001、TC-WEB-042、TC-SEC-007）

参考資料：AAA のガイドライン、プロジェクトに適合したカバレッジ、リリース受け入れ基準については、references/google_testing_standards.mdを参照してください。

クロスプラットフォームアダプターや、別のランタイム／実装との互換性を扱う場合は、モック、期待結果、サポート対象バージョンのケースを選ぶ前に、ランタイム互換性の受け入れ基準を読み込んでください。

決済、調達、フルフィルメント、返金の復旧を扱う場合は、ケースを選ぶ前にトランザクション復旧の受け入れ基準を読み込んでください。スキーマのアップグレード、会計ビュー、統合フィクスチャについては、マイグレーションとフィクスチャの受け入れ基準を読み込んでください。 ファイルベースの状態、スナップショットの依存関係チェック、復旧、または CLI 引数、ラッパー、互換性エイリアス、出力、読み取りコストの変更については、ファイル永続化と CLI の受け入れ基準を読み込んでください。 副作用を引き起こす可能性のある許可判定、アカウント／リソースのバインディング、復旧を扱う場合は、障害の発生タイミングや副作用に関するアサーションを選ぶ前に、許可判定と復旧の受け入れ基準を読み込んでください。 ユーザーによる変更と競合する可能性のある応答、正規化、編集提案については、タイミング、セッション、関連オブジェクトのケースを選ぶ前に、非同期編集と競合の受け入れ基準を読み込んでください。 これらのレシピをアプリケーションの既存の契約とテストハーネスに適用し、一般的な AAA、追跡、レポートのワークフローは維持してください。

3. テストの実行と追跡

グラウンドトゥルースの原則（重要）：

• テストケース文書（例：02-CLI-TEST-CASES.md）＝テスト手順の信頼できる情報源
• 追跡用 CSV＝実行状況のみ（テスト仕様の確認に CSV を使用しないでください）
• ドキュメントと CSV の同期に関する問題の防止については、references/ground_truth_principle.md を参照してください

手動実行：

1. カテゴリ別ドキュメントからテストケースを読む（例：02-CLI-TEST-CASES.md）← 必ずここから開始します
2. 文書に記載されたとおりにテスト手順を実行する
3. 各テストの直後に TEST-EXECUTION-TRACKING.csv を更新する（一括更新はしないでください）
4. テストが失敗した場合は、BUG-TRACKING-TEMPLATE.csv にバグを記録する

自律実行（推奨）：

1. references/master_qa_prompt.md からマスタープロンプトをコピーする
2. LLM セッションに貼り付ける
3. 許可されたバッチを実行し、各結果を追跡して、再現したバグを記録し、証拠を報告する

中断した場合は、チェックポイントを読み返し、不確かな副作用を照合してから、最初の未実施テストを選択してください。今後の実行には、利用可能で許可されたホストランナーが必要です。プロンプトだけではセッションは実行され続けません。

4. バグ報告

適切な重要度分類でバグを記録してください。

必須フィールド：

• Bug ID：連番（BUG-001、BUG-002、...）
• Severity：P0（24 時間以内に修正）→ P4（任意）
• Steps to Reproduce：番号付きの具体的な手順
• Environment：OS、バージョン、構成

重要度の分類：

• P0（ブロッカー）：セキュリティ脆弱性、中核機能の故障、データ損失
• P1（重大）：回避策のある主要機能の故障
• P2（高）：軽微な機能の問題、エッジケース
• P3（中）：外観上の問題
• P4（低）：ドキュメントの誤字

参照：初期化によって tests/docs/templates/BUG-TRACKING-TEMPLATE.csv が作成されます。

5. 品質メトリクスの算出

現在の追跡行からメトリクスを算出します。

uv run "<qa-expert-dir>/scripts/calculate_metrics.py" "<project-root>/tests/docs/templates/TEST-EXECUTION-TRACKING.csv"

メトリクスダッシュボードに含まれる項目：

• テスト実行の進捗（X/Y 件のテスト、Z% 完了）
• 合格率（合格数／実行数 %）
• 一意な関連バグ ID とテスト優先度の内訳
• 品質ゲートのステータス（各ゲートに ✅/❌）

scripts/calculate_metrics.py が、組み込みチェックと CSV フィールドの解釈を担います。結果は ✅ PASSED または ❌ FAILED として記録し、完了ステータスは Completed としてください。P0 チェックが参照するのは、追跡メモに記載された関連バグ ID と P0 のみです。バグログの重要度は参照しません。カバレッジ、OWASP の緩和策、リリース承認には、それぞれ個別のプロジェクト証拠が必要です。CLI は失敗したチェックを出力しますが、終了コードは 0 のままです。これはレポートであり、リリースゲートではありません。リリース承認に従ってください。別のサマリーテーブルを維持するのではなく、必要に応じて現在の合計を算出してください。

6. 進捗報告

関係者向けの QA レポートを作成します。

日次サマリー（終業時）：

• 実行したテスト、合格率、記録したバグ
• ブロッカー（ない場合は「なし」）
• 翌日の計画

週次レポート（毎週金曜日）：

• テンプレート WEEKLY-PROGRESS-REPORT.md を使用する（初期化スクリプトが作成）
• ベースライン BASELINE-METRICS.md と比較する
• 品質ゲートと傾向を評価する

参照：タスク別の報告プロンプトについては、references/llm_prompts_library.md を参照してください。

7. セキュリティテスト（OWASP）

OWASP Top 10 のセキュリティテストを実施します。

カバレッジの目標：

1. A01：アクセス制御の不備 - RLS バイパス、権限昇格
2. A02：暗号化の失敗 - トークンの暗号化、パスワードのハッシュ化
3. A03：インジェクション - SQL インジェクション、XSS、コマンドインジェクション
4. A04：安全でない設計 - レート制限、異常検知
5. A05：セキュリティ設定の不備 - 詳細すぎるエラー、デフォルトの認証情報
6. A07：認証の失敗 - セッションハイジャック、CSRF
7. その他：データ整合性、ロギング、SSRF

セキュリティに関する承認基準は、対象プロジェクトの信頼できるリリースポリシーに基づいて選択してください。

各セキュリティテストでは AAA パターンに従い、具体的な攻撃ベクトルを記録します。

1日目のオンボーディング

新しいQAエンジニアは、手順、チェックポイント、プロジェクトのセットアップ例について、1日目のオンボーディングに従ってください。

自律実行（⭐ 推奨）

単一のマスタープロンプトで、LLM主導の自律的なQAテストを有効にします。

参照：references/master_qa_prompt.md

機能：

• チェックポイントと副作用の照合後、未完了の最初のテストから再開
• プロジェクトで承認されたテスト計画とスケジュールを実行
• 結果を自動追跡（各テスト後にCSVを更新）
• バグを自動登録（失敗時にバグレポートを作成）
• レポートを自動生成（日次サマリー、週次レポート）
• P0バグで停止し、現在の会話で報告。外部へのエスカレーションには許可が必要です

メリット：

• バグの記録を統一
• 進捗をすぐに可視化

使用方法：マスタープロンプトをコピーし、実際のプロジェクトに合わせて設定してから、許可されたバッチを実行します。再開するには再度呼び出してください。無人実行にはホストで許可されたランナーを使用し、その稼働状況は別途確認してください。

プロジェクトに合わせた調整

小規模プロジェクト（50件のテスト）

• 期間：2週間
• カテゴリ：2～3（例：フロントエンド、バックエンド）
• 1日のテスト数：5～7件
• レポート：日次サマリーのみ

中規模プロジェクト（200件のテスト）

• 期間：4週間
• カテゴリ：4～5（CLI、Web、API、DB、セキュリティ）
• 1日のテスト数：10～12件
• レポート：日次＋週次

大規模プロジェクト（500件以上のテスト）

• 期間：8～10週間
• カテゴリ：6～8（複数のコンポーネント）
• 1日のテスト数：10～15件
• レポート：日次＋週次＋隔週のステークホルダー向けレポート

参考ドキュメント

同梱のリファレンスで詳細なガイドラインを確認できます。

• references/day1_onboarding.md - 新しいQAエンジニアのオンボーディング
• references/master_qa_prompt.md - 準備、実行、復旧、報告のSOP
• references/llm_prompts_library.md - 特定のQAタスク向けプロンプト
• references/google_testing_standards.md - AAAパターン、カバレッジ計画、リリース受け入れ、フェイルファスト検証
• references/ground_truth_principle.md - ドキュメントとCSVの同期問題を防止（テストスイートの整合性に不可欠）

アセットとテンプレート

テストケースのテンプレートとバグレポートの形式：

• assets/templates/TEST-CASE-TEMPLATE.md - CLIとセキュリティの例を含む完全なテンプレート

スクリプト

QAインフラストラクチャ向けの自動化スクリプト：

• scripts/init_qa_project.py - QAインフラストラクチャを初期化（ワンコマンドでセットアップ）
• scripts/calculate_metrics.py - 品質メトリクスのダッシュボードを生成

よくあるパターン

パターン1：新規QAの開始

1. uv run "<qa-expert-dir>/scripts/init_qa_project.py" my-app "<fresh-project-root>"
2. Fill in BASELINE-METRICS.md (document current state)
3. Write test cases using assets/templates/TEST-CASE-TEMPLATE.md
4. Copy master prompt from references/master_qa_prompt.md
5. Verify the project harness and authorization, then execute the approved batch

パターン2：LLM主導のテスト（自律型）

1. Read references/master_qa_prompt.md
2. Copy the master prompt and bind the project paths
3. Paste to LLM conversation
4. LLM executes the approved batch using project test specifications
5. LLM updates tracking CSVs automatically
6. LLM generates weekly reports automatically

パターン3：セキュリティテストの追加

1. Read references/google_testing_standards.md (OWASP section)
2. Write TC-SEC-XXX test cases for each OWASP threat
3. Apply the project's approved security acceptance
4. Document mitigations in test cases

パターン4：サードパーティQAへの引き継ぎ

1. Ensure all templates populated
2. Verify BASELINE-METRICS.md complete
3. Package tests/docs/ folder
4. Include references/master_qa_prompt.md for autonomous execution
5. QA team verifies prerequisites, completes the applicable onboarding and follows the project schedule

成功基準

このスキルは、次の条件を満たすと効果的です。

• ✅ テストケースをすべてのエンジニアが再現できる
• ✅ 品質ゲートを客観的に測定できる
• ✅ 再現手順を含め、バグが完全に記録されている
• ✅ 進捗をリアルタイムで確認できる（CSVで追跡）
• ✅ 自律実行が有効になっている（LLMが計画全体を実行できる）
• ✅ サードパーティのQAチームがテストハーネスを見つけ、検証済みの前提条件から再開できる