4. 模板体系与标准化写作

在 Confluence 中，模板体系解决的不是“有没有页面”，而是“页面之间能不能被比较、被检索、被复用、被审计”。当需求、设计、接口、测试报告、复盘报告各自为政时，团队会陷入三种典型困境：同一类信息在不同页面里位置不同，评审时找不到关键字段；状态标识靠正文描述，无法用页面属性筛选；必填字段缺失，导致下游环节反复追问。标准化写作的核心，是把“写什么、写在哪、什么状态、谁负责”从个人习惯变成页面结构。

模板体系的四层结构

一个可落地的模板体系通常由四层构成：模板类型层、元数据层、正文结构层、状态与流转层。模板类型层决定页面属于需求、设计、接口、测试报告还是复盘报告；元数据层用页面属性或固定表格承载编号、负责人、版本、关联需求、优先级等字段；正文结构层规定标题层级和必填段落；状态与流转层用标签或状态字段标识草稿、评审中、已批准、已废弃等阶段。四层缺一不可，否则模板只是“好看的排版”，无法支撑治理。

五类模板的必填字段设计

模板的价值首先体现在“必填字段”上。必填字段不是越多越好，而是要与下游动作直接挂钩。需求文档的必填字段建议包括：需求编号、提出人、目标用户、业务价值、验收标准、优先级、关联设计文档。其中“验收标准”必须可验证，例如“接口响应时间 P95 ≤ 300ms”比“性能良好”更有约束力。设计文档的必填字段包括：设计编号、关联需求、架构图链接、关键决策与备选方案、数据模型、接口清单、风险与降级策略。接口文档的必填字段包括：接口名称、路径、方法、请求参数、响应字段、错误码、调用示例、版本变更记录。测试报告的必填字段包括：测试范围、环境版本、用例总数、通过率、缺陷分布、遗留风险、结论。复盘报告的必填字段包括：事件时间线、影响范围、根因、改进项、责任人、完成时限。

这些字段在 Confluence 中可以通过“页面属性”宏或固定表格实现。页面属性宏的优势是可被搜索、可被报表聚合；固定表格的优势是编辑直观、适合评审时逐项确认。建议对需要跨页面统计的字段使用页面属性，对仅在本页展示的字段使用表格。

统一标题与元数据规范

标题规范要解决“一眼识别”问题。推荐格式为：[类型] 主题 - 版本，例如 [需求] 订单导出功能 - v1.2、[接口] 用户中心查询接口 - v2.0。类型前缀与模板类型层一一对应，便于用 Confluence 搜索或 CQL 按标题前缀过滤。元数据统一放在页面顶部固定表格中，字段顺序固定，避免“有的页面写在开头、有的写在结尾”。

状态标识建议使用标签而非纯文本。标签如 status-draft、status-review、status-approved、status-deprecated，配合页面属性中的“状态”字段，既能人工识别，也能被自动化规则读取。状态变更时，必须在页面底部“变更记录”中追加一行：时间、操作人、原状态、新状态、变更原因。这样复盘时能还原文档生命周期。

模板落地与治理检查

模板创建后，需要配套三项治理动作。第一，模板入口统一：在空间首页放置“模板中心”页面，用“创建来自模板”按钮或模板宏暴露五类模板，避免成员从历史页面复制导致结构漂移。第二，必填字段校验：利用 Confluence 的页面属性报表或第三方插件，定期扫描缺失必填字段的页面，生成待补全清单。第三，模板版本管理：模板本身也要有版本号，当字段增删时，旧页面不强制迁移，但新页面必须使用新模板，并在模板说明中标注生效日期。

一个可参考的模板字段示例

以接口文档模板为例，其元数据表格可设计为：

正文部分则固定包含：接口说明、请求参数表、响应字段表、错误码表、调用示例、变更记录。其中“调用示例”必须给出可复制的 curl 或 JSON 片段，例如：

curl -X GET "https://api.example.com/api/v2/users/1001" \
  -H "Authorization: Bearer <token>" \
  -H "Accept: application/json"

这样接口文档才具备“可执行”属性，而不是只供阅读。测试报告和复盘报告同理，必须包含可验证的数据或时间线，否则模板就退化为格式约束，无法支撑研发治理。

标准化写作的最终目标，是让文档在缺少作者口头解释的情况下仍能被理解、被评审、被追溯。模板体系是手段，统一标题、元数据、状态标识与必填字段是抓手，持续治理才是结果。