roadmap

ロードマップ

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

これは大まかな戦略文書ではありません。デリバリーの設計図です。各フェーズに具体的なタスクがあり、各タスクは実行可能で、フェーズ 1 からリリースまで、後戻りせずに構築できる順序になっています。

使用するタイミング

• 大規模な新製品に着手するとき（deep-research の後、または製品概要から）
• 漠然としたアイデアを実行可能な計画に変えるとき
• Claude Code との複数のセッションにまたがる、数週間の開発を計画するとき
• 「これを作って」と依頼する前 — ロードマップを Claude Code に渡して実行します

入力

次のいずれかが必要です。

入力	場所
詳細調査の概要	.jez/artifacts/research-brief-{topic}.md（/deep-research で作成）
製品概要	ユーザーが作りたいものを説明します
既存の未完成アプリ	CLAUDE.md とコードベースを読み、現在の状態を把握します
模倣・改善する競合製品	URL または製品名 — スキルが分析します

ユーザーが「Cloudflare 上でメモアプリを計画して」とだけ言った場合でも十分です。必要に応じて確認の質問をしてください。

ワークフロー

1. ビジョンを明確にする

技術的な計画を立てる前に、次の点を明確にします。

• 一文で：これは何ですか？（「チームや AI エージェント向けの、クラウドネイティブな Markdown ナレッジワークスペース」）
• 対象ユーザー：主なユーザー、二次的なユーザー、エージェントは誰ですか？（「まず Jez、次に Jezweb チーム、続いてクライアント」）
• 理由：既存のツールでは何ができませんか？どのようなギャップがありますか？（「既存のツールはヘッドレスで、閲覧したり、偶然何かを見つけたりできません」）
• 制約：技術スタック、予算、スケジュール、必須要件は何ですか？（「Cloudflare、MCP が必須、PWA が必要」）
• 構築しないもの：明示的に対象外とするものは何ですか？（「リアルタイムの CRDT コラボレーションやプラグインエコシステムは対象外」）

2. 技術スタックを定義する

ビジョンと制約に基づいて、技術スタックを確定します。

| Layer | Choice | Why |
|-------|--------|-----|
| Frontend | [framework] | [reason] |
| Backend | [framework + runtime] | [reason] |
| Database | [engine + ORM] | [reason] |
| Auth | [provider] | [reason] |
| Storage | [service] | [reason] |
| Search | [method] | [reason] |
| Hosting | [platform] | [reason] |

詳細調査の概要がある場合は、そこから推奨事項を取得します。ない場合は、ユーザーが現在使用している技術スタックに基づいて、明確な方針を持って選択します（パターンを把握するために ~/Documents/ を確認してください）。

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

製品全体で必要となるすべてのテーブル／コレクションを概略設計します。フェーズ 1 の分だけではなく、完全なモデルを設計します。これにより、開発途中でのスキーマの再設計を防げます。

## Data Model

### [entity]
  id, [type]
  [field], [type], [constraints]
  ...
  created_at, updated_at

### [entity]
  ...

### Relationships
- [entity] has many [entity] via [field]
- [entity] belongs to [entity] via [field]

各テーブルがどのフェーズで必要になるかを明示します。フェーズ 1 では 8 個のテーブルのうち 3 個しか必要ない場合でも、すべてを最初に設計しておけば、マイグレーションの負担を避けられます。

4. フェーズを計画する

ロードマップの中核となる部分です。各フェーズは、次の条件を満たす必要があります。

• 明確な目標がある — フェーズ完了時に何が変わるのかを一文で説明します
• 単独でデプロイ可能である — 各フェーズの完了後も、機能を絞った状態でアプリが動作します
• 前のフェーズを基盤とする — それ以前に作ったものを取り除く必要がないようにします
• Claude Code の 1 ～ 3 セッションで完了できる — 1 日以上かかるフェーズは分割します

フェーズの構成

各フェーズについて、次の内容を記述します。

