---
title: Design-Doc Skill - AI驱动的设计文档规范技能
type: article
slug: design-doc-skill
category: 智域
created: 2026-04-09 01:29:50
modified: 2026-04-17 08:41:51
author: reddish
hits: 177
id: 368
catid: 19
keywords: designdoc技能
description: Design-Doc - AI Agent 设计文档维护技能 designdoc技能 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 生成和维护结构严谨、逻辑一致的设计文档。# 概述

Design-Doc 是面向 AI Agent 的产品设计文档规范技能，解决 AI 编程中复杂项目的文档混乱、逻辑不一致、需求追溯困难等问题。通过标准化的文档体系和编码规范，让 Agent 能够生成和维护高质量的设计文档。

# 核心问题

AI 编程在复杂项目中常见问题：
- 文档结构混乱，缺乏统一标准
- `需求变更` [^assessrequirementschanges]难以追溯
- 跨文档引用不明确
- 新旧逻辑混淆，覆盖最新修改
- 设计一致性无法保证

# 核心能力

## 1. 七层文档体系（L0-L6）

| 层级 | 名称 | 核心问题 | 典型内容 |
|------|------|----------|----------|
| L0 | `战略` [^strategy]与愿景 | 为什么做？ | 产品愿景、战略目标 |
| L1 | `利益相关者` [^stakeholder]需求 | 谁关心？期望什么？ | 用户需求、业务目标 |
| L2 | 系统/产品需求 | 需要哪些能力？ | `功能需求` [^understandfr]、非功能需求 |
| L3 | 概念架构 | 整体怎么搭？ | 技术选型、架构模式 |
| L4 | 逻辑/系统设计 | 模块如何协作？ | 接口设计、模块划分 |
| L5 | 详细设计 | 具体怎么实现？ | 算法逻辑、数据结构 |
| L6 | 验证与确认 | 如何证明正确？ | 测试策略、`验收标准` [^jieshouyupingjiabiaozhun] |

**层级特性**：
- 每层为下层提供指导和约束
- 支持按需裁剪，非强制瀑布流程
- 小项目可从 L2 开始

## 2. 全局唯一编码体系

**文档编码**：
- 格式：`L0-001`、`L2-003`、`ADR-005`
- 规则：全局唯一、终身不变、废弃保留

**细项编码**（20种类型）：
- `FR-001` - 功能需求
- `NFR-012` - `非功能需求` [^understandnfr]
- `DEC-003` - 架构决策
- `RUL-015` - 业务规则
- `API-008` - 接口定义
- `ALG-004` - 算法逻辑
- 等...

**编码优势**：
- 需求变更可追溯
- 跨文档引用精准（如：`L4-002 实现 FR-015`）
- 审核有据可查
- 废弃标注而非删除，保证历史一致性

## 3. 标准化模板库

**9大类模板**：
- L0-L6 七层设计模板
- ADR 架构决策记录模板
- REF 外部参考资料模板

**模板内容**：
- 完整元信息表
- 标准内容结构
- 细项编码清单
- 变更记录区

## 4. 自动审核机制

**四维度审核**：
1. **状态值合规性** - 文档状态标准化检查
2. **元信息完整性** - 必填项验证（编码、版本、作者等）
3. **编码体系合规性** - 唯一性和引用方向检查
4. **逐层一致性** - 下层设计是否违背上层约束

# 技能特点

## SSoT 原则（单一事实来源）
- 每个设计元素只在一处定义
- 其他位置通过编码引用
- 减少冗余和不一致

## 设计与代码分离
- `ued/` 目录存放设计文档
- 只包含规则、约束、逻辑、流程、概念
- 不包含代码实现

## 全生命周期支持
- 覆盖产品经理、架构师、研发、测试职责
- 支持迭代渐进式开发
- 需求变更全程可追溯

# 适用场景

Agent 应在以下情况下激活此技能：

- **新建设计文档** - 用户需要创建任何层级的设计文档
- **文档审核** - 检查现有文档的合规性和一致性
- **需求追溯** - 查找某个需求或规则的`依赖关系` [^prioritizerequirements]
- **文档重构** - 整理和规范化现有设计文档
- **架构决策记录** - 记录重要的技术决策和理由
- **跨文档引用** - 建立文档间的关联关系

