@arimakouyou/spec-workflow-mcp 2.2.7

package/.claude-plugin/skills/integration-test/references/fixture-catalog.md

@@ -0,0 +1,155 @@
+# 共通ヘルパー・Fixture カタログ
+
+`tests/integration/helpers/` で定義するテスト用ヘルパーの一覧。
+
+## TestContext（中核ヘルパー）
+
+各テストで独立した DB コンテナと Axum アプリケーションを提供する。
+
+```rust
+pub struct TestContext {
+    pub app: Router,
+    pub db_pool: DbPool,
+    pub valkey: ConnectionManager,
+    _pg_container: ContainerAsync<Postgres>,
+}
+
+impl TestContext {
+    /// 新しいテストコンテキストを作成（実 PostgreSQL コンテナ起動）
+    pub async fn new() -> Self { /* ... */ }
+
+    /// 外部 API がエラーを返す設定で作成
+    pub async fn with_failing_external_api() -> Self { /* ... */ }
+
+    /// GET リクエスト（認証ヘッダー付き）
+    pub async fn get(&self, path: &str) -> TestResponse { /* ... */ }
+
+    /// GET リクエスト（認証なし）
+    pub async fn get_without_auth(&self, path: &str) -> TestResponse { /* ... */ }
+
+    /// POST リクエスト（認証ヘッダー付き）
+    pub async fn post(&self, path: &str) -> RequestBuilder { /* ... */ }
+
+    /// PUT リクエスト（認証ヘッダー付き）
+    pub async fn put(&self, path: &str) -> RequestBuilder { /* ... */ }
+
+    /// DELETE リクエスト（認証ヘッダー付き）
+    pub async fn delete(&self, path: &str) -> TestResponse { /* ... */ }
+}
+```
+
+## DB 関連ヘルパー
+
+### PostgreSQL コンテナ
+
+```rust
+use testcontainers::runners::AsyncRunner;
+use testcontainers_modules::postgres::Postgres;
+
+async fn create_pg_container() -> (ContainerAsync<Postgres>, String) {
+    let container = Postgres::default().start().await.unwrap();
+    let port = container.get_host_port_ipv4(5432).await.unwrap();
+    let url = format!("postgres://postgres:postgres@localhost:{port}/postgres");
+    (container, url)
+}
+```
+
+### マイグレーション実行
+
+```rust
+use diesel_async::AsyncPgConnection;
+use diesel_migrations::{embed_migrations, EmbeddedMigrations, MigrationHarness};
+
+const MIGRATIONS: EmbeddedMigrations = embed_migrations!();
+
+async fn run_migrations(database_url: &str) {
+    // diesel の同期マイグレーションを blocking task で実行
+    let url = database_url.to_string();
+    tokio::task::spawn_blocking(move || {
+        use diesel::prelude::*;
+        let mut conn = PgConnection::establish(&url).unwrap();
+        conn.run_pending_migrations(MIGRATIONS).unwrap();
+    })
+    .await
+    .unwrap();
+}
+```
+
+### テストデータ投入 (Seed)
+
+```rust
+impl TestContext {
+    pub async fn seed_user(&self, new_user: &NewUser) -> User {
+        let mut conn = self.db_pool.get().await.unwrap();
+        diesel::insert_into(users::table)
+            .values(new_user)
+            .get_result(&mut conn)
+            .await
+            .unwrap()
+    }
+
+    pub async fn seed_users(&self, users: &[NewUser]) -> Vec<User> {
+        let mut conn = self.db_pool.get().await.unwrap();
+        diesel::insert_into(users::table)
+            .values(users)
+            .get_results(&mut conn)
+            .await
+            .unwrap()
+    }
+
+    pub async fn find_user_by_id(&self, id: i64) -> Option<User> {
+        let mut conn = self.db_pool.get().await.unwrap();
+        users::table.find(id)
+            .select(User::as_select())
+            .first(&mut conn)
+            .await
+            .optional()
+            .unwrap()
+    }
+}
+```
+
+## 認証ヘッダー
+
+```rust
+fn test_auth_header() -> HeaderMap {
+    let mut headers = HeaderMap::new();
+    headers.insert(
+        "Authorization",
+        HeaderValue::from_static("Bearer test-token-xxx"),
+    );
+    headers
+}
+```
+
+## Axum アプリ構築
+
+```rust
+async fn build_test_app(db_pool: DbPool, valkey: ConnectionManager) -> Router {
+    let state = AppState {
+        db_pool,
+        valkey,
+        config: Arc::new(test_config()),
+    };
+
+    // 本番と同じルーター構成を使用
+    crate::routes::routes()
+        .with_state(state)
+}
+```
+
+## Fixture 選択フロー
+
+```
+テストで何が必要？
+  ├─ DB アクセスが必要
+  │   └─ TestContext::new() を使用
+  │       ├─ テストデータ投入 → seed_user(), seed_users()
+  │       └─ DB 検証 → find_user_by_id(), find_user_by_email()
+  │
+  ├─ 外部 API のモック
+  │   └─ TestContext::with_failing_external_api() or カスタム trait 実装
+  │
+  └─ HTTP リクエスト送信
+      └─ ctx.get(), ctx.post(), ctx.put(), ctx.delete()
+```

