重构规范文档:提取详细规范为 6 个 Skills 实现模块化和按需加载

- 新增 6 个 Skill 文件:api-routing, db-migration, db-validation, doc-management, dto-standards, model-standards
- 简化 AGENTS.md 和 CLAUDE.md,保留核心规范,详细内容移至 Skills
- 添加 Skills 触发表格,说明各规范的加载时机
- 优化规范文档结构,提升可维护性和可读性
This commit is contained in:
2026-01-21 11:19:13 +08:00
parent cfac546f14
commit 9795bb9ace
8 changed files with 1013 additions and 1203 deletions

View File

@@ -0,0 +1,141 @@
---
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 清晰描述触发条件