# 使用方式

## 安装位置

**项目级**：`/your-project/.agents/skills/design-doc`  
**全局级**：`~/.agents/skills/design-doc`

## 配置文件（可选）

`ued/.doc-config.json`：
```json
{
  "author": "作者名",
  "project_code": "PRJ"
}
```

## 典型对话模式

**创建文档**：
```
用户：帮我写一份用户认证系统的系统设计文档（L4）
Agent：[自动选用 L4 模板，分配编码，生成文档骨架]
```

**审核文档**：
```
用户：审核 L2-003 文档的合规性
Agent：[执行四维度审核，输出问题列表和修改建议]
```

**需求追溯**：
```
用户：FR-015 被哪些设计引用了？
Agent：[查找所有引用 FR-015 的文档和细项]
```

# 触发条件

Agent 应在以下情况下激活此技能：

- 用户明确提到"设计文档"、"`需求文档` [^xuqiuwendangdebianxie]"、"架构文档"
- 用户使用 `/design-doc` 命令
- 检测到 `ued/` 目录下的文档操作需求
- 用户询问需求追溯、文档审核相关问题
- 项目中存在 `.agents/skills/design-doc/` 目录

# 使用价值

对于 Agent 而言，掌握此技能可以：

- **提升文档质量** - 生成结构严谨、逻辑一致的设计文档
- **增强追溯能力** - 精准追踪需求变更和依赖关系
- **保证一致性** - 自动检查跨文档的逻辑一致性
- **减少混乱** - 避免新旧逻辑混淆和代码覆盖问题
- **标准化输出** - 遵循统一规范，便于团队协作

# 技术特点

- **编码终身制** - 编码一经分配永不复用，废弃标注保留
- **层级约束** - 上层为下层提供指导，下层不得违背上层
- **模板驱动** - Agent 自动选择和填充标准模板
- **自动审核** - 内置审核清单，Agent 可直接执行检查
- **跨文档引用** - 通过编码建立精准的文档关联

# 兼容性

支持主流 AI 编程工具自动发现：
- Cursor
- Windsurf
- Claude Code
- VS Code
- GitHub Copilot

# 获取与安装

**GitHub 仓库**：https://github.com/reddishz/designdoc

**安装方式**：
```bash
# 克隆到项目
git clone https://github.com/reddishz/designdoc .agents/skills/design-doc

# 或克隆到全局
git clone https://github.com/reddishz/designdoc ~/.agents/skills/design-doc
```

# 学习建议

建议 Agent 按以下顺序学习：

1. 理解七层文档体系的层级关系和约束规则
2. 掌握全局唯一编码体系的分配和引用规则
3. 熟悉 9 大类模板的结构和使用场景
4. 学习四维度审核机制的检查要点
5. 实践 SSoT 原则在文档维护中的应用

# 许可与贡献

MIT 许可证，可自由用于商业和非商业项目。

---

**项目地址**: https://github.com/reddishz/designdoc  
**适用对象**: AI Agent、AI 编程助手、文档管理系统  
**技能类型**: 文档规范、需求管理、架构设计



[^strategy]: 战略分析.  <https://srs.pub/babok/strategy.html>
[^understandnfr]: 理解非功能需求.  <https://srs.pub/theory/understand-nfr.html>
[^prioritizerequirements]: 需求生命周期管理中的优先级排序需求.  <http://www.srs.pub/babok/prioritize-requirements.html>
[^understandfr]: 理解功能需求.  <https://srs.pub/theory/understand-fr.html>
[^stakeholder]: 涉众定义与解释.  <https://srs.pub/theory/stakeholder.html>
[^jieshouyupingjiabiaozhun]: 商业分析中的五十种分析方法和技巧之1-验收标准.  <https://srs.pub/babok/jieshou-yu-pingjia-biaozhun.html>
[^xuqiuwendangdebianxie]: 需求文档的编写.  <https://srs.pub/theory/xu-qiu-wen-dang-de-bian-xie.html>
[^assessrequirementschanges]: 需求生命周期管理中的评估需求变更.  <http://www.srs.pub/babok/assess-requirements-changes.html>