Claude Codeで映画レビューアプリを設計からデプロイまで作ってみた
今回の記事では、Anthropic が提供するAIエージェント Claude Code を用いて、フルスタックwebアプリを設計からデプロイまで構築した取り組みをご紹介します。対象プロジェクトは映画記録・レビュー共有サービスです。Claude Codeがどの範囲まで担えるのか、実際の開発を通じて検証しました。
作ったもの
映画レビューアプリは、映画を記録・レビューして他ユーザーと共有できるwebアプリです。技術スタックは以下のとおりです。
| レイヤー | 技術 |
| フロントエンド | Next.js 15 (App Router), TailwindCSS, shadcn/ui |
| バックエンド | tRPC v11, Drizzle ORM, PostgreSQL |
| インフラ | GCP Cloud Run, Cloud SQL, Artifact Registry |
| 外部API | TMDB（映画情報）, PostHog（アナリティクス） |
| 認証 | JWT（Secret Manager保存） |
実装した主な機能は次の通りです。
- 映画検索・詳細表示：TMDB APIによる検索、ジャンル・年・評価でのフィルター
- ウォッチリスト：「観た / 観てる / 観たい」の3ステータス＋評価・レビュー
- パーソナライズホーム：ウォッチリストのジャンル履歴をもとにムード別カテゴリの並び順を自動調整
- ソーシャル機能：フォロー/フォロワー、他ユーザーのウォッチリスト閲覧
- 認証：JWT認証、プロフィール編集
Claude Codeに担わせた範囲
TypeScript/TSXファイルは合計70本、約4,000行になりました。そのほぼすべてをClaude Codeが生成しています。担当範囲を工程別に整理すると以下のとおりです。
設計
- モノレポ構成の設計（
apps/web+packages/api） - 技術選定と選定理由の文書化（
docs/decisions.md） - Drizzleスキーマ設計（users, movies, watch_entries, follows の4テーブル）
実装
- tRPCルーター5本（auth, movies, watchlist, reviews, follows）
- Next.jsページ7画面（ホーム・映画詳細・検索・ウォッチリスト・プロフィール・ログイン・新規登録）
- TMDB APIラッパー（
packages/api/src/lib/tmdb.ts）
インフラ
- Terraform（Cloud Run × 2, Cloud SQL, VPC, Secret Manager, Artifact Registry）
- Cloud Build設定（
cloudbuild.yaml） - Dockerfile（web / api それぞれ）
指示の渡し方：CLAUDE.mdの活用
最も効果的だったのが CLAUDE.md による文脈の共有です。プロジェクトルートに置いたこのファイルに、ディレクトリ構成・技術スタック・新機能追加パターン・環境変数の在り処を記載しておくことで、Claude Codeはセッションをまたいでもプロジェクトの構造を把握した状態で動きます。
## 新機能追加パターン
### バックエンド（tRPC エンドポイント追加）
1. `packages/api/src/routers/` に procedure 追加
2. TMDB API 呼び出しは `packages/api/src/lib/tmdb.ts` に関数追加
### フロントエンド（ページ追加）
1. `apps/web/src/app/` に `page.tsx` 作成
2. `trpc.xxx.useQuery()` / `useMutation()` でデータ取得
3. 認証が必要な操作は `useAuth()` で `isAuthenticated` を確認規模が大きい機能追加時は、バックエンドエージェントとフロントエンドエージェントに役割を分け、それぞれが packages/api/ と apps/web/src/ だけを担当する形で並列開発を行いました。担当ファイルが重複しないよう役割を明確にしておくことで、変更の干渉なく並行して進めることができます。
できたこと・難しかったこと
できたこと
設計→実装→インフラ→デプロイまで一気通貫で進めることができました。技術選定の根拠を docs/decisions.md として出力させ、ドキュメントとして残せたのも副次的なメリットです。型安全なAPIについては「tRPCのprocedureとしてZodバリデーション付きで実装して」という一言で、入出力型の推論が効いた実装が生成されます。デプロイログについて調査できることも確認しました。
難しかったこと
Cloud RunとCloud SQL間のプライベートVPC接続では、VPC ConnectorのサブネットCIDRが /28 必須であるといった細かい制約のデバッグに時間を要しました。また、UIの微細な動作（ダイアログを閉じるタイミング、楽観的更新の挙動など）は、「なんか変」という感覚的なフィードバックではなく「この操作の後にXという状態になるべき」と具体的に伝えるほうが精度よく修正されました。
まとめ
Claude Codeを用いることで、設計・実装・インフラ・デプロイをひとつのAIエージェントに通して任せることができました。重要だったのは「AIに文脈を渡し続けること」です。CLAUDE.mdでプロジェクト構造を共有し、役割分担を明確にした指示を出すことで、コードの品質と一貫性が保たれます。 また、検証を通じて、知見の少ない領域でのアーキテクチャ・UXの設計、工数見積もりの妥当性確認などに利用できる可能性を感じました。
今後の記事では、tRPC・Drizzle ORM・GCPインフラ・アナリティクスツールなど、実際に利用して得られた知見を、使いどころが伝わる形でお届けしていきます。
