# AI 辅助开发工作流手册

> 本项目基于蓝图×飞轮工作流，以下技能需要在合适时机手动触发。

---

## 快速参考

| 技能 | 什么时候触发 | 一句话说明 |
|------|------------|-----------|
| `/catchup` | **新会话开始时** | 读蓝图状态，找中断任务，告诉你现在在哪、该干嘛 |
| `/architect` | 需求复杂，不知道从哪里改起 | 先读代码再设计，不要直接开写 |
| `/splitter` | architect 出设计文档之后 | 把设计拆成可执行的任务卡 |
| `/spec-check` | 代码写完，提交之前 | 核对是否满足任务卡的验收标准 |
| `/Dev-edge-case` | M 级任务代码写完之后 | 穷举所有边界情况，找出遗漏 |
| `/code-review` | 每次提交之前 | 审查正确性、安全性、一致性 |
| `/smart-commit` | code-review 通过之后 | 生成规范的 Conventional Commits message |
| `/Dev-deep-think` | 感觉方案不够好但说不清哪里有问题 | 深度迭代，推动思考超越表面 |
| `/simplify` | 重构场景，代码写得太复杂 | 找出可复用和可简化的地方 |

---

## 一次会话的完整节奏

### 开始会话
Claude 自动读取 `.blueprint/manifest.yaml`，你无需操作。

如果是**跨会话续接**（上次没做完、新开了一个对话），运行：
```
/catchup
```
它会告诉你上次做到哪里、中断的任务还差什么、可以立即派发的任务有哪些。

---

### 阶段零：聊需求（无需触发技能，Claude 主动更新蓝图）

聊需求时 Claude 会根据你说的话自动更新蓝图，**你不需要触发任何命令**：

| 你说的 | Claude 自动做的 |
|--------|----------------|
| "我想加个 XX 功能" | 在 manifest.yaml 新增模块（status: concept），建 modules/<id>.md |
| "这个功能需要 A、B、C 三步" | 在模块文件里拆出 3 张任务卡 |
| "这个方案确定了" | 模块 status → planned，补充 files 和 acceptance |
| "开始做 XX" | 模块 status → in_progress，任务卡前缀改为 🔵 |
| "为什么选这个方案" | 写入模块的「决策记录」 |

> **注意**：如果 Claude 没有主动更新蓝图，可以直接说"帮我更新一下蓝图"，它会补上。

---

### 场景一：简单任务（S 级）

```
1. 告诉 Claude 要做什么
2. Claude 写代码
3. /spec-check     ← 核对验收标准（可选，有任务卡时推荐）
4. /code-review    ← 审查代码
5. git add
6. /smart-commit   ← 规范提交
```

---

### 场景二：中等任务（M 级）

```
1. 告诉 Claude 要做什么
2. Claude 写代码
3. /spec-check     ← 核对验收标准（可选）
4. /Dev-edge-case  ← 穷举边界情况
5. 补充遗漏的处理
6. /code-review    ← 审查代码
7. git add
8. /smart-commit   ← 规范提交
```

---

### 场景三：复杂需求（L 级，需先拆）

```
1. 告诉 Claude 需求背景
2. /architect      ← 先做架构分析，不写代码
3. 确认设计文档
4. /splitter       ← 拆成 S/M 任务卡，写入蓝图
5. 逐张任务卡按场景一/二执行
```

---

### 场景四：重构 / 代码质量优化

```
1. /simplify       ← 找出过度复杂的地方并简化
2. /code-review    ← 确认重构没有引入问题
3. git add
4. /smart-commit
```

---

## 各技能详解

### `/catchup` — 会话续接
**触发信号**：
- 新开了一个对话，上次任务没做完
- 不确定上次做到哪里了
- 想快速了解当前项目状态和可做的事

**产出**：中断任务的续接建议 + 可派发任务列表 + 阻塞任务摘要

---

### `/architect` — 架构分析
**触发信号**：
- 这个需求涉及多个文件，不知道改哪里
- 需要新增数据表或后端接口
- 感觉随便改会破坏现有逻辑

**不要触发的情况**：
- 需求很明确，只改一两个文件（直接做，S/M 级）

**产出**：设计文档（方案选择 / 受影响文件 / 系统边界 / 风险点）

---

### `/splitter` — 任务拆解
**触发信号**：
- `/architect` 刚出了设计文档
- 设计文档里有"拆解建议"

**前提**：当前对话中必须有 architect 的设计文档，否则结果不可靠。

**产出**：写入 `.blueprint/modules/<id>.md` 的任务卡（有 files + acceptance）

---

### `/spec-check` — 验收核对
**触发信号**：
- 代码刚写完，提交之前
- 任务卡有明确的 acceptance 字段

**价值**：避免"代码跑通了但没满足当初说好的验收条件"

---

### `/Dev-edge-case` — 边界穷举
**触发信号**：
- 任务涉及条件判断、数据校验、异步操作
- M 级任务代码写完后
- code-review 前

**注意**：它只列出缺失的处理，不评价代码好坏。看完它的输出再决定要不要补充。

---

### `/code-review` — 代码审查
**触发信号**：每次 `git add` 之后，`git commit` 之前。

**审查维度**：正确性 / 安全性 / 一致性 / 可维护性 / 性能

**输出**：
- ✅ 好的做法
- ⚠️ 建议改进（非阻塞）
- ❌ 必须修复（阻塞提交）

---

### `/smart-commit` — 规范提交
**触发信号**：code-review 没有 ❌ 问题之后。

**格式**：Conventional Commits
```
feat: 新功能
fix: 修复
refactor: 重构
docs: 文档
style: 样式
test: 测试
chore: 构建/工具
```

**注意**：它会展示生成的 message，等你确认后才执行 `git commit`。

---

### `/Dev-deep-think` — 深度思考
**触发信号**：
- 方案能跑，但感觉哪里不对劲
- code-review 有 ⚠️ 但不确定怎么改
- 想在提交前再推敲一遍设计

**不要滥用**：S 级任务不需要，会浪费上下文。

---

### `/simplify` — 简化重构
**触发信号**：
- 某段代码越改越复杂
- 发现有重复逻辑可以合并
- 明确是重构任务，不是新功能

---

## 自动触发的技能（无需手动）

以下技能 Claude 会根据上下文自动调用，不需要你输入：

| 技能 | 自动触发条件 |
|------|------------|
| `claude-api` | 代码中出现 `import anthropic` 等 |
| `update-config` | 你说"每次 XX 时自动做 YY"类需求 |