@einja/dev-cli 0.1.6

package/scaffolds/steering/acceptance-criteria-and-qa-guide.md

@@ -0,0 +1,415 @@
+# 価値あるテストを生む要件定義とテスト設計ガイド
+
+## 1. 受け入れ基準の原則
+
+### Do
+- 振る舞い・入力・観測可能な結果をセットで書く（Given/When/Then または 条件/操作/期待結果）。
+- ビジネス価値やユーザー影響が分かる文脈を添える（誰が何のために使うか）。
+- 正常系に加え、代表的な異常・境界ケースを列挙する。
+- 観測手段（API レスポンス、イベント、DB 状態など）を明示する。
+- 実装と無関係な用語で書き、内部構造への言及は避ける。
+
+### Don't
+- 「ファイルが存在する」「〇〇を返すクラスがある」など構造・命名のみを確認させる。
+- 単一の肯定文で完結させて振る舞いの条件や観測結果を書かない。
+- テストレベルを曖昧にし、誰がどの観点で検証するか不明瞭にする。
+- 期待結果を「問題ないこと」「成功すること」で済ませる。
+- 実装手段（特定フレームワーク、DB テーブル構造など）を強制する。
+
+### 振る舞い駆動テンプレート
+```
+ACx.y: <振る舞いの名前>
+- 前提: <状態/入力/役割>
+- 操作: <ユーザー操作 or システムイベント>
+- 期待結果: <観測可能なアウトプット>（例: HTTP ステータス/レスポンス/DB 変化/イベント）
+- 検証レベル: <Unit | Integration | E2E | Browser>（複数可）
+  - 詳細は `docs/einja/steering/terminology.md` を参照
+- 補足: <ビジネスルールやエッジケース>
+```
+
+## 2. テスト設計の原則
+
+### テストレベルと責務
+- **単体 (Unit)**: 単一モジュールの意思決定ロジックを高速に検証。外部依存はモック化し、条件分岐とエッジケース網羅。
+- **統合 (Integration)**: 境界（Repository+DB, UseCase+Gateway, API+Middleware など）越しの契約を検証。実際のインフラ接続や本物に近いセットアップを使い、主要なハッピーパス＋代表的な異常系を確認。
+- **E2E**: Playwrightコードによる自動テスト。`pnpm test:e2e`で実行され、リグレッション防止に使用。
+- **Browser**: Playwright MCPによるブラウザテスト。task-qa Skillで実行され、画面フロー・UIインタラクションの確認に使用。
+
+> **Note**: E2EとBrowserの違いについては `docs/einja/steering/terminology.md` を参照してください。
+
+### 価値あるテスト判定基準
+- 仮説: テストが守るべきビジネスルールや SLA が明文化されている。
+- 分離: 振る舞い単位の原因→結果を説明できる。
+- 再現性: 決定論的で、入力と期待結果から誰でも同じ結論を得られる。
+- 監視性: 失敗時に「何が壊れたか」がメッセージやログから分かる。
+- 保守性: 実装ディテールではなく契約・振る舞いに結び付いているため、内部構造変更で安易に壊れない。
+- コスト対価: 実行時間/セットアップコストに見合うリスク低減効果がある。
+
+### テスト-ファースト原則（ATDD）
+テスト設計は**実装前**に行う。ワークフローは以下の順序で実行する：
+
+```
+要件定義 → 設計 → QAテスト仕様（シナリオテスト含む）→ タスク分割 → 実装 → QA（実行のみ）
+```
+
+**禁止事項**:
+- 実装後にテスト設計を行うこと
+- テスト仕様なしでタスク分割を行うこと
+- QAフェーズでテスト設計を新規作成すること（既存仕様の確認・実行のみ）
+
+### シナリオテスト
+シナリオテストは、複数のタスクをまたいで継続的に実行される操作フローを検証する。
+
+**シナリオテストの目的**:
+- 個別タスクのテストでは検出できない統合問題を発見
+- ユーザーが実際に行う操作フロー全体の動作を確認
+- タスク間の依存関係と連携を検証
+
+**シナリオテストの特徴**:
+- 複数のタスクグループにまたがる
+- 各タスク完了時に実施可能な範囲が拡大
+- Issue全体で共有される（`qa-tests/scenarios.md`に記載）
+
+**シナリオテストテンプレート**:
+```markdown
+## シナリオ#1: [シナリオ名]
+
+### 目的
+[このシナリオで確認したいこと]
+
+### 関連
+- **受け入れ条件**: AC2.1, AC4.1, AC8.1（シナリオに関連するAC番号）
+- **関連タスク**: 2.1, 2.4, 3.1（シナリオに含まれるタスク番号）
+
+### 実施タイミング
+- **タスク2.1完了後**: Step 1-3まで実施可能
+- **タスク2.4完了後**: Step 1-5まで実施可能
+- **タスク3.1完了後**: 全Step実施（フルシナリオ）
+
+### テスト手順
+
+| Step | 操作 | 確認項目 | 期待値 | 結果 |
+|------|------|---------|--------|------|
+| 1 | [操作内容] | [確認する項目] | [期待される結果] | - |
+| 2 | ... | ... | ... | - |
+
+### 実行ログ
+（実施後に記載）
+```
+
+**シナリオテストの設計タイミング**:
+- `/spec-create` コマンドの QAテスト仕様生成フェーズで作成
+- requirements.md の受け入れ条件を分析し、複数ACをまたぐフローを特定
+- タスク分割前に完了させる
+
+## 3. 具体例集
+
+### ケース1: データベース層（Repository）
+- 悪い例: 「UserRepository が実装されている」
+- 良い例:
+  ```
+  AC1.1: UserRepository はメールアドレス重複を防ぐ
+  - 前提: 同一メールを持つユーザーが既に存在
+  - 操作: create({email}) を呼ぶ
+  - 期待結果: Result.Err(DuplicateEmail) を返し、DB 状態は変化しない
+  - 検証レベル: Integration（実 DB or Testcontainer）
+  ```
+
+### ケース2: アプリケーション層（UseCase）
+- 悪い例: 「UseCase がオブジェクトリテラル形式で定義されている」
+- 良い例:
+  ```
+  AC2.2: PasswordResetUseCase はトークン発行後にメール送信イベントを発火
+  - 前提: 対象ユーザーが存在し、メール送信サービスが利用可
+  - 操作: execute({userId})
+  - 期待結果:
+      1. TokenRepository に 1 件レコード生成
+      2. DomainEventBus へ PasswordResetRequested を publish
+  - 検証レベル: Unit（メール送信はモック）、Integration（イベントバス接続）
+  ```
+
+### ケース3: API 層（REST）
+- 悪い例: 「API エンドポイントが定義されている」
+- 良い例:
+  ```
+  AC3.4: GET /users/:id は権限エラーを 403 で返す
+  - 前提: 認証済みユーザー A がユーザー B を参照しようとする
+  - 操作: GET /users/B
+  - 期待結果: HTTP 403, body {"code":"FORBIDDEN","message":"..."}
+  - 検証レベル: Integration（API + DB + 認可ミドルウェア）
+  ```
+
+### ケース4: バッチ処理（Cron）
+- 悪い例: 「job:cleanup スクリプトが存在する」
+- 良い例:
+  ```
+  AC4.3: cleanup ジョブは 30 日以上未使用のセッションを削除
+  - 前提: session テーブルに 29 日/30 日/31 日経過データが混在
+  - 操作: job:cleanup を実行
+  - 期待結果: 31 日 > のレコードのみ削除、削除件数をログ出力
+  - 検証レベル: Integration（実 DB）、E2E（ステージングで日次 Cron 監視）
+  ```
+
+### ケース5: フロントエンド（画面）
+- 悪い例: 「ログイン画面コンポーネントが存在する」
+- 良い例:
+  ```
+  AC5.5: ログインフォームは誤ったパスワードで API エラーを表示
+  - 前提: ユーザーが存在、間違った PW を入力
+  - 操作: Submit
+  - 期待結果:
+      1. /api/login が 401 を返すまでスピナー表示
+      2. フォーム上に "メールアドレスまたはパスワードが違います" を表示
+  - 検証レベル: Unit（フォームバリデーション）、E2E（Playwright で API モック無）
+  ```
+
+## 4. QA 仕様書・エージェント指示
+
+### QA 仕様書テンプレート
+```
+## 機能名
+- 背景/価値:
+- 関連 AC:
+- テスト範囲: <Unit/Integration/E2E/Browser>（担当者or自動化）
+- シナリオ:
+  1. タイトル
+     - 前提:
+     - 操作:
+     - 期待結果:
+     - ログ/メトリクス確認方法:
+- 非対象（アウトオブスコープ）:
+- エビデンス（スクショ/ログ）の保存場所:
+```
+※ 構造確認チェックは「非対象」に明記し、必要に応じてリントや型チェックに委譲する。
+
+### エージェント指示
+- **task-executer**
+  - AC で指定された振る舞いをテストで再現しているか確認。
+  - 期待結果を実装ではなく外部契約（レスポンス、イベント、DB 状態）に結び付ける。
+  - 「構造だけを確認するテスト」は reject（例: `expect(fileExists).toBe(true)` など）。
+- **task-qa**（🔴 ATDD準拠・動作確認必須）
+  - **Phase 1-2: テスト設計**
+    - AC に対応する Given/When/Then 形式のテストシナリオを設計。
+    - 構造確認だけのテストは設計禁止（「ファイルが存在する」「ビルドが成功する」等）。
+  - **Phase 3: 動作確認実施（🔴 最重要・必須）**
+    - 画面修正 → **ブラウザテスト（Playwright MCP）** で `browser_navigate` → `browser_snapshot` → 操作 → 結果確認
+    - API修正 → **API打鍵テスト（curl）** で `curl -i` リクエスト送信・レスポンス確認
+    - **ビルド/Lint成功だけでSUCCESSと判定することは禁止**
+    - **動作確認を実施せずにSUCCESSと判定することは禁止**
+    - 動作確認の実行ログを報告に必ず含める
+  - **Phase 4: 自動テスト**
+    - pnpm test, lint, build, typecheck を実行
+  - **Phase 5: 結果報告**
+    - 「Phase 3: 動作確認実施記録」セクションが空の場合、SUCCESSは認められない
+    - AC ごとの検証結果と検証方法を明記
+
+## 5. チェックリスト
+
+### 要件レビュー
+- [ ] AC は「条件/操作/期待結果」が揃っているか。
+- [ ] 観測可能なアウトプットで確認できるか。
+- [ ] ビジネス価値やユーザー影響が説明されているか。
+- [ ] ハッピーパスと主要な異常系が含まれているか。
+- [ ] テストレベルと責任者が明記されているか。
+- [ ] 実装構造への指示（ファイル名/クラス名など）が混入していないか。
+
+### テストレビュー
+- [ ] テスト名・説明が AC やビジネスルールを反映しているか。
+- [ ] 入力→操作→期待結果が可読な形で記述されているか。
+- [ ] 価値のないテスト（構造確認のみ、実装に強く依存）が存在しないか。
+- [ ] フェイル時に原因が特定できるアサーション/ログか。
+- [ ] 実行コスト（時間/環境構築）が妥当か、冗長なダブりがないか。
+- [ ] シナリオのエビデンス（ログ/スクショ）が保存・共有されるか。
+
+---
+
+## 6. QAテストの責務分離
+
+### 単体テスト vs QAテスト
+
+| 観点 | 単体テスト (Unit) | QAテスト (Integration/E2E) |
+|-----|------------------|---------------------------|
+| **担当者** | task-executer（開発者） | task-qa（QAエンジニア） |
+| **ツール** | Jest/Vitest | ブラウザテスト（Playwright MCP）、API打鍵テスト（curl） |
+| **対象** | コンポーネント、関数、Hook等の個別動作 | 画面フロー、API連携、データ永続化等の統合動作 |
+| **モック** | 外部依存はモック化 | 実際のインフラ接続 |
+| **目的** | 単一モジュールの意思決定ロジック検証 | ユーザー視点での最終価値確認 |
+
+**重要**: QAテストは単体テストではカバーできない**統合確認**を行うことが目的です。
+
+---
+
+## 7. QA実行フロー（5 Phase）
+
+```
+Phase 1: 事前確認
+  ├── シナリオテスト仕様（scenarios.md）の確認
+  ├── 必須自動テストの実行（pnpm test/lint/build/typecheck）
+  └── すべて成功 → Phase 2へ / 失敗 → 即座にFAILURE
+
+Phase 2: 実装整合性チェック
+  ├── requirements.md の AC と実装の対応確認
+  ├── design.md の設計と実装の整合性確認
+  └── 不整合発見 → 差し戻し判断
+
+Phase 3: 動作確認実施（🔴 最重要・必須）
+  ├── 画面修正 → Playwright MCP で操作・確認
+  ├── API修正 → Curl でリクエスト・レスポンス確認
+  └── 動作確認なしでのSUCCESS判定は禁止
+
+Phase 4: シナリオテスト実行
+  ├── scenarios.md の該当シナリオを実行
+  └── 複数タスクをまたぐフローの統合確認
+
+Phase 5: 結果報告
+  ├── qa-tests/ に結果を記録
+  ├── 失敗時は原因分類（A/B/C/D）
+  └── 次アクション決定（finisher/executer/qa-retry）
+```
+
+**禁止事項**:
+- ビルド/Lint成功だけでSUCCESSと判定すること
+- Phase 3（動作確認）を実施せずにSUCCESSと判定すること
+
+---
+
+## 8. 失敗原因分類（A/B/C/D）
+
+QAテスト失敗時、以下の4分類のいずれかに分類し、適切な戻し先を決定します。
+
+### 8.1 分類フローチャート
+
+```
+QAテスト失敗
+    ↓
+質問1: 実装コードに問題があるか？
+  YES → 【A: 実装ミス】 → task-executer
+  NO → 質問2へ
+    ↓
+質問2: requirements.md の受け入れ条件が不正確・不完全か？
+  YES → 【B: 要件齟齬】 → requirements.md修正 → task-executer
+  NO → 質問3へ
+    ↓
+質問3: design.md の設計・アーキテクチャに問題があるか？
+  YES → 【C: 設計不備】 → design.md修正 → task-executer
+  NO → 質問4へ
+    ↓
+質問4: 環境・インフラ・テストツールに問題があるか？
+  YES → 【D: 環境問題】 → qa再実行
+  NO → デフォルトで【A: 実装ミス】として扱う
+```
+
+### 8.2 各分類の定義
+
+| 分類 | 定義 | 判定基準例 | 戻し先 |
+|-----|------|----------|-------|
+| **A: 実装ミス** | コードの論理エラー、バグ、実装漏れ | TypeScriptエラー、ランタイムエラー、ロジック不具合、単体テスト失敗 | task-executer |
+| **B: 要件齟齬** | requirements.md の受け入れ条件が実際の要求と異なる | ACの期待結果が曖昧、ビジネスルール未記載、AC間の矛盾 | requirements.md修正 → task-executer |
+| **C: 設計不備** | design.md のアーキテクチャ・設計方針に問題 | トランザクション設計不備、スキーマ設計ミス、インターフェース不備 | design.md修正 → task-executer |
+| **D: 環境問題** | テスト環境、インフラ、ツールの問題 | DB接続エラー、Playwright接続失敗、タイムアウト、ポート競合 | qa再実行 |
+
+### 8.3 判定の優先順位
+
+複数の分類に該当する可能性がある場合：
+
+1. **D（環境問題）**: エラーメッセージが明確に環境起因の場合は最優先
+2. **B（要件齟齬）**: requirements.md の記載が不正確・不完全な場合
+3. **C（設計不備）**: design.md のアーキテクチャに問題がある場合
+4. **A（実装ミス）**: デフォルト（不明な場合は実装ミスとして扱う）
+
+### 8.4 実践例
+
+#### 例1: トークン検証エラー
+```
+症状: TypeError: Cannot read property 'token' of undefined
+分析: 質問1 YES（nullチェック漏れ）
+判定: A: 実装ミス → task-executer
+```
+
+#### 例2: バリデーションエラーメッセージ不一致
+```
+症状: requirements.md「400エラーを返す」、実装「422エラーを返す」
+分析: 質問1 NO、質問2 YES（ステータスコードが不明確）
+判定: B: 要件齟齬 → requirements.md修正 → task-executer
+```
+
+#### 例3: トランザクション未実装
+```
+症状: 競合状態で整合性が保証されない
+分析: 質問1 NO、質問2 NO、質問3 YES（トランザクション設計欠如）
+判定: C: 設計不備 → design.md修正 → task-executer
+```
+
+#### 例4: PostgreSQL接続エラー
+```
+症状: Error: connect ECONNREFUSED 127.0.0.1:5432
+分析: 質問1-3 NO、質問4 YES（PostgreSQLコンテナ未起動）
+判定: D: 環境問題 → qa再実行
+```
+
+---
+
+## 9. 動作確認ツールの使用ガイド
+
+### 9.1 ブラウザテスト（Playwright MCP）
+
+**用途**: ブラウザ操作による画面フロー・UI動作の確認
+
+**基本フロー**:
+```
+1. browser_navigate でURLに移動
+2. browser_snapshot でページ状態を取得
+3. browser_click / browser_type で操作
+4. browser_snapshot で結果確認
+5. 必要に応じてスクリーンショット保存
+```
+
+**使用例（ログインフォーム）**:
+```
+手順1: ログイン画面に移動 (http://localhost:3000/auth/login)
+手順2: スナップショット取得 → メールアドレス入力欄が表示されることを確認
+手順3: メールアドレス入力: test@example.com
+手順4: パスワード入力: password123
+手順5: 送信ボタンをクリック
+手順6: スナップショット取得 → ダッシュボード画面に遷移していることを確認
+```
+
+### 9.2 API打鍵テスト（curl）
+
+**用途**: HTTPリクエスト/レスポンスによるAPI動作の確認
+
+**基本フロー**:
+```bash
+# GETリクエスト
+curl -i http://localhost:3000/api/users
+
+# POSTリクエスト（JSON）
+curl -i -X POST http://localhost:3000/api/auth/login \
+  -H "Content-Type: application/json" \
+  -d '{"email":"test@example.com","password":"password123"}'
+
+# 認証付きリクエスト
+curl -i http://localhost:3000/api/protected \
+  -H "Authorization: Bearer {token}"
+```
+
+**確認項目**:
+- HTTPステータスコード（200, 400, 401, 403, 404, 500等）
+- レスポンスボディの内容
+- レスポンスヘッダー（Content-Type, Set-Cookie等）
+
+### 9.3 テストシナリオ記述形式
+
+QAテスト仕様書では、以下の表形式で手順を記述します：
+
+| No | 手順 | 確認項目 | 期待値 | 結果 | 備考 |
+|----|------|---------|--------|------|------|
+| 1 | ログイン画面に移動 (http://localhost:3000/auth/login) | URLが正しい | /auth/login | - | - |
+| 2 | スナップショット取得 | メールアドレス入力欄が表示される | input[data-testid="email-input"]が存在 | - | - |
+| 3 | メールアドレス入力: test@example.com | - | - | - | - |
+| 4 | 送信ボタンをクリック | ローディング表示される | スピナーアイコンが表示 | - | - |
+
+**重要な原則**:
+- 手順は自然言語で簡潔に記述
+- mcp__playwright などのコマンドは記載しない
+- 「-」は手順のみで確認項目がない場合に使用