multi-agent-e2e-validation

マルチエージェント E2E 検証

自己進化型スキル：このスキルは使用を通じて改善されます。手順に誤りがある、パラメーターにずれが生じている、または回避策が必要になった場合は、後回しにせず、ただちにこのファイルを修正してください。実際に再現できる問題がある場合にのみ更新してください。

概要

データベースのリファクタリングを包括的にテストするため、並列検証エージェントを起動するための規定ワークフローです。QuestDB への移行では、本番環境にリリースされていた可能性のある重大なバグを5件（システム障害率100％）特定しました。

このスキルを使用するタイミング

以下の場合にこのスキルを使用してください。

• データベースのリファクタリング（例：v3.x のファイルベースから v4.x の QuestDB への移行）
• 検証が必要なスキーマ移行
• 大量データ取り込みパイプラインのテスト
• 複数の検証レイヤーを伴うシステム移行
• データベース中心のシステムのリリース前検証

主な成果：

• 包括的なカバレッジを実現する並列エージェント実行
• 構造化された検証レポート（VALIDATION_FINDINGS.md）
• 重大度分類（Critical／Medium／Low）によるバグの発見
• リリース準備状況の評価

基本的な方法論

1. 検証アーキテクチャ（3層モデル）

レイヤー1：環境のセットアップ

• コンテナーのオーケストレーション（Colima/Docker）
• データベースのデプロイとスキーマの適用
• 接続性の検証（ILP、PostgreSQL、HTTP ポート）
• 設定ファイルの作成と検証

レイヤー2：データフローの検証

• 大量取り込みのテスト（CloudFront → QuestDB）
• SLO に対するパフォーマンスのベンチマーク
• 複数月にわたるデータの取り込み
• 重複排除のテスト（再取り込みのシナリオ）
• 型変換の検証（FLOAT→LONG キャスト）

レイヤー3：クエリーインターフェースの検証

• 高水準のクエリーメソッド（get_latest、get_range、execute_sql）
• エッジケース（limit=1、月をまたぐ境界）
• エラー処理（無効なシンボル、日付、パラメーター）
• ギャップ検出 SQL の互換性

2. エージェントのオーケストレーションパターン

逐次実行と並列実行：

Agent 1 (Environment) → [SEQUENTIAL - prerequisite]
  ↓
Agent 2 (Bulk Loader) → [PARALLEL with Agent 3]
Agent 3 (Query Interface) → [PARALLEL with Agent 2]

依存関係のルール：データフロー／クエリーの検証を行う前に、環境の検証に合格する必要があります。

動的な Todo 管理：

• 上位レベルの計画（ADR で定義されたフェーズ）から開始します
• 完了したエージェントを Todo リストから削除します
• バグが見つかった場合は Todo リストを拡張します（例：エージェント3が Bug #5 を発見）
• VALIDATION_FINDINGS.md を段階的に更新します

3. 検証スクリプトの構成

各エージェントが作成するもの：

1. テストスクリプト（例：test_bulk_loader.py）
   • 明確な合否基準を備えた5つ以上のテスト関数
   • 構造化された出力（テスト名、結果、詳細）
   • 最後にサマリーレポート
2. 成果物（ログ、設定ファイル、証跡）
3. 調査結果レポート（バグ、重大度、修正案）

テスト構成の例：

def test_feature(conn):
    """Test 1: Feature description"""
    print("=" * 80)
    print("TEST 1: Feature description")
    print("=" * 80)

    results = {}

    # Test 1a: Subtest name
    print("\n1a. Testing subtest:")
    result_1a = perform_test()
    print(f"   Result: {result_1a}")
    results["subtest_1a"] = result_1a == expected_1a

    # Summary
    print("\n" + "-" * 80)
    all_passed = all(results.values())
    print(f"Test 1 Results: {'✓ PASS' if all_passed else '✗ FAIL'}")
    for test_name, passed in results.items():
        print(f"  - {test_name}: {'✓' if passed else '✗'}")

    return {"success": all_passed, "details": results}

4. バグの分類と追跡

重大度レベル：

• 🔴 Critical：システム障害率100％（例：API の不一致、タイムスタンプの破損）
• 🟡 Medium：機能の劣化（例：SLO を下回るパフォーマンス）
• 🟢 Low：軽微な問題、エッジケース

バグレポートの形式：

#### Bug N: Descriptive Name (**SEVERITY** - Status)

**Location**: `file/path.py:line`

**Issue**: One-sentence description

**Impact**: Quantified impact (e.g., "100% ingestion failure")

**Root Cause**: Technical explanation

**Fix Applied**: Code changes with before/after

**Verification**: Test results proving fix

