0cdaa3678c
- Introduced BlueprintModal in ProjectCard for project blueprint visualization. - Added state management for displaying the BlueprintModal. - Implemented Blueprint-related interfaces and functions in commands.ts for handling blueprint data.
164 lines
5.2 KiB
Markdown
164 lines
5.2 KiB
Markdown
# 蓝图更新规则
|
||
|
||
本文件定义了 `.blueprint/` 目录的维护规范，供 Claude 在对话中遵循。
|
||
|
||
## 目录结构
|
||
|
||
```
|
||
.blueprint/
|
||
├── manifest.yaml ← 模块列表、关系、布局坐标
|
||
├── CONVENTIONS.md ← 本文件（Claude 行为规则）
|
||
└── modules/
|
||
└── <module-id>.md ← 每个模块的详情 + 任务卡
|
||
```
|
||
|
||
## 何时更新蓝图
|
||
|
||
| 事件 | 操作 |
|
||
|------|------|
|
||
| 用户确认了新需求 | 在 manifest.yaml 新增模块，创建 modules/<id>.md |
|
||
| 完成了功能实现 | 更新模块 status → done，标记任务卡 ✅ |
|
||
| 拆分了大需求为子任务 | 在 modules/<id>.md 中添加任务卡 |
|
||
| 调整了架构方向 | 更新 edges 关系，可能调整 area |
|
||
| 放弃了某个方向 | 删除对应模块和文件，或标记 status: abandoned |
|
||
|
||
## 模块状态定义
|
||
|
||
| 状态 | 含义 | 色标 |
|
||
|------|------|------|
|
||
| `done` | 已实现并验证 | 🟢 绿色 |
|
||
| `in_progress` | 正在开发 | 🔵 蓝色 |
|
||
| `planned` | 已规划，需求明确 | 🟡 黄色 |
|
||
| `concept` | 构思中，信息不完整 | ⚪ 灰色 |
|
||
|
||
## 任务卡格式
|
||
|
||
modules/<id>.md 中的每个二级标题（`###`）是一张任务卡：
|
||
|
||
```markdown
|
||
### 📋 任务标题
|
||
- status: todo
|
||
- complexity: M
|
||
- files: src/path/to/file.tsx, src-tauri/src/commands/xxx.rs
|
||
- depends: other-module-id
|
||
- acceptance: 简要描述完成标准
|
||
|
||
详细说明（可选）。
|
||
```
|
||
|
||
### 状态前缀
|
||
|
||
| 前缀 | status | 含义 |
|
||
|------|--------|------|
|
||
| ✅ | done | 已完成 |
|
||
| 🔵 | in_progress | 进行中 |
|
||
| 📋 | todo | 可派发（信息充足） |
|
||
| 💭 | concept | 构思中 |
|
||
|
||
### 可派发标准（📋）
|
||
|
||
任务卡同时满足以下条件时标记为 📋：
|
||
1. status 为 `todo`
|
||
2. 有明确的 `files`（涉及哪些文件）
|
||
3. 有明确的 `acceptance`（验收标准）
|
||
4. complexity 为 `S` 或 `M`
|
||
|
||
不满足条件的 todo 任务保持无前缀，说明还需补充信息。
|
||
|
||
## manifest.yaml 规范
|
||
|
||
### 模块字段
|
||
|
||
```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 画布坐标（可选）
|
||
```
|
||
|
||
### 边字段
|
||
|
||
```yaml
|
||
- from: module-a
|
||
to: module-b
|
||
type: dependency # dependency（实线）/ related（虚线）
|
||
```
|
||
|
||
### 领域字段
|
||
|
||
```yaml
|
||
- id: frontend
|
||
name: 前端
|
||
color: "#3B82F6" # 节点边框/分组背景色
|
||
```
|
||
|
||
## 进度计算
|
||
|
||
模块的 progress 由其任务卡的完成比例推算：
|
||
- 无任务卡的模块：手动设置 progress
|
||
- 有任务卡的模块：`完成数 / 总数 × 100`（取整）
|
||
|
||
## 决策记录格式
|
||
|
||
模块文件中可添加 `## 决策记录` 段落，记录架构决策的 WHY：
|
||
|
||
```markdown
|
||
## 决策记录
|
||
|
||
- 选择阿里云 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/<id>.md |
|
||
| "XX 功能需要 A、B、C 三步" | 在模块文件中拆分为 3 张任务卡 |
|
||
| "这个方案确定了" | 模块 status → planned，补充任务卡的 files/acceptance |
|
||
| "开始做 XX" | 模块 status → in_progress |
|
||
| "为什么选这个方案" | 记录到模块的 `## 决策记录` |
|
||
|
||
### 阶段 3：实现功能 — 标记完成
|
||
```
|
||
完成代码 → 更新任务卡前缀为 ✅ → status: done
|
||
所有任务卡完成 → 模块 status: done
|
||
更新 manifest.yaml 的 updated 日期
|
||
```
|
||
|
||
### 阶段 4：回顾 — 用户在桌面 App 查看
|
||
用户打开蓝图可视化：
|
||
- 看到全景进度
|
||
- 在「下一步」面板查看可派发任务
|
||
- 点击「复制派发」→ 粘贴给新 Claude 会话
|
||
|
||
### 飞轮的反馈信号
|
||
Claude 应关注这些信号来决定是否更新蓝图：
|
||
- 用户说"这个做完了" → 标记 done
|
||
- 用户说"这个不做了" → 标记 abandoned 或删除
|
||
- 用户说"这个要拆一下" → 拆分任务卡
|
||
- 用户说"记住这个决策" → 写入决策记录
|
||
- 用户没提蓝图但在讨论功能 → 主动提议更新蓝图
|
||
|
||
## 注意事项
|
||
|
||
- 不要删除已完成的任务卡，它们是项目历史的一部分
|
||
- 模块 id 一旦确定尽量不要修改（会影响 edges 引用）
|
||
- 每次更新后修改 manifest.yaml 顶部的 `updated` 日期
|
||
- progress 由桌面 App 自动从任务卡完成比例计算，不需要手动维护
|
||
- 当用户的操作隐含了蓝图变更但没有明说时，Claude 应主动提议更新（而非沉默）
|