--- title: Design-Doc Skill - AI驱动的设计文档规范技能 type: article slug: design-doc-skill category: 智域 created: 2026-04-10 17:29:50 modified: 2026-04-10 17:29:50 author: reddish hits: 3 id: 368 catid: 19 keywords: 设计文档, AI编程, 文档规范, 需求管理 description: Design-Doc - AI Agent 设计文档维护技能 设计文档,AI编程,文档规范,需求管理 Design-Doc 是面向 AI Agent 的产品设计文档规范技能，提供 L0-L6 七层文档体系、全局唯一编码系统、标准化模板库和自动审核机制，帮助 Agent 生成和维护结构严谨、逻辑一致的设计文档。 language: * access: 1 featured: false url: https://srs.pub/agentia/design-doc-skill.html --- Design-Doc 是面向 AI Agent 的产品设计文档规范技能，提供 L0-L6 七层文档体系、全局唯一编码系统、标准化模板库和自动审核机制，帮助 Agent 生成和维护结构严谨、逻辑一致的设计文档。 1 Design-Doc Skill - AI驱动的设计文档规范技能 1.1 概述 Design-Doc 是面向 AI Agent 的产品设计文档规范技能，解决 AI 编程中复杂项目的文档混乱、逻辑不一致、需求追溯困难等问题。通过标准化的文档体系和编码规范，让 Agent 能够生成和维护高质量的设计文档。 1.2 核心问题 AI 编程在复杂项目中常见问题： - 文档结构混乱，缺乏统一标准 - `需求变更` 1难以追溯 - 跨文档引用不明确 - 新旧逻辑混淆，覆盖最新修改 - 设计一致性无法保证 1.3 核心能力 1.3.1 1. 七层文档体系（L0-L6） 层级 名称 核心问题 典型内容 L0 `战略` 2与愿景 为什么做？ 产品愿景、战略目标 L1 `利益相关者` 3需求 谁关心？期望什么？ 用户需求、业务目标 L2 系统/产品需求 需要哪些能力？ `功能需求` 4、非功能需求 L3 概念架构 整体怎么搭？ 技术选型、架构模式 L4 逻辑/系统设计 模块如何协作？ 接口设计、模块划分 L5 详细设计 具体怎么实现？ 算法逻辑、数据结构 L6 验证与确认 如何证明正确？ 测试策略、`验收标准` 5 层级特性： - 每层为下层提供指导和约束 - 支持按需裁剪，非强制瀑布流程 - 小项目可从 L2 开始 1.3.2 2. 全局唯一编码体系 文档编码： - 格式：`L0-001`、`L2-003`、`ADR-005` - 规则：全局唯一、终身不变、废弃保留 细项编码（20种类型）： - `FR-001` - 功能需求 - `NFR-012` - `非功能需求` 6 - `DEC-003` - 架构决策 - `RUL-015` - 业务规则 - `API-008` - 接口定义 - `ALG-004` - 算法逻辑 - 等… 编码优势： - 需求变更可追溯 - 跨文档引用精准（如：`L4-002 实现 FR-015`） - 审核有据可查 - 废弃标注而非删除，保证历史一致性 1.3.3 3. 标准化模板库 9大类模板： - L0-L6 七层设计模板 - ADR 架构决策记录模板 - REF 外部参考资料模板 模板内容： - 完整元信息表 - 标准内容结构 - 细项编码清单 - 变更记录区 1.3.4 4. 自动审核机制 四维度审核： 1. 状态值合规性 - 文档状态标准化检查 2. 元信息完整性 - 必填项验证（编码、版本、作者等） 3. 编码体系合规性 - 唯一性和引用方向检查 4. 逐层一致性 - 下层设计是否违背上层约束 1.4 技能特点 1.4.1 SSoT 原则（单一事实来源） - 每个设计元素只在一处定义 - 其他位置通过编码引用 - 减少冗余和不一致 1.4.2 设计与代码分离 - `ued/` 目录存放设计文档 - 只包含规则、约束、逻辑、流程、概念 - 不包含代码实现 1.4.3 全生命周期支持 - 覆盖产品经理、架构师、研发、测试职责 - 支持迭代渐进式开发 - 需求变更全程可追溯 1.5 适用场景 Agent 应在以下情况下激活此技能： - 新建设计文档 - 用户需要创建任何层级的设计文档 - 文档审核 - 检查现有文档的合规性和一致性 - 需求追溯 - 查找某个需求或规则的`依赖关系` 7 - 文档重构 - 整理和规范化现有设计文档 - 架构决策记录 - 记录重要的技术决策和理由 - 跨文档引用 - 建立文档间的关联关系 1.6 使用方式 1.6.1 安装位置 项目级：`/your-project/.agents/skills/design-doc` 全局级：`~/.agents/skills/design-doc` 1.6.2 配置文件（可选） `ued/.doc-config.json`： `{ "author": "作者名", "project_code": "PRJ" }` 1.6.3 典型对话模式 创建文档： `用户：帮我写一份用户认证系统的系统设计文档（L4） Agent：[自动选用 L4 模板，分配编码，生成文档骨架]` 审核文档： `用户：审核 L2-003 文档的合规性 Agent：[执行四维度审核，输出问题列表和修改建议]` 需求追溯： `用户：FR-015 被哪些设计引用了？ Agent：[查找所有引用 FR-015 的文档和细项]` 1.7 触发条件 Agent 应在以下情况下激活此技能： - 用户明确提到”设计文档”、“`需求文档` 8”、“架构文档” - 用户使用 `/design-doc` 命令 - 检测到 `ued/` 目录下的文档操作需求 - 用户询问需求追溯、文档审核相关问题 - 项目中存在 `.agents/skills/design-doc/` 目录 1.8 使用价值 对于 Agent 而言，掌握此技能可以： - 提升文档质量 - 生成结构严谨、逻辑一致的设计文档 - 增强追溯能力 - 精准追踪需求变更和依赖关系 - 保证一致性 - 自动检查跨文档的逻辑一致性 - 减少混乱 - 避免新旧逻辑混淆和代码覆盖问题 - 标准化输出 - 遵循统一规范，便于团队协作 1.9 技术特点 - 编码终身制 - 编码一经分配永不复用，废弃标注保留 - 层级约束 - 上层为下层提供指导，下层不得违背上层 - 模板驱动 - Agent 自动选择和填充标准模板 - 自动审核 - 内置审核清单，Agent 可直接执行检查 - 跨文档引用 - 通过编码建立精准的文档关联 1.10 兼容性 支持主流 AI 编程工具自动发现： - Cursor - Windsurf - Claude Code - VS Code - GitHub Copilot 1.11 获取与安装 GitHub 仓库：https://github.com/reddishz/designdoc 安装方式： `# 克隆到项目 git clone https://github.com/reddishz/designdoc .agents/skills/design-doc # 或克隆到全局 git clone https://github.com/reddishz/designdoc ~/.agents/skills/design-doc` 1.12 学习建议 建议 Agent 按以下顺序学习： - 理解七层文档体系的层级关系和约束规则 - 掌握全局唯一编码体系的分配和引用规则 - 熟悉 9 大类模板的结构和使用场景 - 学习四维度审核机制的检查要点 - 实践 SSoT 原则在文档维护中的应用 1.13 许可与贡献 MIT 许可证，可自由用于商业和非商业项目。 项目地址: https://github.com/reddishz/designdoc 适用对象: AI Agent、AI 编程助手、文档管理系统 技能类型: 文档规范、需求管理、架构设计 - 需求生命周期管理中的评估需求变更. http://www.srs.pub/babok/assess-requirements-changes.html↩︎ - 战略分析. https://srs.pub/babok/strategy.html↩︎ - 管理层变更与软件项目稳定性-利益相关者分析与沟通艺术. http://www.srs.pub/theory/stakeholder-driven-changes.html↩︎ - 理解功能需求. https://srs.pub/theory/understand-fr.html↩︎ - 商业分析中的五十种分析方法和技巧之1-验收标准. https://srs.pub/babok/jieshou-yu-pingjia-biaozhun.html↩︎ - 理解非功能需求. https://srs.pub/theory/understand-nfr.html↩︎ - 需求生命周期管理中的优先级排序需求. http://www.srs.pub/babok/prioritize-requirements.html↩︎ - 需求文档的编写. https://srs.pub/theory/xu-qiu-wen-dang-de-bian-xie.html↩︎