ロードマップ

アプリケーション全体の構築のための包括的な技術ロードマップを生成します。Claude Code が任意のフェーズを選んで何時間も自律的に実行できるほど詳細です。

これは高レベルの戦略文書ではありません。配信ブループリントです — 各フェーズには具体的なタスクがあり、すべてのタスクは実行可能で、フェーズ1からローンチまで巻き戻しなく構築できるように順序付けられています。

使用時期

• 主要な新製品を開始する（深掘り調査後、または製品ブリーフから）
• ぼやけたアイデアを実行可能な計画に変換する
• 複数週間のビルドを計画する（複数の Claude Code セッションにまたがる）
• 「これを構築して」と言う前に — ロードマップは Claude Code が実行するための指針です

入力

スキルは以下のいずれかが必要です:

入力	どこで見つけるか
深掘り調査ブリーフ	.jez/artifacts/research-brief-{topic}.md (/deep-research から)
製品ブリーフ	ユーザーが構築したい内容を説明
既存の部分的なアプリ	CLAUDE.md + コードベースを読んで既存の内容を理解
クローン/改善対象の競合製品	URL または製品名 — スキルが分析

ユーザーが単に「Cloudflare で note-taking アプリを計画して」と言った場合、それで十分です — 必要に応じて明確化の質問をしてください。

ワークフロー

1. ビジョンを確立する

技術的な計画を立てる前に、以下を明確にします:

• 一文: これは何か？ (「クラウドネイティブな markdown 知識ワークスペース、チームと AI エージェント向け」)
• 誰: 主なユーザー、副次的なユーザー、エージェント？ (「Jez まず、その次に Jezweb チーム、その次にクライアント」)
• なぜ: 既存のツールが何に失敗しているか？ ギャップは何か？ (「既存のツールはヘッドレス — ブラウジングできたり、偶然見つけたりできない」)
• 制約: スタック、予算、タイムライン、必須事項？ (「Cloudflare、MCP 必須、PWA である必要あり」)
• 構築しないもの: 明示的に範囲外のものは？ (「リアルタイム CRDT コラボなし、プラグインエコシステムなし」)

2. スタックを定義する

ビジョンと制約に基づいて、技術スタックをロックイン:

| レイヤー | 選択 | 理由 |
|-------|--------|-----|
| フロントエンド | [フレームワーク] | [理由] |
| バックエンド | [フレームワーク + ランタイム] | [理由] |
| データベース | [エンジン + ORM] | [理由] |
| 認証 | [プロバイダー] | [理由] |
| ストレージ | [サービス] | [理由] |
| 検索 | [方法] | [理由] |
| ホスティング | [プラットフォーム] | [理由] |

深掘り調査ブリーフが存在する場合、そこから推奨事項を取得します。そうでない場合、ユーザーの既存スタックに基づいて意見的な選択をします（~/Documents/ でパターンを確認）。

3. データモデルを設計する

完全な製品に必要なすべてのテーブル/コレクションをスケッチします。フェーズ1だけでなく、完全なモデルです。これはスキーマ再設計の中盤での実施を防ぎます。

## データモデル

### [エンティティ]
  id, [型]
  [フィールド], [型], [制約]
  ...
  created_at, updated_at

### [エンティティ]
  ...

### リレーションシップ
- [エンティティ] has many [エンティティ] via [フィールド]
- [エンティティ] belongs to [エンティティ] via [フィールド]

どのテーブルがどのフェーズで必要かをマーク。フェーズ1は8テーブル中3テーブルのみ必要かもしれませんが、事前にすべてを設計することでマイグレーションの痛みを回避します。

4. フェーズを計画する

これはロードマップの核です。各フェーズは次の条件を満たす必要があります:

• 明確な目標がある — このフェーズが終わったときに異なっている内容を1文で説明
• 独立してデプロイ可能である — 各フェーズ後、アプリは機能します（機能は削減）
• 前のフェーズの上に構築される — フェーズは前の内容を破棄することを必要としません
• 1～3つの Claude Code セッション内に完了可能である — フェーズが1日以上かかる場合、分割します

