# 模板推导详细方法

> 本文件包含模板灵活度判断、固定外壳定义、核心章节推导的完整方法。
> 在执行工作流 Phase 3（模板推导）时读取本文件。

---

## 📋 目录

1. [推导根基：三轨制](#推导根基三轨制)
2. [四种模板灵活度](#四种模板灵活度)
3. [固定外壳三级分类](#固定外壳三级分类)
4. [核心章节推导](#核心章节推导)
5. [完整推导流程](#完整推导流程)

---

## 推导根基：三轨制

模板推导从三轨出发——**先确定轨道，轨道决定模板骨架，分组决定具体章节**。

| 轨道 | 模板倾向 | 固定外壳重点 | 核心章节来源 |
|------|---------|------------|------------|
| 🔴 Intent | 固定模板或全结构统一 | 设计背景/动机、关键决策 | 设计意图相关的问题 |
| 🟢 Contract | 取决于分组 | 变更历史、技术实现 | 代码结构相关的问题 |
| 🔵 Constraint | 外壳统一 | 规则列表、检查清单 | 约束相关的问题 |

---

## 四种模板灵活度

### 判断流程

```
分组内文档回答同一类问题吗？
├── 否 → 灵活度 1: 完全独立
└── 是 → 读者对每份文档的期望完全相同吗？
         ├── 是 → 灵活度 3: 全结构统一
         └── 否 → 核心章节有共性但也有独特需求吗？
                  ├── 是 → 灵活度 4: 混合模式
                  └── 否 → 灵活度 2: 外壳统一
```

### 四种灵活度详解

| # | 灵活度 | 条件 | 模板内容 | 示例 |
|---|--------|------|---------|------|
| 1 | **完全独立** | 分组内文档回答不同问题 | 只有固定外壳，核心章节完全自由 | 架构文档（C4图 vs 时序图 vs 类图） |
| 2 | **外壳统一** | 职责相同、内容不同 | 固定外壳 + 固定核心章节名 | 编码规范（都列出规则+示例+检查清单） |
| 3 | **全结构统一** | 读者期望完全相同 | 固定外壳 + 固定核心章节名 + 固定顺序 | 模块文档（都需要概述+API+配置+指南） |
| 4 | **混合模式** | 外壳统一 + 核心自由 | 固定外壳 + 共性核心章节 + 允许独特章节 | 游戏系统文档（概述+集成指南相同，但 AI 系统有行为树章节、渲染系统有 Shader 管线章节） |

### 三轨对灵活度的影响

| 轨道 | 推荐的灵活度 | 理由 |
|------|------------|------|
| Intent | 灵活度 2 或 3 | 设计意图的记录方式是稳定的 |
| Contract | 视分组而定 | 模块文档→3；架构文档→4 或 1 |
| Constraint | 灵活度 2 | 约束文档的职责天然一致 |

---

## 固定外壳三级分类

### 📌 必须包含（所有文档）

| 元素 | 作用 | 格式 |
|------|------|------|
| **标题 + 一句话职责** | 身份识别 | `# 模块名` + 第一段一句话概括 |
| **📋 目录** | 微观导航 | 列出所有二级和三级标题 |
| **轨道标签** | 标明所属轨道 | 文档头部标注 🔴Intent / 🟢Contract / 🔵Constraint |

### 📎 推荐包含（大多数文档）

| 元素 | 作用 | 例外 |
|------|------|------|
| **概述/背景** | 回答"为什么要读这份文档" | 极短文档（<50行）可省略 |
| **相关文档** | 交叉引用 | 独立文档（如纯参考表）可省略 |

### 📎 可选包含（按需）

| 元素 | 触发条件 | 理由 |
|------|---------|------|
| **变更历史** | Contract 轨文档 或 开源项目 | Intent 轨不需要（冻结） |
| **检查清单** | Constraint 轨文档 | 其他轨道通常不需要 |
| **Mermaid 图** | 架构/流程文档 | API 参考表不需要 |

### 三轨对外壳的影响

| 外壳元素 | Intent | Contract | Constraint |
|---------|:------:|:--------:|:----------:|
| 轨道标签 | 🔴 | 🟢 | 🔵 |
| 变更历史 | ❌（冻结） | ✅（跟随代码） | ⚠️（规则变更时） |
| 检查清单 | ❌ | ❌ | ✅ |
| Mermaid 图 | ✅（设计图） | ✅（实现图） | ❌ |

---

## 核心章节推导

### 路径 A：从读者问题反推（主路径）

核心方法论：**问"读这份文档的人想回答什么问题？"**

#### 推导步骤

1. 识别目标读者（AI Agent / 人类开发者 / 两者兼有）
2. 列出读者会问的问题
3. 每个问题映射为一个章节
4. 补充"读者不会问但必要的"章节（限制、已知问题、安全注意事项等）

#### 三轨的典型读者问题

**Intent 轨 → 典型章节：**

| 读者问题 | 章节名 |
|---------|--------|
| "为什么要这样设计？" | 设计背景/动机 |
| "目标是什么？" | 设计目标 |
| "方案是什么？" | 方案概述 |
| "做了哪些关键决策？" | 关键决策记录 |
| "有什么约束条件？" | 约束与限制 |

**Contract 轨 → 典型章节：**

| 读者问题 | 章节名 |
|---------|--------|
| "这个模块做什么？" | 概述 |
| "怎么用？" | 使用指南 |
| "有哪些 API？" | API 参考 |
| "怎么配置？" | 配置参考 |
| "内部怎么实现的？" | 技术设计 |
| "有哪些限制？" | 已知限制 |

**Constraint 轨 → 典型章节：**

| 读者问题 | 章节名 |
|---------|--------|
| "这个规范的目的？" | 规范目的 |
| "具体规则是什么？" | 规则列表 |
| "怎么检查合规？" | 检查清单 |

### 路径 B：从代码模式归纳（辅助路径）

从代码结构自动补充技术性章节：

| 代码特征 | 补充章节 |
|---------|---------|
| 公开方法/函数/端点 | API 参考 |
| 配置类/环境变量 | 配置参考 |
| 事件/回调/Hook | 事件参考 |
| 依赖关系 | 依赖说明 |
| 错误/异常定义 | 错误处理 |
| 数据模型/Schema | 数据模型 |

### 现场调研辅助

当用户同意时，查询该领域/技术栈的常见文档模板作为启发提示：
- 例：React 组件库 → Storybook 文档通常包含 Overview / Props / Events / Slots / Examples / Accessibility
- 调研结果作为启发，不作为强制模板

---

## 完整推导流程

```
Phase 1: 轨道分类
  ├── 这份文档属于 Intent / Contract / Constraint 哪个轨道？
  └── 轨道决定模板的大方向和固定外壳的组成

Phase 2: 灵活度选择
  ├── 分组内文档是否回答同一类问题？
  ├── 读者期望是否完全相同？
  └── 是否有共性但也有独特需求？→ 四种灵活度

Phase 3: 固定外壳生成
  ├── 必须层：标题+职责 + 目录 + 轨道标签
  ├── 推荐层：概述 + 相关文档
  └── 可选层：变更历史 / 检查清单 / Mermaid 图

Phase 4: 核心章节推导
  ├── 主路径：读者问题反推（三轨的典型问题作为起点）
  ├── 辅助路径：代码模式归纳（补充技术性章节）
  ├── 调研辅助（可选）：联网查询业界实践
  └── 补充"读者不会问但必要的"章节

Phase 5: 用户确认
  ├── 展示推导过程 + 生成的模板
  └── 用户可增删章节、调整顺序
```