| name | design-docs |
| description | AbilityKit 设计文档治理——Docs/design/ canonical 体系与 00-index.md 总索引、E0-E5 证据分级、文档类型(能力地图/Canonical/接入指南/审计/演进计划)、单篇最小结构、事实状态语言(规范/实现/示例策略/目标/限制)、能力下沉判定、文档版本记录维护。触发场景:写/改设计文档、判成熟度、E0-E5、canonical、能力地图、事实基线、文档版本、能力下沉、区分框架原语与项目应用层。 |
design-docs skill
基于源码核校(2026-08-17)。设计文档是"能力边界、源码落点、生命周期、限制、证据等级"的 canonical 入口,总索引是 Docs/design/00-index.md。写/改任何跨模块结论前,先看它。
E0-E5 证据分级(判成熟度的唯一口径)
| 等级 | 含义 |
|---|
| E0 | 源码/接口/配置存在,可定位实现 |
| E1-E2 | 有示例消费者,或进入某项目/服务端主链 |
| E3 | 有可执行的单元/契约/本地回环测试 |
| E4 | 有指定环境、配置和日期的 Smoke/Acceptance artifact |
| E5 | 有实际 CI/发布门禁、预算和失败阻断责任 |
铁律:局部 E3 不能外推为跨平台 E4;workflow 文件存在 ≠ 本次 E5 运行结果;"存在实现" ≠ "生产就绪"。下结论/写文档时显式标证据等级,别拿类名当能力。
文档类型
能力地图 / Canonical 设计 / 接入指南 / 示例分析 / 历史审计 / 演进计划。每篇开头用 > 文档类型:… 声明,并带 事实基线 日期。
单篇最小结构
能力定位 → 文档类型 → 设计方案(抽象边界/核心对象/生命周期/扩展点)→ 源码入口(Unity 包/.NET 工程/Server 工程)→ 运行流程(Mermaid)→ 使用路径 → 事实状态 → 风险与约束(生命周期/线程/确定性/性能/跨端)。
事实状态语言(必须区分)
规范约束 / 当前实现 / 示例策略 / 目标设计 / 已知限制 / 历史结论——同一篇里绝不能把"示例策略"写成"框架默认",把"目标设计"写成"当前实现"。
能力下沉判定(决定 demo 代码是否晋升为框架能力)
一段示例代码要同时满足 5 条才下沉:①语义稳定 ②依赖可反转 ③所有权明确 ④扩展成本受控 ⑤交叉验证(第二个非同构示例/真实项目证明)。只满足"多个项目大概都有这段代码"→ 保留为 Recipe/Starter/示例,不发布为运行时依赖。
文档版本维护
- 每篇末尾:
文档类型:… | 事实基线:YYYY-MM-DD | 证据等级:… + *文档版本:vX.Y | 最后更新:YYYY-MM-DD*。
00-index.md 末尾有版本记录表:改动要加一条 | 日期 | 版本 | 内容范围 |,历史记录行不删(是 changelog,不是当前状态)。
- 改源码/测试后,对应 canonical 文档的"事实状态/证据等级"要同步,否则文档-实现漂移(历史教训:
ModifierPipeline.Create() 注释与实现不符、logic World 双定义等)。
坑
- 文档里引用的类名/API 可能是过时的——写文档时按当前源码核校,别照抄旧文档。
- 设计文档目录编号有历史遗留(如
04-PresentationLayerDesign/04-* 实际是客户端流程运行时),改结构前先看 00-index.md 的"文档目录"导航,别乱建新编号。
- 涉及"成熟度"的表述必须落到 E0-E5 具体等级,禁止"基本稳定/可用"这种不可验证的说法。
相关 skill