git-learn/.agents/skills/sm-flow/references/templates.md

# 模板

这些是最小模板。只有在能提升未来可读性时，才增加额外章节。保留 PRD、ADR、OpenSpec、slug 等行业术语，其余说明尽量使用中文。

## Brief 模板

```markdown
# {标题} Brief

## 背景

- 用户目标：{goal}
- 当前问题：{problem}
- 关联 OpenSpec：`openspec/changes/{slug}/`
- devflow 分档：micro | standard | complex

## 范围

- 本次要做：{in scope}
- 本次不做：{out of scope}
- 影响区域：{modules/files if known}

## OpenSpec 对齐

- proposal 覆盖状态：已覆盖 / 待修正 / 不适用
- specs 覆盖状态：已覆盖 / 待修正 / 不适用
- tasks 覆盖状态：已覆盖 / 待修正 / 不适用
```

## Evidence 模板

```markdown
# {标题} Evidence

## 证据

| 来源 | 证据 | 结论 | 是否已汇报 |
| --- | --- | --- | --- |
| {file/doc/test/ADR} | {evidence summary} | {conclusion} | 是 / 否 |

## Evidence-driven 结论

- 结论：{conclusion}
  - 证据：{evidence}
  - 风险：{risk if any}
  - 用户确认：需要 / 不需要 / 已确认
```

## Decisions 模板

```markdown
# {标题} Decisions

## Question Pool

| # | 维度 | 问题 | 模式 | 状态 |
|---|---|---|---|---|
| Q1 | 术语 | {question} | evidence-driven / user-interview | 已解决 / 未解决 |
| Q2 | 边界 | {question} | evidence-driven / user-interview | 已解决 / 未解决 |
| Q3 | 验收 | {question} | evidence-driven / user-interview | 已解决 / 未解决 |

## Evidence-driven

| 结论 | 证据来源 | 是否已汇报用户 |
|---|---|---|
| {conclusion} | {file/doc/test/ADR} | 已汇报 / 待汇报 |

## User-interview

| 问题原文 | 用户原话 | 确认状态 | OpenSpec 回写 |
|---|---|---|---|
| {question} | {user's exact words} | 已确认 / 未确认 | 已回写 / 不影响 / 待回写 |

## 关键取舍

- 决策：{decision}
  - 原因：{why}
  - 影响：{impact}
  - 风险接受：{accepted by whom/when}
```

## 接口影响记录模板

```markdown
# {标题} 接口影响记录

## 分级

- 级别：L1 内部实现 / L2 内部接口 / L3 协作接口 / L4 破坏性接口
- 判级原因：{why this level}
- 是否需要独立接口文档：是 / 否

## 变更对象

- 接口/字段/DTO/事件/回调/数据库契约：
- 判断逻辑变化：
- 可观察行为变化：返回数据 / 状态 / 错误码 / 权限结果 / 过滤排序 / 幂等性 / 时序 / 副作用 / 无

## 影响范围

- 调用方/消费者：
- 是否跨模块/跨服务/跨团队：
- 旧调用方是否需要改动：

## 兼容与迁移

- 是否向后兼容：
- 迁移/灰度/回滚要求：
- 风险接受：

## 验收方式

- 如何证明新行为正确：
- 如何证明旧行为未破坏：
- 需要用户确认的问题：
```

## 实现期冲突记录模板

```markdown
# {标题} 实现期冲突记录

## 冲突摘要

- 触发来源：用户质疑 / 用户变更 / 代码发现 / 测试失败 / 运行行为
- 冲突对象：proposal / design / specs / tasks / ADR / 代码行为
- 分类：实现偏差 / 规格遗漏 / 设计冲突 / 用户变更

## 证据

- OpenSpec 依据：
- 代码或测试证据：
- 用户反馈：

## 处理

- 决策：
- 是否需要用户确认：是 / 否
- OpenSpec 回写：不需要 / 已回写 / 待回写
- 代码处理：
- 验证方式：
```

## PRD 模板

