Claude Code CLIでフルスタックWebアプリを共同開発した話 — 仕様書ドリブンの進め方

はじめに

自作デスクトップアプリの設定シミュレーターを、Claude AI（Claude Code CLI）との共同作業でフルスタックWebアプリとして開発しました。

完成品: https://obott9.github.io/ime-simulator/
ソースコード: https://github.com/obott9/ime-simulator

層	技術
フロントエンド	React 19 + Vite 7 + Tailwind CSS 4
バックエンド	Express 5 + Node.js 22
データベース	Supabase (PostgreSQL)
認証	Supabase Auth (GitHub OAuth)
CI/CD	GitHub Actions → GitHub Pages

技術構成や各サービスの具体的な設定内容は別記事にまとめています。

この記事では、Claude AIとどう協業したか——仕様書の作り方、コード生成の進め方、うまくいった点と注意点を共有します。

自分のバックグラウンド

元々は機械設計技術者で、1989年から制御系・組み込みソフトウェア開発でキャリアをスタートしました。ABS油圧テスターのファームウェア → 衛星携帯電話基地局シミュレータ → HDDレコーダー → 携帯電話（Brew）→ iOS/Android → Javaサーバーサイドと、マイコンからクラウドまで36年間活動してきました。

業務での主要言語はC、C++、Java、Objective-C、PHP。直近はJava業務系（Play Framework、PostgreSQL、Oracle等）が中心です。

今回のプロジェクトは、ポートフォリオとしてモダンフロントエンド + BaaS構成のスキルを示すことが目的でした。React、Vite、Tailwind CSS、Supabase、Docker、GitHub Actions——このあたりは実務経験がない状態からのスタートです。Express（Node.js）はJavaサーバーサイドの経験があるので概念は馴染みがありましたが、エコシステムは別物でした。

開発の進め方：3つのフェーズ

Phase 1: 仕様書をまず作る

いきなりコードを書かせない。 これが最も重要なポイントです。

最初にClaude AIと対話しながら、やりたいことを設計仕様書（ime-simulator-spec.md）にまとめました。

ime-simulator-spec.md（約350行）の内容:

1. 概要・目的
2. 技術構成とホスティング先の選定
3. 機能一覧（時計プレビュー、IMEインジケーター、プリセット、認証、i18n）
4. 各機能の設定項目・UI・デフォルト値
5. API設計（エンドポイント一覧、リクエスト/レスポンス例）
6. DBスキーマ（テーブル定義、インデックス）
7. 画面構成（ASCII図）
8. ファイル構成
9. デプロイ手順
10. 開発フェーズの分割と優先順位

たとえば画面構成はこんな感じでASCII図にしました：

┌─────────────────────────────────────────────────┐
│ Header: ロゴ / タイトル / 言語切替 / ログイン   │
├────────────────────┬────────────────────────────┤
│   設定パネル       │     プレビューエリア       │
│   (左サイドバー)   │                            │
│                    │   ┌──────────────────┐     │
│   □ 時計設定       │   │  時計プレビュー   │     │
│   □ IME設定        │   └──────────────────┘     │
│   □ プリセット     │   🇯🇵 🇺🇸 🇰🇷 🇹🇼 🇨🇳       │
├────────────────────┴────────────────────────────┤
│ Footer                                          │
└─────────────────────────────────────────────────┘

API設計もこの段階でエンドポイント・認証要否・リクエスト例まで決めました：

| Method | Path              | Auth | 説明                 |
|--------|-------------------|------|----------------------|
| GET    | /presets/default  | 不要 | デフォルトプリセット |
| GET    | /presets/popular  | 不要 | 人気ランキング       |
| POST   | /presets          | 必要 | プリセット保存       |
| POST   | /presets/:id/like | 必要 | いいね切替           |
| ...    | ...               | ...  | ...                  |

仕様書作成のコツ

• 「何を作りたいか」を日本語で具体的に伝える: 「時計アプリの設定をWebでプレビューしたい。アナログとデジタルの切替、IME言語ごとの色変更、プリセット保存ができるように」
• 制約を明示する: 「ホスティングは全部無料枠で。GitHub Pages + Render + Supabase」
• 既存のデスクトップアプリの設定項目を参照資料として渡す: Claude AIが設定項目の意味を理解し、適切なUIを提案してくれる
• 曖昧な部分は対話で詰める: 「認証はSupabase Authで。フロントから直接？バックエンド経由？」→ 議論の結果、認証フローのみ直接接続、データAPIはExpressを挟む構成に

