# Design Records

设计记录分三类：稳定知识、议题研究、结构性改动的设计稿。三类内容都重要，但不应该混在一个入口里。

## 分类

| 类型 | 适合放哪里 | 主要作用 | 不该承担的作用 |
| --- | --- | --- | --- |
| 稳定知识 | `docs/wiki/` | 解释长期有效的结构、边界和操作入口 | 记录推演过程、承接临时讨论 |
| 议题研究 | 单独保存的研究文档 | 保存背景、比较、推理和阶段性结论 | 充当仓库首页或维护手册 |
| 设计稿 | 单独维护的 proposal / design / tasks | 管理结构性改动的方案和实施边界 | 代替当前实现说明 |

## 当前仓库里的研究文档

仓库里另外保存了几篇比较关键的研究长文，主题包括：

- skill runtime
- find-skill
- 项目整体改进
- curated PR 流程

这些文档共同特点是：它们解释为什么、比较过什么、接下来可能往哪走。它们不负责定义主干今天已经做到什么程度。

## 怎么读这些文档

### skill runtime 设计研究

适合回答：

- 这个方向为什么值得做
- 关键约束是什么
- 当时比较过哪些方案

不适合回答：

- 主干代码今天实现到了哪
- 当前线上行为到底是不是按它运行

### find-skill 研究

适合回答：

- 当前 find-skill 的优势和瓶颈
- 外部系统有什么可借鉴
- 演进顺序应该怎么排

不适合回答：

- 当前产品文档应该怎么写
- 哪些方案已经正式定版

### 项目整体改进研究

适合回答：

- 哪些问题是结构性的
- 哪些改进优先级更高
- 数据、工程、社区还有哪些短板

不适合回答：

- 某个改动现在具体做到哪一步
- 本周应该执行哪几项任务

### curated PR 流程研究

适合回答：

- curated PR 流程现在缺什么
- 哪些审核和自动检测能力还没落地
- 流程可以往哪加强

不适合回答：

- 当前主干已经完全按这份文档实现
- 这里列出的项都已经进入默认流程

## 什么时候该提炼进 wiki

满足下面几个条件时，就该把内容从研究文档提炼进 wiki：

- 这个问题被反复问到
- 结论短期内不会大改
- 多人协作都依赖同一套说法
- 它更像仓库知识，而不是一次研究过程

wiki 负责稳定入口，不负责保存全部推理细节。

## 什么时候不要提炼进 wiki

以下内容不适合直接塞进 wiki：

- 还在摇摆的方案比较
- 只有作者本人需要的长链路推理
- 很快会过期的实现细节
- 还没有被团队采纳的个人偏好

把这些内容直接放进 wiki，后面的人只会更难分辨什么是事实、什么是草稿。

## 维护方式

### 对研究文档

这类长文开头最好明确：

- 日期
- 状态
- scope

这样旧研究不会被误读成当前实现。

### 对设计稿

真正准备进入实施的结构性改动，不要只留在普通研究文档里。应该单独写 proposal、design、tasks，把目标、边界和实施路径固定下来。

### 对 wiki

只保留稳定结论、入口、边界和操作方式。不要把整段推理过程原样搬过来。

## 判断标准

一份记录写得值不值，不取决于它有多长，而取决于接手的人能不能很快判断：

- 哪份该当事实
- 哪份该当背景
- 哪份该当计划

这三件事分不清，文档越多，噪音越大。

## 活跃的设计稿入口

结构性改动的 proposal / design / tasks 统一放在 `openspec/changes/<change-name>/` 下，完成后归档进 `openspec/specs/<capability>/`。近期活跃的设计稿：

- **add-evo-command** — `/eac:evo` 客户端质量演化命令，rubric 改编自 [darwin-skill](https://github.com/alchaincyf/darwin-skill)。proposal + design + specs + tasks 均在 [`openspec/changes/add-evo-command/`](../../openspec/changes/add-evo-command/)。rubric 规范源 [`docs/wiki/evo-rubric.md`](./evo-rubric.md)。
