---
name: doc-management
description: 规范文档管理。添加新规范、更新规范文档、维护 AGENTS.md 时使用。包含规范文档流程和维护规则。
---

# 规范文档管理

**当你需要为项目添加新的开发规范时，必须遵循以下流程。**

## 触发条件

在以下情况下必须遵守本规范：
- 添加新的开发规范
- 更新现有规范文档
- 维护 AGENTS.md 文件
- 创建技术指南文档

## 添加新规范的流程

### 步骤 1：创建详细规范文档

在 `docs/` 目录下创建详细的规范文档（Markdown 格式）：

```
docs/
├── api-documentation-guide.md    # API 文档生成规范
├── code-review-checklist.md      # 代码审查清单
├── testing-guide.md               # 测试规范
└── ...
```

**文档内容要求**：
- ✅ 包含完整的规范说明、示例代码、常见问题
- ✅ 使用中文编写，代码示例使用英文
- ✅ 提供正确示例（✅）和错误示例（❌）的对比
- ✅ 包含故障排查和调试指南

### 步骤 2：在 AGENTS.md 中添加简短引导

在 `AGENTS.md` 的相关章节中添加**简短**的规范说明 + 引导链接：

```markdown
## XXX 规范

**核心要求：一句话说明最重要的规则。**

```go
// ✅ 正确示例（3-5 行）
...

// ❌ 错误示例（3-5 行）
...
```

**关键要点**：
- 规则 1
- 规则 2
- 规则 3

**完整指南**: 参见 [`docs/xxx-guide.md`](docs/xxx-guide.md)
```

**注意**：
- ⚠️ AGENTS.md 中的说明不超过 20 行
- ⚠️ 只保留最核心的规则和示例
- ⚠️ 必须包含引导链接到详细文档

### 步骤 3：在 README.md 中添加文档链接

在 `README.md` 的"## 文档"章节中添加链接：

```markdown
## 文档

### 开发规范

- **[API 文档生成规范](docs/api-documentation-guide.md)**：路由注册规范、DTO 规范、OpenAPI 文档生成流程
- **[XXX 规范](docs/xxx-guide.md)**：简短的一句话说明
```

**分类规则**：
- 开发规范：代码规范、API 规范、测试规范
- 功能指南：功能使用指南、配置指南
- 架构设计：设计文档、技术选型

## 规范文档的维护

### 更新规范时

1. 优先更新 `docs/` 下的详细文档
2. 如果核心规则变化，同步更新 AGENTS.md 中的简短说明
3. 保持 AGENTS.md 简洁，避免冗余

### 删除规范时

1. 删除 `docs/` 下的详细文档
2. 删除 AGENTS.md 中的相关章节
3. 删除 README.md 中的链接
4. 说明删除原因（在 commit message 中）

## Skill 规范管理

### 何时创建 Skill

当规范内容满足以下条件时，应该提取为 Skill：
- 内容超过 50 行
- 只在特定任务场景需要
- 包含详细的步骤和示例

### Skill 文件结构

```
.claude/skills/{skill-name}/
└── SKILL.md
```

### Skill 命名规范

- 使用小写字母和连字符
- 名称应描述规范主题
- 示例：`dto-standards`、`db-migration`、`api-routing`

### Skill Frontmatter

```yaml
---
name: skill-name
description: 简短描述（1-2 句话），说明何时使用此 skill
---
```

## AI 助手检查清单

添加/更新规范后必须：

1. ✅ 详细文档在 `docs/` 目录
2. ✅ AGENTS.md 中有简短引导（≤20 行）
3. ✅ README.md 中有文档链接
4. ✅ 如果内容 >50 行，考虑提取为 Skill
5. ✅ Skill 的 name 与目录名一致
6. ✅ Skill 的 description 清晰描述触发条件