package/.claude-plugin/skills/integration-test/references/parallel-execution.md

@@ -0,0 +1,124 @@
+# 並列実行フロー詳細
+
+Agent Teams を使った並列テスト作成の全フェーズ詳細。
+
+## チーム構成
+
+| 役割 | 数 | 責務 |
+|------|:--:|------|
+| Command（司令塔） | 1 | 分析・分担・監視・最終検証 |
+| Workers（テスト実装） | 1-2 | テストファイル作成 |
+| Pentagon（品質レビュー） | 1 | 品質ゲート判定 |
+
+## フェーズ詳細
+
+### P0: Parse & Analyze
+
+```
+入力: /integration-test users,posts
+  ↓
+カンマで分割 → ["users", "posts"]
+  ↓
+各対象を分析:
+  users → src/handlers/users.rs → src/db/repository/users.rs → src/models/user.rs
+  posts → src/handlers/posts.rs → src/db/repository/posts.rs → src/models/post.rs
+  ↓
+Worker 分担:
+  alpha → users (test_users.rs)
+  bravo → posts (test_posts.rs)
+```
+
+### P1: Setup Team
+
+1. 共通ヘルパーの確認
+   - `tests/integration/helpers/` が存在するか
+   - TestContext が対象ドメインで動作するか
+   - 新規 fixture が必要なら Command が追加
+
+2. ホワイトボード作成
+   - `whiteboard-template.md` に従い作成
+   - Key Questions を 1-3 個設定
+
+### P2: Launch Agents
+
+Workers と Pentagon を `.claude/agents/` のエージェント定義を使ってサブエージェントとして起動。
+
+**起動順序:**
+1. Pentagon（`subagent_type: "integ-test-auditor"`）— 起動後はレビュー依頼待ち
+2. Workers（`subagent_type: "integ-test-worker"`）— alpha, bravo を並列起動
+
+```
+# Pentagon 起動
+Agent(subagent_type: "integ-test-auditor", prompt: "ホワイトボード: {whiteboard_path}\nレビュー依頼を待機")
+
+# Worker 起動（並列）
+Agent(subagent_type: "integ-test-worker", prompt: "Worker名: alpha\nドメイン: {domain_a}\n...")
+Agent(subagent_type: "integ-test-worker", prompt: "Worker名: bravo\nドメイン: {domain_b}\n...")
+```
+
+### P3: Monitor & Facilitate
+
+```
+while 未完了タスクが存在:
+  ├─ Worker 完了を検出
+  │   ├─ ホワイトボードに Findings 転記
+  │   ├─ Pentagon にレビュー依頼
+  │   └─ Pentagon 結果を待つ
+  │       ├─ PASS → Quality Gate 更新、次タスクがあれば割当
+  │       └─ FAIL → レビュー回数確認
+  │           ├─ < 3 回 → Worker に差し戻し
+  │           └─ = 3 回 → 残存指摘付きで完了
+  └─ 全タスク完了 → P4 へ
+```
+
+**差し戻し時の Worker 再実行:**
+- 元の prompt に Pentagon の指摘事項を追加
+- 「修正箇所」と「修正理由」を明示
+
+### P4: Final Verification
+
+```bash
+# 全テスト実行
+cargo test --test integration_users --test integration_posts -- --nocapture
+
+# コード品質チェック
+rustfmt tests/integration/test_users.rs tests/integration/test_posts.rs
+cargo clippy --tests --quiet
+```
+
+失敗した場合:
+- コンパイルエラー → Command が直接修正
+- テスト失敗 → 原因を特定し Command が修正 or Worker に再依頼
+- clippy 警告 → Command が修正
+
+### P5: Cleanup & Report
+
+1. ホワイトボードを `.claude/_docs/deleted/` に移動
+2. 最終レポート出力
+
+```
+integration-test 並列実装完了
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+対象: users, posts
+
+生成ファイル:
+  tests/integration/test_users.rs (12 tests)
+  tests/integration/test_posts.rs (10 tests)
+
+テスト結果:
+  22 tests passed, 0 failed
+
+品質ゲート:
+  test_users.rs: PASS (cycle 1)
+  test_posts.rs: PASS (cycle 2)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+## タイムアウトと中断
+
+| 状況 | 対処 |
+|------|------|
+| Worker が 10 分以上応答なし | Command が状態確認、必要なら再起動 |
+| Pentagon が 5 分以上応答なし | Command が状態確認、必要なら再起動 |
+| 3 回差し戻し後も品質不足 | 残存指摘付きで完了、レポートに注記 |

package/.claude-plugin/skills/integration-test/references/quality-gate.md

@@ -0,0 +1,80 @@
+# 品質ゲート
+
+Pentagon（Reviewer）がテストファイルをレビューする際の判定基準。
+全項目 PASS で合格、1 項目でも FAIL で差し戻し。
+
+## 判定項目
+
+### A. 5 分類カバレッジ
+
+- [ ] 正常系テストが存在する
+- [ ] 異常系テスト（バリデーションエラー、404 等）が存在する
+- [ ] 境界値テスト（空リスト、最大長等）が存在する
+- [ ] エッジケース（重複、同時更新等）が考慮されている
+- [ ] 外部依存エラー時の挙動がテストされている（該当する場合）
+
+### B. 振る舞い契約の検証
+
+- [ ] HTTP ステータスコードが正しい
+- [ ] レスポンスボディの構造が正しい（フィールド名、型）
+- [ ] DB の状態変更が検証されている（POST/PUT/DELETE）
+- [ ] エラーレスポンスのフォーマットが統一されている
+
+### C. コード品質
+
+- [ ] Given-When-Then 構造が明確
+- [ ] テスト関数名が振る舞いを説明している
+- [ ] テスト間に依存がない（独立して実行可能）
+- [ ] 不要な assert がない（1 テスト 1 概念）
+- [ ] ハードコードされたマジックナンバーがない
+
+### D. Hermetic & Deterministic
+
+- [ ] 各テストが独立した DB 状態を持つ（testcontainers or トランザクション）
+- [ ] 外部 API は trait DI でテストダブルに差し替えている
+- [ ] 時刻依存のテストは Clock trait で制御している
+- [ ] テスト実行順序に依存しない
+- [ ] `sleep` や固定タイムアウトに依存しない
+
+### E. Rust 固有
+
+- [ ] `#[tokio::test]` が正しく使われている
+- [ ] `unwrap()` はテストコード内でのみ使用（本番コードに混入していない）
+- [ ] `clippy` 警告がない
+- [ ] `rustfmt` でフォーマット済み
+
+## 判定フロー
+
+```
+全項目チェック
+  ├─ 全 PASS → PASS（テスト承認）
+  ├─ FAIL あり（修正可能）→ FAIL + 具体的な修正指示
+  └─ FAIL あり（設計レベル）→ FAIL + 設計変更の提案
+```
+
+## レポートフォーマット
+
+```
+[Pentagon Review] {test_file}
+
+判定: PASS / FAIL
+
+A. 5分類カバレッジ: PASS / FAIL
+   {不足があれば具体的に}
+
+B. 振る舞い契約: PASS / FAIL
+   {問題があれば具体的に}
+
+C. コード品質: PASS / FAIL
+   {問題があれば具体的に}
+
+D. Hermetic: PASS / FAIL
+   {問題があれば具体的に}
+
+E. Rust 固有: PASS / FAIL
+   {問題があれば具体的に}
+
+修正指示:
+  1. {具体的な修正内容}
+  2. {具体的な修正内容}
+```

