Webアプリの正体は「フォルダの中のテキストファイルの集合」。難しそうに見えて、中身は読めるテキストが並んでいるだけ。
| ファイル / フォルダ | 役割 |
|---|---|
src/ | ソースコード本体 |
public/ | ブラウザに直接配信するファイル |
package.json | 使用ライブラリの一覧（部品リスト） |
node_modules/ | ダウンロード済みのライブラリ本体 |
.env | APIキーなど秘密の設定値 |
CLAUDE.md | Claude Codeへの指示ファイル |
CHANGELOG.md | バージョン変更の記録 |
| 拡張子 | 役割 |
|---|---|
.html | 画面の骨格（構造） |
.css | 見た目・デザイン |
.js | 動き・ロジック |
.json | 設定・データ構造 |
.md | Markdown文書（ドキュメント・メモ） |
.env | 環境変数（APIキー等、Gitに上げない） |
ファイル名と拡張子を見れば「これはデザインのファイル」「これは設定ファイル」と判別できる。Claude Codeが「style.css を編集しました」と言ったとき、それがデザインの変更だと分かる。
「プログラミング言語」と一口に言っても、動く場所が違う。ブラウザ側・サーバー側・データベースで使う言語は別物。
HTMLとCSSとJSだけで動くアプリはフロントエンドだけで完結する。サーバーもデータベースも不要。今回の訪問記録APPのVer1（IndexedDB）はこの形に近かった。
ブラウザが「このURLのページをくれ」とリクエストを送り、サーバーが「はい、これ」とレスポンスを返す。このやり取りがHTTPという共通ルールで動いていて、アプリを使っている間ずっと繰り返される。
↑ 目次へ戻る世の中のWebサービスは、この5つの層に分けて考えると整理しやすい。新しいサービスが出てきても、瞬時にどの層のものか判別できるようになる。
Claude Code、Cursor、CopilotGitHub（一強）、GitLabSupabase、Firebase、NeonCloudflare Pages、Vercel、NetlifyCloudflare ⟷ Vercel ⟷ Netlify は全部④の層。役割が同じなので1個選べばいい。
Supabase ⟷ Firebase ⟷ Neon は全部③の層。同じく1個でいい。
GitHub（②）+ Supabase（③）+ Cloudflare（④）は役割が違うので全部必要。「集約」の発想は無意味。
アプリは最初から完成形で作らない。3つの段階を順番に登っていくのが現実的な進め方。
自分のPCの中だけで動く状態。「試行錯誤の最高の遊び場」。失敗してもすぐやり直せる。ここで動きと感触を確かめてから次に進む。
ブラウザのローカルDBであるIndexedDBを使えば、サーバーなしでもデータを一時保存できる。ただしその端末のそのブラウザにしか存在しないデータになる。
「世界から見える状態にする」のがこの段階の課題。Cloudflare PagesやVercelを使えば、GitHubにコードをプッシュするだけで数秒でURLが発行される。
ローカルでは「自分が使う」前提だったが、公開後は不特定多数がアクセスしてくる。想定外の使い方・不正な入力・同時アクセス・セキュリティリスクが全部出てくる。ローカルで通用した「雑さ」は通用しなくなる。
.env ファイルやAPIキーをGitHubに上げてしまうのが初心者の定番ミス。.gitignore に必ず追加する。
「ユーザーが入力したデータを次回も見せたい」「複数人で共有したい」となったらデータベースが必要になる。Supabaseはデータベース＋認証機能をセットで提供してくれるため、個人〜小規模チームにちょうどいい。
稼働中サービスのデータ構造を変えるのは「走るバスのタイヤ交換」に近い。最初にどんなデータを持つか・ユーザーごとのアクセス権限はどうするか・将来の機能拡張を考慮して設計する必要がある。
| サービス | 無料デプロイ | 帯域 | 向く用途 |
|---|---|---|---|
| Cloudflare Pages | 500回/月（毎月リセット） | 無制限 | 小〜中規模。Workers/D1との連携◎ |
| Vercel | 十分な無料枠 | 100GB/月 | Next.jsとの相性が最高 |
| Netlify | 枠が狭くなってきた | 100GB/月 | 以前は定番。今は消極的選択肢 |
迷ったらCloudflare Pagesをデフォルトにする。Next.jsを本格的に使うならVercel。顧客がすでに別サービスを使っているならそれに乗る。Netlifyを新規で選ぶ理由は今は薄い。
| サービス | 特徴 | 向く用途 |
|---|---|---|
| Supabase | PostgreSQL + 認証 + ストレージ + Edge Functions をセット提供 | 個人〜小規模チーム。認証が必要なアプリ全般 |
| Firebase | Googleが運営。リアルタイムDB・NoSQL | チャット等リアルタイム性が高いアプリ |
| Neon | PostgreSQLのサーバーレス版。軽量 | DBだけ欲しいシンプルなケース |
| Cloudflare D1 | CloudflareのSQLiteベースDB。Workers連携が容易 | Cloudflare完結スタックを作りたい場合 |
従来：「複数プラットフォームを学ぶのは大変だから集約しよう」
今：プラットフォーム知識はCLAUDE.mdとドキュメントの中に書けばいい。頭で全部覚える必要はない。「集約しなければ」という圧力は半減している。適材適所で選べる。
抽象的な話より、実際に動いているアプリのスタックを見た方が分かりやすい。
訪問看護の時間記録アプリを実際に作った際の発展過程：
| バージョン | 段階 | スタック |
|---|---|---|
| Ver 1.x | ローカル動作 | HTML / CSS / JS + IndexedDB（ブラウザ内DB） |
| Ver 2.1 | ネットワーク版 | Supabase（PostgreSQL + Auth）+ Netlify |
| Ver 2.3 | Git導入 | GitHub連携 → 自動デプロイ |
| Ver 2.4〜 | Cloudflare移行 | Cloudflare Pages + Resend（メール通知） |
| フェーズ | 流れ |
|---|---|
| 開発時 | コードを修正 → git push → GitHubへ保存 → Cloudflareが自動検知 → デプロイ完了（数秒） |
| 利用時 | スマホ・PCでURLを開く → CloudflareがHTML/JSを配信 → ブラウザで動作 → 操作のたびSupabaseと通信 → データ保存・取得 |
コード（GitHub + Cloudflare）とデータ（Supabase）は別の場所にある。コードをいくら変えてもデータは消えないし、データが増えてもコードは変わらない。これがクラウドネイティブな設計の基本。
地図を持つことの実際の価値はここにある。構造が分かると、AIへの指示が変わる。
| 曖昧な指示 | 精度の高い指示 |
|---|---|
| 「ログイン機能を追加して」 | 「Supabaseのメール認証を使って、profilesテーブルと連携するログイン機能を追加して」 |
| 「データを保存して」 | 「Supabaseのvisitsテーブルに、user_id・日付・滞在時間を保存して。RLSは本人のみ読み書き可能にして」 |
| 「デプロイして」 | 「GitHubにプッシュして。Cloudflare Pagesが自動でデプロイするか確認して」 |
AIはコードが書ける。でも「何を作るか」「どの層に実装するか」「どのサービスを使うか」はこちらが決める必要がある。地図がある人は正確にナビゲートできる。地図がない人はAIが独断で決めた結果を受け取るだけになる。
毎回口頭で説明しなくていいように、プロジェクトのCLAUDE.mdに方針を書いておく：
| 書いておく内容 | 効果 |
|---|---|
| 使用するスタック（Supabase / Cloudflare） | 毎回「どのサービスを使いますか？」と聞かれなくなる |
| バージョン管理の方針（CHANGELOG.mdに記録する等） | 自動でCHANGELOGを更新してくれる |
| コーディングスタイルの好み | 一貫したスタイルで書いてくれる |