roadmap

路线图

生成一份全面的技术路线图，用于构建完整的应用。详细程度应足以让 Claude Code 接手任意阶段，并自主执行数小时。

这不是一份高层战略文档，而是一份交付蓝图——每个阶段都有具体任务，每项任务都可执行，整体顺序经过规划，让你可以从阶段 1 一路构建到上线，无需返工。

适用场景

• 开始开发一款重要的新产品（完成 deep-research 后，或根据产品简介开始）
• 将模糊的想法转化为可执行的计划
• 规划跨越多个 Claude Code 会话、历时数周的开发工作
• 在提出“构建这个”之前——路线图就是你交给 Claude Code 执行的内容

输入

该技能需要以下其中一项：

输入	查找位置
深度研究简介	.jez/artifacts/research-brief-{topic}.md（来自 /deep-research）
产品简介	用户描述他们想要构建的内容
现有的部分应用	阅读 CLAUDE.md 和代码库，了解现有内容
要克隆或改进的竞品	URL 或产品名称——该技能会对其进行分析

如果用户只是说“规划一款运行在 Cloudflare 上的笔记应用”，这就足够了——根据需要提出澄清问题。

工作流

1. 明确愿景

开始任何技术规划之前，先明确以下内容：

• 一句话说明：这是什么？（“面向团队和 AI Agent 的云原生 Markdown 知识工作区”）
• 用户：主要用户、次要用户、Agent？（“先是 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. 规划阶段

这是路线图的核心。每个阶段必须：

• 目标明确——用一句话说明阶段完成后有什么变化
• 可独立部署——每个阶段结束后，应用都能正常工作（只是功能有所减少）
• 基于前一阶段构建——任何阶段都不需要推倒之前完成的内容
• 可在 1-3 个 Claude Code 会话内完成——如果一个阶段需要超过一天，就把它拆分

阶段结构

每个阶段包含：

## 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——让产品真正成型

第二阶段将 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/，则写入项目根目录）。

该文件应是一份独立的 Markdown 文档，Claude Code 可在任意会话开始时读取，并确切了解接下来要构建什么。它是项目的指引。

生成后，还要更新：

• 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 的内容	路线图的内容
含有“当前位置”的 SESSION.md	ROADMAP.md 中已勾选的任务
“恢复说明”	下一个未勾选的任务就是说明
“可用功能”部分	带提交哈希的已完成阶段
检查点提交	阶段边界提交
结束会话	最终阶段 + 全面审查

路线图就是会话文件。无需单独的跟踪文档。