**Status**: ✅ FIXED / ⚠️ PARTIAL / ❌ OPEN

5. リリース準備状況の判断フレームワーク

Go／No-Go の基準：

BLOCKER = Any Critical bug unfixed
SHIP = All Critical bugs fixed + (Medium bugs acceptable OR fixed)
DEFER = >3 Medium bugs unfixed OR any High-severity bug

判断例：

• Critical なバグが5件見つかる → すべて修正済み ✅
• Medium のバグが1件（パフォーマンスがSLOを55％下回る） → 許容可能 ✅
• 判定：リリース準備完了

ワークフロー：手順

ステップ1：検証計画の作成（ADR 主導）

入力：ADR ドキュメント（例：ADR-0002 QuestDB Refactor） 出力：3～7個のエージェントによる検証計画

計画の構成：

## Validation Agents

### Agent 1: Environment Setup

- Deploy QuestDB via Docker
- Apply schema.sql
- Validate connectivity (ILP, PG, HTTP)
- Create .env configuration

### Agent 2: Bulk Loader Validation

- Test CloudFront → QuestDB ingestion
- Benchmark performance (target: >100K rows/sec)
- Validate deduplication (re-ingestion test)
- Multi-month ingestion test

### Agent 3: Query Interface Validation

- Test get_latest() with various limits
- Test get_range() with date boundaries
- Test execute_sql() with parameterized queries
- Test detect_gaps() SQL compatibility
- Test error handling (invalid inputs)

ステップ2：エージェント1を実行（環境）

ディレクトリー構成：

tmp/e2e-validation/
  agent-1-env/
    test_environment_setup.py
    questdb.log
    config.env
    schema-check.txt

検証チェックリスト：

• ✅ コンテナーが実行中
• ✅ ポートにアクセス可能（9009 ILP、8812 PG、9000 HTTP）
• ✅ エラーなくスキーマを適用済み
• ✅ .env ファイルを作成済み

ステップ3：エージェント2～3を並列実行

エージェント2：一括ローダー

tmp/e2e-validation/
  agent-2-bulk/
    test_bulk_loader.py
    ingestion_benchmark.txt
    deduplication_test.txt

エージェント3：クエリーインターフェース

tmp/e2e-validation/
  agent-3-query/
    test_query_interface.py
    gap_detection_test.txt

実行：

# Terminal 1
cd tmp/e2e-validation/agent-2-bulk
uv run python test_bulk_loader.py

# Terminal 2
cd tmp/e2e-validation/agent-3-query
uv run python test_query_interface.py

ステップ4：VALIDATION_FINDINGS.md に調査結果を記録

テンプレート：

# E2E Validation Findings Report

**Validation ID**: ADR-XXXX
**Branch**: feat/database-refactor
**Date**: YYYY-MM-DD
**Target Release**: vX.Y.Z
**Status**: [BLOCKED / READY / IN_PROGRESS]

## Executive Summary

E2E validation discovered **N critical bugs** that would have caused [impact]:

| Finding | Severity | Status | Impact       | Agent   |
| ------- | -------- | ------ | ------------ | ------- |
| Bug 1   | Critical | Fixed  | 100% failure | Agent 2 |

**Recommendation**: [RELEASE READY / BLOCKED / DEFER]

## Agent 1: Environment Setup - [STATUS]

...

## Agent 2: [Name] - [STATUS]

...

ステップ 5：修正を繰り返す

バグごとに：

1. VALIDATION_FINDINGS.md に重大度を 🔴／🟡／🟢 で記録します
2. ソースコードに修正を適用します
3. 失敗したテストを再実行します
4. バグのステータスを ✅ FIXED に更新します
5. セマンティックなメッセージでコミットします（例：fix: correct timestamp parsing in CSV ingestion）

修正コミットの例：

git add src/gapless_crypto_clickhouse/collectors/questdb_bulk_loader.py
git commit -m "fix: prevent pandas from treating first CSV column as index

BREAKING CHANGE: All timestamps were defaulting to epoch 0 (1970-01)
due to pandas read_csv() auto-indexing. Added index_col=False to
preserve first column as data.

Fixes #ABC-123"

ステップ 6：最終検証とリリース判断

すべてのテストを実行します：

/usr/bin/env bash << 'SKILL_SCRIPT_EOF'
cd tmp/e2e-validation
for agent in agent-*; do
    echo "=== Running $agent ==="
    cd $agent
    uv run python test_*.py
    cd ..
done
SKILL_SCRIPT_EOF

VALIDATION_FINDINGS.md のステータスを更新します：

