メインコンテンツへスキップ
見出し画像

AIと3日間でオンラインThree Dragon Anteを作った話

    はじめに

    「D&Dの世界観を持つカードゲーム『Three Dragon Ante』を、ブラウザでオンライン対戦できるようにしたい」

    そんな思いつきから始まったこのプロジェクト。AIコーディングアシスタント「Kiro」と二人三脚で、TypeScriptによるフルスタック開発を行い、わずか3日間でCPU対戦・有人対戦が動作するところまで到達しました。

    本記事では、AIアシスタントとの協働開発がどのようなものだったか、技術的な設計判断、そして実際にぶつかった壁とその解決策を共有します。

    画像
    作業中のKiroの画面

    Three Dragon Ante とは

    Three Dragon Ante: Legendary Editionは、ダンジョンズ&ドラゴンズ(D&D)の世界観をベースにしたカードゲームです。ゲームデザイナーはロブ・ハインソー(Rob Heinsoo)。

    ゲームの基本ルール

    • 4〜6人のプレイヤーが参加し、各自ゴールド(人数×10)を持ってスタート

    • 「ガンビット」と呼ばれる賭けラウンドを繰り返す

    • アンティ → カードプレイ(3ラウンド)→ 勝者決定の流れ

    • 前のプレイヤーと同じか低い強度のカードを出すと特殊能力が発動

    • 誰かのゴールドが0になったらゲーム終了、最多ゴールド保持者が勝利

    全100枚のカードに33種類の固有能力があり、善ドラゴン・悪ドラゴン・定命の存在・レジェンダリーの4カテゴリに分類されます。

    このゲームの面白さは、単純な数字の大小だけでなく、カード能力の連鎖にあります。例えば「The Princess」は編隊内の善ドラゴン全ての能力を再発動させ、「Copper Trickster」は自分のカードを捨てて新しいカードに置き換え、さらにその新カードの能力を発動させます。こうした能力の連鎖をデジタルで正確に再現することが、このプロジェクト最大の技術的チャレンジでした。

    技術スタックの全体像

    モノレポ構成

    pnpm workspaces + Turborepoによるモノレポ構成を採用しました。

    three-dragon-ante/
    ├── packages/
    │   ├── shared/          — 共有型定義(全パッケージの基盤)
    │   ├── game-engine/     — ゲームロジック(純粋TS、外部依存なし)
    │   ├── matchmaking/     — マッチメイキング + WebSocketサーバー
    │   ├── auth-service/    — 認証API
    │   ├── stats-service/   — 統計API
    │   ├── frontend/        — React SPA
    │   └── infra/           — AWS CDK
    ├── docs/                — ルール文書、API仕様、カードデータ
    └── compose.yaml         — ローカル開発用コンテナ

    依存関係は `shared → game-engine → matchmaking/auth-service/stats-service → frontend` の一方向で、循環依存を排除しています。

    バックエンド

    | サービス | 技術 | 役割 |
    |---------|------|------|
    | matchmaking | Express + WebSocket (ws) + DynamoDB | ルーム管理、リアルタイムゲーム通信 |
    | auth-service | Express + Prisma + PostgreSQL + Cognito | ユーザー登録・ログイン |
    | stats-service | Express + Prisma + PostgreSQL | 戦績記録・統計API |

    認証はAWS Cognitoに委譲し、JWTトークンの検証にはjwks-rsaを使用。入力バリデーションは全サービスでZodを統一的に使用しています。

    フロントエンド

    • React 18 + Vite 5

    • Zustand(クライアント状態管理)

    • @tanstack/react-query(サーバー状態管理)

    • react-router-dom v6(ルーティング)

    ローカル開発環境

    Finch Compose(Docker互換のARM64対応コンテナランタイム)でDynamoDB LocalとPostgreSQLを起動します。

    services:
      dynamodb-local:
        image: amazon/dynamodb-local:latest
        platform: linux/arm64
        ports: ["8000:8000"]
      postgres:
        image: postgres:15
        platform: linux/arm64
        ports: ["5432:5432"]

    AIとの協働開発プロセス

    AI-DLC(AI Development Life Cycle)ワークフロー

    今回の開発では、AI-DLCと呼ばれる構造化された開発ワークフローを採用しました。これは従来のSDLC(Software Development Life Cycle)をAIアシスタントとの協働に最適化したもので、以下の3フェーズで構成されます。

    1. INCEPTION(構想): 要件分析、ユーザーストーリー、ワークフロー計画、アプリケーション設計

    2. CONSTRUCTION(構築): 機能設計、NFR設計、インフラ設計、コード生成、ビルド&テスト

    3. OPERATIONS(運用): デプロイ、監視(今回は未着手)

    各フェーズで、AIが設計文書やコードを生成し、人間がレビュー・承認するというサイクルを回します。重要なのは「AIに丸投げ」ではなく、各ステージで人間が判断を下すゲートを設けている点です。

    Kiroのスキルとステアリング

    Kiroには「スキル」と「ステアリング」という仕組みがあります。

    • スキル: `plan-first`(実装前に計画を提示)、`game-rules-check`(ルール文書との照合)など、特定のタスクパターンに対する振る舞いを定義

    • ステアリング: プロジェクト固有のルール(技術スタック、セキュリティポリシー、開発ワークフロー)を常にAIのコンテキストに含める

    例えば、カード能力の実装時には `game-rules-check` スキルが自動的にルール文書(`docs/three-dragon-ante-rules.md`)を参照し、実装がルールに準拠しているかを検証します。

    「ソースオブトゥルース」の明確化

    AIとの協働で最も重要だったのは、「何が正しいか」の基準を明確にすることでした。

    • ゲームルール → `docs/three-dragon-ante-rules.md`

    • カードデータ → `docs/card-data.json`(100枚分の能力テキスト)

    • API仕様 → `docs/api/.openapi.yaml`、`docs/api/.asyncapi.yaml`

    • 型定義 → `packages/shared/src/types/`

    • 機能の正しさ → テストファイル

    これらを「ソースオブトゥルース」として定義し、AIが実装を生成する際に必ず参照するようステアリングで指示しました。AIが勝手に仕様を変更することを防ぎ、一貫性を保つための重要な仕組みです。

    ゲームエンジンの設計

    純粋TypeScriptによる実装

    `packages/game-engine/` は外部依存ゼロの純粋TypeScriptパッケージです。Express、WebSocket、データベースなど一切の外部ライブラリに依存しません。これにより:

    • テストが高速(99テスト全体で数百ミリ秒)

    • フロントエンドでも再利用可能

    • ロジックの正確性を独立して検証可能

    カード能力システム

    33種類のカード能力は、カテゴリ別にファイルを分割して実装しています。

    powers/
    ├── good-dragons.ts       — 善ドラゴン(Gold, Silver, Bronze, Copper, Brass)
    ├── evil-dragons.ts       — 悪ドラゴン(Red, Blue, Black, White, Green)
    ├── legendary-dragons.ts  — レジェンダリー(Bahamut, Tiamat, 各Overlord等)
    ├── mortals.ts            — 定命の存在(Princess, Kobold, Sorcerer等)
    └── power-dispatcher.ts   — 能力ディスパッチャー(カード名→能力関数のルーティング)

    能力の発動条件は「リーダーが最初にプレイした場合」または「右隣のプレイヤーの強度以下をプレイした場合」の2パターン。この判定ロジックは `core/play-phase.ts` の `shouldTriggerPower` 関数に集約しています。

    pendingChoice — 人間プレイヤーの選択を待つ仕組み

    カード能力の中には、プレイヤーの選択が必要なものがあります。例えば:

    • Blue Dragon: 「対戦相手から1G奪う」か「掛け金から1G取る」かの2択

    • Brass Dragon: 「5G支払う」か「手札から条件に合うカードを渡す」か

    • The Sorcerer: デッキ上3枚から1枚を選んで自分のカードと交換

    • The Kobold: 手札から好きな枚数を捨てて同数ドロー

    CPUプレイヤーなら即座に判断できますが、人間プレイヤーの場合はWebSocket経由で選択肢を送信し、回答を待つ必要があります。

    この非同期の選択待ちを `pendingChoice` という仕組みで実装しました。ゲームエンジンが能力を処理する途中で人間の選択が必要になると、`pendingChoice` オブジェクトをゲーム状態に設定してリターン。WebSocketサーバーが `choice_required` イベントをクライアントに送信し、クライアントから `submit_choice` が返ってきたら、ゲームエンジンの処理を再開します。

    この仕組みで特に難しかったのが「能力の連鎖中の中断と再開」です。例えば The Princess は編隊内の善ドラゴン全ての能力を順次再発動しますが、途中のドラゴン(例えばBlue Dragon)で人間の選択が必要になると、そこで処理を中断し、選択後に次のドラゴンから再開する必要があります。

    特別な編隊の検出

    Three Dragon Anteには「単色編隊」(同じ色のドラゴン3体以上)と「同一強度編隊」(同じ強度のカード3枚以上)という特別な編隊があり、達成すると追加のゴールドを獲得できます。

    実装上の注意点として、Tiamatは5色全ての悪ドラゴンとしてカウントされるため、単色編隊の判定で特別な処理が必要でした。また、「同じプレイヤーが1ガンビットで同じ種類の特別な編隊を2回達成することはできない」というルールがあり、当初はboolean型で管理していましたが、異なるプレイヤーがそれぞれ達成するケースに対応するため `Set<string>` に変更しました。

    CPU AIの戦略

    CPU AIは `packages/game-engine/src/ai/cpu-ai.ts` に実装されています。完全なゲーム理論に基づくAIではなく、ヒューリスティックベースの判断を行います。

    • アンティ: 手札の中間的な強度のカードを選択(強すぎず弱すぎず)

    • カードプレイ: 能力発動条件を考慮し、有利な能力を持つカードを優先

    • 能力選択: 各能力ごとに最適な選択肢を評価(例: Brass Dragonなら手札に弱いカードがあれば渡す、なければ5G支払い)

    WebSocketによるリアルタイム通信

    プロトコル設計

    ゲームのリアルタイム通信はWebSocketで実装しています。プロトコルはAsyncAPI仕様で定義しました。

    クライアント → サーバー:

    • `submit_ante` — アンティカード提出

    • `play_card` — カードプレイ

    • `submit_choice` — 能力の選択肢回答

    • `select_ante_cards` — 同一強度編隊達成時のアンティカード選択

    サーバー → クライアント:

    • `game_state` — ゲーム状態の全体更新

    • `waiting_for_action` — プレイヤーのアクション待ち通知

    • `power_triggered` — カード能力発動通知

    • `special_flight` — 特別な編隊達成通知

    • `gambit_result` — ガンビット結果通知

    • `game_end` — ゲーム終了通知

    セッション管理とCPU処理

    WebSocketセッション(`game-session.ts`)は、人間プレイヤーとCPUプレイヤーの処理を統合的に管理します。人間プレイヤーのアクション後、CPUプレイヤーのターンを自動的に処理し、結果をブロードキャストします。

    CPUの処理には意図的な遅延(アンティ500ms、プレイ1000ms)を入れています。これは、CPUが瞬時に全てのアクションを完了すると、人間プレイヤーがゲームの進行を追えなくなるためです。

    フロントエンドの実装

    ファンタジーテーマのUI

    ゲームの世界観に合わせて、中世ファンタジー風のUIテーマを実装しました。

    • フォント: Cinzel(見出し・数字)、MedievalSharp(カード名・タイトル)をGoogle Fontsから読み込み

    • カラーパレット: 酒場風のダークテーマ(深い紫/茶系の背景)にゴールド(#c9a84c)のアクセント

    • カードデザイン: タイプ別のグラデーション背景(善=緑、悪=赤、定命=紫)、タイプアイコン(✨善/🔥悪/⚔定命)

    • ツールチップ: `getBoundingClientRect` で動的に位置を計算し、画面端でも見切れないように上下・左右を自動調整

    画面構成

    | 画面 | ファイル | 機能 |
    |------|---------|------|
    | ログイン | LoginPage.tsx | Cognito認証 |
    | 登録 | RegisterPage.tsx | ユーザー登録 |
    | ロビー | LobbyPage.tsx | ルーム作成・参加、CPU対戦開始 |
    | 待機室 | WaitingRoomPage.tsx | 参加者一覧、ゲーム開始待ち |
    | ゲーム | GamePage.tsx | メインゲーム画面 |
    | 統計 | StatsPage.tsx | 勝率、ゲーム履歴、カード傾向 |

    WebSocketフック

    `useGameWebSocket` カスタムフックがWebSocket通信の全てを管理します。接続確立、メッセージのパース、ゲーム状態の更新、切断時の再接続、そして `choice_required` イベントの検出と選択UIの表示を一元的に処理します。

    開発中に特に苦労したのが、Viteの HMR(Hot Module Replacement)との相性です。HMRが発火するたびにWebSocketが再接続され、ゲーム状態がリセットされる問題がありました。`useEffect` の依存配列を適切に設定することで解決しましたが、リアルタイム通信とHMRの組み合わせは注意が必要です。

    開発中にぶつかった壁と解決策

    1. Monorepoのビルド問題

    問題: `tsconfig.base.json` で `declaration: true` を設定していたところ、サービスパッケージ(Express使用)でExpress型の推論エラーが大量発生。

    解決: tsconfig をライブラリ用(`declaration: true`)とアプリケーション用(`declaration: false`)に分割。shared と game-engine はライブラリ用、サービスパッケージはアプリケーション用を継承するようにしました。

    2. Prisma Client のmonorepo問題

    問題: auth-service と stats-service の両方が Prisma を使用しているが、`prisma generate` が同じ `node_modules/.prisma/client/` に出力するため、最後に実行したスキーマで上書きされる。

    解決: 各サービスの Prisma 設定で出力先を `node_modules/.prisma/auth-client/` と `node_modules/.prisma/stats-client/` に分離。

    3. カードデータのパス解決

    問題: `card-data.json` を読み込む `card-loader.ts` で、vitest実行時(`src/` ディレクトリ)とビルド後(`dist/` ディレクトリ)で `__dirname` が異なり、ファイルが見つからない。

    解決: 上位ディレクトリを探索して `docs/card-data.json` を見つける方式に変更。`__dirname` から親ディレクトリを辿り、`card-data.json` が存在するパスを動的に解決します。

    4. ガンビット番号のずれ

    問題: ガンビットが終了して次のガンビットに移行する際、前のガンビットの `readyFlags`(アンティ準備完了フラグ)が残っていて、CPUが即座にアンティを開始し、ガンビットが飛ばされる。

    解決: `handleAction` でアクション処理前後の `gambitNumber` を比較し、変化があった場合に `readyFlags` と `readyTimers` をクリアするようにしました。

    5. pendingChoice の検出漏れ

    問題: 通知配列を `slice(-200)` で最新200件に制限していたが、インデックスベースで `pendingChoiceId` を管理していたため、配列のスライスでインデックスがずれ、`choice_required` が検出されない。

    解決: インデックスベースの管理を廃止し、`WeakSet` による参照ベースの管理に変更。通知オブジェクトの参照自体で「処理済みかどうか」を判定するため、配列のスライスに影響されません。

    6. CPU処理のスタック

    問題: CPUの処理中にエラーが発生すると、`cpuProcessing` ロックが解放されず、以降のCPU処理が全てブロックされる。

    解決: `executeCpuStep` の `catch` ブロックでロックを確実に解放。さらに、`processCpuTurns` に30秒の安全弁タイマーを追加し、万が一ロックが残っても自動的に解放されるようにしました。

    テスト戦略

    ユニットテスト

    全パッケージでVitestを使用し、合計120以上のテストが全て合格しています。

    | パッケージ | テスト数 | 内容 |
    |-----------|---------|------|
    | game-engine | 99 | カード能力39件、pendingChoice 9件、編隊検出14件、Silver Dragon 6件、他31件 |
    | auth-service | 7 | ルーターバリデーション |
    | matchmaking | 4 | ルーム管理(DynamoDBモック) |
    | stats-service | 5 | バリデーション |
    | frontend | 8 | OpenAPI型整合性 |

    game-engine のテストが圧倒的に多いのは、33種類のカード能力それぞれに対してエッジケースを含むテストを書いているためです。特に `powers-modified.test.ts`(39件)は、能力の連鎖、pendingChoice の中断・再開、特別な編隊との組み合わせなど、複雑なシナリオをカバーしています。

    Playwright MCPによるE2Eストレステスト

    ブラウザ上での動作確認には、Playwright MCPを使用した自動プレイスクリプトを活用しました。WebSocket経由でCPU対戦を連続実行し、ゲームロジックの安定性を検証します。

    • 合計8ゲーム完了、致命的なゲームロジックエラー0件

    • 15種類以上のカード能力の発動を確認

    • タイムアウト(ゲームが120秒を超過)が数件発生したが、ロジックエラーではなくゲーム時間の長さが原因

    AWSインフラ設計


    画像
    AWSアーキテクチャ

    CDKスタック構成

    AWS CDK v2でインフラをコード化しています。

    infra/lib/
    ├── backend-stack.ts     — VPC, Aurora, DynamoDB, ECS, ALB
    ├── frontend-stack.ts    — CloudFront, S3
    └── monitoring-stack.ts  — CloudWatch

    バックエンドアーキテクチャ

    Internet
      │
      ├── CloudFront (frontend)
      │     └── S3 (React SPA)
      │
      └── ALB (api.example.com)
            ├── /api/auth/*  → ECS Fargate (auth-service, 256CPU/512MB)
            ├── /api/stats/* → ECS Fargate (stats-service, 256CPU/512MB)
            ├── /api/game/*  → ECS Fargate (matchmaking, 512CPU/1024MB)
            └── /ws/*        → ECS Fargate (matchmaking, sticky session)
                  │
                  ├── Aurora Serverless v2 (PostgreSQL 15)
                  └── DynamoDB (rooms table, PAY_PER_REQUEST)

    WebSocket接続にはALBのスティッキーセッション(Cookie、24時間TTL)を設定し、同じクライアントが常に同じタスクに接続されるようにしています。

    全サービスはARM64(Graviton)で動作し、コスト効率を最大化。Aurora Serverless v2は最小0.5 ACU〜最大2 ACUで、アイドル時のコストを抑えています。

    AIとの協働で学んだこと

    うまくいったこと

    1. ソースオブトゥルースの明確化: ルール文書、カードデータ、API仕様を事前に用意し、AIが参照できるようにしたことで、実装の一貫性が保たれました。

    2. パッケージ境界の厳守: 「1ステップで複数パッケージを変更しない」というルールを徹底したことで、変更の影響範囲が明確になり、デバッグが容易になりました。

    3. テストファーストの姿勢: AIが生成したコードに対して、テストで正しさを検証するサイクルを回すことで、バグの早期発見ができました。特にゲームエンジンの99テストは、能力実装の正確性を担保する上で不可欠でした。

    4. ステアリングによるコンテキスト維持: プロジェクト固有のルール(技術スタック、セキュリティポリシー、コーディング規約)をステアリングファイルに記述することで、セッションをまたいでも一貫した開発が可能でした。

    注意が必要だったこと

    1. AIの「勝手な仕様変更」: テストを通すためにテストコードを修正したり、エラーを抑制するためにlint設定を変更したりする傾向があります。「テストファイルを修正してはいけない」「lint設定を変更してはいけない」というルールをステアリングに明記する必要がありました。

    2. コンテキストの消失: 長いセッションでは、AIが以前の決定事項を忘れることがあります。`session-resume-prompt.md` を用意し、セッション再開時に貼り付けることで対処しました。

    3. 複雑な状態遷移のデバッグ: カード能力の連鎖やpendingChoiceの中断・再開など、複雑な状態遷移のバグは、AIだけでは原因特定が難しいケースがありました。デバッグログの体系化(`ENGINE_DEBUG` 環境変数による制御)が有効でした。

    4. ブラウザ固有の問題: game-engineのテストでは正常動作するが、ブラウザ上では動かないケースがいくつかありました(Copper Dragon能力不発動、Silver Seer選択後の手札未反映など)。これはmatchmaking層やフロントエンド層の問題であり、レイヤーをまたいだデバッグが必要でした。

    数字で見るプロジェクト

    | 項目 | 数値 |
    |------|------|
    | 開発期間 | 約3日間 |
    | パッケージ数 | 7(shared, game-engine, matchmaking, auth-service, stats-service, frontend, infra) |
    | カード能力 | 33種類 |
    | テスト数 | 120以上(全パッケージ合計) |
    | game-engineテスト | 99件 |
    | WebSocketイベント種別 | 10種類 |
    | REST APIエンドポイント | 12以上 |
    | カードデータ | 100枚 |
    | AWSサービス | 8種類(Cognito, DynamoDB, Aurora, ECS, ALB, CloudFront, S3, Route 53) |

    今後の展望

    Phase 1〜6まで全て完了し、AWS上でのオンライン対戦が動作する状態に到達しています。

    • Phase 1〜3 ✅: ビルド検証、ユニットテスト、CPU対戦ローカル動作

    • Phase 4 ✅: フロントエンド動作確認、全33種カード能力実装、UIファンタジーテーマ

    • Phase 5 ✅: AWS CDKによるインフラデプロイ(ECS Fargate、Aurora Serverless v2、CloudFront)

    • Phase 6 ✅: オンライン対戦テスト(複数ブラウザでの有人対戦確認)

    今後取り組みたいこと:

    • 品質向上: テストカバレッジ80%以上、CI/CDパイプライン構築

    • UI改善: カードアニメーション、AI生成カードアート、レスポンシブ対応

    • 運用: CloudWatchダッシュボード、アラート設定、コスト最適化

    • 機能拡張: ランキングシステム、フレンド対戦、観戦モード


    画像
    実際のプレイ画面(CPU戦)

    おわりに

    正直に言うと、私はどちらかと言えばクラウドインフラ寄りのエンジニアです。AWSのサービス設計は得意分野ですが、今回使ったソフトウェアスタック — React、Express、WebSocket、Zustand、Prisma — については触り程度の知識しかありませんでした。TypeScriptは、自分の手で書いた経験は一行もありません。

    それでも、AIアシスタントとの協働によって、7パッケージ・合計約11,000行に及ぶフルスタックWebアプリケーションを作り上げることができました。これらを自力でゼロから書くことは、少なくとも短期間では不可能だったでしょう。

    AIコーディングアシスタントとの協働開発は、「AIに全てを任せる」のではなく、「AIの得意なこと(大量のボイラープレート生成、パターンの適用、ドキュメントの参照)を活かしつつ、人間が設計判断とレビューを行う」というスタイルが最も効果的でした。私の場合、インフラ設計やアーキテクチャの判断は自分で行い、TypeScriptの具体的な実装はAIに主導してもらうという役割分担が自然に生まれました。

    Three Dragon Anteのような複雑なルールを持つゲームのデジタル化は、ルールの解釈、エッジケースの発見、状態遷移の設計など、人間の判断が不可欠な場面が多くあります。一方で、6パッケージにまたがるmonorepoの構築、100枚のカードデータの型定義、33種類の能力実装のスキャフォールディングなど、AIが大幅に効率化してくれた部分も多大です。

    「自分の専門外の技術でも、AIと組めばここまで作れる」— この体験は、エンジニアとしての可能性を大きく広げてくれるものでした。この記事が、同じようにAIとの協働開発に興味を持つ方の参考になれば幸いです。

    当たり前なんですが、Three Dragon AnteはWizards of the Coastが著作権を持っているゲームなので、このウェブアプリは公開しません。

    参考


     
     

    siseru

     
     
    Dungeon MasterとSolution Architectのマルチクラスしてます。

    あなたへのおすすめ