重构规范文档:提取详细规范为 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:
141
.claude/skills/doc-management/SKILL.md
Normal file
141
.claude/skills/doc-management/SKILL.md
Normal 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 清晰描述触发条件
|
||||
Reference in New Issue
Block a user