告别混乱文档，让 AI 成为你的文档架构师。
你是否也遇到过这些问题？
AI编码在面对简单的项目时，非常有帮助。但是对于稍微复杂点的项目，很多的编程模型就显得有些痴呆了。 严重的情况下还会得健忘症，在最新的修改中混入很久之前废弃的旧逻辑代码，并且覆盖最新的修改。让人不胜头疼。
显然规格驱动的开发，设计文档，是这里的唯一良药。
但是如果项目稍微复杂，普通的设计文档，对于AI编程来说帮助也是非常有限的。
同时一个很普遍的现象就是，即便是设计文档，很多也是AI生成、编辑、和维护的。
由此带来一个很重要的问题，就是设计文档的严密性，精确性，一致性，可核查，可追踪，互相关联关系明确可见等等高标准的要求显得格外的重要。
design-doc 正是为解决这些问题而生。
什么是 design-doc？
design-doc 是一个面向 AI 编程助手的产品设计文档规范。它以 Agent Skill 的形式存在，安装到项目后，AI 助手会自动遵循规范，帮你生成结构严谨、编码统一、层级清晰的设计文档。
它不是一个需要学习的新工具，而是一套 AI 能直接理解和执行的文档标准。你只需用自然语言描述需求，AI 会自动完成模板选择、编码分配、结构生成。
也可以通过指定skill，来完成整个项目的设计文档的规范化重构，整理，一致性核查等等。
通过本skill， 既可以随时新增功能、需求、设计规范、流程、逻辑、算法、约束、引用等等内容，也可以要求她基于现有的文档重新整理完善的设计文档。
通过designdoc技能维护的设计文档，严格的遵循相关的规范，并且统一实行SSoT标准。每一个规则、流程等等都有唯一的编码，并互相引用。 随时可以检索到某个规则所依赖的其他逻辑，流程定义，以及依赖他的相关项。 从而构建一个即足够细分的，又整体一致的系统逻辑。
足够细分，是为了AI能够高效的理解和明确的实现。 整体一致，是保证整个系统能够可靠运作的基础。
核心能力
本skill维护的设计文档，即遵循相关软件工程的标准，又不局限于某个单一目的的规范。而是试图将整个产品项目所需的文档，按照一定的层次柔和到了一起。契合当前的OPC的概念，在一个模版内视图整个整个产品、项目所需的设计文档。
具体来说，本技能将设计文档按照级别，分成了L0到 L6的七个级别。涵盖了产品经理，技术架构，研发，测试的职责范围，基本覆盖产品设计的全生命周期。 分别介绍如下：
| 层级 | 名称 | 回答的核心问题 |
|---|---|---|
| L0 | 战略与愿景 | 我们为什么要做这件事？ |
| L1 | 利益相关者需求 | 谁在关心？他们期望什么？ |
| L2 | 系统/产品需求 | 系统需要具备哪些能力？ |
| L3 | 概念架构 | 整体怎么搭？技术怎么选？ |
| L4 | 逻辑/系统设计 | 内部模块怎么协作？接口怎么定？ |
| L5 | 详细设计 | 具体怎么实现？算法逻辑是什么？ |
| L6 | 验证与确认 | 怎么证明我们做对了？ |
注意这里的层级是有意义的。每一层为下一层提供指导、依据和约束，同时是上一层的细化。越是上层，越需要外部、管理层、多部门确认。
一个完整的产品通常是需要从0级开始的。 但是不是必须或强制的，小的项目，目标清晰明确的情况下，也可以直接从2级开始。
同时也不强制瀑布流程，支持迭代渐进。团队可以根据项目规模按需裁剪，不必每个层级都写满。
全局唯一编码体系
这是 design-doc 的核心差异化能力之一。每份文档、每个需求条目、每条业务规则，都有全局唯一的编码标识：
- 文档编码：
L0-001、L2-003、ADR-005 - 细项编码：
FR-001（功能需求）、NFR-012（非功能需求）、DEC-003（架构决策）
编码全局唯一，且终身单一，一致。一经分配，永不删除、永不复用。如果不用了，不能删除，只能标注废弃。 以保证完整的产品生命周期内的需求规则等一致性。
废弃的编码标注状态保留。这种做法除了一致性，还有很多的优点：
- 需求变更可追溯：任何改动都能追踪到源头
- 跨文档引用精准：
L4-002 的接口设计满足 FR-015-- 一目了然 - 审核有据可查：逐层检查下层是否违背上层约束
本技能默认就提供了 20 种细项类型码，覆盖目标、场景、需求、原则、决策、组件、接口、流程、算法、测试等所有常见设计元素。一般的产品、项目的设计是足够的了。
开箱即用的模板库
除了7个层级外，还有一些其他的辅助类别。总共构成了9个大类。 每个类别都有明确的标准模板。如下：
- L0 战略与愿景模板
- L1 利益相关者需求模板
- L2 系统/产品需求模板
- L3 概念架构模板
- L4 逻辑/系统设计模板
- L5 详细设计模板
- L6 验证与确认模板
- ADR 架构决策记录模板
- REF 外部参考资料模板
每套模板包含完整的元信息表、内容结构、细项编码清单和变更记录。AI 助手读取模板后，会自动填充结构，你只需专注于业务内容。
内置审核机制
本技能同时提供标准化的审核清单，涵盖四个维度：
- 状态值合规性 -- 确保文档状态从标准集合中选择
- 元信息完整性 -- 编码、版本、作者、日期等必填项检查
- 编码体系合规性 -- 全局唯一性、引用方向正确性验证
- 逐层一致性 -- 自动检查下层设计是否违背上层约束
AI 助手可以直接执行这些检查，帮你在提交前发现问题。
也可以明确的指定 /design-doc， 让他审查现有的设计文档。
与 AI 编程助手的协作方式
design-doc 遵循 Agent Skills 开放标准，存放于 .agents/skills/design-doc/ 路径下。主流 AI 编程工具可自动发现和加载：
| IDE / 工具 | 支持状态 |
|---|---|
| Cursor | 自动发现 |
| Windsurf | 自动发现 |
| Claude Code | 自动发现 |
| VS Code | 自动发现 |
| GitHub Copilot | 自动发现 |
安装后，你可以直接用自然语言与 AI 协作：
帮我写一份用户认证系统的系统设计文档（L4）
AI 会自动选用 L4 模板、分配文档编码、生成完整的文档骨架，你只需补充业务细节。
审核一下 L2-003 文档的合规性
AI 会按照审核清单逐项检查，输出问题列表和修改建议。
快速上手
第一步：安装到你的项目
试用时，可以复制到项目目录下. 如果觉得还可以，建议安装到个人主目录下，供所有的项目使用。
项目级安装：
/your-project/.agents/skills/design-doc
全局安装：
~/.agents/skills/design-doc
第二步：配置作者信息（可选）
如果你希望在生成的文档中，标注你的名字，可以配置 项目目录下的ued/.doc-config.json 配置文件。
在项目的 ued/.doc-config.json 中配置：
{
"author": "你的名字",
"project_code": "CRM"
}
如未配置，系统会依次从 git config 和默认值中获取。
其中 project_code 为项目编码。如果期望在多个项目中唯一引用，可以添加这个project_code。 添加后， RUL-013(13号规则 ) 就变成了 CRM-RUL-013
第三步：开始使用
在你的 AI 编程助手中输入文档需求，剩下的交给 AI。
也可以通过在描述相关需求是，输入 /design-doc (大部分AI能识别), 明确的指定 本 skill。
谁适合使用？
- 产品团队 -- 需要标准化的需求文档和设计文档
- 架构师 -- 需要结构化记录架构决策和系统设计
- 技术负责人 -- 需要确保团队文档质量和一致性
- 独立开发者 -- 需要用最少的精力产出专业的技术文档
设计理念
design-doc 遵循 单一事实来源（SSoT） 原则。每个设计元素只在一处定义，其他地方通过编码引用。这不仅减少了信息冗余和不一致，也让 AI 能更准确地理解和维护文档间的关联关系。
同时，文档内容与代码实现严格分离。ued/ 目录下只存放设计性内容 -- 规则、约束、逻辑、流程、概念、标准、策略，不包含任何代码。这让设计文档真正成为"设计"文档，而非代码注释的另一种形式。
开源许可
design-doc 采用 MIT 许可证发布，可自由用于商业和非商业项目。
地址：https://github.com/reddishz/designdoc
用 AI 的方式写文档，用规范的力量驯服复杂度。
GitHub: design-doc | 参考规范: srs.pub | 标准合规: Agent Skills
::: {#author name=reddish}
本文同步发表在 软件需求探索的https://srs.pub/auxiliary/designdoc.html
作者: reddish@srs.pub
:::
