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
2026-02-13 02:41:50 +08:00 · 2026-01-29 15:28:21 +08:00
parent 26283e7a5a
commit b791c09476
4 changed files with 512 additions and 352 deletions
--- a/.claude/skills/skill-generator/SKILL.md
+++ b/.claude/skills/skill-generator/SKILL.md
@@ -94,6 +94,7 @@ Phase 01 → Phase 02 → Phase 03 → ... → Phase N
 | Document | Purpose | Priority |
 |----------|---------|----------|
 | [../_shared/SKILL-DESIGN-SPEC.md](../_shared/SKILL-DESIGN-SPEC.md) | 通用设计规范 - 定义所有 Skill 的结构、命名、质量标准 | **P0 - 最高** |
+| [specs/reference-docs-spec.md](specs/reference-docs-spec.md) | **参考文档生成规范** - 确保生成的skill中Reference Documents部分有正确的分阶段组织和使用时机指引 | **P0 - 最高** |

 ### 模板文件 (生成前必读)

@@ -193,6 +194,7 @@ Phase 3: Phase/Action Generation
 Phase 4: Specs & Templates
   └─ Generate domain specifications and templates
      ├─ Input: skill-config.json (domain context)
+      ├─ ⚠️ 参考规范: [specs/reference-docs-spec.md](specs/reference-docs-spec.md) - 确保生成的参考文档有正确的分阶段组织
      ├─ Tool: Write
      │   ├─ Generate: specs/{domain}-requirements.md
      │   ├─ Generate: specs/quality-standards.md
@@ -273,105 +275,89 @@ Write(`${skillDir}/README.md`, generateReadme(config, validation));

 ---

-## Phase Reference Guide

-Navigation and entry points for each execution phase:
+## Reference Documents by Phase

-### Phase 0: Specification Study (Mandatory)
+> **重要**: 本部分展示skill-generator如何组织自己的参考文档，这是生成的skill应该模仿的示例。详见 [specs/reference-docs-spec.md](specs/reference-docs-spec.md)

-**Document**: 🔗 [SKILL-DESIGN-SPEC.md](../_shared/SKILL-DESIGN-SPEC.md)
+### 🔧 Phase 0: Specification Study (强制前置)

-**Purpose**: Understand skill design standards before generating
+所有生成操作前必须阅读的规范

