qa-workflow

QA ワークフローのスキル

概要

実装の完全性と正確性を検証し、承認されるまで修正サイクルを繰り返す、包括的な品質保証ワークフローです。リリース前の最後の砦となります。

基本原則： あなたは最後の砦です。あなたが承認すれば、その機能はリリースされます。徹底的に確認してください。

使用するタイミング

常に：

• 実装が完了としてマークされた後
• 変更をマージまたはデプロイする前
• 受け入れ基準を検証するとき

例外：

• ドキュメントのみの変更（最小限の検証でもかまいません）
• skip_validation フラグが設定された軽微な修正

厳守事項

1. すべての受け入れ基準を検証せずに承認してはなりません。あなたは最後の砦です。一部だけの検証は、検証していないのと同じです。
2. 問題は正確なファイルパスと行番号を添えて必ず記録してください。「テストが失敗する」のような曖昧な報告では修正できず、修正サイクルを無駄にします。
3. テストが失敗している実装に決して承認を与えてはなりません。承認前に、すべてのテストカテゴリ（単体、統合、E2E）が例外なく合格している必要があります。
4. リグレッション確認のため、必ずテストスイート全体を実行してください。新しいテストの結果に関係なく、既存機能を壊す機能は本番環境にリリースできる状態ではありません。
5. 人によるレビューにエスカレーションせずに、修正ループを5回以上繰り返してはなりません。ループが何度も続く場合、自動修正では解決できない根本原因があることを示しています。

アンチパターン

アンチパターン	失敗する理由	正しいアプローチ
すべての受け入れ基準を確認する前に承認する	機能を装ったバグをリリースし、品質契約を破ります	判定を記述する前に、仕様書の基準をすべて検証します
曖昧な問題報告を書く（「テストが失敗する」「壊れている」）	開発者は、正確な説明のない問題を再現したり修正したりできません	ファイルパス、行番号、正確なエラーメッセージ、再現手順を記載します
失敗しているテストが分かっていながら承認する	失敗しているテストは、記録済みのバグを本番環境にリリースすることになります	すべてのテストに合格する必要があります。テストに誤りがある場合は、まず修正し、変更内容を記録します
新しいテストだけを実行し、リグレッションテストスイート全体を実行しない	テストスイート全体を実行しなければ、新しいコードが既存機能を壊しても気づけません	--coverage を指定して、必ずテストスイート全体を実行します。リグレッションがあれば承認しません
「整理」のために QA で見つかった範囲を超えて修正する	過剰な修正は新たなバグを招き、修正サイクルのスコープを拡大します	変更は最小限にとどめます。QA で特定したものだけを修正し、それ以外は変更しません

承認前に、すべての受け入れ基準を検証する必要があります。

パート 1：QA レビュー

フェーズ 0：コンテキストの読み込み

# Read the spec (your source of truth for requirements)
cat .claude/context/specs/[task-name]-spec.md

# Read any previous QA reports
cat .claude/context/reports/qa/qa-report.md 2>/dev/null || echo "No previous report"

# See what files were changed
git diff main...HEAD --name-status

# Read QA acceptance criteria from spec
grep -A 100 "## QA Acceptance" spec.md

フェーズ 1：すべての作業の完了を確認

# Check git log for implementation commits
git log --oneline main..HEAD

# Verify expected files were modified
git diff main...HEAD --name-only

実装が完了していない場合は停止してください。 QA は実装後に行います。

フェーズ 2：テスト環境の起動

# Start services as needed
npm run dev  # or appropriate command

# Verify services are running
curl http://localhost:3000/health 2>/dev/null || echo "Service not responding"

次に進む前に、すべてのサービスが正常な状態になるまで待ちます。

フェーズ 3：自動テストの実行

単体テスト

影響を受ける領域の単体テストをすべて実行します。

# Run test suite
npm test
# or
pytest
# or
go test ./...

結果を記録します：

UNIT TESTS:
- [area-name]: PASS/FAIL (X/Y tests)

統合テスト

該当する場合は統合テストを実行します。

# Run integration test suite
npm run test:integration

結果を記録します：

INTEGRATION TESTS:
- [test-name]: PASS/FAIL