Phase 2: 仕様書を渡してコード生成

仕様書ができたら、Claude Code CLIに読ませてコードを生成します。

# Claude Code CLIでの作業イメージ
> この仕様書 (ime-simulator-spec.md) に基づいて、
> フロントエンドとバックエンドのコードを生成してください。
> Phase 1（コアUI）から始めてください。

ここでのポイントはフェーズを分けて段階的に進めることです。

フェーズ分割の実例

Phase 1: コアUI
  → 時計描画、IMEインジケーター、設定パネル、言語切替ボタン
  → ここで一度ローカルで動作確認

Phase 2: バックエンド + 認証
  → Supabaseセットアップ、Express API、JWT検証、プリセットCRUD
  → フロントとバックエンドの結合テスト

Phase 3: 多言語 + 仕上げ
  → react-i18next導入、5言語の翻訳ファイル生成
  → レスポンシブ対応、デプロイ設定

全部一気に生成させると、どこで問題が起きたかわからなくなります。1フェーズごとに動作確認 → 次のフェーズのサイクルが重要です。

一度に生成されたもの（Phase 1の例）

Phase 1の指示だけで、以下がまとめて生成されました：

• AnalogClock.jsx — DOM + CSS transformによるアナログ時計
• DigitalClock.jsx — ロケール対応のデジタル時計
• IMEIndicator.jsx — 3層グラデーションのIMEインジケーター
• ClockPreview.jsx — プレビュー領域
• SettingsPanel.jsx — 設定パネル
• useSettings.js — 状態管理フック
• vite.config.js — Vite設定

仕様書にUI、設定項目、デフォルト値が書いてあるので、生成されたコードが仕様書と一致しているか照合するだけで済みます。これが仕様書ドリブンの強みです。

Phase 3: 動作確認と微調整

生成されたコードをローカルで動かし、UIの調整やバグ修正をClaude AIとの対話で進めます。

# 実際の微調整の例
> アナログ時計の秒針が太すぎる。もう少し細くして
> プリセット読み込み時にdirtyフラグが立ってしまうのを直して
> コールドスタート時のUXが悪い。接続中のバナーを出して

自然言語で指示できるので、CSSの微調整やロジックの修正が非常にスムーズです。

Claude AIが特に活躍した場面

1. 技術スタック横断のコード生成

React、Express、SQL、Docker、GitHub Actions——異なる技術領域のコードを一貫した設計思想で生成できるのは大きな利点です。

たとえば認証フロー：

• SQL: RLSポリシーの定義
• Express: requireAuthミドルウェアでJWT検証
• React: useAuthフックでセッション管理
• API Client: リクエストに自動でBearerトークン付与

これらが一貫した設計で生成されるので、結合テストでの不整合が少なかったです。

2. 5言語の翻訳ファイル

日本語・英語・韓国語・繁体字中国語・簡体字中国語の5言語の翻訳JSONファイルを一括生成してもらいました。

手動でやると相当な時間がかかる作業ですが、Claude AIなら一度で全言語分を生成できます。中国語は繁体字（台湾・香港）と簡体字（中国大陸）で用語が異なるため、そこも適切に分けてくれました。

3. Webのベストプラクティスの補完

業務ではJavaサーバーサイドやC/C++の制御系が中心だったため、Reactエコシステム特有の判断で自信を持てない場面がありましたが、Claude AIが適切な選択肢を提示してくれました：

• Canvas vs DOM: 「アナログ時計はCanvasで描く？」→ ReactならDOM + CSS transformの方が宣言的で管理しやすいと提案された
• 状態管理: 「Redux使うべき？」→ この規模ならカスタムフック（useSettings）で十分と判断
• 環境変数の扱い: ViteのVITE_プレフィックス、GitHub SecretsとActions連携の設定方法
• CORSの設定: 開発/本番で異なるオリジンをどう扱うか

