---
description: 保存总体设计方案 — 将架构讨论结果保存为 epics/ 目录下的方案文档
---

# 保存总体设计方案

将讨论共识整理为 `./epics/<名称>.md`。可多次执行更新。

## 演进场景的章节处理

当方案文档已存在且本次为「进行中演进」（部分子任务已落地）时，对原有章节的处理遵循以下规则：

| 变更类型 | 处理方式 |
|---|---|
| **新增功能** | 直接在文档相应位置新增章节（如新增一个包，则在"五、包结构与职责"追加；新增决策，则在"七、关键设计决策"追加） |
| **内容调整** | 在原章节顶部加引用块标注本次变更，原内容可保留或更新（更新时在引用块中说明改了什么） |
| **取消功能** | 原章节**不删除**，在章节标题下首行加引用块标注「已取消」，并简述原因；正文保留作为决策记录 |

引用块格式：

```markdown
## 五、包结构与职责

> [变更 YYYY-MM-DD] 调整：xxx 包职责由 A 改为 B，原因：实施中发现 A 与现有 Y 冲突。已完成任务 3 不受影响，未开始任务 5 需同步调整。

<原内容或更新后内容>
```

取消场景：

```markdown
## 五、包结构与职责

> [变更 YYYY-MM-DD] **已取消**：原计划的 xxx 模块取消实施。原因：实施任务 4 时发现依赖的 Y 能力不可用。替代方案：改用 Z（详见 §X）。已完成部分无影响。

<原内容保留不动>
```

每次重大演进（涉及章节调整/取消/新增）都需在文末「附录：演进历史」追加一条记录。

## 执行流程

**第一步：信息整理**

回顾已确认内容：核心隐喻、关键文件与模块、包结构与职责、关键执行链路、关键决策、约束与边界。不确定时用 `question` 确认。

**第二步：保存方案文档**

```markdown
# <方案名称>

> 讨论日期：YYYY-MM-DD

## 一、设计理念
核心原则、与现有/主流对比、关键隐喻

## 二、平台约束
运行环境、业务场景、安全模型

## 三、基础设施
依赖的已有能力、可复用代码

## 四、关键文件与模块
<探索代码库发现的关键路径和模块结构，方便后续恢复上下文>

## 五、包结构与职责
每个包：名称、状态[已有/新建/增强]、核心模型、职责描述、待实现清单

## 六、关键执行链路
主流程数据流图、核心循环

## 七、关键设计决策
"做了什么"和"为什么不做另一种"，及理由

## 八、开发优先级

## 九、待确定问题（可选）
尚未达成共识的设计疑问、需要进一步调研的技术选型、依赖外部确认的事项

## 附录

### 演进历史（每次重大演进追加）

| 日期 | 类型 | 范围 | 说明 |
|---|---|---|---|
| YYYY-MM-DD | 新增/调整/取消 | 涉及的章节或子任务编号 | 简述变更内容和原因 |

### 其他附录
与旧方案对比、参考来源、领域特定设计（如上下文策略、记忆系统等）
```

可按实际情况省略不相关章节。

**第三步：用户审查**

等待反馈：修改章节 / 补充细节 / 调整方向 / 审查通过。每次修改展示变更摘要。通过则引导下一步。

> 演进场景下，审查时需特别确认：① 取消的章节其涉及代码处理方式（保留/删除/标记废弃）；② 新增子任务编号已顺延（详见 `/epic-list`）；③ 影响到的「未开始」或「开发中」任务是否需同步调整草案。

**第四步：引导下一步（必须主动向用户输出以下内容）**

首次保存：

```
方案文档已保存: epics/<名称>.md
  /epic-list    ← 拆分为可执行任务列表
```

演进保存（追加）：

```
方案文档已更新: epics/<名称>.md
  /epic-list    ← 重新预览任务列表（新任务顺延编号，取消任务标状态）
  /epic-drafts  ← 同步更新 drafts/（调整依赖列、状态、新增/取消草案）
```

## 约束

- 可以修改 `./epics/` 文件
- 基于讨论共识，不添加用户未确认内容
- 讨论不充分时先补讨论，再写文档