エンドツーエンドテスト

E2E テストがある場合：

# Run E2E test suite
npm run test:e2e

結果を記録します：

E2E TESTS:
- [flow-name]: PASS/FAIL

フェーズ 4：手動検証

仕様書に記載された受け入れ基準ごとに、次を実行します。

1. 該当する領域に移動します
2. 基準を満たしていることを確認します
3. コンソールエラーがないか確認します
4. エッジケースをテストします
5. 確認結果を記録します

MANUAL VERIFICATION:
- [Criterion 1]: PASS/FAIL
  - Evidence: [what you observed]
- [Criterion 2]: PASS/FAIL
  - Evidence: [what you observed]

フェーズ 5：コードレビュー

セキュリティレビュー

一般的な脆弱性がないか確認します。

# Look for security issues
grep -r "eval(" --include="*.js" --include="*.ts" . 2>/dev/null
grep -r "innerHTML" --include="*.js" --include="*.ts" . 2>/dev/null
grep -r "dangerouslySetInnerHTML" --include="*.tsx" --include="*.jsx" . 2>/dev/null

# Check for hardcoded secrets
grep -rE "(password|secret|api_key|token)\s*=\s*['\"][^'\"]+['\"]" . 2>/dev/null

パターン準拠

コードが既存のパターンに従っていることを確認します。

# Compare new code to existing patterns
# Read pattern files, compare structure

確認結果を記録します：

CODE REVIEW:
- Security issues: [list or "None"]
- Pattern violations: [list or "None"]
- Code quality: PASS/FAIL

フェーズ 6：回帰チェック

回帰を検出するために、テストスイート全体を実行します。

# Run ALL tests, not just new ones
npm test -- --coverage

既存の重要な機能が引き続き動作することを確認します。

REGRESSION CHECK:
- Full test suite: PASS/FAIL (X/Y tests)
- Existing features verified: [list]
- Regressions found: [list or "None"]

フェーズ 7：QA レポートの生成

# QA Validation Report

**Task**: [task-name]
**Date**: [timestamp]

## Summary

| Category            | Status    | Details     |
| ------------------- | --------- | ----------- |
| Unit Tests          | PASS/FAIL | X/Y passing |
| Integration Tests   | PASS/FAIL | X/Y passing |
| E2E Tests           | PASS/FAIL | X/Y passing |
| Manual Verification | PASS/FAIL | [summary]   |
| Security Review     | PASS/FAIL | [summary]   |
| Pattern Compliance  | PASS/FAIL | [summary]   |
| Regression Check    | PASS/FAIL | [summary]   |

## Issues Found

### Critical (Blocks Sign-off)

1. [Issue description] - [File/Location]

### Major (Should Fix)

1. [Issue description] - [File/Location]

### Minor (Nice to Fix)

1. [Issue description] - [File/Location]

## Verdict

**SIGN-OFF**: [APPROVED / REJECTED]

**Reason**: [Explanation]

**Next Steps**:

- [If approved: Ready for merge]
- [If rejected: List of fixes needed]

レポートを .claude/context/reports/qa/qa-report.md に保存します。

フェーズ 8：判定

APPROVED の場合

=== QA VALIDATION COMPLETE ===

Status: APPROVED

All acceptance criteria verified:
- Unit tests: PASS
- Integration tests: PASS
- Manual verification: PASS
- Security review: PASS
- Regression check: PASS

The implementation is production-ready.
Ready for merge.

REJECTED の場合

修正依頼を作成し、パート 2 に進みます。

---

パート 2：QA 修正ループ

フェーズ 0：修正依頼の読み込み

# Read the QA report with issues
cat .claude/context/reports/qa/qa-report.md

# Identify issues to fix
grep -A 50 "## Issues Found" .claude/context/reports/qa/qa-report.md

レポートから以下を抽出します。

• 修正が必要な問題の詳細
• ファイルの場所
• 必要な修正
• 検証基準

フェーズ 1：修正要件の解析

QA レポートからチェックリストを作成します。

FIXES REQUIRED:
1. [Issue Title]
   - Location: [file:line]
   - Problem: [description]
   - Fix: [what to do]
   - Verify: [how to check]

