3つのWebサービス開発で学んだ「失敗しないロードマップ」の作り方

はじめに

個人開発でWebサービスを立ち上げるときに、とりあえずコードを書き始めると「あ、これ先に決めておくべきだった」という場面に何度も遭遇します。

そこで、3つのWebサービス（FolioInk、ポートフォリオサイト、エペナビ）の開発過程で踏んだ数々の地雷を元に、「次のプロジェクトで同じ失敗をしないためのロードマップテンプレート」 を作りました。

この記事では、そのテンプレートの全体像と、各フェーズに込めた「なぜこの順番なのか」という意図を解説します。
私と同じような個人開発者の方のロードマップ作成の参考となれば幸いです。

想定読者:

• 個人開発でWebサービスを立ち上げようとしている方

• 過去にプロジェクトで「あとから気づく系」の手戻りに苦しんだ方

• Claude Code等のAIコーディングツールを活用して開発している方

技術スタック（参考）:

• Next.js (App Router) + TypeScript + Tailwind CSS + shadcn/ui

• デプロイ先: Vercel

• AI: Claude Code + 専用エージェントチーム

ロードマップの全体構成

Phase 0: 基盤整備（コードを書く前の準備）
  ├── 0-0: プロジェクト基盤（環境・ツール・外部サービス）
  ├── 0-1: 要件定義
  ├── 0-2: デザインガイド
  ├── 0-3: 実装仕様書
  └── 0-4: データ・コンテンツ準備

Phase 1: 基盤実装（型・データ・レイアウト）

Phase 2: 機能実装（プロジェクト固有）

Phase 3: 仕上げ（デプロイ前 → デプロイ → デプロイ後）

最大のポイント: Phase 0が全体の半分以上を占めること。

PDCAのP（Plan）が非常に重要だと思っているため、「コードを書く前の準備」に最も時間をかけています。準備の質が実装スピードと最終品質の両方を決めると考えています。

Phase 0-0: プロジェクト基盤 — 「後回しにしない」リスト

Phase 0-0は、開発環境・ツール・外部サービスの選定をまとめて行うフェーズです。

開発環境・ツール

- CLAUDE.md 整備（AIへの指示書）
- エージェント定義の作成
- スキル・MCPの選定
- 実装ロードマップの作成・合意

AI駆動開発では、AIに何をどう指示するかの設計がプロジェクト基盤の一部になります。CLAUDE.mdにコーディング規約・エージェントの役割分担・レビューフローを定義しておくことで、AIの出力品質が安定します。←とClaude Codeが言っています。

プロジェクト初期化

- Next.js プロジェクト作成
- UIライブラリ選定
- .npmrc 作成（min-release-age=2）← サプライチェーン攻撃対策
- Git初期化 + GitHubリポジトリ作成
- Vercel連携 + 自動デプロイ確認
- .env.example 作成

.npmrc の min-release-age=2 は、npm パッケージの公開から2日以内のバージョンをインストールしない設定です。悪意あるパッケージが公開直後に拡散されるリスクを軽減します。小さな設定ですが、最初に入れておけばプロジェクト全体を守れます。

外部サービス選定 — ここが最も後回しにされやすい

- アクセス解析ツール（GA4 / Vercel Analytics等）
- カスタムドメイン
- DB選定・プロジェクト作成
- 決済サービス（Stripe等）
- メール送信サービス（Resend等）
- 認証プロバイダ（Google / GitHub OAuth等）
- ファイルストレージ（Supabase Storage等）

失敗談: アクセス解析の後回し

3つ目のプロジェクト（エペナビ）で、アクセス解析ツールの選定をPhase 0で行わず、実装の後半まで先送りにしてしまいました。結果、「デプロイしたけどユーザーの行動が全く見えない」状態が発生。解析ツールの導入には、プライバシーポリシーの更新やCookie利用の記載も必要なため、後から入れると影響範囲が広がります。

教訓: 「必要になってから考える」ではなく「最初に全部決める」。 不要なものは後で外せばいいだけです。

Phase 0-1〜0-3: 要件 → デザイン → 実装仕様

この3つのフェーズは必ずこの順番で進めます。

Phase 0-1: 要件定義

- 各ページ/機能の目的・ターゲット・ユーザーフローの定義
- 機能別の詳細要件
- 外部APIの選定・動作検証

失敗談: 外部APIの検証を先送り

エペナビで、ランク分布データを外部APIから取得する想定で要件を組みました。しかし、実際にAPIを叩いてみると必要なエンドポイントが存在しないことが判明。要件定義の段階で検証していれば、代替手段の検討を早期に始められました。

教訓: 外部APIは「使えるはず」ではなく「使えることを確認した」状態にする。

Phase 0-2: デザインガイド

- カラーパレット（WCAG AA準拠のコントラスト比を最初から考慮）
- タイポグラフィ
- スペーシング・レイアウトグリッド
- コンポーネントスタイルガイド

失敗談: コントラスト比の後回し

SaaSプラットフォームで、見た目の良さを優先してカラーパレットを決めた結果、デプロイ後のアクセシビリティ検証でWCAGコントラスト比不足が大量に発覚。カラー変更はUIの広範囲に影響するため、修正コストが大きくなりました。

教訓: カラーパレット策定時にWCAG AA準拠を最初から考慮する。 「きれいだけど読めない」は本末転倒です。

