junhong_cmp_fiber/.claude/skills/doc-management/SKILL.md

name, description

name	description
doc-management	规范文档管理。添加新规范、更新规范文档、维护 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 的相关章节中添加简短的规范说明 + 引导链接：

## XXX 规范

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

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

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

关键要点：

• 规则 1
• 规则 2
• 规则 3

完整指南: 参见 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

---
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 清晰描述触发条件