-**What to Read**:
- Skill structure conventions
- Naming standards
- Quality criteria
- Output format specifications
+| Document | Purpose | When to Use |
+|----------|---------|-------------|
+| [../_shared/SKILL-DESIGN-SPEC.md](../_shared/SKILL-DESIGN-SPEC.md) | Skill设计通用规范 | 理解Skill结构和命名规范 ✅ **必读** |
+| [specs/reference-docs-spec.md](specs/reference-docs-spec.md) | 参考文档生成规范 | 确保Reference Documents有正确的组织方式 ✅ **必读** |
+
+### 📋 Phase 1: Requirements Discovery
+
+收集Skill需求和配置
+
+| Document | Purpose | When to Use |
+|----------|---------|-------------|
+| [phases/01-requirements-discovery.md](phases/01-requirements-discovery.md) | Phase 1执行指南 | 理解如何收集用户需求和生成配置 |
+| [specs/skill-requirements.md](specs/skill-requirements.md) | Skill需求规范 | 理解Skill应包含哪些信息 |
+
+### 🔧 Phase 2: Structure Generation
+
+生成目录结构和入口文件
+
+| Document | Purpose | When to Use |
+|----------|---------|-------------|
+| [phases/02-structure-generation.md](phases/02-structure-generation.md) | Phase 2执行指南 | 理解如何生成目录结构 |
+| [templates/skill-md.md](templates/skill-md.md) | SKILL.md模板 | 了解如何生成入口文件 |
+
+### ⚙️ Phase 3: Phase/Action Generation
+
+根据执行模式生成具体的phase或action文件
+
+| Document | Purpose | When to Use |
+|----------|---------|-------------|
+| [phases/03-phase-generation.md](phases/03-phase-generation.md) | Phase 3执行指南 | 理解Sequential vs Autonomous生成逻辑 |
+| [templates/sequential-phase.md](templates/sequential-phase.md) | Sequential Phase模板 | 生成Sequential模式的phase文件 |
+| [templates/autonomous-orchestrator.md](templates/autonomous-orchestrator.md) | Orchestrator模板 | 生成Autonomous模式的编排器 |
+| [templates/autonomous-action.md](templates/autonomous-action.md) | Action模板 | 生成Autonomous模式的action |
+
+### ✅ Phase 4: Specs & Templates
+
+生成领域特定的规范和模板
+
+| Document | Purpose | When to Use |
+|----------|---------|-------------|
+| [phases/04-specs-templates.md](phases/04-specs-templates.md) | Phase 4执行指南 | 理解如何生成domain-specific文档 |
+| [specs/reference-docs-spec.md](specs/reference-docs-spec.md) | 参考文档规范 | ⭐ 生成Specs时要遵循的规范 |
+
+### 🏁 Phase 5: Validation & Documentation
+
+验证生成结果并生成最终文档
+
+| Document | Purpose | When to Use |
+|----------|---------|-------------|
+| [phases/05-validation.md](phases/05-validation.md) | Phase 5执行指南 | 理解如何验证生成的skill完整性 |
+
+### 🔍 Debugging & Troubleshooting
+
+遇到问题时查阅
+
+| Issue | Solution Document |
+|-------|------------------|
+| 生成的Skill缺少Reference Documents | [specs/reference-docs-spec.md](specs/reference-docs-spec.md) - 检查是否遵循分阶段组织 |
+| 参考文档组织混乱 | [specs/reference-docs-spec.md](specs/reference-docs-spec.md) - 核心原则部分 |
+| 生成的文档不符合质量标准 | [../_shared/SKILL-DESIGN-SPEC.md](../_shared/SKILL-DESIGN-SPEC.md) |
+
+### 📚 Reference & Background
+
+用于深度学习和设计决策
+
+| Document | Purpose | Notes |
+|----------|---------|-------|
+| [specs/execution-modes.md](specs/execution-modes.md) | 执行模式详细规范 | Sequential vs Autonomous的对比和适用场景 |
+| [specs/cli-integration.md](specs/cli-integration.md) | CLI集成规范 | 生成的Skill如何与CLI集成 |
+| [specs/scripting-integration.md](specs/scripting-integration.md) | 脚本集成规范 | Phase中如何使用脚本 |
+| [templates/script-template.md](templates/script-template.md) | 脚本模板 | Bash + Python统一模板 |

 ---