Phase 0-3: 実装仕様書

- コンポーネント仕様（Props定義・ファイル配置）
- API Route 仕様
- DBスキーマ設計
- 決済フロー設計
- メタデータ仕様
- セキュリティ要件定義
- テスト方針（← 0-3確定後に実施）

失敗談: 決済フローの設計ミス

SaaSプラットフォームでStripe Connectを導入した際、Account用とConnected accounts用のWebhookエンドポイントが別であることを見落としました。公式ドキュメントでフロー（実行順序・データの流れ）を確認せずに設計に入ったのが原因です。

教訓: 外部サービス連携は、公式ドキュメントでフローを確認してから設計する。 「たぶんこういう仕組みだろう」で進めない。

Phase 0-4: データ・コンテンツ準備

- 静的データ・コンテンツの作成
- 法的文書の作成（利用規約・プライバシーポリシー等）
- 外部データの初回取得・検証

AIに実装を任せる場合でも、「自分の言葉」で書くべきコンテンツは人間が用意する必要があります。自己紹介文、サービスの説明文、プロジェクト情報など。

法的文書もこの段階で用意しておくと、Phase 2で実装する際にスムーズです。

Phase 1: 基盤実装 — 型・データ・レイアウト

- 型定義（src/types/）
- DB接続設定・ORM初期化
- 静的データのコード化（src/data/）
- Header / Footer / Nav コンポーネント
- ルートレイアウト更新

Phase 0で決めた要件・デザイン・仕様を、コードの「骨格」として実装するフェーズです。ここまでの準備が整っていれば、迷うことなく進められます。

Phase 2: 機能実装

ここはプロジェクト固有のフェーズです。SaaSなら認証→収益化→成長機能の順、ツールサイトならコア機能→サブ機能の順など、優先順位マトリクスに基づいて実装します。

テンプレートとして共通化できるのは以下のみ:

- ページ・機能の実装（優先順位順）
- 法的ページの実装
- 問い合わせ機能の実装 ← メール受信設定とセットで計画する
- カスタム404ページ

注意: 問い合わせ機能とメール受信設定は必ずセットで計画してください。 後述のPhase 3-16と関連します。

Phase 3: 仕上げ — 最も地雷が多いフェーズ

仕上げフェーズは「デプロイ前」「デプロイ」「デプロイ後」の3段階に分かれます。ここが最も教訓の多いフェーズです。

デプロイ前チェックリスト

- ファビコン・Apple Icon
- SEO・OGP・メタデータ（JSON-LD、Canonical URL、OGP画像）
- パフォーマンス最適化（Lighthouse監査）
- アクセシビリティ検証（WCAG AA準拠）
- コードレビュー・セキュリティ監査（OWASP Top 10ベース）
- セキュリティヘッダー整合性確認（CSP・HSTS・Permissions-Policy）
- カスタムドメイン設定・リダイレクト方向確認
- 環境変数の本番設定

失敗談: ファビコンがデフォルトのまま本番公開

ポートフォリオサイトで、ファビコンを変更しないまま本番デプロイしてしまいました。Next.jsのデフォルトアイコンのまま公開されるという、地味に恥ずかしい状態に。チェックリストに含めていなかったのが原因です。

失敗談: ドメインのリダイレクト方向が逆

ポートフォリオサイトで、www.jir0.com → jir0.com にリダイレクトしたかったのに、逆方向（jir0.com → www.jir0.com）になっていました。カスタムドメイン設定時にリダイレクト方向を確認しなかったのが原因です。

失敗談: セキュリティヘッダーの見落とし

CSPの設計方式を統一する作業中、同じ設定ファイル内のHSTSヘッダーを見落としました。「指定された項目だけ修正する」のではなく「同カテゴリの項目を全て確認する」習慣が必要でした。

デプロイ

- GitHub経由で本番デプロイ（ローカル直接デプロイ禁止）
- デプロイ後の動作確認

失敗談: ローカルから直接デプロイしようとした

ポートフォリオサイトで npx vercel deploy を実行してしまい、GitHub連携とは別の不整合なデプロイが発生。デプロイは必ずGitHub経由（push → Vercel自動デプロイ）のフローを守るべきです。

デプロイ後 — 見落としやすいタスクの宝庫

- GA4 プロパティ作成 + コンバージョンイベント設計
- プライバシーポリシー更新確認 ← GA4導入とセット
- Google Search Console 連携
- HSTS Preload List申請 ← ヘッダー設定だけでは不十分
- メール受信設定 ← 問い合わせ機能とセット
- Webhook本番エンドポイント設定
- Dependabot設定
- エラー監視の導入検討

失敗談: 問い合わせメールが受信できない

SaaSプラットフォームで、問い合わせフォームを実装し mailto: リンクも設置したのに、メールの受信設定（MXレコード / メール転送）を行っていませんでした。「フォームが動く = メールが届く」ではないのです。DNS設定まで含めて「問い合わせ機能」です。

失敗談: GA4導入後にプライバシーポリシーの追記が必要と判明

GA4はCookieを使用するため、プライバシーポリシーにCookie利用と第三者提供について追記が必要でした。GA4導入とプライバシーポリシー更新は必ずセットで計画すべきです。

まとめ: 3つのプロジェクトで学んだこと

もし、実際に作成したロードマップをご覧になりたい方は、コメントいただければお配りします。