フェーズの構造

各フェーズについて:

## フェーズ N — [名前]
*目標: [一文 — このフェーズ後、ユーザーが以前はできなかったことが何ができるようになるか]*
*依存: フェーズ N-1*
*推定時間: [時間/セッション]*

### 新機能
[ユーザーが見える機能の箇条書き]

### データベース変更
[新しいテーブル、新しい列、必要なマイグレーション]

### API ルート
[このフェーズが追加する新しいエンドポイント]

### フロントエンド
[新しいページ、コンポーネント、UI 変更]

### インフラストラクチャ
[新しい Cloudflare リソース、シークレット、設定]

### タスク チェックリスト
[実行可能なタスク (領域別にグループ化) — これらが Claude Code が実行する内容]

#### セットアップ
- [ ] [タスク]

#### データレイヤー
- [ ] [タスク]
- [ ] [タスク]

#### API
- [ ] [タスク]

#### フロントエンド
- [ ] [タスク]

#### テスト & ポーリッシング
- [ ] [タスク]
- [ ] [タスク]

### 完了の定義
[このフェーズが完了したことを確認する方法 — テストする内容、デプロイする内容]

5. フェーズ計画パターン

フェーズ1 — 常に MVP

最初のフェーズは1人が1つの目的のために使用できるものを生成する必要があります。デモではなく、スケルトンではなく、ユーザーが現在実施していることを置き換えるワーキングツール（スプレッドシートや Apple Notes の場合でも）。

フェーズ1範囲テスト: 「これを現在使用しているものの代わりに使用しますか？」 いいえの場合、MVP は薄すぎます。

典型的なフェーズ1:

• 認証（シングルユーザーまたはインバイトのみ）
• コアデータモデル（2～3テーブル）
• プライマリエンティティの CRUD
• 基本 UI（リスト + 詳細 + 作成/編集）
• 本番ドメインへのデプロイ
• 最小限のスタイリング（ダークモード、レスポンシブ）

フェーズ2 — 本物にする

2番目のフェーズは MVP を他の人に見せたくなるようにします:

• UI をポーリッシング
• 二次的な機能を追加（検索、フィルター、ソート）
• より良いエラーハンドリングと検証
• 空の状態とオンボーディング（onboarding-ux スキルを使用）
• モバイルレスポンシブ
• データ エクスポート/インポート

フェーズ3 — 差別化要素

この製品を代替製品と異なるものにするものは何か？ ここで構築:

• AI 機能、MCP サーバー、セマンティック検索
• 競合他社にないもの
• 誰かがこれを確立されたプレーヤーの代わりに選ぶ理由

フェーズ4+ — 成長機能

その後の各フェーズは機能を追加:

• マルチユーザー/チーム機能
• 高度なビュー（グラフ、キャンバス、カレンダー、かんばん）
• 統合（API、ウェブフック、サードパーティ接続）
• 管理/設定
• パフォーマンス最適化
• パブリック向け機能（共有、埋め込み、ホワイトラベル）

最終フェーズ — プラットフォーム

製品が マルチテナント/SaaS に向かっている場合のみ:

• クライアント ワークスペース
• 課金/プラン
• ホワイトラベル/カスタムドメイン
• サードパーティ アクセス用 API トークン

6. ビルド順序

フェーズの概要をテーブルにまとめます:

| フェーズ | 目標 | 新しいテーブル | 新しいルート | セッション |
|-------|------|-----------|-----------|----------|
| 1 | パーソナル MVP | 3 | 8 | 2-3 |
| 2 | ポーリッシング + 検索 | +1 | +4 | 1-2 |
| 3 | AI + MCP | +1 (ベクトル) | +5 | 2-3 |
| 4 | チーム機能 | +2 | +6 | 2-3 |
| 5 | 統合 | 0 | +4 | 1-2 |
| 6 | プラットフォーム | +2 | +8 | 3-4 |