```markdown
# {标题} PRD

## 问题陈述

用用户视角描述问题。

## 解决方案

用用户视角描述预期解决方案。

## 用户故事

1. 作为{角色}，我希望{能力}，以便{收益}。

## 实现决策

- 决策：{decision}
  - 原因：{why}
  - 影响：{affected modules or behavior}

## 测试决策

- 好测试应该通过{public interface}验证{observable behavior}。
- 必须覆盖：{critical paths}
- 不测试：{explicit exclusions}

## 非目标

- {excluded behavior}

## 补充说明

- {open question or useful context}
```

## 词汇表模板

```markdown
# 上下文词汇表

## 术语

### {术语}

- 定义：{precise definition}
- 使用场景：{feature/module/context}
- 备注：{ambiguities, synonyms, or rejected meanings}

## 业务规则

- {rule}: {meaning and source}
```

## ADR 模板

```markdown
# ADR-{编号}: {决策标题}

**状态**：提议中 | 已接受 | 已废弃  
**日期**：YYYY-MM-DD

## 背景

是什么情况迫使我们做这个决策？

## 决策

我们选择了什么？

## 替代方案

| 方案 | 拒绝原因 |
| --- | --- |
| {option} | {reason} |

## 后果

### 正面

- {benefit}

### 负面

- {cost or risk}
```

## 技术调研模板

```markdown
# {标题} 技术调研

## 摘要

- 变更原因：{reason}
- 变更范围：{scope}
- 主要技术方案：{approach}

## 源产物

- OpenSpec change: `openspec/changes/{slug}/`
- 关联 PRD: `prd.md` 或 `brief.md`

## 关键发现

- {finding}

## 假设

- {assumption and validation status}
```

## 设计模板

```markdown
# {标题} 设计

## 架构摘要

描述输入 → 处理 → 输出。

## 关键决策

- {decision}: {reason}

## 模块地图

| 模块 | 职责 | 备注 |
| --- | --- | --- |
| {module} | {responsibility} | {notes} |

## 架构审计

- 风险：{risk}
- 缓解：{mitigation}
```

## 任务模板

```markdown
# {标题} 任务

## 需求追踪

| 需求 | 状态 | 备注 |
| --- | --- | --- |
| {requirement} | 已完成 / 待处理 / 部分完成 | {notes} |

## 实现任务

- [ ] {task}
```

## 验收模板

```markdown
# {标题} 验收

## 结果

已接受 / 部分接受 / 未接受。

## 验证

### 静态验证

- 命令/检查：`{command or check}`
- 结果：{passed/failed/not run}
- 备注：{important output or reason not run}

### 脚本验证

- 命令：`{command}`
- 结果：{passed/failed/not run}
- 备注：{important output or reason not run}

### 浏览器/人工验证

- 步骤：{manual steps}
- 结果：{passed/failed/not run}
- 备注：{observations or reason not run}

## 已完成范围

- {completed behavior}

## 已知限制

- {limitation}

## Bug 修复和诊断

- {bug}: {diagnosis summary and regression coverage}

## 交接

- 下一步：{archive, deploy, review, or follow-up}
- OpenSpec 归档确认：{已询问/用户确认归档/用户暂不归档/不适用}
```

## Cross-Artifact 对齐检查表模板

specify 阶段的 checkpoint 必须包含此检查表。每项标记"已对齐"或"存在 gap"。

```markdown
## Cross-Artifact 对齐检查

| 上游 → 下游 | 检查内容 | 状态 |
|---|---|---|
| brief/prd → proposal | 目标、范围、非目标、验收预期是否进入 proposal | 已对齐 / 存在 gap |
| proposal → design | 范围、约束、关键承诺是否进入 design | 已对齐 / 存在 gap |
| design → specs/tasks | 影响实现的约束、接口影响、架构结论是否进入 specs 或 tasks | 已对齐 / 存在 gap |
| specs → tasks | 可观察行为是否被 tasks 覆盖为可执行切片 | 已对齐 / 存在 gap |

### Gap 详情（如有）

- gap 1：{描述哪个字段/约束/行为/切片只停留在上游，未进入下游}
  - 修复：{如何修正 OpenSpec}
```

## 复合知识模板

```markdown
# {标题}

**类型**：learning | trick | decision | explore  
**日期**：YYYY-MM-DD

## 背景

这条经验来自哪里？

## 经验

未来代理应该复用什么经验？

## 适用性

什么时候适用？什么时候不适用？
```