qe-aqe-v2-v3-migration

AQE v2 から v3 への移行スキル

<default_to_action> v2 から v3 に移行する場合：

1. 現在の v2 インストール環境を分析します
2. 変更を加える前に、すべてのデータをバックアップします
3. 設定、メモリ、パターンを移行します
4. 移行が成功したことを検証します
5. ロールバック手順を提示します

ユーザーの明示的な確認なしに、v2 のデータを削除してはいけません。 </default_to_action>

クイックリファレンス

移行コマンド

# When v3 becomes main release, just update the package
npm install agentic-qe@latest

# Run migration
aqe migrate

# Or use this skill
/aqe-v2-v3-migration

移行される内容

コンポーネント	v2 の場所	v3 の場所	自動移行
メモリ DB	.agentic-qe/memory.db	.aqe/agentdb/	はい
設定	.agentic-qe/config.json	.aqe/config.json	はい
パターン	.agentic-qe/patterns/	.aqe/reasoning-bank/	はい
キャッシュ	.agentic-qe/cache/	.aqe/cache/	任意
ログ	.agentic-qe/logs/	.aqe/logs/	いいえ（新規開始）

---

移行チェックリスト

移行前

• v2 がインストールされていることを確認します（.agentic-qe/ ディレクトリ）
• v2 のバージョンを確認します：aqe --version（2.x.x である必要があります）
• 現在のデータをバックアップします：npm run backup（v2 プロジェクト内で実行）
• カスタム設定があれば記録します
• 現在のテスト数とカバレッジを記録します

移行中

• v3 に更新します：npm install agentic-qe@latest
• 移行を実行します：aqe migrate
• 移行レポートを確認します
• データが正しく転送されたことを確認します

移行後

• v3 のテストを実行します：aqe test
• カバレッジを確認します：aqe coverage
• パターンが読み込まれていることを確認します：aqe patterns list
• Claude Code との MCP 統合をテストします

---

アーキテクチャの変更（v2 → v3）

モノリシックから DDD へ

v2 Structure:                    v3 Structure:
├── src/mcp/tools/              ├── src/domains/
│   ├── test-*.ts (40+ tools)   │   ├── test-generation/
│   └── ...                     │   ├── test-execution/
├── src/core/agents/            │   ├── coverage-analysis/
│   ├── mixed agents            │   ├── quality-assessment/
│   └── ...                     │   ├── defect-intelligence/
└── src/core/memory/            │   ├── requirements-validation/
    └── scattered impls         │   ├── code-intelligence/
                                │   ├── security-compliance/
                                │   ├── contract-testing/
                                │   ├── visual-accessibility/
                                │   ├── chaos-resilience/
                                │   └── learning-optimization/
                                ├── src/kernel/
                                │   ├── event-bus.ts
                                │   └── coordinator.ts
                                └── src/mcp/
                                    └── domain-handlers.ts

主な API の変更

v2 API	v3 API	備考
aqe init	aqe init	バイナリが異なります
aqe.generateTests()	testGeneration.generate()	ドメインベース
aqe.analyzeGaps()	coverageAnalysis.findGaps()	現在は O(log n)
memory.store()	agentDB.store()	HNSW インデックス付き
patterns.learn()	reasoningBank.record()	判定結果付き

---

設定の移行

v2 の設定形式

{
  "version": "2.8.2",
  "memory": {
    "path": ".agentic-qe/memory.db",
    "type": "sqlite"
  },
  "agents": {
    "enabled": ["test-generator", "coverage-analyzer"]
  }
}

v3 の設定形式

{
  "version": "3.0.0",
  "kernel": {
    "eventBus": "in-memory",
    "coordinator": "queen"
  },
  "domains": {
    "test-generation": { "enabled": true },
    "test-execution": { "enabled": true },
    "coverage-analysis": {
      "enabled": true,
      "algorithm": "hnsw",
      "dimensions": 128
    }
  },
  "memory": {
    "backend": "agentdb",
    "path": ".aqe/agentdb/",
    "hnsw": {
      "M": 16,
      "efConstruction": 200
    }
  },
  "learning": {
    "reasoningBank": true,
    "sona": true
  }
}

---

メモリの移行

SQLite から AgentDB へ

// v2: Direct SQLite access
import Database from 'better-sqlite3';
const db = new Database('.agentic-qe/memory.db');
const patterns = db.prepare('SELECT * FROM patterns').all();

// v3: AgentDB with HNSW
import { AgentDB } from 'agentic-qe';
const db = new AgentDB('.aqe/agentdb/');
await db.initialize({ dimensions: 128, M: 16 });

// Migration script transfers and indexes
for (const pattern of v2Patterns) {
  await db.store({
    key: pattern.id,
    value: pattern.data,
    embedding: await generateEmbedding(pattern.data),
    metadata: { migratedFrom: 'v2', originalId: pattern.id }
  });
}

---

破壊的変更

更新必須

1. インポートパス

   // v2
   import { AgenticQE } from 'agentic-qe';
   
   // v3 (when v3 becomes main release, package name is still 'agentic-qe')
   import { TestGenerationDomain } from 'agentic-qe/domains';
   

2. CLI コマンド

   # v2
   aqe test --parallel
   
   # v3
   aqe test --workers=4 --topology=mesh
   

3. MCP サーバー

   # v2
   claude mcp add aqe -- npx aqe-mcp
   
   # v3 (same CLI name, enhanced capabilities)
   claude mcp add aqe -- npx aqe mcp
   

非推奨（警告が表示されます）

• aqe.runTests() → ドメイン固有のメソッドを使用してください
• メモリへの直接アクセス → AgentDB API を使用してください
• フラットなエージェントリスト → ドメインコーディネーターを使用してください

---

ロールバック手順

移行に失敗した場合、または元に戻す必要がある場合：

# 1. v3 does NOT modify v2 data
# Your .agentic-qe/ folder is untouched

# 2. Downgrade to v2
npm install [email protected]
rm -rf .aqe/

# 3. Continue using v2
aqe --version  # Should show 2.x.x

---

エージェント連携の例

移行エージェントの起動

// Use Task tool to spawn migration agents in parallel
Task({
  prompt: "Analyze v2 memory.db and extract all patterns",
  subagent_type: "researcher",
  description: "Analyze v2 patterns"
});

Task({
  prompt: "Convert v2 config to v3 format",
  subagent_type: "coder",
  description: "Convert config"
});

Task({
  prompt: "Validate migration results",
  subagent_type: "tester",
  description: "Validate migration"
});

---

トラブルシューティング

よくある問題

問題	原因	解決策
「.agentic-qe/ が見つかりません」	v2 がインストールされていません	先に aqe init を実行してください
「メモリの移行に失敗しました」	SQLite が破損しています	バックアップを使用します：npm run backup:restore
「HNSW インデックスエラー」	次元が一致しません	設定で dimensions: 128 を指定してください
「パターンが見つかりません」	移行されていません	再実行します：aqe migrate --patterns

デバッグモード

# Run migration with debug output
DEBUG=aqe:migrate aqe migrate

# Check migration logs
cat .aqe/logs/migration.log

---

サポート

• 移行に関する問題：[v2-v3-migration] タグを付けて Issue を作成してください
• ドキュメント：移行ガイド
• Discord：#v3-migration チャンネル

---

バージョン互換性マトリックス

v2 バージョン	v3 バージョン	移行サポート
2.8.x	3.0.x	完全
2.7.x	3.0.x	完全
2.6.x	3.0.x	一部（設定のみ）
2.5.x 以下	3.0.x	手動移行

---

スキルバージョン：1.0.0 | 最終更新日：2026-01-11