-### Phase 1: Requirements Discovery
-
-**Document**: 🔗 [phases/01-requirements-discovery.md](phases/01-requirements-discovery.md)
-
-| Attribute | Value |
-|-----------|-------|
-| **Purpose** | Gather configuration from user via interactive prompts |
-| **Input** | User responses (Skill name, purpose, execution mode) |
-| **Output** | `skill-config.json` (configuration file) |
-| **Key Decision** | Execution mode: Sequential vs Autonomous vs Hybrid |
-
---
-
-### Phase 2: Structure Generation
-
-**Document**: 🔗 [phases/02-structure-generation.md](phases/02-structure-generation.md)
-
-| Attribute | Value |
-|-----------|-------|
-| **Purpose** | Create directory structure and entry file |
-| **Input** | `skill-config.json` (from Phase 1) |
-| **Output** | `.claude/skills/{skill-name}/` directory + `SKILL.md` |
-
---
-
-### Phase 3: Phase/Action Generation
-
-**Document**: 🔗 [phases/03-phase-generation.md](phases/03-phase-generation.md)
-
-| Attribute | Value |
-|-----------|-------|
-| **Purpose** | Generate execution phases or actions based on mode |
-| **Input** | `skill-config.json` + Templates |
-| **Output** | Sequential: `phases/01-*.md` ... OR Autonomous: `phases/orchestrator.md` + `actions/*.md` |
-
-**Decision Logic**:
-```
-IF execution_mode === "sequential":
-  └─ Generate sequential phases with linear flow
-ELSE IF execution_mode === "autonomous":
-  └─ Generate orchestrator + independent actions
-```
-
---
-
-### Phase 4: Specs & Templates
-
-**Document**: 🔗 [phases/04-specs-templates.md](phases/04-specs-templates.md)
-
-| Attribute | Value |
-|-----------|-------|
-| **Purpose** | Generate domain specifications and template files |
-| **Input** | `skill-config.json` (domain context) |
-| **Output** | `specs/{skill-name}-requirements.md`, `specs/quality-standards.md` |
-
---
-
-### Phase 5: Validation & Documentation
-
-**Document**: 🔗 [phases/05-validation.md](phases/05-validation.md)
-
-| Attribute | Value |
-|-----------|-------|
-| **Purpose** | Verify completeness and generate usage documentation |
-| **Input** | All files from previous phases |
-| **Output** | `README.md`, `validation-report.json` |
-
---
-
-## Template Reference
-
-| Template | Generated For | When Used |
-|----------|--------------|-----------|
-| [skill-md.md](templates/skill-md.md) | SKILL.md entry file | Phase 2 |
-| [sequential-phase.md](templates/sequential-phase.md) | Sequential phase files | Phase 3 |
-| [autonomous-orchestrator.md](templates/autonomous-orchestrator.md) | Orchestrator (autonomous) | Phase 3 |
-| [autonomous-action.md](templates/autonomous-action.md) | Action files | Phase 3 |
-| [code-analysis-action.md](templates/code-analysis-action.md) | Code analysis actions | Phase 3 |
-| [llm-action.md](templates/llm-action.md) | LLM-powered actions | Phase 3 |
-| [script-template.md](templates/script-template.md) | Bash + Python scripts | Phase 3/4 |
-
 ## Output Structure

 ### Sequential Mode
@@ -415,4 +401,86 @@ ELSE IF execution_mode === "autonomous":
 │   └── action-base.md
 ├── scripts/
 └── README.md
