はじめに
「AIで落語の台本を作って音声化するWebアプリ」を個人開発で作りました。GitHub Copilot（Agent Mode）と仕様駆動開発ツール「Spec Kit」を組み合わせ、設計から実装・デプロイまで約3日で完成させた記録です。
途中、本番環境としてAWS OpenShift（ROSA）を選んだものの、コストが想定以上で急遽EC2 + Docker Composeに構成を変更するという判断もありました。
🎭 公開中！実際に触れます 👉 https://app.autostorytellers.net
どんなアプリ？
Storyteller Rakugoは、あらすじを入力するとAIが落語の台本を生成し、さらに音声合成で音声ファイルを作成するWebアプリケーションです。
主な機能
- あらすじ入力 → AIが落語台本を生成
- チャットで台本を改善（「もっとオチを強くして」など）
- 話者プロファイルを選んで音声合成
- 作成した落語の一覧管理・音声ダウンロード
- 利用規約・プライバシーポリシーの同意フロー
- 管理者ダッシュボード（ユーザー管理・アクセスログ）
技術スタック
| レイヤー | 技術 |
|---|---|
| フロントエンド | Next.js 15, React 19, TypeScript, Tailwind CSS |
| バックエンド | FastAPI (Python 3.12), SQLAlchemy 2.0, Alembic |
| 認証 | Keycloak 26.2, NextAuth 5.0 |
| データベース | PostgreSQL 16 |
| キャッシュ | Redis 7 |
| ストレージ | MinIO (dev) / AWS S3 (prod) |
| AI | OpenAI API (GPT-4o-mini, TTS) |
| リバースプロキシ | Caddy (自動HTTPS) |
| メール送信 | AWS SES (Keycloak経由) |
| インフラ | AWS EC2 t3.medium, Docker Compose |
アーキテクチャ
┌─────────┐ HTTPS ┌──────────────────────────────────┐
│ User │ ◄────────────► │ Caddy (TLS終端) │
│(Browser)│ │ Let's Encrypt 自動証明書更新 │
└─────────┘ └──────┬────────┬────────┬─────────┘
│ │ │
/app/* /api/* /auth/*
│ │ │
┌──────▼──┐ ┌───▼────┐ ┌▼─────────┐
│Frontend │ │Backend │ │ Keycloak │
│Next.js │ │FastAPI │ │ 26.2.4 │
│ :3000 │ │ :8000 │ │ :8080 │
└─────────┘ └───┬────┘ └─────┬─────┘
│ │
┌─────────┼────────────┤
│ │ │
┌─────▼──┐ ┌────▼───┐ ┌─────▼──────┐
│ Redis │ │Postgres│ │Keycloak DB │
│ :6379 │ │ :5432 │ │ (Postgres) │
└────────┘ └────────┘ └────────────┘
│
┌───────▼───────┐
│ MinIO / S3 │
│ (音声ファイル) │
└───────────────┘
Keycloak ──────► AWS SES
(メール送信)
全7コンテナがEC2 t3.medium (4GB RAM) の1台に載り、AWSマネージドサービス（S3・SES）と連携しています。
OpenShiftが高すぎた話
当初の計画: ROSA (Red Hat OpenShift on AWS)
最初はエンタープライズ感のあるOpenShift（ROSA）で本番デプロイする計画でした。理由は：
- Kubernetes をフルマネージドで運用できる
- OpenShift Route で簡単にHTTPS公開
- Operator エコシステム（Keycloakなど）が充実
実際にROSAクラスタを作成し、マニフェストも書いて動くところまで持っていきました。
現実: 月額コスト
ROSAクラスタのコスト内訳（概算）:
- コントロールプレーン: $140/月
- ワーカーノード (m5.xlarge x2): $280/月
- EBS ボリューム: $30/月
- データ転送: $10/月
────────────────────────────────
合計: 約 $460/月（≒ 約7万円）
趣味プロジェクトに月7万円はさすがに無理。
方針転換: EC2 + Docker Compose
即座に方針を転換し、EC2 t3.medium + Docker Compose という最小構成に切り替えました。
EC2構成のコスト内訳（概算）:
- EC2 t3.medium: $30/月
- EBS 30GB: $3/月
- S3 (音声ファイル): $1/月
- データ転送: $2/月
────────────────────────────────
合計: 約 $36/月（≒ 約5,500円）
コスト約1/13。 OpenShiftのマニフェストはそのまま残しつつ（将来戻す選択肢を維持）、infra/ec2/ ディレクトリに新しい構成を作りました。
Caddy をリバースプロキシに採用し、Let's Encrypt 証明書の自動取得・更新もワンライナーで実現。HTTPS対応のために追加の設定は不要でした。
Spec Kit による仕様駆動開発
このプロジェクトで最も効率化に貢献したのが Spec Kit です。VS Code の GitHub Copilot Agent Mode と連携する仕様駆動開発ツールで、以下のワークフローで開発を進めました。
ワークフロー
/speckit.specify → 仕様書(spec.md)を生成
↓
/speckit.clarify → 仕様の曖昧な点を質問で洗い出し、specに反映
↓
/speckit.plan → 実装計画(plan.md)を生成
↓
/speckit.tasks → タスク分解(tasks.md)を生成
↓
/speckit.implement → タスクに従って実装を実行
実際のフィーチャー一覧
| # | フィーチャー | 内容 |
|---|---|---|
| 001 | 落語作成・管理 | コア機能：あらすじ入力→AI台本生成→音声合成 |
| 002 | DBスキーママイグレーション | Alembicによるマイグレーション整備 |
| 003 | ユーザー管理 | Keycloak連携の認証・認可 |
| 004 | AWS本番デプロイ (ROSA) | OpenShiftデプロイ（後にコスト問題で断念） |
| 005 | EC2 Docker Composeデプロイ | 最小コスト構成への移行 |
| 006 | 管理者ダッシュボード | ユーザー一覧・アクセスログ |
| 007 | 利用規約・登録UX改善 | プライバシーポリシー・入力改善 |
Spec Kit の何がよかったか
1. /speckit.clarify で仕様の穴を埋める
/speckit.specify で生成した仕様書には、曖昧な部分が残ることがあります。/speckit.clarify を実行すると、AIが仕様の不足箇所を最大5つの質問で指摘してくれます。回答すると、その内容が spec.md に自動反映されます。
例えば「音声ファイルの保存期間は？」「管理者がユーザーを削除したとき音声データはどうする？」といった、自分では見落としがちなエッジケースを洗い出してくれるのが便利でした。
2. Constitutionによるブレない設計
プロジェクトの「憲法」を最初に定義します。例えば：
- あらすじ入力を必ず起点とすること
- 音声生成前に話者プロファイルを確認すること
- 全データはリクエストまでトレーサブルであること
各フィーチャーの plan.md には「Constitution Check」が含まれ、設計が原則に違反していないか自動チェックされます。
3. 仕様→計画→タスクの一貫性
spec.md に書いたユーザーストーリーとAcceptanceシナリオが、plan.md の設計判断、tasks.md の実装タスクまで一貫して追跡できます。人間がやると面倒なトレーサビリティを自動化してくれます。
4. /speckit.implement でタスクを順番に実行
tasks.md に定義されたタスクを、依存関係を尊重しながら1つずつ実行していきます。テストファースト、フェーズ分割、完了チェックまで自動です。
Copilot Agent Mode でのデバッグ事例
全自動で完璧に動くわけではなく、デバッグが必要な場面も多くありました。以下は実際に遭遇した問題と対応です。
1. Keycloakログインテーマが反映されない
カスタムテーマを作成して Docker の volumes でマウントしたのに反映されない。
原因: Keycloak はテーマをキャッシュするため、ファイルを更新してもコンテナ再起動が必要だった。また、レルム設定に loginTheme を適用する API 呼び出しが必要だった。
解決: configure-user-profile.sh にテーマ設定の API 呼び出しを追加。
2. Next.js standalone ビルドで Markdown ファイルが読めない
利用規約ページが fs.readFileSync でMarkdownファイルを読んでいるが、Docker コンテナ内で 404 になる。
原因: Next.js の output: 'standalone' ビルドでは process.cwd() が .next/standalone/ になるが、src/content/ ディレクトリがそこにコピーされていなかった。
解決: Containerfile に src/content/ を standalone ディレクトリにコピーするステップを追加。
RUN if [ -d src/content ]; then \
mkdir -p .next/standalone/src/content && \
cp -r src/content/* .next/standalone/src/content/; \
fi
3. Keycloak の OIDC Provider が削除できない
ROSA クラスタ削除後、OIDC Provider の残骸が残り、rosa delete oidc-provider が 404 を返す。
原因: ROSA 側ではリソースが削除済みだが、IAM 側のリソースだけが残存。
解決: AWS CLI で IAM から直接削除。
aws iam delete-open-id-connect-provider \
--open-id-connect-provider-arn "arn:aws:iam::xxxxx:oidc-provider/..."
4. ヘルスチェックで curl が使えない
Docker コンテナのヘルスチェックで curl を使っていたが、slim イメージには curl が入っていない。
解決: フロントエンドは Node.js の fetch()、バックエンドは Python の urllib でヘルスチェックを実装。追加のパッケージインストールを回避。
開発タイムライン
Day 1: プロジェクト初期化、Constitution定義、
001-落語管理、002-DBマイグレーション、003-ユーザー管理
→ Spec Kit で仕様→計画→実装を一気に実行
Day 2: 004-ROSA本番デプロイ 作成・デプロイ実施
→ コスト判明、即日クラスタ削除
Day 3: 005-EC2 Docker Compose デプロイ
→ 本番公開完了、動作確認
Last: 006-管理者ダッシュボード、007-利用規約・UX改善
→ テーマカスタマイズ、プライバシーポリシー整備
コア機能の開発（設計〜実装〜デプロイ）は実質 3日間 で完了しています。Spec Kit がなければ仕様書を書くだけで数日かかっていたと思います。
Copilot + Spec Kit で感じたこと
よかった点
- 仕様の一貫性: Constitution → Spec → Plan → Tasks の流れで、設計判断がブレにくい
- 実装速度: 7つのフィーチャーを3日で実装・デプロイまで完了
- デバッグ効率: Copilot Agent Mode がエラーログを読んで修正案を提示してくれる
-
インフラ変更に強い: OpenShift → EC2 の構成変更も、新しいSpec を書いて
/speckit.implementするだけ
注意点
-
/speckit.implementが生成するコードは完璧ではなく、特にインフラ周りは手動調整が必要 - Keycloak のようなステートフルなサービスとの連携は、AI だけでは解決しにくい場面がある
- 生成されたテストが不十分な場合があるので、手動での動作確認は必須
まとめ
| 項目 | 詳細 |
|---|---|
| 開発期間 | 約3日（コア機能） |
| コード行数 | フロントエンド ~5,000行、バックエンド ~4,000行 |
| コンテナ数 | 7 (frontend, backend, keycloak, postgres, keycloak-db, redis, minio/caddy) |
| 月額コスト | 約 $36/月（EC2 t3.medium） |
| 使用AI | GitHub Copilot (Claude Opus 4), OpenAI API (GPT-4o-mini, TTS) |
趣味プロジェクトでも、仕様駆動で進めることで「何を作るか」「なぜそう作るか」が明確になり、Copilot との協業がスムーズになります。OpenShift のコスト問題は痛い授業料でしたが、EC2 に切り替えたことでランニングコストを大幅に削減できました。
ぜひ実際に触ってみてください。あらすじを入力するだけで、AIが落語を作ってくれます。
URL: https://app.autostorytellers.net