164 lines
3.7 KiB
Markdown
164 lines
3.7 KiB
Markdown
# Canvas 白板驱动开发工作流指南
|
||
|
||
## 核心理念
|
||
|
||
```
|
||
传统开发：代码 → 口头沟通 → 脑补架构 → 代码失控
|
||
Canvas方式：代码 ⇄ 白板 ⇄ AI ⇄ 人类（白板为单一真相源）
|
||
```
|
||
|
||
**图形是第一公民，代码是白板的序列化形式。**
|
||
|
||
## 工具准备
|
||
|
||
1. **Obsidian** - 免费开源白板工具
|
||
- 下载: https://obsidian.md/download
|
||
- 启用 Canvas 功能（默认已启用）
|
||
|
||
2. **AI 助手** - Claude/GPT-4
|
||
- 需支持读取 Canvas JSON 格式
|
||
- 推荐使用 Claude Code 或 Codex CLI
|
||
|
||
## 完整工作流
|
||
|
||
### Phase 1: 生成架构白板
|
||
|
||
**场景**: 接手新项目，快速理解架构
|
||
|
||
```
|
||
1. 提供项目代码路径给 AI
|
||
2. 使用架构分析提示词
|
||
3. AI 生成 .canvas 文件
|
||
4. 用 Obsidian 打开查看
|
||
```
|
||
|
||
**提示词模板**:
|
||
```
|
||
分析 {PROJECT_PATH} 项目，生成 Obsidian Canvas 架构白板。
|
||
粒度: {file/class/service}
|
||
重点关注: API路由、数据库模型、外部服务调用
|
||
```
|
||
|
||
### Phase 2: 人工优化白板
|
||
|
||
**场景**: 调整自动生成的白板
|
||
|
||
```
|
||
1. 拖动节点调整布局
|
||
2. 补充遗漏的依赖连线
|
||
3. 添加注释节点标注设计决策
|
||
4. 删除错误的连接
|
||
```
|
||
|
||
**布局原则**:
|
||
- 按功能分层（前端 → API → 服务 → 数据）
|
||
- 同层节点垂直对齐
|
||
- 保持连线不交叉
|
||
|
||
### Phase 3: 白板驱动编码
|
||
|
||
**场景**: 新功能开发
|
||
|
||
```
|
||
1. 在白板上画出新模块框
|
||
2. 添加预期的调用连线
|
||
3. 导出白板 JSON 发给 AI
|
||
4. AI 根据白板生成代码
|
||
```
|
||
|
||
**提示词模板**:
|
||
```
|
||
根据以下 Canvas 白板生成代码:
|
||
{CANVAS_JSON}
|
||
|
||
技术栈: {TECH_STACK}
|
||
目标目录: {TARGET_DIR}
|
||
```
|
||
|
||
### Phase 4: 白板驱动重构
|
||
|
||
**场景**: 架构调整
|
||
|
||
```
|
||
1. 在白板上删除/重连依赖线
|
||
2. 标注需要拆分的大模块
|
||
3. 发送修改后的白板给 AI
|
||
4. AI 生成重构代码
|
||
```
|
||
|
||
**提示词模板**:
|
||
```
|
||
白板已更新，请对比新旧版本重构代码:
|
||
旧白板: {OLD_CANVAS}
|
||
新白板: {NEW_CANVAS}
|
||
只输出需要修改的文件
|
||
```
|
||
|
||
### Phase 5: 一致性检查
|
||
|
||
**场景**: PR/MR 合并前
|
||
|
||
```
|
||
1. 运行一致性检查脚本
|
||
2. 对比白板节点与实际文件
|
||
3. 修复不一致之处
|
||
4. 优先修正白板（白板是事实来源）
|
||
```
|
||
|
||
## 场景速查
|
||
|
||
| 场景 | 操作 | 提示词关键词 |
|
||
|:---|:---|:---|
|
||
| 接手新项目 | 生成白板 | "分析项目，生成架构白板" |
|
||
| 新功能开发 | 画白板 → 生成代码 | "按这个白板实现代码" |
|
||
| 架构重构 | 改白板 → 重构代码 | "按新白板重构" |
|
||
| Code Review | 看白板全局 | "检查这条调用链" |
|
||
| 团队协作 | 共享白板 | "指着白板讲" |
|
||
|
||
## 最佳实践
|
||
|
||
### DO ✅
|
||
|
||
- 每次代码变更后更新白板
|
||
- 用颜色区分不同类型的模块
|
||
- 为复杂依赖添加 label 说明
|
||
- 定期运行一致性检查
|
||
|
||
### DON'T ❌
|
||
|
||
- 不要让白板与代码长期不同步
|
||
- 不要在白板中包含敏感信息
|
||
- 不要创建过于复杂的白板（拆分为多个）
|
||
- 不要忽略循环依赖警告
|
||
|
||
## 与其他工具集成
|
||
|
||
### CI/CD 集成
|
||
|
||
```yaml
|
||
# .github/workflows/canvas-check.yml
|
||
name: Canvas Sync Check
|
||
on:
|
||
pull_request:
|
||
paths: ['**.py', '**.canvas']
|
||
jobs:
|
||
check:
|
||
runs-on: ubuntu-latest
|
||
steps:
|
||
- uses: actions/checkout@v4
|
||
- run: python scripts/canvas_sync_check.py
|
||
```
|
||
|
||
### VS Code 集成
|
||
|
||
1. 安装 Obsidian 插件
|
||
2. 配置 `.canvas` 文件关联
|
||
3. 使用 Claude Code 读取白板
|
||
|
||
## 相关资源
|
||
|
||
- [Canvas白板驱动开发详解](../../../documents/guides/playbook/图形化AI协作-Canvas白板驱动开发.md)
|
||
- [架构分析提示词](../../../workflow/canvas-dev/prompts/01-架构分析.md)
|
||
- [白板驱动编码提示词](../../../workflow/canvas-dev/prompts/02-白板驱动编码.md)
|
||
- [白板同步检查提示词](../../../workflow/canvas-dev/prompts/03-白板同步检查.md)
|