mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-02-14 02:42:04 +08:00
docs: Add reference-docs-spec and optimize skill-generator for proper document organization
- Create specs/reference-docs-spec.md with comprehensive guidelines for phase-based reference document organization - Update skill-generator's Mandatory Prerequisites to include new reference-docs-spec - Refactor skill-md.md template to generate phase-based reference tables with 'When to Use' guidance - Add generateReferenceTable() function to automatically create structured reference sections - Replace flat template reference lists with phase-based navigation - Update skill-generator's own SKILL.md to demonstrate correct reference documentation pattern - Ensure all generated skills will have clear document usage timing and context
This commit is contained in:
catlog22
271
.claude/skills/skill-generator/specs/reference-docs-spec.md
Normal file
271
.claude/skills/skill-generator/specs/reference-docs-spec.md
Normal file
@@ -0,0 +1,271 @@
|
||||
# Reference Documents Generation Specification
|
||||
|
||||
> **重要**: 本规范定义如何在生成的skill中组织和展现参考文档，避免重复问题。
|
||||
|
||||
## 核心原则
|
||||
|
||||
### 1. 分阶段组织 (Phase-Based Organization)
|
||||
|
||||
参考文档必须按照skill的执行阶段组织，而不是平铺列表。
|
||||
|
||||
**❌ 错误方式** (平铺列表):
|
||||
```markdown
|
||||
## Reference Documents
|
||||
|
||||
| Document | Purpose |
|
||||
|----------|---------|
|
||||
| doc1.md | ... |
|
||||
| doc2.md | ... |
|
||||
| doc3.md | ... |
|
||||
```
|
||||
|
||||
**✅ 正确方式** (分阶段导航):
|
||||
```markdown
|
||||
## Reference Documents by Phase
|
||||
|
||||
### 📋 Phase 1: Analysis
|
||||
执行Phase 1时查阅的文档
|
||||
|
||||
| Document | Purpose | When to Use |
|
||||
|----------|---------|-------------|
|
||||
| doc1.md | ... | 理解x概念 |
|
||||
|
||||
### ⚙️ Phase 2: Implementation
|
||||
执行Phase 2时查阅的文档
|
||||
|
||||
| Document | Purpose | When to Use |
|
||||
|----------|---------|-------------|
|
||||
| doc2.md | ... | 实现y功能 |
|
||||
```
|
||||
|
||||
### 2. 四个标准分组
|
||||
|
||||
参考文档必须分为以下四个分组：
|
||||
|
||||
| 分组 | 使用时机 | 内容 |
|
||||
|-----|---------|------|
|
||||
| **Phase N: [Name]** | 执行该Phase时 | 该阶段相关的所有文档 |
|
||||
| **🔍 Debugging** | 遇到问题时 | 问题→文档映射表 |
|
||||
| **📚 Reference** | 深度学习时 | 模板、原始实现、最佳实践 |
|
||||
| (可选) **📌 Quick Links** | 快速导航 | 最常查阅的5-7个文档 |
|
||||
|
||||
### 3. 每个文档条目必须包含
|
||||
|
||||
```
|
||||
| [path](path) | Purpose | When to Use |
|
||||
```
|
||||
|
||||
**When to Use 列要求**:
|
||||
- ✅ 清晰说明使用场景
|
||||
- ✅ 描述解决什么问题
|
||||
- ❌ 不要简单说 "参考" 或 "了解"
|
||||
|
||||
**良好例子**:
|
||||
- "理解issue数据结构"
|
||||
- "学习Planning Agent的角色"
|
||||
- "检查implementation是否达到质量标准"
|
||||
- "快速定位状态异常的原因"
|
||||
|
||||
**糟糕例子**:
|
||||
- "参考文档"
|
||||
- "更多信息"
|
||||
- "背景知识"
|
||||
|
||||
### 4. 执行流程中嵌入文档指引
|
||||
|
||||
在"Execution Flow"部分，每个Phase说明中应包含"查阅"提示：
|
||||
|
||||
```markdown
|
||||
### Phase 2: Planning Pipeline
|
||||
→ **查阅**: action-plan.md, subagent-roles.md
|
||||
→ 具体流程说明...
|
||||
```
|
||||
|
||||
### 5. 问题排查快速查询表
|
||||
|
||||
应包含常见问题到文档的映射：
|
||||
|
||||
```markdown
|
||||
### 🔍 Debugging & Troubleshooting
|
||||
|
||||
| Issue | Solution Document |
|
||||
|-------|------------------|
|
||||
| Phase执行失败 | 查阅相应Phase文档 |
|
||||
| 输出格式不符 | specs/quality-standards.md |
|
||||
| 数据验证失败 | specs/schema-validation.md |
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 生成规则
|
||||
|
||||
### 规则 1: 文档分类识别
|
||||
|
||||
根据skill的phases自动生成分组：
|
||||
|
||||
```javascript
|
||||
const phaseEmojis = {
|
||||
'discovery': '📋', // 收集、探索
|
||||
'generation': '🔧', // 生成、创建
|
||||
'analysis': '🔍', // 分析、审查
|
||||
'implementation': '⚙️', // 实现、执行
|
||||
'validation': '✅', // 验证、测试
|
||||
'completion': '🏁', // 完成、收尾
|
||||
};
|
||||
|
||||
// 为每个phase生成一个章节
|
||||
phases.forEach((phase, index) => {
|
||||
const emoji = phaseEmojis[phase.type] || '📌';
|
||||
const title = `### ${emoji} Phase ${index + 1}: ${phase.name}`;
|
||||
// 列出该phase相关的所有文档
|
||||
});
|
||||
```
|
||||
|
||||
### 规则 2: 文档到Phase的映射
|
||||
|
||||
在config中，specs和templates应标注所属的phases：
|
||||
|
||||
```json
|
||||
{
|
||||
"specs": [
|
||||
{
|
||||
"path": "specs/issue-handling.md",
|
||||
"purpose": "Issue数据规范",
|
||||
"phases": ["phase-2", "phase-3"], // 这个spec与哪些phase相关
|
||||
"context": "理解issue结构和验证规则"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### 规则 3: 优先级和必读性
|
||||
|
||||
用视觉符号区分文档的重要性：
|
||||
|
||||
```markdown
|
||||
| Document | When | Notes |
|
||||
|----------|------|-------|
|
||||
| spec.md | **执行前必读** | ✅ 强制前置 |
|
||||
| action.md | 执行时查阅 | 操作指南 |
|
||||
| template.md | 参考学习 | 可选深入 |
|
||||
```
|
||||
|
||||
### 规则 4: 避免重复
|
||||
|
||||
- **Mandatory Prerequisites** 部分：列出强制必读的P0规范
|
||||
- **Reference Documents by Phase** 部分：列出所有文档 (包括强制必读的)
|
||||
- 两个部分的文档可以重叠，但目的不同：
|
||||
- Prerequisites：强调"必须先读"
|
||||
- Reference：提供"完整导航"
|
||||
|
||||
---
|
||||
|
||||
## 实现示例
|
||||
|
||||
### Sequential Skill 示例
|
||||
|
||||
```markdown
|
||||
## ⚠️ Mandatory Prerequisites (强制前置条件)
|
||||
|
||||
| Document | Purpose | When |
|
||||
|----------|---------|------|
|
||||
| [specs/issue-handling.md](specs/issue-handling.md) | Issue数据规范 | **执行前必读** |
|
||||
| [specs/solution-schema.md](specs/solution-schema.md) | 解决方案结构 | **执行前必读** |
|
||||
|
||||
---
|
||||
|
||||
## Reference Documents by Phase
|
||||
|
||||
### 📋 Phase 1: Issue Collection
|
||||
执行Phase 1时查阅的文档
|
||||
|
||||
| Document | Purpose | When to Use |
|
||||
|----------|---------|-------------|
|
||||
| [phases/actions/action-list.md](phases/actions/action-list.md) | Issue加载逻辑 | 理解如何收集issues |
|
||||
| [specs/issue-handling.md](specs/issue-handling.md) | Issue数据规范 | 验证issue格式 ✅ **必读** |
|
||||
|
||||
### ⚙️ Phase 2: Planning
|
||||
执行Phase 2时查阅的文档
|
||||
|
||||
| Document | Purpose | When to Use |
|
||||
|----------|---------|-------------|
|
||||
| [phases/actions/action-plan.md](phases/actions/action-plan.md) | Planning流程 | 理解issue→solution转换 |
|
||||
| [specs/solution-schema.md](specs/solution-schema.md) | 解决方案结构 | 验证solution JSON格式 ✅ **必读** |
|
||||
|
||||
### 🔍 Debugging & Troubleshooting
|
||||
|
||||
| Issue | Solution Document |
|
||||
|-------|------------------|
|
||||
| Phase 1失败 | [phases/actions/action-list.md](phases/actions/action-list.md) |
|
||||
| Planning输出不符 | [phases/actions/action-plan.md](phases/actions/action-plan.md) + [specs/solution-schema.md](specs/solution-schema.md) |
|
||||
| 数据验证失败 | [specs/issue-handling.md](specs/issue-handling.md) |
|
||||
|
||||
### 📚 Reference & Background
|
||||
|
||||
| Document | Purpose | Notes |
|
||||
|----------|---------|-------|
|
||||
| [../issue-plan.md](../../.codex/prompts/issue-plan.md) | 原始实现 | Planning Agent system prompt |
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 生成算法
|
||||
|
||||
```javascript
|
||||
function generateReferenceDocuments(config) {
|
||||
let result = '## Reference Documents by Phase\n\n';
|
||||
|
||||
// 为每个phase生成一个章节
|
||||
const phases = config.phases || config.actions || [];
|
||||
|
||||
phases.forEach((phase, index) => {
|
||||
const phaseNum = index + 1;
|
||||
const emoji = getPhaseEmoji(phase.type);
|
||||
const title = phase.display_name || phase.name;
|
||||
|
||||
result += `### ${emoji} Phase ${phaseNum}: ${title}\n`;
|
||||
result += `执行Phase ${phaseNum}时查阅的文档\n\n`;
|
||||
|
||||
// 找出该phase相关的所有文档
|
||||
const docs = config.specs.filter(spec =>
|
||||
(spec.phases || []).includes(`phase-${phaseNum}`) ||
|
||||
matchesByName(spec.path, phase.name)
|
||||
);
|
||||
|
||||
if (docs.length > 0) {
|
||||
result += '| Document | Purpose | When to Use |\n';
|
||||
result += '|----------|---------|-------------|\n';
|
||||
docs.forEach(doc => {
|
||||
const required = doc.phases && doc.phases[0] === `phase-${phaseNum}` ? ' ✅ **必读**' : '';
|
||||
result += `| [${doc.path}](${doc.path}) | ${doc.purpose} | ${doc.context}${required} |\n`;
|
||||
});
|
||||
result += '\n';
|
||||
}
|
||||
});
|
||||
|
||||
// 问题排查部分
|
||||
result += '### 🔍 Debugging & Troubleshooting\n\n';
|
||||
result += generateDebuggingTable(config);
|
||||
|
||||
// 深度学习参考
|
||||
result += '### 📚 Reference & Background\n\n';
|
||||
result += generateReferenceTable(config);
|
||||
|
||||
return result;
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 检查清单
|
||||
|
||||
生成skill的SKILL.md时，参考文档部分应满足：
|
||||
|
||||
- [ ] 有明确的"## Reference Documents by Phase"标题
|
||||
- [ ] 每个Phase都有对应的章节 (用emoji标识)
|
||||
- [ ] 每个文档条目包含"When to Use"列
|
||||
- [ ] 包含"🔍 Debugging & Troubleshooting"部分
|
||||
- [ ] 包含"📚 Reference & Background"部分
|
||||
- [ ] 强制必读文档用✅和**粗体**标记
|
||||
- [ ] Execution Flow部分中有"→ **查阅**: ..."指引
|
||||
- [ ] 避免过长的文档列表 (一个Phase最多5-8个文档)
|
||||
Reference in New Issue
Block a user