36年間ソフトウェア開発をしてきたので、設計やロジックの勘所はわかります。ただ、Reactのエコシステム特有の作法（フック、コンポーネント設計、ビルドツール周り）はClaude AIに教わる形で進めました。

4. DBスキーマとセキュリティ設計

Supabase特有のRLSポリシー、auth.uid()関数の使い方、SECURITY DEFINER関数など、Supabase固有のパターンを仕様書の要件に合わせて生成してくれました。

注意点・うまくいかなかった点

生成コードは必ず読む

当然ですが、セキュリティに関わる部分は自分の目で確認が必須です。

具体的に確認したポイント：

• 認可チェック: プリセットの更新・削除で所有者チェックが入っているか
• デフォルトプリセットの保護: is_default = TRUEのプリセットが削除されないか
• 入力バリデーション: nameの長さ制限、settingsがオブジェクトであることの検証
• 環境変数: service_roleキーがフロントエンドに露出していないか

仕様書が曖昧だと出力も曖昧

仕様書に「プリセット機能をつける」とだけ書くと、CRUDの粒度、共有の仕組み、いいねの仕組みなど、AIが推測で埋めることになります。結果、自分の意図と違うものが生成されることがあります。

仕様書には「なぜそうするか」まで書くのがコツです。たとえば：

△ プリセットに共有機能をつける
○ プリセットに共有機能をつける。8文字のランダムコードを生成し、
  URLパラメータ (?share=xxx) で共有する。コードは暗号学的に安全な
  ランダム生成を使う。既に共有コードがあれば再生成しない。

フェーズを分けないと破綻する

最初にすべてを一度に生成させようとしたこともありましたが、以下の問題が発生しました：

• 生成されるコード量が多すぎて確認しきれない
• フロントエンドとバックエンドの不整合に気づきにくい
• どこでバグが入ったか特定しにくい

結局、Phase 1で動くUIを確認 → Phase 2でバックエンド結合 → Phase 3で仕上げのステップが最も効率的でした。

開発にかかった時間

フェーズ	内容	所要時間
仕様書作成	Claude AIと対話しながら仕様を策定	約3時間
Phase 1	コアUI（時計、インジケーター、設定パネル）	約4時間
Phase 2	バックエンド + 認証 + プリセットCRUD	約4時間
Phase 3	多言語対応 + レスポンシブ + デプロイ	約3時間
微調整	UI調整、バグ修正、コールドスタートUX	約2時間
合計		約16時間

フルスタックアプリをゼロから約2日で形にできました。36年の開発経験があるとはいえ、モダンフロントエンドは未経験の状態でこのスピードは、Claude AIなしでは不可能だったと思います。

まとめ：仕様書ドリブン AI開発のフロー

1. 仕様書を書く（AIと対話しながら）
   ├── 機能一覧
   ├── API設計
   ├── DBスキーマ
   ├── 画面構成
   └── 制約条件

2. フェーズに分けてコード生成
   ├── Phase 1: コアUI → 動作確認
   ├── Phase 2: バックエンド → 結合テスト
   └── Phase 3: 仕上げ → デプロイ

3. 微調整（自然言語で指示）
   ├── UIの調整
   ├── バグ修正
   └── UX改善

4. セキュリティ確認（人間の目で）
   ├── 認可チェック
   ├── 入力バリデーション
   └── 環境変数の管理

このフローの肝は**「仕様書の精度がコードの品質を決める」**ことです。仕様書作成に時間をかけるほど、後工程がスムーズになります。

制御系・業務系の開発者がモダンWeb開発に参入する、あるいは専門外の技術スタックに挑戦する際に、Claude AIは強力なパートナーになります。ただし、AIが出すコードを理解し、設計判断を下すのは自分自身です。AIは共同開発者であって、丸投げ先ではない——その意識が良い結果につながると感じました。

ソースコード: https://github.com/obott9/ime-simulator
Live Demo: https://obott9.github.io/ime-simulator/
構成の詳細: 別記事

---

🙏 Support / 開発者をサポート

このアプリ（記事）が役に立ちましたら、応援いただけると大変励みになります。

IMEIndicatorClock をはじめ、多言語ユーザー向けツールの開発を続けるために、皆さまのサポートをお待ちしています。

---

Developed in collaboration with Claude AI