dev-manager-tauri/.blueprint/CONVENTIONS.md

version	updated	source
1.0.0	2026-04-03	dev-manager-tauri

蓝图更新规则

⚠️ 本文件由 dev-manager-tauri 统一管理，请勿手动修改。规则更新请在 dev-manager-tauri 项目中进行。

本文件定义了 .blueprint/ 目录的维护规范，供 Claude 在对话中遵循。

目录结构

.blueprint/
├── manifest.yaml        ← 模块列表、关系、布局坐标
├── CONVENTIONS.md       ← 本文件（Claude 行为规则）
└── modules/
    └── <module-id>.md   ← 每个模块的详情 + 任务卡

何时更新蓝图

事件	操作
用户确认了新需求	在 manifest.yaml 新增模块，创建 modules/.md
完成了功能实现	更新模块 status → done，标记任务卡 ✅
拆分了大需求为子任务	在 modules/.md 中添加任务卡
调整了架构方向	更新 edges 关系，可能调整 area
放弃了某个方向	删除对应模块和文件，或标记 status: abandoned

模块状态定义

状态	含义	色标
done	已实现并验证	🟢 绿色
in_progress	正在开发	🔵 蓝色
planned	已规划，需求明确	🟡 黄色
concept	构思中，信息不完整	⚪ 灰色
blocked	执行受阻，需架构师介入	🔴 红色

任务卡格式

modules/.md 中的每个二级标题（###）是一张任务卡：

### 📋 任务标题
- status: todo
- complexity: M
- files: src/path/to/file.tsx, src-tauri/src/commands/xxx.rs
- depends: other-module-id
- acceptance: 简要描述完成标准
- blocked_reason: （仅 status: blocked 时填写）执行受阻的具体原因

详细说明（可选）。

状态前缀

前缀	status	含义
✅	done	已完成
🔵	in_progress	进行中
📋	todo	可派发（信息充足）
💭	concept	构思中
🔴	blocked	执行受阻

可派发标准（📋）

任务卡同时满足以下条件时标记为 📋：

1. status 为 todo
2. 有明确的 files（涉及哪些文件）
3. 有明确的 acceptance（验收标准）
4. complexity 为 S 或 M

不满足条件的 todo 任务保持无前缀，说明还需补充信息。

manifest.yaml 规范

模块字段

- id: kebab-case-id        # 唯一标识，同时是 modules/ 下的文件名
  name: 显示名称
  area: frontend            # 所属领域 ID
  status: done              # done / in_progress / planned / concept
  progress: 100             # 0~100，done 自动视为 100
  position: [x, y]          # React Flow 画布坐标（可选）

边字段

- from: module-a
  to: module-b
  type: dependency          # dependency（实线）/ related（虚线）

领域字段

- id: frontend
  name: 前端
  color: "#3B82F6"          # 节点边框/分组背景色

进度计算

模块的 progress 由其任务卡的完成比例推算：

• 无任务卡的模块：手动设置 progress
• 有任务卡的模块：完成数 / 总数 × 100（取整）

决策记录格式

模块文件中可添加 ## 决策记录 段落，记录架构决策的 WHY：

## 决策记录

- 选择阿里云 OSS 而非 GitHub Releases 作为更新源，因为国内用户访问 GitHub 不稳定
- 使用 document-driven 蓝图而非数据库存储，因为 Claude 天然支持文件读写且可版本控制

桌面 App 会以琥珀色卡片展示在模块详情面板中。

飞轮工作流

Claude 在每次对话中应遵循以下流程：

阶段 1：进入对话 — 读取蓝图

读取 .blueprint/manifest.yaml → 了解项目全景和当前状态

• 识别哪些模块 in_progress，哪些有可派发任务
• 用简短话语告诉用户当前项目进展（如 "18/22 模块已完成，2 个进行中"）

阶段 2：讨论需求 — 同步更新蓝图

用户说的	Claude 应做的
"我想加个 XX 功能"	确认需求后：manifest 加模块 (status: concept)，创建 modules/.md
"XX 功能需要 A、B、C 三步"	在模块文件中拆分为 3 张任务卡
"这个方案确定了"	模块 status → planned，补充任务卡的 files/acceptance
"开始做 XX"	模块 status → in_progress
"为什么选这个方案"	记录到模块的 ## 决策记录

阶段 3：实现功能 — 标记完成或上报阻塞

成功 → 更新任务卡前缀为 ✅ → status: done
所有任务卡完成 → 模块 status: done
更新 manifest.yaml 的 updated 日期

失败且可自行解决 → 继续尝试
失败且无法独立解决 → 标记 🔴 blocked + 填写 blocked_reason → 留给架构师处理

架构师处理 blocked 任务

当 Opus 读蓝图发现 🔴 blocked 任务时：

1. 分析 blocked_reason，定位根因
2. 根据情况采取行动：
   • 拆：任务本身拆得不好 → 标记原任务 abandoned → 产出新任务卡
   • 补：缺少前置依赖 → 创建前置任务卡 → 原任务加 depends
   • 调：架构方向需调整 → 更新模块设计/决策记录 → 重新拆任务卡
3. 新任务卡就绪后，原 blocked 任务可标记为 abandoned 或更新为 todo

阶段 4：回顾 — 用户在桌面 App 查看

用户打开蓝图可视化：

• 看到全景进度
• 在「下一步」面板查看可派发任务
• 点击「复制派发」→ 粘贴给新 Claude 会话

飞轮的反馈信号

Claude 应关注这些信号来决定是否更新蓝图：

• 用户说"这个做完了" → 标记 done
• 用户说"这个不做了" → 标记 abandoned 或删除
• 用户说"这个要拆一下" → 拆分任务卡
• 用户说"记住这个决策" → 写入决策记录
• 用户没提蓝图但在讨论功能 → 主动提议更新蓝图
• 执行模型遇到无法解决的问题 → 标记 🔴 blocked + blocked_reason
• Opus 看到 blocked 任务 → 分析原因，拆/补/调后产出新任务卡

注意事项

• 不要删除已完成的任务卡，它们是项目历史的一部分
• 模块 id 一旦确定尽量不要修改（会影响 edges 引用）
• 每次更新后修改 manifest.yaml 顶部的 updated 日期
• progress 由桌面 App 自动从任务卡完成比例计算，不需要手动维护
• 当用户的操作隐含了蓝图变更但没有明说时，Claude 应主动提议更新（而非沉默）