2. [Issue Title]
   ...

すべての問題に対処する必要があります。

フェーズ 2：問題を 1 つずつ修正

各問題について、次の手順を実行します。

1. 確認 問題箇所を読みます
2. 把握 何が問題なのかを理解します
3. 実装 修正を行います
4. 検証 ローカルで修正を確認します

以下のルールに従ってください。

• 必要最小限の変更にとどめます
• 周辺のコードをリファクタリングしません
• 機能を追加しません
• 既存のパターンに合わせます
• 修正のたびにテストします

フェーズ 3：テストの実行

すべての修正を適用した後、次を実行します。

# Run the full test suite
npm test

# Run specific tests that were failing
[failed test commands from QA report]

先に進む前に、すべてのテストに合格する必要があります。

フェーズ 4：自己検証

再レビューを依頼する前に、各修正を確認します。

SELF-VERIFICATION:
[ ] Issue 1: [title] - FIXED
    - Verified by: [how you verified]
[ ] Issue 2: [title] - FIXED
    - Verified by: [how you verified]
...

ALL ISSUES ADDRESSED: YES/NO

未修正の問題がある場合は、フェーズ 2 に戻ります。

フェーズ 5：修正のコミット

# Add fixed files
git add [fixed-files]

# Commit with descriptive message
git commit -m "fix: Address QA issues

Fixes:
- [Issue 1 title]
- [Issue 2 title]

Verified:
- All tests pass
- Issues verified locally"

フェーズ 6：再レビューの依頼

=== QA FIXES COMPLETE ===

Issues fixed: [N]

1. [Issue 1] - FIXED
   Commit: [hash]

2. [Issue 2] - FIXED
   Commit: [hash]

All tests passing.
Ready for QA re-validation.

---

QA ループの動作

QA → 修正 → QA のループは、次の条件を満たすまで続きます。

1. 重大な問題がすべて解決されている
2. すべてのテストに合格している
3. 回帰がない
4. QA の承認を得ている

最大反復回数：5

最大反復回数に達しても承認されない場合：

• 人によるレビューにエスカレーションします
• 残っている問題をすべて記録します
• 詳細なレポートを保存します

重大度のガイドライン

CRITICAL - 承認を妨げる問題：

• テストの失敗
• セキュリティ上の脆弱性
• 必須機能の欠落
• データ破損のリスク

MAJOR - 修正すべき問題：

• エッジケースの処理不足
• パフォーマンスの問題
• UX の問題
• パターン違反

MINOR - 修正するとよい問題：

• スタイルの不統一
• ドキュメントの不足
• 軽微な最適化

検証チェックリスト

承認する前に、次を確認します。

• すべてのユニットテストに合格している
• すべてのインテグレーションテストに合格している
• すべての E2E テストに合格している（該当する場合）
• 受け入れ基準を手動で検証している
• セキュリティレビューが完了している
• パターンへの準拠を確認している
• 回帰が見つかっていない
• QA レポートが生成されている

よくある間違い

早すぎる承認

問題点： バグをユーザーに届けてしまいます。

代わりに行うこと： 受け入れ基準をすべて確認します。

あいまいな問題報告

問題点： 開発者が内容を理解できない問題は修正できません。

代わりに行うこと： 正確なファイルパス、行番号、再現手順を記載します。

修正範囲の拡大

問題点： 既存の問題を修正する過程で新たなバグを引き起こす可能性があります。

代わりに行うこと： 変更を最小限に抑えます。QA で指摘された問題だけを修正します。

他のスキルとの連携

このスキルは次のスキルと相性がよいです。

• complexity-assessment：検証の深さを判断します
• tdd：TDD を使って修正のテストを作成します
• debugging：テスト失敗の調査に使用します

メモリプロトコル

開始前： .claude/context/memory/learnings.md を読みます。

完了後：

• 新しいパターン → .claude/context/memory/learnings.md
• 発見した問題 → .claude/context/memory/issues.md
• 決定事項 → .claude/context/memory/decisions.md

中断されることを前提にしてください。メモリに記録されていなければ、起きていないのと同じです。