Skip to content

canvas-dev.md

Latest commit

 

History

History
228 lines (165 loc) · 6.32 KB

canvas-dev.md

File metadata and controls

228 lines (165 loc) · 6.32 KB

Canvas 白板驱动开发

图形是第一公民，代码是白板的序列化形式

核心理念

传统开发：代码 → 口头沟通 → 脑补架构 → 代码失控
Canvas 方式：代码 ⇄ 白板 ⇄ AI ⇄ 人类（白板为单一真相源）
痛点 解法
🤖 AI 看不懂项目结构 ✅ AI 直接读白板 JSON，秒懂架构
🧠 人类记不住复杂依赖 ✅ 连线清晰，牵一发动全身一目了然
💬 团队协作靠嘴说 ✅ 指着白板讲，新人 5 分钟看懂

文件结构

canvas-dev/
├── README.md                 # 工作流概述
├── workflow.md               # 完整工作流步骤
├── prompts/
│   ├── 01-架构分析.md        # 从代码生成白板的提示词
│   ├── 02-白板驱动编码.md    # 根据白板生成代码的提示词
│   └── 03-白板同步检查.md    # 校验白板与代码一致性
├── templates/
│   ├── project.canvas        # Obsidian Canvas 项目模板
│   └── module.canvas         # 单模块白板模板
└── examples/
    └── demo-project.canvas   # 示例项目白板

快速开始

1. 准备工具

  • Obsidian - 免费开源白板工具
  • AI 助手（Claude/GPT-4，需支持读取 Canvas JSON）

2. 生成项目架构白板

# 将项目代码路径提供给 AI，使用架构分析提示词
# AI 自动生成 .canvas 文件

3. 用白板驱动开发

  • 在白板上画出新模块和依赖关系
  • 导出白板 JSON 发送给 AI
  • AI 根据白板生成/修改代码

完整工作流（15 步）

阶段 1：理解与准备

1. 理解核心理念

  • Canvas 白板作为唯一真相源
  • 代码是其序列化形式
  • 图形语言优于文字描述
  • 人类负责架构设计，AI 负责代码实现

2. 准备工具环境

  • 安装 Obsidian（免费开源白板工具）
  • 配置 AI 助手（Claude/GPT-4，需支持读取 Canvas JSON 格式）
  • 准备目标项目代码库

阶段 2：生成初始架构

3. 生成初始架构白板

  • 向 AI 提供项目代码路径
  • 使用架构分析提示词让 AI 扫描项目结构
  • AI 自动生成 .canvas 文件，包含模块节点和依赖连线

4. 用 Obsidian 打开 .canvas 文件

  • 导入生成的架构白板
  • 检查自动识别的模块、文件、API 调用关系
  • 验证关键依赖连线是否准确

阶段 3：人工优化

5. 人工优化白板架构

  • 拖动调整模块位置使布局清晰
  • 补充 AI 遗漏的隐式依赖连线
  • 添加注释节点标注关键设计决策
  • 删除冗余或错误的连接

阶段 4：同步机制

6. 建立代码 - 白板同步机制

  • 配置代码变更监听脚本
  • 设置白板自动更新规则（新文件→新节点，新 import→新连线）
  • 或手动维护：每次代码改动后更新对应白板区域

阶段 5：白板驱动开发场景

7. 新功能开发场景

  • 在白板上画出新模块框和预期调用关系
  • 导出白板 JSON 发送给 AI
  • 指令："按照这个架构图实现具体代码"
  • AI 根据节点名称、连线方向生成文件和函数调用

8. 代码重构场景

  • 在白板上删除/重连模块间的依赖线
  • 标注需要拆分的大模块
  • 发送修改后的白板给 AI："按新架构重构代码，列出需要修改的文件清单"

9. Code Review 场景

  • Review 前先看白板全局架构
  • 识别异常连线（如前端直接连数据库、循环依赖）
  • 在白板上标注问题点
  • 讨论时指着白板说明："这条调用链不应该存在"

阶段 6：团队协作

10. 加速团队协作

  • 新人入职时先看白板 1 分钟理解全局
  • 需求评审时在白板上画出变更范围
  • 技术方案会议投屏白板而非代码
  • 会后将白板标注转化为开发任务

阶段 7：维护一致性

11. 维护白板与代码一致性

  • 每次 PR/MR 合并前检查白板是否需要更新
  • 定期运行自动校验脚本：对比白板 JSON 与实际代码依赖
  • 发现不一致时优先修正白板（因为白板是事实来源）

阶段 8：扩展应用场景

12. 扩展应用场景

  • 接手遗留项目时先自动生成白板快速理解
  • 性能优化时用白板标注热点路径
  • 安全审计时检查白板上的敏感数据流向
  • API 设计时画出服务间调用拓扑

缺口澄清

13. 明确项目类型

  • A) 单体应用（单进程多模块）
  • B) 微服务架构（多服务 RPC 通信）
  • C) 前后端分离（前端框架 + 后端 API）

14. 选择白板粒度级别

  • A) 文件级（每个代码文件一个节点）
  • B) 类/函数级（每个类一个节点）
  • C) 服务级（仅显示大模块）
  • 推荐：新手选 A，复杂项目选 C

持续迭代

15. 持续迭代工作流

  • 每周回顾白板是否反映真实架构
  • 收集团队反馈优化节点命名和布局规则
  • 探索白板与 CI/CD 集成（如 PR 触发白板 diff 检查）
  • 分享最佳实践案例到团队知识库

提示词模板

架构分析提示词

你是一个专业的软件架构师。请分析以下项目代码结构，生成一个架构白板。

项目路径：[项目路径]

要求：
1. 识别所有模块/文件
2. 分析模块间的依赖关系
3. 生成 .canvas 文件格式的输出
4. 用连线表示数据流和调用关系

白板驱动编码提示词

根据以下架构白板生成代码实现。

白板文件：[附上 .canvas 文件或截图]

要求：
1. 按照白板上的模块划分创建文件
2. 按照连线方向实现函数调用
3. 每个模块保持职责单一
4. 生成后说明文件结构和关键实现

白板同步检查提示词

请检查以下代码库与架构白板是否一致。

代码路径：[项目路径]
白板文件：[.canvas 文件]

检查项：
1. 是否有新增文件未在白板中标注
2. 是否有依赖关系已变更但白板未更新
3. 是否有白板上的模块已被删除
4. 生成差异报告

相关资源

维护

  • 来源：tukuaiai/vibe-coding-cn 仓库 assets/workflow/canvas-dev/
  • 最后更新：2026-03-23