第 6 章：实战开发
需求分析与架构设计
与 Claude 协作完成
软件开发中最昂贵的错误，不是在编码阶段引入的 bug，而是在需求阶段就走错了方向。传统模式下，产品经理写 PRD、架构师出设计文档、开发者照单实现——信息在传递中不断失真，最终交付物与原始愿景相去甚远。
Claude Code 的出现改变了这一格局。它不仅能理解自然语言描述的需求，还能主动追问、拆解功能、生成技术方案，甚至直接产出可执行的文档。本章将系统讲解如何与 Claude 协作完成从"一句话需求"到"完整技术方案"的全过程，涵盖需求描述、功能拆解、架构设计、技术选型以及文档产出等核心环节。
一、用自然语言向 Claude 描述项目需求
1.1 为什么自然语言是最佳起点
Claude Code 的核心优势在于其对自然语言的深度理解能力。与模板化的需求文档不同，自然语言允许你以最接近人类思维的方式表达意图。你可以描述用户场景、业务痛点、期望效果，而不必过早陷入技术细节。
然而，自然语言描述需求也是一把双刃剑。描述过于模糊，Claude 会做出错误的假设；描述过于技术化，又失去了 AI 辅助思考的价值。关键在于找到"足够清晰但不过度约束"的平衡点。
1.2 需求描述的结构化方法
根据软件工程最佳实践和 Claude Code 社区经验1，向 Claude 描述需求时应遵循以下结构：
（1）业务背景与目标
先说明"为什么做"，再讲"做什么"。Claude 需要理解业务上下文才能给出合理的技术建议。
用户：我们要做一个在线协作白板工具，类似 Miro 但面向教育场景。
核心目标是让老师和学生能在课堂上实时协作完成思维导图和流程图。
主要用户是 K12 教师，他们通常没有技术背景，需要极简的操作体验。
（2）核心功能清单
用清单形式列出必须实现的功能，区分"必须有"和"最好有"。
用户：核心功能包括：
- 创建和编辑白板（必须）
- 多人实时协作（必须）
- 基础图形库：矩形、圆形、箭头、文本（必须）
- 思维导图自动布局（必须）
- 导出为图片/PDF（最好有）
- 课堂模板库（最好有）
（3）约束条件
明确技术约束、合规要求、性能指标等边界条件。
用户：约束条件：
- 前端必须用 Vue 3 + TypeScript
- 后端优先考虑 Node.js 生态
- 需要支持 50 人同时在线协作
- 数据必须存储在国内服务器
- 需要符合教育行业数据安全规范
（4）用户场景示例
用具体场景帮助 Claude 理解用户旅程。
用户：典型使用场景：
1. 王老师课前创建一个"细胞结构"主题白板
2. 课堂上学生通过链接加入，每人用不同颜色标注细胞器
3. 王老师实时看到所有学生的操作，可以锁定某些区域
4. 课后导出白板作为课堂记录发给家长
1.3 让 Claude 主动追问
Claude Code 内置了 AskUserQuestion 工具2，可以在你给出初步需求后主动发起结构化访谈。这是避免需求遗漏的最有效手段。
对话示例：
用户：我想做一个在线协作白板工具，面向 K12 教育场景。
请你先不要写代码，先通过 AskUserQuestion 工具 interview 我，
把需求彻底搞清楚。重点关注技术实现、UI/UX、边界情况和权衡取舍。
Claude：好的，我会通过一系列问题来深入理解您的需求。
首先，关于实时协作：
[AskUserQuestion] 您期望的实时协作粒度是什么？
是类似 Google Docs 的字符级同步，还是更粗粒度的
"操作级"同步（如"添加了一个矩形"）？
这会直接影响我们选择的协作算法（CRDT vs OT）。
用户：操作级同步就够了，教育场景不需要那么精细。
Claude：明白了。下一个问题：
[AskUserQuestion] 关于离线支持，如果学生在网络不稳定
的环境下使用，您期望系统如何处理？是完全不可用，
还是允许本地编辑后同步？
用户：最好能支持本地缓存，网络恢复后自动同步。
Claude：了解。继续下一个关键问题：
[AskUserQuestion] 白板的权限模型是怎样的？
老师是否拥有完全控制权（可以删除学生的内容）？
学生之间是否可以互相修改对方的内容？
用户：老师有完全控制权，学生只能修改自己的内容，
但可以看到所有人的内容。
这种访谈式需求收集通常能挖掘出大量你最初没想到的需求点。Ran Isenberg 在构建 Propel（个人 Kanban 应用）时使用类似的 BMAD 框架进行需求访谈，有效发现了许多最初未考虑到的用户流程3。
二、Claude 辅助需求拆解：功能模块划分与用户故事生成
2.1 从需求到功能模块的自动划分
当需求收集完成后，下一步是将其拆解为可执行的功能模块。Claude 可以基于领域知识自动识别功能边界，并建议合理的模块划分。
对话示例：
用户：基于我们刚才讨论的需求，请帮我将这个项目拆解为
功能模块。每个模块需要包含：模块名称、职责描述、
包含的核心功能点、与其他模块的依赖关系。
Claude：基于您的需求，我建议将项目划分为以下 6 个核心模块：
┌─────────────────────────────────────────────────────┐
│ 协作白板系统 │
├─────────────┬─────────────┬─────────────┬───────────┤
│ 白板引擎 │ 实时协作 │ 用户管理 │ 权限控制 │
│ (Canvas) │ (WebSocket)│ (Auth) │ (RBAC) │
├─────────────┼─────────────┴─────────────┴───────────┤
│ 图形编辑器 │ 导出服务 │
│ (Shapes) │ (Export) │
└─────────────┴────────────────────────────────────────┘
模块详情：
1. 白板引擎 (Whiteboard Engine)
职责：管理白板的创建、加载、状态持久化
功能：白板 CRUD、画布坐标系统、缩放/平移、历史记录
依赖：用户管理（获取创建者信息）
2. 图形编辑器 (Shape Editor)
职责：提供图形创建和编辑能力
功能：基础图形绘制、选中/拖拽/缩放、属性面板、
思维导图自动布局算法
依赖：白板引擎（操作目标画布）
3. 实时协作 (Real-time Collaboration)
职责：实现多用户实时同步
功能：WebSocket 连接管理、操作广播、光标同步、
在线用户列表、冲突处理（CRDT）
依赖：白板引擎、图形编辑器
4. 用户管理 (User Management)
职责：处理用户身份和会话
功能：注册/登录、OAuth（微信/钉钉）、访客模式、
用户资料管理
依赖：无（基础模块）
5. 权限控制 (Access Control)
职责：管理白板访问权限
功能：角色定义（老师/学生/访客）、内容所有权、
操作权限校验、白板分享链接
依赖：用户管理、白板引擎
6. 导出服务 (Export Service)
职责：将白板内容导出为各种格式
功能：PNG/JPG 导出、PDF 生成、JSON 数据导出
依赖：白板引擎、图形编辑器
2.2 用户故事的自动生成
功能模块确定后，Claude 可以进一步将其转化为符合 INVEST 原则的用户故事，并补充验收标准。
对话示例：
用户：请为"图形编辑器"模块生成详细的用户故事，
使用 Gherkin 格式（Given-When-Then），
并标注优先级（P0/P1/P2）和估算点数。
Claude：以下是"图形编辑器"模块的用户故事：
───────────────────────────────────────────────
US-001: 创建基础图形 [P0] - 3 点
───────────────────────────────────────────────
作为：课堂上的学生
我想：从工具栏拖拽基础图形到画布上
以便：快速构建我的思维导图
验收标准：
Scenario: 拖拽创建矩形
Given 用户处于编辑模式
When 从工具栏拖拽矩形图标到画布位置 (x: 100, y: 200)
Then 画布上应该出现一个默认大小 (120x80) 的矩形
And 矩形应该被自动选中，显示调整手柄
Scenario: 图形属性默认值
Given 用户刚创建了一个矩形
Then 填充颜色应该是白色 (#FFFFFF)
And 边框颜色应该是深灰色 (#333333)
And 边框宽度应该是 2px
───────────────────────────────────────────────
US-002: 编辑图形属性 [P0] - 5 点
───────────────────────────────────────────────
作为：课堂上的学生
我想：修改已创建图形的颜色、大小和文字
以便：让我的思维导图更美观和有意义
验收标准：
Scenario: 修改填充颜色
Given 用户选中了一个矩形
When 在属性面板点击颜色选择器并选择 #FF6B6B
Then 矩形的填充颜色应该立即变为 #FF6B6B
And 该变更应该实时同步给所有协作者
Scenario: 调整图形大小
Given 用户选中了一个矩形
When 拖拽右下角的调整手柄向右下方移动 50px
Then 矩形的宽度应该增加 50px
And 矩形的高度应该增加 50px
And 保持宽高比（如果 Shift 键被按住）
───────────────────────────────────────────────
US-003: 思维导图自动布局 [P1] - 8 点
───────────────────────────────────────────────
作为：课堂上的老师
我想：选中多个节点后一键生成思维导图布局
以便：节省手动排版的时间
验收标准：
Scenario: 基础树形布局
Given 画布上有 1 个中心节点和 6 个子节点
When 用户点击"自动布局"按钮并选择"树形"
Then 子节点应该以中心节点为根均匀分布
And 节点之间保持最小 40px 的间距
And 连接线自动绘制且不相交（如果可能）
社区开发者 PetterLiu 在博客中分享了一种更结构化的需求拆分方法4：使用 Claude Code 将需求文档按固定模板拆分为独立的需求卡片，每张卡片包含需求编号、类型、来源、场景、描述、原因、验收标准、重要性权重、需求关联等维度。这种方式特别适合需要严格需求管理的项目。
2.3 需求评审与冲突检测
Claude 不仅能生成需求，还能帮助评审需求的完整性和一致性。
对话示例：
用户：请评审我们刚才生成的用户故事，检查：
1. 是否有遗漏的边界情况
2. 不同故事之间是否有冲突
3. 验收标准是否可测试
4. 是否有过度设计的地方
Claude：经过评审，我发现了以下问题：
[边界情况遗漏]
- US-001 未考虑画布边界情况：当用户拖拽图形到画布边缘
或外部时应该如何处理？
- US-002 未定义"同时多人编辑同一图形"的冲突解决策略
- 缺少"撤销/重做"相关的用户故事（这是编辑器的核心功能）
[故事间冲突]
- US-002 要求"变更实时同步"，但未定义同步失败时的降级策略
- US-003 的自动布局可能会覆盖用户手动调整的位置，
需要明确的用户确认机制
[验收标准改进建议]
- "保持宽高比（如果 Shift 键被按住）"应该拆分为独立场景
- "连接线自动绘制且不相交（如果可能）"中的"如果可能"
不够精确，建议改为"在树形结构中保证不相交"
[潜在过度设计]
- 建议将 US-003 的"多种布局算法"（树形/ radial / 鱼骨）
拆分为 P1（树形）和 P2（其他），降低首版风险
三、架构设计协作：技术选型、架构模式与数据流
3.1 技术选型的协作讨论
技术选型是架构设计中最关键的决策之一。Claude 可以根据你的约束条件提供多方案对比，并分析每种方案的优劣。
对话示例：
用户：关于实时协作的数据同步，我在 CRDT 和 OT 之间犹豫。
我们的场景是：操作级同步、最多 50 人同时在线、
以图形编辑器为主（不是文本）。请帮我分析。
Claude：基于您的场景，我建议使用 CRDT（Conflict-free Replicated
Data Types），原因如下：
┌─────────────────┬──────────────────┬──────────────────┐
│ 维度 │ CRDT │ OT │
├─────────────────┼──────────────────┼──────────────────┤
│ 实现复杂度 │ 较低 │ 较高 │
│ 服务端依赖 │ 无（可 P2P）[^4] │ 主流实现需中央服 │
│ 离线支持 │ 原生支持 │ 需要额外处理 │
│ 图形编辑器适配 │ 原生支持图形操作 │ 文本操作更成熟 │
│ 内存占用 │ 较高 │ 较低 │
│ 生态成熟度 │ Yjs 成熟 │ ot.js 等现代实现 │
└─────────────────┴──────────────────┴──────────────────┘
具体分析：
1. 图形编辑器天然适合 CRDT
白板的操作是"添加图形"、"移动图形"、"修改属性"，
这些操作可以建模为 CRDT 数据结构（如 LWW-Map、
MV-Register 等）。实际实现中，图形的位置、大小、
旋转角度、z-index 等属性需要更复杂的 CRDT 类型，
并非简单的 LWW 寄存器或计数器。相比之下，OT 的变换
函数对非文本操作的定义非常繁琐。
2. 离线支持是教育场景的刚需
学生网络不稳定是常态。CRDT 允许本地编辑后异步同步，
无需复杂的冲突解决 UI。OT 在离线场景下需要中央服务器
协调，体验会差很多。
3. 推荐技术栈
- 客户端：Yjs（最成熟的 CRDT 库）
- 传输层：y-websocket 或自定义 WebSocket
- 持久化：Yjs 的更新可以序列化为 Uint8Array 存储
4. 需要注意的风险
- CRDT 的内存占用随操作历史增长，需要定期快照
- 50 人同时操作一个白板时，Yjs 的更新广播量会很大，
建议按"视口"做区域订阅，只同步可见区域的操作
用户：按视口订阅这个想法很好，请详细设计一下。
Claude：视口订阅方案设计如下：
[核心思路]
将画布划分为固定大小的网格（如 500x500px），
每个客户端只订阅当前视口覆盖的网格区域。
当用户平移或缩放导致视口变化时，动态调整订阅。
[数据结构]
```typescript
interface ViewportSubscription {
userId: string;
viewport: { x: number; y: number; width: number; height: number };
subscribedGrids: Set<string>; // "grid-x-y" 格式
}
interface GridCell {
id: string;
bounds: { x: number; y: number; w: number; h: number };
shapeIds: Set<string>;
subscribers: Set<string>; // userIds
}
```
[同步流程]
1. 客户端每 100ms 上报一次视口位置（节流）
2. 服务端计算视口覆盖的网格，更新订阅关系
3. 图形操作只广播给该图形所在网格的订阅者
4. 客户端进入新网格时，请求该网格的当前状态快照
[边界处理]
- 跨网格图形：如果一个图形跨越多个网格，它属于所有
覆盖到的网格，操作广播给所有相关订阅者的并集
- 缩放场景：当用户缩放到看到整个画布时，自动切换为
"全量订阅"模式
3.2 架构模式建议
Claude 可以根据项目规模和团队能力推荐合适的架构模式。
对话示例：
用户：请为这个项目推荐整体架构模式。团队有 3 名前端、
2 名后端，预计 3 个月 MVP 上线。
Claude：基于您的团队规模和 timeline，我推荐采用
"模块化单体 + 清晰分层"的架构：
┌─────────────────────────────────────────────┐
│ 前端 (Vue 3) │
│ ┌──────────┐ ┌──────────┐ ┌──────────────┐ │
│ │ 白板页面 │ │ 协作页面 │ │ 管理后台 │ │
│ └────┬─────┘ └────┬─────┘ └──────┬───────┘ │
│ └─────────────┴──────────────┘ │
│ 共享组件库 (UI Library) │
│ ┌──────────┐ ┌──────────┐ ┌──────────────┐ │
│ │ 图形引擎 │ │ 协作客户端 │ │ 状态管理 │ │
│ │ (Canvas) │ │ (Yjs) │ │ (Pinia) │ │
│ └──────────┘ └──────────┘ └──────────────┘ │
└─────────────────────┬───────────────────────┘
│ WebSocket / HTTP
┌─────────────────────┴───────────────────────┐
│ 后端 (Node.js + Express) │
│ ┌─────────────────────────────────────────┐ │
│ │ API Gateway │ │
│ └─────────────────────────────────────────┘ │
│ ┌──────────┐ ┌──────────┐ ┌──────────────┐ │
│ │ 白板服务 │ │ 协作服务 │ │ 用户服务 │ │
│ │ (REST) │ │ (WS) │ │ (REST) │ │
│ └──────────┘ └──────────┘ └──────────────┘ │
│ ┌──────────┐ ┌──────────┐ ┌──────────────┐ │
│ │ 导出服务 │ │ 通知服务 │ │ 权限服务 │ │
│ └──────────┘ └──────────┘ └──────────────┘ │
└─────────────────────┬───────────────────────┘
│
┌─────────────────────┴───────────────────────┐
│ 数据层 │
│ ┌──────────┐ ┌──────────┐ ┌──────────────┐ │
│ │ PostgreSQL│ │ Redis │ │ 对象存储 │ │
│ │ (主数据) │ │ (缓存/WS)│ │ (导出文件) │ │
│ └──────────┘ └──────────┘ └──────────────┘ │
└─────────────────────────────────────────────┘
选择理由：
1. 单体架构降低部署复杂度，5 人团队无需运维负担
2. 服务内部分层清晰，未来可平滑拆分为微服务
3. Yjs 的协作服务可以独立扩展（WebSocket 连接密集型）
4. PostgreSQL + Redis 是 Node.js 生态最成熟的组合
3.3 数据流设计
Claude 可以帮你梳理系统的数据流，识别潜在的瓶颈和一致性问题。
对话示例：
用户：请设计白板创建到协作的完整数据流，包括正常流程
和异常处理。
Claude：以下是完整的白板生命周期数据流：
[正常流程：创建白板]
老师浏览器 后端服务 数据库
│ │ │
│ POST /whiteboards │ │
│ { title, template } │ │
│ ────────────────────────> │ │
│ │ INSERT whiteboards │
│ │ RETURNING id │
│ │ ───────────────────────> │
│ │ <────────────────────────│
│ { id, title, ... } │ │
│ <──────────────────────── │ │
│ │ │
│ WebSocket: join-room │ │
│ { whiteboardId } │ │
│ ────────────────────────> │ │
│ │ CREATE y-doc instance │
│ │ (if not exists) │
│ │ │
│ WebSocket: room-joined │ │
│ { users: [...] } │ │
│ <──────────────────────── │ │
[正常流程：学生协作]
学生A浏览器 学生B浏览器 协作服务 Yjs Doc
│ │ │ │
│ 拖拽矩形 │ │ │
│ (本地更新) │ │ │
│ ─────┐ │ │ │
│ │ │ │ │
│ ▼ │ │ │
│ Yjs 更新编码 │ │ │
│ (Uint8Array) │ │ │
│ ─────────────>│ broadcast │ │
│ │ ─────────────────>│ apply update │
│ │ │ ──────────────>│
│ │ │ <──────────────│
│ │ broadcast │ │
│ │ <─────────────────│ │
│ │ │ │
│ │ Yjs 更新解码 │ │
│ │ (本地更新) │ │
│ │ ─────┐ │ │
│ │ ▼ │ │
│ │ 渲染新位置 │ │
[异常处理：学生断线]
1. 检测到 WebSocket 断开（心跳超时 30s）
2. 服务端标记用户为"离线"，广播给房间其他用户
3. 客户端进入"本地模式"：
- 继续允许本地编辑
- 操作存入本地 IndexedDB 队列
- 显示"离线模式"提示
4. 网络恢复后：
- 重新连接 WebSocket
- 发送本地队列中的所有更新
- Yjs 自动合并冲突（CRDT 特性）
5. 如果断线超过一定时间阈值（如 5 分钟，具体根据业务需求设定）：
- 提示用户"会话已过期"
- 提供"保存为本地文件"选项
四、Claude 的局限性：需求理解偏差与过度工程化风险
4.1 需求理解偏差的典型表现
尽管 Claude 在需求分析方面表现出色，但它并非完美。以下是常见的理解偏差类型5：
（1）隐含假设偏差
Claude 会基于训练数据中的常见模式做出假设，而这些假设可能不适用于你的特定场景。
用户：给 Todo 应用加个标签功能。
Claude：[生成代码，假设标签是字符串数组、支持多标签、
标签颜色随机分配]
问题：用户可能只需要单标签、不需要颜色、
或者标签需要层级关系（如"工作/项目A"）。
这些细节在未明确说明时，Claude 会按"最常见"的实现方式处理。
（2）规模感知偏差
Claude 难以准确判断项目的真实规模，倾向于给出"通用但可能过度"的方案。
用户：做一个内部使用的员工信息查询页面，
数据量在 500 人以内。
Claude：[建议使用微服务架构、Kubernetes 部署、
分布式缓存、CQRS 模式]
问题：500 人的内部系统用单体应用 + SQLite 都绰绰有余。
需要明确告知"简单优先"的约束。
（3）领域知识缺口
对于高度专业化的领域（如金融合规、医疗设备、特定行业法规），Claude 可能不了解关键的约束条件。
用户：做一个医疗影像查看系统。
Claude：[生成通用的图片查看器代码]
问题：未考虑 DICOM 标准、HIPAA 合规、
影像数据的匿名化处理等医疗行业特定要求。
4.2 过度工程化风险
AI 编程助手的一个普遍倾向是"展示能力"——给出技术上最优雅的方案，而非最适合当前阶段的方案6。防范过度工程化需要你在对话中主动设置约束。
防范策略：
用户：请设计用户认证系统。约束条件：
- 这是 MVP 阶段，用户量预计 < 1000
- 不要引入不必要的复杂度
- 优先选择"够用且好维护"的方案，而非"最先进"的
- 如果某个功能可以用 10 行代码实现，不要用库
Claude：[基于约束，推荐 Session + bcrypt 的简化方案，
明确说明哪些高级功能（JWT、OAuth、SSO）
留到后续版本再考虑]
4.3 应对策略
（1）显式约束法
在每次技术讨论前，先声明"不要做什么"。
用户：在开始设计之前，有几个明确的约束：
- 不要引入微服务，保持单体架构
- 不要使用 GraphQL，REST 就够了
- 不要引入消息队列，直接调用即可
- 数据库只用 PostgreSQL，不要多数据库
（2）渐进式披露法
不要一次性给 Claude 所有需求。先给核心需求，确认理解正确后再补充细节。
用户：第一步，我们只实现最核心的功能：
创建白板 + 添加矩形/圆形/文本 + 拖拽移动。
其他功能（协作、导出、模板）后续再讨论。
（3）对标验证法
要求 Claude 将其方案与已知的简单方案对比。
用户：你建议用 Redis + Bull 队列来处理导出任务。
请对比这个方案和"直接用 Node.js 的 worker_threads
处理导出"的优劣。如果后者在 100 并发内够用，
我倾向于选择更简单的方案。
五、实践流程：从一句话需求到完整技术方案的迭代过程
5.1 四阶段迭代流程
基于社区最佳实践和 Anthropic 官方指南13，推荐以下迭代流程：
┌─────────────────────────────────────────────────────────────────┐
│ 需求分析与架构设计迭代流程 │
├─────────────────────────────────────────────────────────────────┤
│ │
│ 阶段 1: 需求澄清 (30-60 分钟) │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ 输入: 一句话需求或粗略想法 │ │
│ │ 动作: Claude 通过 AskUserQuestion 主动访谈 │ │
│ │ 产出: 结构化的需求摘要 (SPEC.md) │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ 阶段 2: 方案设计 (60-120 分钟) │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ 输入: SPEC.md + 技术约束 │ │
│ │ 动作: 模块划分 + 技术选型 + 架构设计 │ │
│ │ 产出: 架构设计文档 (ARCHITECTURE.md) │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ 阶段 3: 计划拆解 (30-60 分钟) │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ 输入: ARCHITECTURE.md │ │
│ │ 动作: 用户故事生成 + 任务拆解 + 依赖排序 │ │
│ │ 产出: 实施路线图 (ROADMAP.md) + 任务清单 (TASKS.md) │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ 阶段 4: 验证评审 (30 分钟) │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ 输入: 全部文档 │ │
│ │ 动作: 自洽性检查 + 风险识别 + 简化机会识别 │ │
│ │ 产出: 评审报告 (REVIEW.md) │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
5.2 Plan Mode：设计阶段的安全网
Claude Code 的 Plan Mode（计划模式）是架构设计阶段的关键工具1。在 Plan Mode 下，Claude 只能读取和分析，不能修改任何文件。这强制分离了"思考"和"执行"两个阶段。
使用方式：
用户：/plan
Claude：[进入 Plan Mode]
用户：请分析我们当前代码库中认证相关的实现，
然后设计一个基于 JWT 的 SSO 集成方案。
不要修改任何代码，只输出分析报告和设计方案。
Claude：[读取相关文件，输出分析报告和设计方案]
用户：[评审方案，确认无误后按 Shift+Tab 切换回 default 模式]
用户：请按照刚才确认的方案实现 JWT SSO 集成。
Plan Mode 的核心价值在于：它给了你一个"暂停按钮"，让你在 Claude 开始改代码之前有机会纠正方向。对于架构层面的决策，这个暂停至关重要。
六、文档产出：PRD、架构图与 API 设计文档
6.1 PRD（产品需求文档）
Claude 可以基于需求访谈直接生成结构化的 PRD。
对话示例：
用户：基于我们刚才的所有讨论，请生成一份完整的 PRD，
保存为 docs/PRD.md。格式要求：
- 使用 Markdown
- 包含版本历史
- 每个功能点都有对应的用户故事编号
- 非功能需求单独成章
Claude：[生成 PRD 文档]
# 协作白板产品需求文档
## 版本历史
| 版本 | 日期 | 作者 | 变更内容 |
|------|------|------|----------|
| v0.1 | 2026-04-26 | Claude + 产品经理 | 初始版本 |
## 1. 产品概述
### 1.1 背景
[内容...]
### 1.2 目标用户
K12 教师和学生
### 1.3 核心价值主张
让课堂协作像在白板上画画一样简单
## 2. 功能需求
### 2.1 白板管理 [US-001 ~ US-005]
### 2.2 图形编辑 [US-006 ~ US-015]
### 2.3 实时协作 [US-016 ~ US-025]
### 2.4 权限控制 [US-026 ~ US-030]
### 2.5 导出分享 [US-031 ~ US-035]
## 3. 非功能需求
### 3.1 性能
- 首屏加载 < 3s（4G 网络）
- 图形操作响应 < 50ms
- 协作延迟 < 100ms（同区域）
### 3.2 兼容性
- Chrome 90+, Firefox 88+, Safari 14+, Edge 90+
- 支持平板触摸操作
- 最低支持 1280x768 分辨率
### 3.3 安全
- 所有数据传输使用 TLS 1.3
- 白板数据加密存储（AES-256）
- 数据传输和存储需满足《个人信息保护法》的技术要求（加密、访问控制等），具体合规方案需咨询法律顾问
6.2 架构设计文档
架构文档应包含系统拓扑、技术栈、数据模型和接口契约。
对话示例：
用户：请生成架构设计文档，保存为 docs/ARCHITECTURE.md。
需要包含：
1. 系统架构图（用文本字符画或 Mermaid 语法）
2. 技术栈清单及选型理由
3. 核心数据模型（ER 图）
4. 关键接口定义
5. 部署架构
Claude：[生成架构文档]
## 系统架构图
```mermaid
graph TB
Client[Vue 3 SPA] -->|HTTP| APIGateway[API Gateway]
Client -->|WebSocket| Collaboration[协作服务]
APIGateway --> Whiteboard[白板服务]
APIGateway --> User[用户服务]
APIGateway --> Export[导出服务]
Collaboration --> Redis[(Redis)]
Whiteboard --> PostgreSQL[(PostgreSQL)]
User --> PostgreSQL
Export --> ObjectStorage[(对象存储)]
```
## 技术栈
| 层级 | 技术 | 选型理由 |
|------|------|----------|
| 前端框架 | Vue 3 + TypeScript | 团队熟悉、生态成熟 |
| 状态管理 | Pinia | Vue 3 官方推荐 |
| 画布渲染 | Fabric.js | 功能丰富、文档完善 |
| 协作同步 | Yjs | CRDT 领域最成熟 |
| 后端框架 | Express.js | 轻量、团队熟悉 |
| 数据库 | PostgreSQL | 支持 JSON、可靠 |
| 缓存 | Redis | Pub/Sub 支持协作 |
| 部署 | Docker Compose | 简单、够用 |
6.3 API 设计文档
Claude 可以根据用户故事生成 RESTful API 定义，包括 OpenAPI 规范。
对话示例：
用户：请为白板管理模块生成 API 设计文档，
使用 OpenAPI 3.0 格式，保存为 docs/api/whiteboard.yaml。
Claude：[生成 OpenAPI 规范]
openapi: 3.0.0
info:
title: 白板管理 API
version: 1.0.0
paths:
/whiteboards:
post:
summary: 创建白板
requestBody:
content:
application/json:
schema:
type: object
properties:
title:
type: string
maxLength: 100
template:
type: string
enum: [blank, mindmap, flowchart]
isPublic:
type: boolean
default: false
responses:
'201':
description: 创建成功
content:
application/json:
schema:
$ref: '#/components/schemas/Whiteboard'
'400':
description: 参数错误
'401':
description: 未认证
get:
summary: 获取白板列表
parameters:
- name: page
in: query
schema:
type: integer
default: 1
- name: pageSize
in: query
schema:
type: integer
default: 20
maximum: 100
responses:
'200':
description: 成功
content:
application/json:
schema:
type: object
properties:
items:
type: array
items:
$ref: '#/components/schemas/Whiteboard'
total:
type: integer
components:
schemas:
Whiteboard:
type: object
properties:
id:
type: string
format: uuid
title:
type: string
ownerId:
type: string
createdAt:
type: string
format: date-time
updatedAt:
type: string
format: date-time
thumbnailUrl:
type: string
nullable: true
七、案例：一个真实项目的需求分析与架构设计全过程
7.1 项目背景
项目名称：ClassBoard（课堂协作白板） 团队规模：5 人（3 前端 + 2 后端） 时间约束：3 个月 MVP 原始需求："做一个给 K12 老师用的在线白板，能让学生一起画画"
7.2 第一阶段：需求澄清（1 小时）
初始输入：
产品经理：我们要做一个给 K12 老师用的在线白板，
能让学生一起画画。类似 Miro 但更简单。
Claude 的访谈过程：
Claude 通过 12 轮追问，澄清了以下关键问题：
- 用户规模：一个课堂通常 30-50 人，需要支持同时在线协作
- 设备类型：教室用平板为主，老师用笔记本
- 网络环境：学校 WiFi 不稳定，需要离线支持
- 内容类型：主要是图形和文字，不需要自由手绘
- 数据归属：白板属于老师，学生只有临时编辑权
- 合规要求：需要符合教育行业数据安全规范
- 集成需求：需要能接入学校现有的钉钉/企业微信
- 导出需求：需要导出图片发给家长
- 模板需求：需要常见课堂模板（思维导图、流程图、时间线）
- 权限粒度：老师可以锁定区域，学生只能编辑自己的内容
- 历史版本：不需要，但误删需要回收站
- 移动端：不需要原生 App，但 Web 需要适配平板
产出：SPEC.md（需求规格说明书）
7.3 第二阶段：方案设计（2 小时）
技术选型讨论：
| 决策点 | 选项 A | 选项 B | 最终选择 | 理由 |
|---|---|---|---|---|
| 协作算法 | CRDT (Yjs) | OT | CRDT | 离线支持更好，图形操作适配性更强 |
| 画布技术 | Canvas 2D | SVG | Canvas 2D | 性能更好，Fabric.js 生态成熟 |
| 后端架构 | 单体 | 微服务 | 单体 | 团队小，部署简单 |
| 数据库 | PostgreSQL | MongoDB | PostgreSQL | 关系型数据为主，团队更熟悉 |
| 实时传输 | WebSocket | SSE | WebSocket | 双向通信，协作场景必需 |
| 部署 | Docker | Serverless | Docker | 可控性强，成本可预测 |
产出：ARCHITECTURE.md（架构设计文档）
7.4 第三阶段：计划拆解（1 小时）
里程碑划分：
| 里程碑 | 周期 | 交付物 | 用户故事 |
|---|---|---|---|
| M1：基础白板 | Week 1-2 | 可创建/编辑白板的单用户版本 | US-001 ~ US-010 |
| M2：图形编辑 | Week 3-4 | 完整的图形库和属性编辑 | US-011 ~ US-020 |
| M3：实时协作 | Week 5-7 | 多用户实时同步 | US-021 ~ US-030 |
| M4：权限与导出 | Week 8-10 | 权限控制和导出功能 | US-031 ~ US-038 |
| M5：优化上线 | Week 11-12 | 性能优化、Bug 修复、上线 | 技术债务 + 测试 |
产出：ROADMAP.md + TASKS.md
7.5 第四阶段：验证评审（30 分钟）
Claude 自检发现的问题：
- 白板删除后没有软删除机制，需要补充
- 协作服务的 WebSocket 连接没有心跳检测
- 导出服务的并发控制缺失
- 平板触摸操作的支持不够详细
修复后产出：REVIEW.md
7.6 最终文档清单
docs/
├── PRD.md # 产品需求文档
├── ARCHITECTURE.md # 架构设计文档
├── ROADMAP.md # 实施路线图
├── TASKS.md # 详细任务清单
├── REVIEW.md # 评审报告
├── api/
│ ├── whiteboard.yaml # 白板 API 规范
│ ├── auth.yaml # 认证 API 规范
│ └── export.yaml # 导出 API 规范
└── assets/
├── architecture.png # 架构图
└── er-diagram.png # ER 图
八、总结与最佳实践
8.1 核心原则
- 人类是架构师，AI 是助手：Claude 可以生成方案，但最终的架构决策必须由人做出7
- 先计划，后编码：使用 Plan Mode 强制分离设计和实现阶段
- 渐进式披露：不要一次性给 Claude 所有信息，分阶段确认理解
- 显式约束：明确说出"不要做什么"，防止过度工程化
- 验证一切：让 Claude 生成测试用例来验证其理解是否正确
8.2 对话模式模板
需求澄清模式：
我想做 [一句话描述]。请你不要写代码，
先通过 AskUserQuestion 工具 interview 我，
重点关注 [技术实现/UI/边界情况/权衡]。
完成后生成 SPEC.md。
架构设计模式：
基于 SPEC.md，请设计系统架构。
约束条件：[列出约束]。
请提供至少 2 个方案对比，推荐一个并说明理由。
输出保存为 ARCHITECTURE.md。
任务拆解模式：
基于 ARCHITECTURE.md，请生成实施路线图。
要求：
- 按里程碑划分，每里程碑 1-2 周
- 每个任务包含：编号、描述、依赖、估算
- 识别关键路径和风险点
输出保存为 ROADMAP.md。
8.3 常见陷阱
| 陷阱 | 表现 | 对策 |
|---|---|---|
| 需求漂移 | Claude 逐渐偏离原始需求 | 定期对照 SPEC.md 检查 |
| 过度设计 | 引入不必要的复杂度 | 设置"简单优先"约束 |
| 上下文丢失 | 长会话后 Claude 忘记早期决策 | 使用 /clear 或开新会话 |
| 幻觉假设 | Claude 做出不合理的假设 | 要求 Claude 列出所有假设并确认 |
| 文档过时 | 代码变更后文档未更新 | 将文档更新作为代码审查 checklist 项 |
参考来源
Footnotes
- Anthropic. "Best Practices for Claude Code." Claude Code Documentation, 2026. https://code.claude.com/docs/en/best-practices ↩ ↩2 ↩3
- Anthropic. "Using CLAUDE.md files: Customizing Claude Code for your codebase." Claude Blog, 2025. https://claude.com/blog/using-claude-md-files ↩
- Isenberg, Ran. "Claude Code Best Practices: Lessons From Real Projects." Ran the Builder, 2026. https://ranthebuilder.cloud/blog/claude-code-best-practices-lessons-from-real-projects/ ↩ ↩2
- PetterLiu. "ClaudeCode实现简单需求文档分析与拆分." 博客园, 2025. https://www.cnblogs.com/wintersun/p/19080511 ↩
- Ryz Labs. "Why Most Developers Misunderstand the Limitations of AI Coding Assistants." Ryz Labs Learn, 2026. https://learn.ryzlabs.com/ai-coding-assistants/why-most-developers-misunderstand-the-limitations-of-ai-coding-assistants ↩
- Dhaliwal, Paul. "6 limitations of AI code assistants and why developers should be cautious." All Things Open, 2025. https://allthingsopen.org/articles/ai-code-assistants-limitations ↩
- Mangla, Sudhir. "The Claude Code: From Concept to Container: An Architect's Guide to the AI-Powered SDLC." Developers Voice, 2025. https://developersvoice.com/blog/ai/claude-code-architect-sdlc/ ↩