--- title: Design-Doc 4.2 - 从模板规范到可冻结基线 type: article slug: design-doc-v4 category: 智域 created: 2026-09-12 10:29:08 modified: 2026-09-12 10:29:08 author: reddish hits: 3 id: 379 catid: 19 keywords: 状态即基线 description: Design-Doc 4.2 - 状态即基线、按文档实现与可机检 状态即基线 Design-Doc 当前版本 4.2。相对初版，真正改变用法的是 3.x 定下的口径：四态冻结、未定稿不得拿去写代码、编号永不复用、定义块可跳转、check_docs.py 可机检。4.x 不另起一套规则，只把规范拆清、模板不再把写作说明抄进文档。适合已经用过初版、或想弄清它和「只是文档模板」有何不同的读者。 language: * access: 1 featured: false url: https://srs.pub/agentia/design-doc-v4.html --- Design-Doc 当前版本 4.2。相对初版，真正改变用法的是 3.x 定下的口径：四态冻结、未定稿不得拿去写代码、编号永不复用、定义块可跳转、check_docs.py 可机检。4.x 不另起一套规则，只把规范拆清、模板不再把写作说明抄进文档。适合已经用过初版、或想弄清它和「只是文档模板」有何不同的读者。# 概述 [Design-Doc](https://srs.pub/agentia/design-doc-skill.html) 初版解决的是「文档长什么样」：L0–L6 分层、全局编码、标准模板、审核清单。后来补上的是另一半——**文档怎么活、怎么被 AI 拿去写代码**。 一句话：正式内容冻结后不能随手改；还没定稿的不能当实现依据；编号一旦用过就永久占用。技能因此从「帮 AI 填模板」变成「可冻结、可追溯、可机检的设计基线」。 当前技能版本 **4.2**。分层与模板的入门仍见 [初版介绍](https://srs.pub/agentia/design-doc-skill.html)；本文写相对初版真正改变用法的部分。仓库：https://github.com/reddishz/designdoc # 版本怎么读 不必再单独找一篇「v4 介绍」。 | 世代 | 对使用者意味着什么 | |------|-------------------| | **初版**（约 2.x） | 分层、编码、模板、清单——文档长什么样 | | **3.x** | 定口径：四态、冻结、按文档实现、编号永不复用、定义块、规划与 ADR 分界 | | **4.x（当前 4.2）** | **不改上述口径**。规范按职责拆文件、模板不再把写作说明复制进目标文档、检查脚本能核模板哨兵和包内锚点 | 4.x 是把 3.x 已经生效的规则收干净，不是第二套状态、也不是新的层级。下面各节写的就是当前 4.2 的用法。 # 核心问题 初版上线后，协作里反复出现的不是「哪一层该写什么」，而是： - 草稿和定稿混在一起，AI 按过期表述写了代码 - 「正式」文档被下一轮对话就地改掉，下游引用 silently 失效 - 编码删了又用、缺口说不清，追溯链断了 - 审核靠人眼和记忆，同一类错误反复出现 - 规划项、路线图、架构决策和需求细项搅在同一套状态里 针对的是这些问题，而不是再发明一套层级。 # 核心能力 ## 1. 状态即基线 文档和细项共用四种状态：**初稿 / 正式 / 草案 / 废弃**。 | 状态 | 含义 | 典型用法 | |------|------|----------| | 初稿 | 从未进入基线，内容还可以整体推翻 | 新建默认值 | | 正式 | 已冻结，标题和业务含义不就地改 | 可以拿去实现、被下游引用 | | 草案 | 从正式解冻，正在修订 | 改完再定稿；解冻时才升版本号 | | 废弃 | 放弃，编号仍占用 | 不删除、不复用 | 定稿不升版本号。唯一正规的升号时机是 **正式 → 草案**（解冻）。提交前 AI 会列出本轮改过的未冻结对象，问你要不要定稿——它不会自己把初稿升成正式。 ## 2. 按文档实现 这是和「只是文档模板」差别最大的一条。 AI 被要求**依据 `ued/` 写代码**时，先看状态： - **初稿**：请你先定稿。从未进过基线，含义可能整段推翻，没有绕过的理由。 - **草案**：默认也请先定稿；解冻轮次里确要按草案改代码，必须你逐项明确豁免，并在变更记录里留痕。 - **正式**：才是实现依据。 「先按现状实现、以后再对齐」这条路是关掉的。未冻结对象写进代码，定稿时改了标题或含义，代码会静默过期。 ## 3. 编号锁定与定义块 - **编号一经分配永久占用**。作废不释放、不复用；索引里出现缺口一律当缺陷，先修索引或补废弃记录，再发新号。 - 每个细项在正文里只有一个定义位：锚点 + 标题 + 属性行 + 正文。别处用编码链接跳转，不用「见上一节」「§1.4.3」。 - 改已正式对象的含义：不是改原编号，而是作废 + 分配下一个号。`初稿` 改标题可以，但要先反查全部引用再一起改。 反查命令： ``` python3 .agents/skills/design-doc/scripts/check_docs.py --refs FR-015 ``` ## 4. 可机检 `check_docs.py` 不是可有可无的附件。它核对应编码格式、四态、正文 / 文末清单 / README 索引是否一致、引用能否跳转、编号缺口、规划项是否落实闭环等。4.x 起还会检查模板：写作说明不得漏进待复制正文，技能包内部锚点要能跳转。 ``` python3 .agents/skills/design-doc/scripts/check_docs.py -p ued ``` 脚本只出静态提示，不代替人工审查，也不代替你点头定稿。 ## 5. 规划与决策分界 初版把「以后再说」和「已经定了」容易写进同一套需求里。现在分开： | 对象 | 放哪 | 注意 | |------|------|------| | `产品路线图` [^productroadmap] | L0 | 阶段与主题，不写排期、工时、团队 | | 规划项 PLN | 定义在需求层（默认 L2），总览里只登记 | 状态管生命周期，落实与否另记；不写执行进度 | | ADR | L3 目录，与架构文档平放 | 宏观「为什么这么选」；小事用 `DEC` 细项 | | 需求 / 设计细项 | 各层正文 | 本轮要做的，直接用 FR / IF 等，不要先登 PLN | # 使用方式上的变化 相对初版介绍，有几处不要再按旧文操作： **不再使用 `ued/.doc-config.json`。** 项目名、作者写在当前作用域的 `ued/README.md`。没有独立配置文件。 **不必配置 `doc_mode`。** 一个应用就把文档放在 `ued/` 下；多个应用各占 `ued/{应用名}/`。有几个应用，目录里就是几个。 **新建默认是「初稿」。** 不是写完就算正式。 **多数项目仍从 L2 + L4 起步**，不要一次生成 L0–L6。 **模板里的使用说明不会进你的文档。** 复制的是哨兵之间的正文；编码规则、禁止章节编号这类话写在技能包里，不会再出现在 `ued/` 文首。 典型对话： ``` 用户：帮我写一份用户认证系统的系统设计文档（L4） Agent：选用 L4 模板，分配编码，状态为初稿；收尾时询问哪些条目要定稿 ``` ``` 用户：按 L4-002 把登录接口实现了 Agent：先看 L4-002 及引用细项的状态；未冻结则拒绝实现，列出清单请你定稿 ``` ``` 用户：FR-015 被哪些地方引用了？ Agent：跑 --refs FR-015，列出定义、清单和引用位置 ``` # 搭配使用 动笔写分层文档之前，若问题本身还没想清楚，可先用 [Multi-Angle Thinking](https://srs.pub/agentia/multi-angle-thinking.html)（仓库：https://github.com/reddishz/multi-angle-thinking）：从规划、事实、感受、风险、价值、创意六个角度讨论，再落到 Design-Doc 的 L0–L6。 想清楚是讨论；写进 `ued/` 并定稿，才是基线。 # 获取与安装 **GitHub**：https://github.com/reddishz/designdoc 把仓库里的 `.agents/skills/design-doc/` 复制或链接到你项目的 `.agents/skills/design-doc/`。首页 README 是给安装者看的介绍；完整规则在 skill 内的 `SKILL.md`。 兼容 Cursor、Windsurf、Claude Code、VS Code、GitHub Copilot 等能自动发现 Agent Skills 的工具。MIT 许可。 # 学习建议 已经读过初版介绍的，建议按这个顺序补： 1. 四种状态分别允许改什么、什么时候升版本号 2. 「按文档实现」何时拒绝、初稿和草案有何不同 3. 编号为什么不能删、`--refs` 什么时候必须跑 4. 本地对一份 `ued/` 跑通 `check_docs.py` 5. 分清 PLN、路线图、ADR 和需求细项，避免再写进同一套状态 初版的七层、编码类型、模板选型仍然有效，不需要重学。 --- **项目地址**: https://github.com/reddishz/designdoc **初版介绍**: https://srs.pub/agentia/design-doc-skill.html **适用对象**: AI Agent、AI 编程助手、已经在用 Design-Doc 的团队 **技能类型**: 文档规范、需求管理、规格驱动开发 [^productroadmap]: 产品路线图.