package/.claude-plugin/skills/integration-test/references/test-case-design.md

@@ -0,0 +1,88 @@
+# テストケース設計ガイド
+
+## 5 分類体系
+
+インテグレーションテストのケースは以下の 5 分類で網羅する。
+
+| 分類 | 説明 | 例 |
+|------|------|-----|
+| **正常系** | 正しい入力で期待通りの結果 | ユーザー作成成功、一覧取得 |
+| **異常系** | 不正な入力やエラー条件 | バリデーションエラー、認証エラー |
+| **境界値** | 境界条件の動作確認 | 空リスト、最大長、ページ境界 |
+| **エッジケース** | 特殊な状況 | 重複データ、同時更新、空文字 |
+| **外部依存エラー** | 外部システムの障害 | DB 接続エラー、外部 API タイムアウト |
+
+## HTTP メソッド別必須テストケース
+
+### GET 一覧
+
+| 分類 | テストケース |
+|------|------------|
+| 正常系 | データが存在する場合に全件返す |
+| 境界値 | データが0件の場合に空配列を返す |
+| 正常系 | ページネーションが正しく動作する |
+| 境界値 | 最終ページの件数が正しい |
+| 異常系 | 認証なしで 401 |
+
+### GET 詳細
+
+| 分類 | テストケース |
+|------|------------|
+| 正常系 | 存在する ID で正しいデータを返す |
+| 異常系 | 存在しない ID で 404 |
+| 異常系 | 不正な ID 形式で 400 |
+| 異常系 | 認証なしで 401 |
+
+### POST 作成
+
+| 分類 | テストケース |
+|------|------------|
+| 正常系 | 有効な入力で 201 + DB に保存 |
+| 異常系 | 必須フィールド欠落で 400 |
+| 異常系 | バリデーション違反で 400 |
+| エッジケース | 重複データで 409 (Conflict) |
+| 外部依存 | 外部 API エラー時にロールバック |
+| 異常系 | 認証なしで 401 |
+
+### PUT/PATCH 更新
+
+| 分類 | テストケース |
+|------|------------|
+| 正常系 | 有効な入力で更新成功 + DB に反映 |
+| 異常系 | 存在しない ID で 404 |
+| 異常系 | バリデーション違反で 400 |
+| 境界値 | 変更なし (同じ値) で正常応答 |
+| 異常系 | 認証なしで 401 |
+
+### DELETE 削除
+
+| 分類 | テストケース |
+|------|------------|
+| 正常系 | 存在する ID で 204 + DB から削除 |
+| 異常系 | 存在しない ID で 404 |
+| エッジケース | 関連データがある場合の挙動 |
+| 異常系 | 認証なしで 401 |
+
+## テストケース導出手順
+
+1. **handler を読む**: ルート定義からエンドポイント一覧を把握
+2. **リクエスト/レスポンス型を読む**: DTO の構造からバリデーション条件を特定
+3. **repository を読む**: クエリロジックからエッジケースを特定
+4. **5 分類マトリクスに当てはめる**: 上記のテーブルを参考にケースを列挙
+
+## ケース数の目安
+
+| エンドポイント種別 | 最小ケース数 |
+|------------------|:----------:|
+| GET 一覧 | 4-5 |
+| GET 詳細 | 3-4 |
+| POST 作成 | 5-6 |
+| PUT/PATCH 更新 | 4-5 |
+| DELETE 削除 | 3-4 |
+
+## UT との棲み分け
+
+| テスト種別 | 対象 | DB | 外部 API |
+|-----------|------|:--:|:-------:|
+| UT | ビジネスロジック単体 | mock/fake | mock |
+| IT | HTTP → handler → repository → DB 全層 | 実 DB (testcontainers) | trait DI |