7. 意図的に構築しないもの

明示的に範囲外のものと理由をリスト。実行中のスコープ クリープを防ぎます:

## 意図的に構築しないもの (v1)

- リアルタイム協調編集（CRDT）— 複雑すぎる、フェーズ5以降の最早
- プラグイン エコシステム — サーフェス エリアが大きすぎる
- ネイティブ モバイル アプリ — PWA で十分
- オフライン優先とローカルストレージ — クラウドネイティブです

8. スキーマ進化マップ

データベースがフェーズ全体でどのように成長するかを示します:

| テーブル | フェーズ 1 | フェーズ 2 | フェーズ 3 | フェーズ 4 |
|-------|---------|---------|---------|---------|
| users | ✓ | | | |
| notes | ✓ | +tags col | +embeddings | |
| folders | ✓ | | | |
| note_links | | ✓ | | |
| workspaces | | | | ✓ |
| workspace_users | | | | ✓ |

9. API サーフェス マップ

API がどのように成長するかを示します:

| ルート | フェーズ | 認証 | 目的 |
|-------|-------|------|---------|
| POST /api/auth/* | 1 | — | 認証 |
| GET/POST /api/notes | 1 | Yes | Note CRUD |
| GET /api/search | 2 | Yes | 全文検索 |
| GET /api/search/semantic | 3 | Yes | ベクトル検索 |
| GET/POST /mcp/tools | 3 | Token | MCP インターフェース |
| POST /api/workspaces | 4 | Yes | チーム ワークスペース |

出力

ロードマップを docs/ROADMAP.md に書き込む（docs/ がない場合はプロジェクトルート）。

ファイルは単一の markdown ドキュメントであるべきで、Claude Code がセッション開始時に読み込んで次に何を構築するべきかを正確に知ることができます。プロジェクトの北極星です。

生成後、次も更新:

• CLAUDE.md — ロードマップへの参照を追加
• SESSION.md — 現在のフェーズを設定

品質ルール

1. すべてのタスクは実行可能である必要があります — 「認証をセットアップして」は曖昧です。「better-auth をメール/パスワードで設定、ユーザーとセッション テーブルを作成、Hono に認証ミドルウェアを追加」が実行可能です。
2. フェーズはデプロイ可能である必要があります — 各フェーズ後、アプリは機能。「インフラストラクチャ フェーズ」は使用可能なものを生成しません。
3. フェーズ1 は容赦なく小さい — 2～3セッション以上かかる場合、スコープをカット。
4. データモデルは事前に完全である必要があります — ビルド中盤でのスキーマ再設計が #1 の時間浪費者。
5. 「意図的に構築しないもの」は必須です — なければ、すべてのフェーズが成長します。
6. タスクはレイヤーでグループ化します（データ、API、フロントエンド、インフラ）— Claude Code は機能ではなくレイヤーで作業します。
7. 各フェーズに完了の定義があります — テストして確認する具体的な内容。
8. スタック テーブルを含めます — Claude Code に技術選択を推測させないでください。

---

実行モード

ロードマップは単なるドキュメントではなく、実行エンジンです。計画を生成した後、これらのモードを使用してビルドを推進します。

モード: start

トリガー: 「ビルドを開始して」、「ロードマップを実行して」、「全体を構築して」、「フェーズ1から始めて」

1. docs/ROADMAP.md を読む
2. プロジェクトがセットアップされていることを確認（リポジトリが存在し、依存関係がインストールされ、Cloudflare リソースが作成されている）
3. フェーズ1を開始し、タスクごとに実行
4. 各タスク後: 動作を確認（ビルド、実行、テスト）
5. フェーズ内のすべてのタスク後: 完了の定義チェックを実行
6. コミット: git add -A && git commit -m "Phase N complete: [goal]"
7. 該当する場合にデプロイ: npx wrangler deploy
8. デプロイされたアプリで /ux-audit quick を実行
9. ロードマップを更新: フェーズを完了としてマーク
10. 次のフェーズに進む。止めるな。聞くな。
11. すべてのフェーズが完了するか、ブロッカーに遭遇するまで繰り返す

モード: resume

トリガー: 「ビルドを再開して」、「続けて」、「続行」、「どのフェーズですか」

1. docs/ROADMAP.md を読む — 最初の未完了フェーズを見つける
2. git log をチェック — 最後のロードマップ関連コミットは何か？
3. コードベースの既存内容とフェーズが期待する内容をチェック
4. 現在のフェーズの最初の未完了タスクから選んで進行
5. start モードと同じように実行を続行

モード: status

トリガー: 「ロードマップステータス」、「どこにいるのか」、「何が完了しているか」

docs/ROADMAP.md を読み、サマリーを生成:

フェーズ1: パーソナル MVP ✓ (コミット abc1234)
フェーズ2: ポーリッシング + 検索 ✓ (コミット def5678)
フェーズ3: AI + MCP ← 進行中 (15タスク中7タスク完了)
フェーズ4: チーム機能 — 未開始
フェーズ5: 統合 — 未開始

実行ルール

続行する。 デフォルトはフェーズ完了後、次のフェーズに続行することです。フェーズ間で一時停止して許可を求めないでください。ロードマップが許可です。

フェーズの境界でコミット。 完了したすべてのフェーズは明確なメッセージを含む自身のコミットを取得。これは自然な復元ポイントを作成。

すべてのフェーズ後にデプロイ。 プロジェクトにデプロイメント目標（wrangler.jsonc、vercel.json）がある場合、各フェーズ完了後にデプロイ。実際のデプロイはローカル開発が検出しない問題をキャッチ。

フェーズ間で迅速な監査。 デプロイされたアプリを迅速に視覚的にチェック — レイアウト問題、壊れたルート、明らかな回帰を次の構築前に捕捉。

最後に徹底的な監査。 最終フェーズ後、以下を実行:

1. /ux-audit thorough — 包括的な一晩テスト
2. /onboarding-ux — 空の状態、ウェルカム フロー、ヘルプ コンテンツを生成
3. /project-docs — アーキテクチャ ドキュメントを更新

停止する場合のみ:

• タスクが失敗し、理由がわからない（見たことのないエラー）
• 資格情報、API キー、またはアクセスが必要だが持っていない
• 設計決定に人間の入力が必要（「これはモーダルかページか？」）
• ビルドが完了している

停止しないで:

• 「続行すべきか？」— はい、常に
• 「デプロイすべきか？」— はい、デプロイメント目標がある場合
• 「コミットすべきか？」— はい、フェーズの境界で
• 次のタスクをブロックしない小さな問題 — GitHub の問題としてログし、続行

進捗追跡

docs/ROADMAP.md で直接完了フェーズをマーク:

## フェーズ1 — パーソナル MVP ✅
*完了: 2026-03-19、コミット abc1234*
*目標: 1人のユーザー用に Apple Notes を置き換える*

また、現在のフェーズについて、完了したタスクをマーク:

### タスク チェックリスト
- [x] D1 スキーマ — notes、folders テーブル
- [x] Hono API ルート: notes の CRUD
- [ ] CodeMirror 6 統合  ← 現在
- [ ] クイックスイッチャー (Cmd+K)

これは resume がロードマップを読んで正確にどこを選ぶかを知ることができます。

これが dev-session をどのように置き換えるか

古い dev-session スキルはクロスセッション ハンドオフ用の SESSION.md ファイルを管理していました。ロードマップの進捗追跡はそれを置き換えます:

dev-session にあった	ロードマップにある
SESSION.md の「現在位置」	ROADMAP.md のチェック済みタスク
「再開手順」	チェック済みされていない次のタスクが指示です
「動作内容」セクション	コミット ハッシュ付きの完了フェーズ
チェックポイント コミット	フェーズ境界コミット
セッション をラップ	最終フェーズ + 徹底的な監査

ロードマップはセッション ファイル。個別の追跡ドキュメントは不要。