-```
+```
+
+---
+
+## Reference Documents by Phase
+
+> **重要**: 本部分展示skill-generator如何组织自己的参考文档，这是生成的skill应该模仿的示例。详见 [specs/reference-docs-spec.md](specs/reference-docs-spec.md)
+
+### 🔧 Phase 0: Specification Study (强制前置)
+
+所有生成操作前必须阅读的规范
+
+| Document | Purpose | When to Use |
+|----------|---------|-------------|
+| [../_shared/SKILL-DESIGN-SPEC.md](../_shared/SKILL-DESIGN-SPEC.md) | Skill设计通用规范 | 理解Skill结构和命名规范 ✅ **必读** |
+| [specs/reference-docs-spec.md](specs/reference-docs-spec.md) | 参考文档生成规范 | 确保Reference Documents有正确的组织方式 ✅ **必读** |
+
+### 📋 Phase 1: Requirements Discovery
+
+收集Skill需求和配置
+
+| Document | Purpose | When to Use |
+|----------|---------|-------------|
+| [phases/01-requirements-discovery.md](phases/01-requirements-discovery.md) | Phase 1执行指南 | 理解如何收集用户需求和生成配置 |
+| [specs/skill-requirements.md](specs/skill-requirements.md) | Skill需求规范 | 理解Skill应包含哪些信息 |
+
+### 🔧 Phase 2: Structure Generation
+
+生成目录结构和入口文件
+
+| Document | Purpose | When to Use |
+|----------|---------|-------------|
+| [phases/02-structure-generation.md](phases/02-structure-generation.md) | Phase 2执行指南 | 理解如何生成目录结构 |
+| [templates/skill-md.md](templates/skill-md.md) | SKILL.md模板 | 了解如何生成入口文件 |
+
+### ⚙️ Phase 3: Phase/Action Generation
+
+根据执行模式生成具体的phase或action文件
+
+| Document | Purpose | When to Use |
+|----------|---------|-------------|
+| [phases/03-phase-generation.md](phases/03-phase-generation.md) | Phase 3执行指南 | 理解Sequential vs Autonomous生成逻辑 |
+| [templates/sequential-phase.md](templates/sequential-phase.md) | Sequential Phase模板 | 生成Sequential模式的phase文件 |
+| [templates/autonomous-orchestrator.md](templates/autonomous-orchestrator.md) | Orchestrator模板 | 生成Autonomous模式的编排器 |
+| [templates/autonomous-action.md](templates/autonomous-action.md) | Action模板 | 生成Autonomous模式的action |
+
+### ✅ Phase 4: Specs & Templates
+
+生成领域特定的规范和模板
+
+| Document | Purpose | When to Use |
+|----------|---------|-------------|
+| [phases/04-specs-templates.md](phases/04-specs-templates.md) | Phase 4执行指南 | 理解如何生成domain-specific文档 |
+| [specs/reference-docs-spec.md](specs/reference-docs-spec.md) | 参考文档规范 | ⭐ 生成Specs时要遵循的规范 |
+
+### 🏁 Phase 5: Validation & Documentation
+
+验证生成结果并生成最终文档
+
+| Document | Purpose | When to Use |
+|----------|---------|-------------|
+| [phases/05-validation.md](phases/05-validation.md) | Phase 5执行指南 | 理解如何验证生成的skill完整性 |
+
+### 🔍 Debugging & Troubleshooting
+
+遇到问题时查阅
+
+| Issue | Solution Document |
+|-------|------------------|
+| 生成的Skill缺少Reference Documents | [specs/reference-docs-spec.md](specs/reference-docs-spec.md) - 检查是否遵循分阶段组织 |
+| 参考文档组织混乱 | [specs/reference-docs-spec.md](specs/reference-docs-spec.md) - 核心原则部分 |
+| 生成的文档不符合质量标准 | [../_shared/SKILL-DESIGN-SPEC.md](../_shared/SKILL-DESIGN-SPEC.md) |
+
+### 📚 Reference & Background
+
+用于深度学习和设计决策
+
+| Document | Purpose | Notes |
+|----------|---------|-------|
+| [specs/execution-modes.md](specs/execution-modes.md) | 执行模式详细规范 | Sequential vs Autonomous的对比和适用场景 |
+| [specs/cli-integration.md](specs/cli-integration.md) | CLI集成规范 | 生成的Skill如何与CLI集成 |
+| [specs/scripting-integration.md](specs/scripting-integration.md) | 脚本集成规范 | Phase中如何使用脚本 |
+| [templates/script-template.md](templates/script-template.md) | 脚本模板 | Bash + Python统一模板 |
--- a/.claude/skills/skill-generator/specs/reference-docs-spec.md
+++ b/.claude/skills/skill-generator/specs/reference-docs-spec.md
@@ -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个文档)
--- a/.claude/skills/skill-generator/templates/skill-md.md
+++ b/.claude/skills/skill-generator/templates/skill-md.md
@@ -80,7 +80,9 @@ Bash(\`mkdir -p "\${workDir}"\`);
 {{output_structure}}
 \`\`\`

-## Reference Documents
+## Reference Documents by Phase
+
+> **重要**: 参考文档应按执行阶段组织，清晰标注使用时机和场景。避免平铺文档列表。

 {{reference_table}}

@@ -132,12 +134,12 @@ function generatePrerequisites(config) {
  const templates = config.templates || [];

  let result = '### 规范文档 (必读)\n\n';
-  result += '| Document | Purpose | Priority |\n';
-  result += '|----------|---------|----------|\n';
+  result += '| Document | Purpose | When |\n';
+  result += '|----------|---------|------|\n';

  specs.forEach((spec, index) => {
-    const priority = index === 0 ? '**P0 - 最高**' : 'P1';
-    result += `| [${spec.path}](${spec.path}) | ${spec.purpose} | ${priority} |\n`;
+    const when = index === 0 ? '**执行前必读**' : '执行前推荐';
+    result += `| [${spec.path}](${spec.path}) | ${spec.purpose} | ${when} |\n`;
  });

  if (templates.length > 0) {
@@ -151,6 +153,80 @@ function generatePrerequisites(config) {

  return result;
 }
+
+// ⭐ 新增：生成分阶段参考文档指南
+function generateReferenceTable(config) {
+  const phases = config.phases || config.actions || [];
+  const specs = config.specs || [];
+  const templates = config.templates || [];
+
+  let result = '';
+
+  // 为每个执行阶段生成文档导航
+  phases.forEach((phase, index) => {
+    const phaseNum = index + 1;
+    const phaseEmoji = getPhaseEmoji(phase.type || 'default');
+    const phaseTitle = phase.display_name || phase.name;
+
+    result += `### ${phaseEmoji} Phase ${phaseNum}: ${phaseTitle}\n`;
+    result += `执行Phase ${phaseNum}时查阅的文档\n\n`;
+
+    // 列出该阶段相关的文档
+    const relatedDocs = filterDocsByPhase(specs, phase, index);
+    if (relatedDocs.length > 0) {
+      result += '| Document | Purpose | When to Use |\n';
+      result += '|----------|---------|-------------|\n';
+      relatedDocs.forEach(doc => {
+        result += `| [${doc.path}](${doc.path}) | ${doc.purpose} | ${doc.context || '查阅内容'} |\n`;
+      });
+      result += '\n';
+    }
+  });
+
+  // 问题排查部分
+  result += '### 🔍 Debugging & Troubleshooting (问题排查)\n';
+  result += '遇到问题时查阅的文档\n\n';
+  result += '| Issue | Solution Document |\n';
+  result += '|-------|-------------------|\n';
+  result += `| Phase执行失败 | 查阅相应Phase的文档 |\n`;
+  result += `| 输出不符合预期 | [specs/quality-standards.md](specs/quality-standards.md) - 验证质量标准 |\n`;
+  result += '\n';
+
+  // 深度学习参考
+  result += '### 📚 Reference & Background (深度学习)\n';
+  result += '用于理解原始实现和设计决策\n\n';
+  result += '| Document | Purpose | Notes |\n';
+  result += '|----------|---------|-------|\n';
+  templates.forEach(tmpl => {
+    result += `| [${tmpl.path}](${tmpl.path}) | ${tmpl.purpose} | 生成时参考 |\n`;
+  });
+
+  return result;
+}
+
+// 辅助函数：获取Phase表情符号
+function getPhaseEmoji(phaseType) {
+  const emojiMap = {
+    'discovery': '📋',
+    'generation': '🔧',
+    'analysis': '🔍',
+    'implementation': '⚙️',
+    'validation': '✅',
+    'completion': '🏁',
+    'default': '📌'
+  };
+  return emojiMap[phaseType] || emojiMap['default'];
+}
+
+// 辅助函数：根据Phase过滤文档
+function filterDocsByPhase(specs, phase, phaseIndex) {
+  // 简单过滤逻辑：匹配phase名称关键词
+  const keywords = phase.name.toLowerCase().split('-');
+  return specs.filter(spec => {
+    const specName = spec.path.toLowerCase();
+    return keywords.some(kw => specName.includes(kw));
+  });
+}
 ```

 ## Sequential 模式示例