package/.claude-plugin/skills/integration-test/references/test-patterns.md

@@ -0,0 +1,215 @@
+# テスト実装パターン
+
+インテグレーションテストで使う典型的なパターン集。
+
+## ファイル構成テンプレート
+
+```
+tests/
+├── integration.rs           # テストバイナリエントリポイント（mod で下記を参照）
+├── integration/
+│   ├── helpers/
+│   │   ├── mod.rs          # 共通ヘルパー
+│   │   ├── app.rs          # テスト用 Axum app 構築
+│   │   ├── db.rs           # testcontainers DB セットアップ
+│   │   └── auth.rs         # テスト用認証ヘッダー
+│   ├── test_users.rs       # ドメインごとのテストファイル
+│   └── test_posts.rs
+```
+
+## パターン1: リスト取得 (GET /)
+
+```rust
+#[tokio::test]
+async fn list_users_returns_all_users() {
+    let ctx = TestContext::new().await;
+    // Given: DB にテストデータを投入
+    ctx.seed_users(&[
+        NewUser { name: "Alice", email: "alice@example.com" },
+        NewUser { name: "Bob", email: "bob@example.com" },
+    ]).await;
+
+    // When: GET /api/users
+    let response = ctx.get("/api/users").await;
+
+    // Then
+    assert_eq!(response.status(), StatusCode::OK);
+    let body: Vec<UserResponse> = response.json().await;
+    assert_eq!(body.len(), 2);
+}
+```
+
+## パターン2: 作成 (POST /)
+
+```rust
+#[tokio::test]
+async fn create_user_returns_created() {
+    let ctx = TestContext::new().await;
+
+    // When
+    let response = ctx.post("/api/users")
+        .json(&json!({ "name": "Alice", "email": "alice@example.com" }))
+        .await;
+
+    // Then: レスポンス検証
+    assert_eq!(response.status(), StatusCode::CREATED);
+    let body: UserResponse = response.json().await;
+    assert_eq!(body.name, "Alice");
+
+    // Then: DB にも保存されたことを検証
+    let user = ctx.find_user_by_email("alice@example.com").await;
+    assert!(user.is_some());
+}
+```
+
+## パターン3: 詳細取得 (GET /:id)
+
+```rust
+#[tokio::test]
+async fn get_user_returns_user_when_exists() {
+    let ctx = TestContext::new().await;
+    let user = ctx.seed_user(&NewUser { name: "Alice", email: "alice@example.com" }).await;
+
+    let response = ctx.get(&format!("/api/users/{}", user.id)).await;
+
+    assert_eq!(response.status(), StatusCode::OK);
+    let body: UserResponse = response.json().await;
+    assert_eq!(body.id, user.id);
+}
+
+#[tokio::test]
+async fn get_user_returns_not_found_when_missing() {
+    let ctx = TestContext::new().await;
+
+    let response = ctx.get("/api/users/99999").await;
+
+    assert_eq!(response.status(), StatusCode::NOT_FOUND);
+}
+```
+
+## パターン4: 更新 (PUT /:id)
+
+```rust
+#[tokio::test]
+async fn update_user_modifies_existing_record() {
+    let ctx = TestContext::new().await;
+    let user = ctx.seed_user(&NewUser { name: "Alice", email: "alice@example.com" }).await;
+
+    let response = ctx.put(&format!("/api/users/{}", user.id))
+        .json(&json!({ "name": "Alice Updated" }))
+        .await;
+
+    assert_eq!(response.status(), StatusCode::OK);
+
+    // DB も更新されたことを検証
+    let updated = ctx.find_user_by_id(user.id).await.unwrap();
+    assert_eq!(updated.name, "Alice Updated");
+}
+```
+
+## パターン5: 削除 (DELETE /:id)
+
+```rust
+#[tokio::test]
+async fn delete_user_removes_record() {
+    let ctx = TestContext::new().await;
+    let user = ctx.seed_user(&NewUser { name: "Alice", email: "alice@example.com" }).await;
+
+    let response = ctx.delete(&format!("/api/users/{}", user.id)).await;
+
+    assert_eq!(response.status(), StatusCode::NO_CONTENT);
+
+    // DB から削除されたことを検証
+    let deleted = ctx.find_user_by_id(user.id).await;
+    assert!(deleted.is_none());
+}
+```
+
+## パターン6: parametrize (rstest)
+
+```rust
+use rstest::rstest;
+
+const LONG_NAME: &str = "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"; // 256文字
+
+#[rstest]
+#[case("", StatusCode::BAD_REQUEST)]
+#[case(LONG_NAME, StatusCode::BAD_REQUEST)]
+#[case("valid_name", StatusCode::CREATED)]
+#[tokio::test]
+async fn create_user_validates_name(
+    #[case] name: &str,
+    #[case] expected_status: StatusCode,
+) {
+    let ctx = TestContext::new().await;
+
+    let response = ctx.post("/api/users")
+        .json(&json!({ "name": name, "email": "test@example.com" }))
+        .await;
+
+    assert_eq!(response.status(), expected_status);
+}
+```
+
+## パターン7: ページネーション
+
+```rust
+#[tokio::test]
+async fn list_users_supports_pagination() {
+    let ctx = TestContext::new().await;
+    ctx.seed_users_count(25).await;
+
+    // 1ページ目
+    let response = ctx.get("/api/users?page=1&per_page=10").await;
+    assert_eq!(response.status(), StatusCode::OK);
+    let body: PaginatedResponse<UserResponse> = response.json().await;
+    assert_eq!(body.items.len(), 10);
+    assert_eq!(body.total, 25);
+
+    // 3ページ目（残り5件）
+    let response = ctx.get("/api/users?page=3&per_page=10").await;
+    let body: PaginatedResponse<UserResponse> = response.json().await;
+    assert_eq!(body.items.len(), 5);
+}
+```
+
+## パターン8: 外部 API エラー時の挙動
+
+```rust
+#[tokio::test]
+async fn create_user_returns_error_when_external_api_fails() {
+    let ctx = TestContext::with_failing_external_api().await;
+
+    let response = ctx.post("/api/users")
+        .json(&json!({ "name": "Alice", "email": "alice@example.com" }))
+        .await;
+
+    assert_eq!(response.status(), StatusCode::BAD_GATEWAY);
+
+    // DB にはロールバックされていることを検証
+    let user = ctx.find_user_by_email("alice@example.com").await;
+    assert!(user.is_none());
+}
+```
+
+## パターン9: 認証エラー
+
+```rust
+#[tokio::test]
+async fn unauthenticated_request_returns_401() {
+    let ctx = TestContext::new().await;
+
+    let response = ctx.get_without_auth("/api/users").await;
+
+    assert_eq!(response.status(), StatusCode::UNAUTHORIZED);
+}
+```
+
+## よくあるエラーと対処法
+
+| エラー | 原因 | 対処 |
+|--------|------|------|
+| `connection refused` | testcontainers コンテナ未起動 | Docker デーモンが起動しているか確認 |
+| `table not found` | マイグレーション未実行 | TestContext でマイグレーション実行を確認 |
+| テスト間でデータが干渉 | トランザクション未ロールバック | 各テストで独立した DB / トランザクションを使用 |
+| `tokio runtime` エラー | `#[test]` を使っている | `#[tokio::test]` に変更 |