---
description: 启动大型架构设计 — 通过多轮讨论，将模糊需求转化为清晰的设计方向
---

# 启动架构设计

## 流程定位

```
/epic-new [epics/xxx.md]  → 启动/恢复讨论（本命令）
  │                           /dev-research（任意阶段可用）
  ├─ /epic-save             → 保存方案文档（可多次）
  ├─ /epic-list              → 预览任务列表（不落盘，可多次）
  └─ /epic-drafts            → 输出草案到 ./drafts/
      └─ /dev-new ./drafts/xxx/1-xxx.md  → 进入详细设计
```

本命令是大型功能模块的架构设计入口。如果用户指定了 `epics/xxx.md` 路径，说明是恢复之前暂停或正在进行的讨论——需重新加载方案并重新探索代码库。

## 两种恢复场景

加载已有方案时，必须先判断属于以下哪种场景，处理方式不同：

| 场景 | 识别标志 | 处理重点 |
|---|---|---|
| **暂停恢复** | 仅存在 `epics/xxx.md`，无 `drafts/<名称>/summary.md` | 方案未落地，可较自由调整设计方向 |
| **进行中演进** | 同时存在 `epics/xxx.md` 和 `drafts/<名称>/summary.md`（部分子任务已完成或开发中） | 已落地代码不可轻易推翻；变更需兼顾已完成部分；新方案要兼容现有实现 |

> 进行中演进场景的典型诱因：实施中发现设计阶段未注意到的新信息、遇到实际问题需调整方案、需要新增功能等。

## 约束

- ⛔ 设计过程中**禁止编写代码**，仅限阅读/分析/搜索/沟通
- 允许 `/epic-save` 和 `/epic-drafts` 写入文件
- 不要急于拆解——先确定方向，再分解
- 被否决的方案也要记录（"为什么不做"的决策记录）
- 外部技术用 `/dev-research`，不凭记忆判断
- **进行中演进场景**：已完成（已合并到主分支）的子任务对应代码**默认视为硬约束**——除非用户明确同意返工，否则新方案必须兼容已完成部分；如确需推翻，必须显式向用户说明影响范围（涉及哪些已合并代码、回退成本）并获得确认

## 经验机制（必须先加载）

在分析代码前必须先加载经验，理解用户的决策偏好（取舍方向）：

```bash
# 首次 /dev-new 或 /epic-new：查看经验列表
~/mtools/dev-experience-list

# 加载本次相关经验（经验名以列表输出为准）
~/mtools/dev-experience-read "经验名1" "经验名2"

# 同一上下文中已有列表时跳过 dev-experience-list，按需 dev-experience-read
```

目的是在面对取舍时做出更符合用户预期的建议，减少返工。

## 执行流程

**第〇步：加载已有方案（如指定了 epics/xxx.md）**

**0.1 通用加载**

1. 读取方案文档，获取之前架构设计（设计理念、包结构、关键决策、关键文件等）
2. **重新探索代码库**（方案中"关键文件与模块"章节为起点）——环境可能已变化
3. 逐项评估：依赖能力是否还在？可复用代码是否已变？平台约束是否变化？模块边界是否合理？

**0.2 进行中演进场景的额外加载**

若同时存在 `drafts/<对应名称>/summary.md`（即"进行中演进"场景），还需：

1. 读取 `drafts/<对应名称>/summary.md`：明确每个子任务的当前状态（已完成 / 开发中 / 未开始 / 已取消）、依赖关系、整体进度
2. 通读各草案文件（特别是"已完成"任务的草案）：了解已落地代码的设计意图和验收标准
3. 探索已完成子任务对应的实际代码：验证方案文档与代码的一致性，识别可能的偏差
4. 与用户确认本次演进的目标：
   - **新增功能**？→ 探讨新功能与现有架构的关系，作为新增章节
   - **修改/取消原功能**？→ 评估对已完成代码的影响（是否需要回退/兼容层/平滑迁移）
   - **方案修正**？→ 找出设计与实现的偏差，决定是修正方案还是修正实现

**0.3 演进决策**

用 `question` 工具向用户呈现：

- 哪些原方案内容**沿用**
- 哪些**需调整**（及对已完成任务的影响）
- 哪些**新增**
- 哪些**取消**（及原因）
- 是否需要先 `/epic-save` 固化演进结论，再 `/epic-list` 调整任务列表

> 方案文档是"之前的结论"，必须基于**当前代码**和**实施进展**验证，不假设一切没变。

**第一步：理解需求**

1. 读 `AGENTS.md` 了解项目约束
2. 用只读工具（`glob`、`grep`、`lsp_*`）探索相关模块：定位目录/文件结构，理解现有代码模式和数据流，记录关键路径（后续写入方案文档"关键文件与模块"章节）
3. 涉及外部技术时用 `/dev-research` 搜索最佳实践

**第二步：架构讨论（多轮对话）**

原则：
1. 先给方向性判断，再细化
2. 能用代码库回答的先探索代码库，不直接问用户
3. 每个关键决策提供备选方案及取舍理由
4. 不猜测用户设计偏好——不确定的边界必须问
5. 主动讨论"不做什么"——边界比能力更重要

覆盖维度：核心隐喻、模块边界与职责、数据流向、关键决策（做什么/不做什么）、与现有代码关系

**第三步：输出方案方向并引导（必须主动向用户输出以下引导）**

满足以下条件即可固化：核心隐喻已确立且用户认可、模块边界清晰、关键链路数据流已画通、"不做什么"已确认。

向用户输出：

```
架构方向已清晰：
  /epic-save    ← 保存总体设计方案到 epics/<名称>.md
```

不满意则继续第二步。