• 重大なバグの件数：修正済み X 件、未解決 Y 件
• 中程度のバグの件数：修正済み X 件、未解決 Y 件
• 判断フレームワークを適用します
• Status フィールドを ✅ RELEASE READY または ❌ BLOCKED に更新します

実例：QuestDB のリファクタリング検証

コンテキスト：ファイルベースのストレージ（v3.x）から QuestDB（v4.0.0）への移行

見つかったバグ：

1. 🔴 Sender API の不一致 - 存在しない Sender.from_uri() を使用していました。正しくは Sender.from_conf() です
2. 🔴 型変換 - number_of_trades は FLOAT として送信されていましたが、スキーマでは LONG が想定されていました
3. 🔴 タイムスタンプの解析 - pandas が最初の列をインデックスとして扱い、タイムスタンプがエポック 0 になっていました
4. 🔴 重複排除 - WAL モードでは UPSERT セマンティクスが提供されません（DEDUP ENABLE UPSERT KEYS が必要でした）
5. 🔴 SQL の非互換性 - detect_gaps() では、QuestDB がサポートしていない入れ子のウィンドウ関数が使用されていました

影響：この検証を行わなければ、v4.0.0 はデータが 100% 破損し、取り込みが 100% 失敗する状態でリリースされていたでしょう

結果：5 件のバグすべてを修正し、システムを検証したうえで、v4.0.0 のリリースに成功しました

よくある落とし穴

1. 環境検証を省略する

❌ 悪い例：Docker／データベースが動作していると決めつけ、データ取り込みテストに進む ✅ 良い例：エージェント 1 が最初に環境を検証し、ポートの競合やスキーマエラーを早期に検出する

2. エージェントを順番に実行する

❌ 悪い例：エージェント 2 を実行して完了を待ち、その後エージェント 3 を実行する ✅ 良い例：エージェント 2 と 3 を並列実行する（相互に依存関係はありません）

3. テスト結果を手作業で報告する

❌ 悪い例：テスト出力をコピーして Slack／メールに貼り付ける ✅ 良い例：重大度、ステータス、修正状況を記録した構造化された VALIDATION_FINDINGS.md を使用する

4. 中程度のバグを無視する

❌ 悪い例：「パフォーマンスは SLO を 55% 下回っていますが、後で修正します」 ✅ 良い例：VALIDATION_FINDINGS.md に記録し、リリース可否を明確に判断する

5. 修正後に再検証しない

❌ 悪い例：修正を適用し、動作すると決めつけて先に進む ✅ 良い例：失敗したテストを再実行し、VALIDATION_FINDINGS.md のステータスを更新する

リソース

scripts/

該当なし - 検証スクリプトはプロジェクト固有です（tmp/e2e-validation/ に保存）

references/

• example_validation_findings.md - VALIDATION_FINDINGS.md の完全なテンプレート
• agent_test_template.py - 検証テストスクリプトを作成するためのテンプレート
• bug_severity_classification.md - 詳細な重大度基準と例

assets/

該当なし - 検証成果物はプロジェクト固有です

---

トラブルシューティング

問題	原因	解決策
コンテナが起動しない	Colima/Docker が起動していない	Agent 1 の前に colima start を実行します
ポートの競合	ポートがすでに使用中	競合しているコンテナを停止するか、別のポートを使用します
スキーマの適用に失敗する	SQL 構文が無効	schema.sql がデータベース固有の互換性を満たすか確認します
Agent 1 なしで Agent 2/3 が失敗する	環境が検証されていない	Agent 2/3 を開始する前に Agent 1 が完了していることを確認します
テストスクリプトのインポートエラー	依存関係が不足している	agent ディレクトリで uv pip install を実行します
バグのステータスが更新されない	VALIDATION_FINDINGS.md が古い	修正のたびにステータスを手動で更新します
並列エージェント間の干渉	共有リソースが競合している	エージェントが分離されたディレクトリを使用するようにします
判断が不明確	重大度が Critical/Medium で混在	ドキュメントに従い、Go/No-Go 基準を厳格に適用します

実行後の振り返り

このスキルの完了後、タスクを終了する前に振り返ります：

0. 自分の場所を特定します。 — 編集する前に、この SKILL.md の正規パスを確認します。
1. 何が失敗しましたか？ — 原因となった指示を修正します。
2. 予想以上にうまくいったことは何ですか？ — 推奨プラクティスとして取り入れます。
3. 何が現状からずれていますか？ — 現実と一致しなくなったスクリプト、参照情報、依存関係を修正します。
4. 記録します。 — 発生条件、修正内容、証拠を含む進化ログのエントリーを追加します。

先送りしてはいけません。次回の実行では、あなたが残した状態が引き継がれます。