## Phase N — [Name]
*Goal: [One sentence — what the user can do after this phase that they couldn't before]*
*Depends on: Phase N-1*
*Estimated effort: [hours/sessions]*

### What's New
[Bullet list of user-visible features]

### Database Changes
[New tables, new columns, migrations needed]

### API Routes
[New endpoints this phase adds]

### Frontend
[New pages, components, UI changes]

### Infrastructure
[New Cloudflare resources, secrets, config]

### Task Checklist
[Actionable tasks grouped by area — these are what Claude Code executes]

#### Setup
- [ ] [task]

#### Data Layer
- [ ] [task]
- [ ] [task]

#### API
- [ ] [task]

#### Frontend
- [ ] [task]

#### Testing & Polish
- [ ] [task]
- [ ] [task]

### Definition of Done
[How to verify this phase is complete — what to test, what to deploy]

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

フェーズ 1 — 常に MVP

最初のフェーズでは、一人が一つの目的に使えるものを作る必要があります。デモでも、骨組みだけのものでもありません。ユーザーが現在行っている作業（スプレッドシートや Apple Notes で行っている場合も含む）を置き換えられる、実用的なツールにします。

フェーズ 1 の範囲を判断する基準：「今使っているものの代わりに、これを使いますか？」答えが「いいえ」なら、MVP の機能が足りません。

フェーズ 1 の一般的な内容：

• 認証（単一ユーザーまたは招待制）
• 中核となるデータモデル（テーブル 2 ～ 3 個）
• 主要なエンティティの CRUD
• 基本的な UI（一覧＋詳細＋作成／編集）
• 本番ドメインへのデプロイ
• 最低限のスタイリング（ダークモード、レスポンシブ対応）

フェーズ 2 — 実用レベルに仕上げる

2 番目のフェーズでは、他の人に見せられるレベルまで MVP を仕上げます。

• UI の磨き込み
• 二次機能の追加（検索、フィルター、並べ替え）
• エラーハンドリングとバリデーションの改善
• 空の状態とオンボーディング（onboarding-ux スキルを使用）
• モバイル対応
• データのエクスポート／インポート

フェーズ 3 — 差別化要素

この製品は代替製品と何が違いますか？ここでその違いを形にします。

• AI 機能、MCP サーバー、セマンティック検索
• 競合製品にないもの
• 定番製品ではなく、これを選ぶ理由

フェーズ 4 以降 — 成長機能

以降の各フェーズで機能を追加します。

• 複数ユーザー／チーム機能
• 高度なビュー（グラフ、キャンバス、カレンダー、カンバン）
• インテグレーション（API、Webhook、サードパーティとの接続）
• 管理／設定
• パフォーマンスの最適化
• 公開向け機能（共有、埋め込み、ホワイトラベル）

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

製品がマルチテナント／SaaS を目指す場合に限ります。

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

6. ビルド順序

フェーズを表にまとめます。

| Phase | Goal | New tables | New routes | Sessions |
|-------|------|-----------|-----------|----------|
| 1 | Personal MVP | 3 | 8 | 2-3 |
| 2 | Polish + search | +1 | +4 | 1-2 |
| 3 | AI + MCP | +1 (vectors) | +5 | 2-3 |
| 4 | Team features | +2 | +6 | 2-3 |
| 5 | Integrations | 0 | +4 | 1-2 |
| 6 | Platform | +2 | +8 | 3-4 |

7. 意図的に開発しないもの

明示的にスコープ外とするものと、その理由を列挙します。これにより、実行中のスコープの拡大を防ぎます。

## Deliberately Not Building (v1)

- Real-time collaborative editing (CRDTs) — too complex, Phase 5+ at earliest
- Plugin ecosystem — too much surface area
- Native mobile app — PWA is good enough
- Offline-first with local storage — we're cloud-native

8. スキーマの進化マップ

フェーズごとにデータベースがどのように拡張されるかを示します。

| Table | Phase 1 | Phase 2 | Phase 3 | Phase 4 |
|-------|---------|---------|---------|---------|
| users | ✓ | | | |
| notes | ✓ | +tags col | +embeddings | |
| folders | ✓ | | | |
| note_links | | ✓ | | |
| workspaces | | | | ✓ |
| workspace_users | | | | ✓ |

9. API サーフェスマップ

API がどのように拡張されるかを示します。

| Route | Phase | Auth | Purpose |
|-------|-------|------|---------|
| POST /api/auth/* | 1 | — | Authentication |
| GET/POST /api/notes | 1 | Yes | Note CRUD |
| GET /api/search | 2 | Yes | Full-text search |
| GET /api/search/semantic | 3 | Yes | Vector search |
| GET/POST /mcp/tools | 3 | Token | MCP interface |
| POST /api/workspaces | 4 | Yes | Team workspaces |

出力

ロードマップを docs/ROADMAP.md に作成します（docs/ がない場合はプロジェクトのルートに作成します）。

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

生成後、以下も更新します。

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

品質ルール

1. すべてのタスクを実行可能にすること — 「認証をセットアップする」では曖昧すぎます。「better-auth をメールアドレス／パスワード認証で設定し、ユーザーとセッションのテーブルを作成して、Hono に認証ミドルウェアを追加する」なら実行可能です。
2. 各フェーズをデプロイ可能にすること — フェーズ完了後にはアプリが動作する必要があります。使えるものが何もできない「インフラフェーズ」は設けません。
3. フェーズ 1 は徹底的に小さくすること — 2～3 セッション以上かかる場合は、スコープを削ります。
4. データモデルを最初に完成させること — 構築途中でのスキーマの再設計は、時間を浪費する最大の原因です。
5. 「意図的に開発しないもの」は必須です — これがなければ、フェーズごとにスコープが膨らみます。
6. タスクはレイヤーごとにグループ化すること（データ、API、フロントエンド、インフラ） — Claude Code は機能ごとではなく、レイヤーごとに作業します。
7. 各フェーズに完了の定義を設けること — テストして確認すべき具体的な項目を示します。
8. スタックの表を含めること — フェーズごとの技術選定を Claude に推測させないでください。

---

実行モード

ロードマップは単なるドキュメントではなく、実行エンジンです。計画の生成後、これらのモードを使って構築を進めます。

モード：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 を読み、概要を作成します。

Phase 1: Personal MVP ✓ (committed abc1234)
Phase 2: Polish + Search ✓ (committed def5678)
Phase 3: AI + MCP ← IN PROGRESS (7/15 tasks done)
Phase 4: Team Features — not started
Phase 5: Integrations — not started

実行ルール

続行してください。 既定では、各フェーズの完了後、次のフェーズに進みます。許可を求めてフェーズ間で一時停止しないでください。ロードマップ自体が許可です。

フェーズの区切りでコミットしてください。 完了したフェーズごとに、明確なメッセージを付けて個別にコミットします。これにより、自然な復元ポイントが作成されます。

各フェーズの後にデプロイしてください。 プロジェクトにデプロイ先（wrangler.jsonc、vercel.json）がある場合は、各フェーズの完了後にデプロイします。実際にデプロイすることで、ローカル開発では見つからない問題を検出できます。

フェーズ間に簡易監査を行ってください。 フェーズ間に、デプロイ済みアプリの表示を簡単に確認します。次の作業に進む前に、レイアウトの問題、壊れたルート、明らかなリグレッションを見つけます。

最後に徹底的な監査を行ってください。 最終フェーズの後、次を実行します。

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

次の場合にのみ停止してください。

• タスクが失敗し、原因を特定できない場合（これまで見たことのないエラー）
• 手元にない認証情報、API キー、アカウントへのアクセスが必要な場合
• 設計上の判断に人の意見が必要な場合（「モーダルにするか、ページにするか？」）
• ビルドが完了した場合

次の場合は停止しないでください。

• 「続けてもよいですか？」— はい、常に続けてください
• 「デプロイしてもよいですか？」— デプロイ先がある場合は、はい
• 「コミットしてもよいですか？」— フェーズの区切りで、はい
• 次のタスクを妨げない軽微な問題 — GitHub イシューとして記録し、作業を続けてください

進捗の追跡

完了したフェーズは、docs/ROADMAP.md で直接マークします。

## Phase 1 — Personal MVP ✅
*Completed: 2026-03-19, commit abc1234*
*Goal: Replace Apple Notes for one user.*

現在のフェーズでは、完了したタスクにマークを付けます。

### Task Checklist
- [x] D1 schema — notes, folders tables
- [x] Hono API routes: CRUD for notes
- [ ] CodeMirror 6 integration  ← CURRENT
- [ ] Quick switcher (Cmd+K)

これにより、resume はロードマップを読み取り、作業を再開すべき場所を正確に把握できます。

dev-session の置き換え方法

以前の dev-session スキルでは、セッション間の引き継ぎに SESSION.md ファイルを管理していました。ロードマップの進捗追跡が、その役割を置き換えます。

dev-session にあったもの	ロードマップにあるもの
「Current Position」を記載した SESSION.md	ROADMAP.md のチェック済みタスク
「Resume Instructions」	次の未チェックタスクがそのまま指示になります
「What Works」セクション	コミットハッシュ付きの完了済みフェーズ
チェックポイントのコミット	フェーズの区切りでのコミット
セッションの終了	最終フェーズ＋徹底的な監査

ロードマップがセッションファイルの役割を果たします。別の追跡ドキュメントは必要ありません。