# Creekmoon Strategic Decision Report

> 技术战略决策报告写作与核查标准——仅在一个场景触发：技术方向和方案已定、尚未落地，需要向领导/上级做书面汇报，讲清"要怎么实施、考虑过哪些取舍、最终怎么决策"，让懂技术但不了解本仓库细节的领导知晓并认可。本质是一场写给领导看的技术分享，不是请领导拍板，不是和实现者讨论怎么做，更不是 TRD/技术方案/ADR 本身。写后派独立子代理以读者视角核查再修订；理解与表达意图永远优先于模板，章节可按实际情况增删。仅当用户要"给领导/上级汇报技术决策""写决策汇报材料""把已定方案提炼成给领导看的报告"，或评审/改写这类汇报材料时使用；写 TRD、做方案论证或选型讨论、写代码设计文档、写周报等场景，一律不用本 skill。

- Skill: `creekmoon/creekmoon-strategic-decision-report` (Agent Skill)
- Install (CLI): `npx skillmds@latest add creekmoon/creekmoon-strategic-decision-report`
- Raw SKILL.md: https://api.skillmd.com/api/skills/creekmoon/creekmoon-strategic-decision-report/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: creekmoon (https://skillmd.com/u/creekmoon)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/creekmoon/creekmoon-strategic-decision-report

---


# 技术战略决策报告

> 唯一使用场景：**技术方向和方案已经定了、还没落地，要向领导书面汇报这个决策。**
> 读者：**懂技术、但不了解（也不关注）本仓库代码细节的领导**。他懂架构、懂 HTTP/回调/状态机这类通用概念，但不知道你系统里叫什么、长什么样。
> 目的：让领导**知晓并认可**——"知道这回事，同意这样做"。名义上是汇报，实际是一场书面技术分享：把"要怎么实施、考虑过什么、最终怎么定"讲到他能跟上并认同。不是请他做选择题，不是和他讨论实现。

其他场景（写 TRD、做选型论证、讨论实现方案、代码设计文档、周报总结）不要用本标准。

## 第一优先级：理解意图、表达意图

模板、原则、清单都是工具，**把这次决策向这位领导表达清楚才是目的**。

- **动笔前先理解意图**：这次汇报要让领导记住什么、认可什么？他最关心什么（为什么做、为什么不用现成方案、风险多大、代价多少）？意图不同，同一份素材写出的报告完全不同。
- **表达意图优先于模板叙事**：后文的参考结构只是默认起点，章节**允许增、删、并、换序**。每一节、每一句话都用同一个问题裁决：它是否帮助这位领导理解并认可这个决策？不帮助就删，缺了就补。
- 模板与表达冲突时，改模板，不改表达。

## 读者认知模型（先想明白读者是谁）

- 领导的通用技术认知不缺，缺的是**本系统的上下文**：内部系统名、模块名、机制名、历史沿革，他一概不知。
- **把读者的认知预设为低于作者**：凡是作者天天在用、习以为常的概念，他大概率第一次见。默认他需要被铺垫，而不是默认他能跟上。
- 他读报告的心理是"让我听懂、让我认可"，不是"让我参与实现"，更不是"让我查证"。只对实现者或文档管理者有意义的信息（改哪个类、见哪个章节、对应哪个编号），都是噪声。

## 表达四原则（本标准的核心）

### 原则一：术语必须铺开，首次出现即解释

本系统的内部概念（系统名、模块名、机制名、黑话），第一次出现时必须用一两句话讲清它是什么。两个去处：

- 少量、关键的：集中在开头设「背景与术语」一节，一张表讲清。
- 其余：在首次出现处就地解释。

判断标准：一个不了解本仓库的技术人，从头读到尾，**不需要问"这是什么"**。

**术语表必须可跳回**：读者是跳读的（常从速览表直接跳到某个决策），不能让人手工往回翻。做法：

- 在「背景与术语」表处放一个固定锚点（如 `<a id="terms"></a>`，不要用标题自动生成的锚点——章节一重编号链接就全失效）。
- 每个术语在术语表之后的**首次出现处**加一次跳回链接（`[术语](#terms)`），之后再用不再加。
- 不要每处出现都加链接——满屏链接伤可读性，源文件也难维护；首次出现处一次即可。

### 原则二：不许拿仓库内部细节当未解释的"因"

每个"因为/所以"的因，必须是读者已经能理解的东西：通用技术语言、已解释过的概念、或业务/运维给出的硬约束。禁止出现"内部细节 → 结论"的推理跳跃——读者跟不上因，就不会认可果。

**反例**：
> 因为系统内存在 15 道闸门，所以重写代价大。

读者不知道 15 道闸门是什么、和代价有什么关系，这个因果对他不成立。

**正例**：
> ChatBot 处理每条用户消息，要顺序通过 15 个业务校验关卡（机器人是否启用、算力与套餐是否充足等，下称"15 道闸门"）。重写意味着这 15 个关卡都要在新链路重建并逐一回归验证；而在闸门之后新增一个分流层，老链路一行不动。

先把"因"翻译成读者能懂的东西，再推"果"。

### 原则三：技术分享的语气，不是实现讨论的语气

- 讲"是什么、为什么这样定"，让读者跟上思路并认同；不讲"怎么做、改哪里"（那是 TRD 的事）。
- 把判断讲成**任何懂技术的人都能复现的推理**：约束是什么 → 选项有哪些 → 为什么这个赢。读者认的是推理过程，不是你的内部权威。
- 不把读者拉到和自己一个水平线：不甩内部名词、不甩代码符号、不用"大家都知道"的口吻省略铺垫。

**标题与行文规范**（AI 味最大的来源是栏目腔和导览腔）：

- **标题用克制的名词短语**，准确命名这节讲什么：「方案与预期」「硬约束」「决策」「需知晓与需协调事项」。
- **禁止导览腔/栏目腔**：不要「一页看懂」「怎么用这份文档」「速览一览」「汇报前请花一分钟」这类栏目名；不要在标题里加括号解说词。
- **禁止元叙述手脚架**：不写"本节的结构是……""下面从几个方面……""每节按统一格式……"——结构通过一致性体现，不靠声明。
- **不用助手腔**：不出现「值得注意的是」「综上所述」「我们可以看到」；不用 ✅❌ 当正文主力；加粗每段最多 1-2 处。
- **判断句标题是少用工具**：决策小节的标题可以带最终结论（如「外部编排引擎选型：引入 n8n」），但全篇正文标题以名词短语为主。

### 原则四：报告必须自包含，正文零外部引用

报告是给领导一次读完的，不是给编者交叉溯源的。**正文不出现任何指向其他文档或代码库的内容**：

- 不写「见 TRD §x」「详见某文档」类指针；不在每个决策末尾挂「落地细节见 XX」。
- 不挂 ADR、EC 等外部编号；事项需要编号时，用本文自己的局部编号（1、2、3…）。
- 不附代码文件路径与行号。证据用大白话讲机制（"调用方不等待，结果由回调返回"），不用仓库坐标证明。
- 不做「与其他文档的对应关系」附录。关联文档只在文头出现一次。
- 例外：文头的元信息（文档类型、关联文档、版本表）属于文档管理簿记，可以保留；版本表是本文自己的历史，可以留。

**可追溯性是写作过程的纪律，不是交付物的内容。** 写前从 TRD/PRD 提取口径锚点、写后逐条回查——这些留在工作过程里（落盘到工作区），一个字都不进报告。

## 写作禁忌

以下行为一律禁止。写完后逐条对照——违反任一条，报告就不及格。

**信息源头（防幻觉）**
- 不编造源文档中没有的选项、数据、风险或约束。选项表里每一行都必须来自 TRD/PRD 讨论过的方案
- 不估算数字——所有数量、阈值、百分比必须从源文档提取；源文档缺失的，交付时向用户指出，不在报告里填假数
- 不替领导添加"最佳实践建议"——报告只承载已定决策，不夹带私货

**表达方式**
- 不甩未解释的内部术语、系统名、模块名、黑话（→ 原则一）
- 不用内部细节直接当"因为"（→ 原则二）
- 不写实现口吻——不出现"改 XX 类""调 YY 方法""重构 ZZ 模块"
- 不出现栏目腔标题、导览腔、元叙述手脚架、助手腔（→ 原则三）

**文档边界**
- 正文不出现任何外部引用——无文档指针、无代码路径行号、无 ADR/EC 编号（→ 原则四）
- 不设"待拍板/待确认/待批准"栏目——有未决问题说明方案还没定
- 不设「决策顺序/依赖关系」或「与其他文档对应关系」章节

**规模控制**
- 每决策小节 ≤ 约 20 行；全文 ≤ 约 300 行
- 术语解释一两句话即可——铺开 ≠ 展开

## 战略级 vs 战术级：判定方法

一条内容该不该留在报告里，用一个问题判定：

> **这个细节删掉，会影响领导理解"要改成什么样、为什么这么定"吗？**

- 会 → 留下（如：选项各自的排除理由、风险等级、硬约束）。
- 不会 → 下沉到 TRD（过程记录，正文不留指针）。

常见误判清单（这些看起来像决策，其实是战术或噪声）：

| 内容 | 归属 |
|------|------|
| 类名/方法名/文件行号（如 `XxxService.dispatch()`） | TRD / 过程记录 |
| 接口契约、payload 字段清单、枚举值表 | TRD |
| 落地修改清单、影响范围（改哪些文件） | TRD |
| ADR/EC 等外部编号、「见 TRD §x」指针、文档间对应关系附录 | 过程记录，不进报告 |
| 决策对象的名称与一句话定位（如"新建统一回调入口"） | 报告可留，领导需要知道决策对象是什么；但名称若属内部黑话，按原则一解释 |

## 执行流程

写稿与挑错是两种相反的思路：写稿要共情读者的无知（"怎么让读者听懂"），挑错要扮演读者的质疑（"哪里还没讲清楚"）。同一上下文里写完稿再自查，挑错必然流于形式——写的人看自己的稿子怎么看怎么顺。所以下面四步中，第三步必须换上下文，派独立子代理执行。

### 取材：定意图、圈边界

- 与用户确认汇报意图：汇报给谁、他最关心什么、读完要得到什么结论。
- 通读 TRD/PRD，提取口径锚点（最终决策、硬数字、阈值、风险定性、术语口径），落盘到工作区。发现源文档自身不一致时记下，交付时向用户指出（不擅自改 TRD/PRD）。

### 写初稿

- 心态：站在领导位置想"我需要听到什么，才听得懂、才认可"。
- 结构以后文参考模板为起点，**按意图增删章节**；行文遵守表达原则与写作禁忌。
- 每个决策以"可选项 + 最终选择"呈现；每个"因"先翻译成读者已知的话，再推"果"。
- 这一步只管把意图表达清楚，不边写边自查。

### 派独立子代理核查

- 派一个全新子代理，让它扮演那位不了解本仓库的领导通读初稿，专挑毛病：不复读素材找理由，不体谅作者。
- prompt 必须给全：报告初稿路径、口径锚点路径、本标准全文、"你是读者不是作者"的设定。
- 要求逐项过《核查清单》，并加做跳读测试和抽因测试。
- 子代理只回不符合项清单（位置 + 问题 + 改法），不直接改稿——改不改、怎么改，由拿着汇报意图的主线裁决。

### 修订与交付

- 按不符合项逐条修订；有争议时回到"是否有助于这位领导理解并认可"裁决。
- 核查—修订可循环多轮，直到核查清单全过。
- 交付时向用户说明：汇报意图是什么、结构如何为意图服务（增删了哪些章节及原因）、核查发现与处理、口径回查结果、源文档不一致处。

## 参考结构（默认起点，可增删）

```markdown
# <主题>关键决策

**文档类型**：技术战略决策报告（向领导汇报用）
**关联文档**：<TRD>（落地细节）、<PRD>（业务背景）
**适用对象**：上级领导（知晓与确认）；架构与研发（按决策执行）
**评审状态**：草稿，待汇报

| 版本表（保留历史，新增一行说明本次变更） |

## 一、方案与预期
### 1.1 方案概述（一句话链路，不动/新增标清；+ 一两句决策口径，如"本期上线即用"）
### 1.2 背景与术语（| 术语 | 一句话解释 |，覆盖后文所有内部概念）
### 1.3 最终预期（验收标尺：什么算达成、什么算失败）
### 1.4 决策速览（| 编号 | 决策 | 最终选择 | 一句话理由 |）

## 二、硬约束
（一句话说明约束来源与"违反即排除"；| 约束 | 来源 | 影响的决策 |）

## 三、决策
### D1 外部编排引擎选型：引入 n8n（标题带最终结论）
（必要时一两句背景铺垫，用读者已知的话讲）
| 选项 | 说明（一句话） | 结论（选定 / 排除：一句话理由） |
决策理由：≤3 条，每条一句；每条理由的"因"都必须是读者已知的。
| 风险 | 对策 |（≤3 行，只留战略级风险）

## 四、需知晓与需协调事项
（本期边界、风险定性、后续安排、需外部配合事项；含上线硬前置一句）
```

要点：

- **「背景与术语」是原则一的集中落点**：把后文用到的内部概念各用一句话讲清，后文就可以干净地使用术语而不反复打断行文。
- **决策速览表是文档的"首页"**：读者只看这张表也应能了解全貌并给出意见。表里不放"关联 ADR"这类溯源列。
- **每个决策小节格式完全统一**：选项表 → 决策理由 → 风险与对策。选项表里每个选项只写一句话说明 + 一句话排除理由；优缺点四维度全表展开是 TRD 的事。
- **不放「决策顺序 / 依赖关系」类章节**：那是拍板件的视角；报告里决策已定，顺序与依赖对读者无意义，有排期价值时属于 TRD。
- **§4 的语气是"知悉"不是"请示"**：写清本期边界（什么不做、什么二期再做）、已定性的风险、后续安排。不设"待拍板/待确认事项"栏目——真有未决问题，说明方案还没定，那就还不该写这份报告。

章节存废判断（"表达意图优先"的落地）：

- 「背景与术语」：后文用到内部概念就必须有；全是通用概念时可省。
- 「决策速览」：决策 ≥2 个时是文档首页；只有一个决策时可省。
- 「硬约束」：真有"违反即排除"的约束才设；没有就不设，不硬凑。
- 「需知晓与需协调事项」：确有边界、风险定性或外部配合事项才写。
- 意图需要时可增设章节，如「不做什么」（范围边界）、「成本与投入」、「上线与回退」——只要它帮助这位领导理解并认可这个决策。


## 核查清单（逐项自检）

- [ ] 汇报意图明确，且全文每个章节都服务于这个意图（无模板凑数章节，无该有而没有的章节）
- [ ] 一个不了解本仓库的领导通读全文，不需要问"这是什么"（术语首次出现均有解释或已入术语表）
- [ ] 术语表带固定锚点，每个术语在术语表后的首次出现处有一次跳回链接（非每处都链）
- [ ] 全文每个"因为/所以"的因，不查仓库就能理解（无内部细节直接当因）
- [ ] 正文零外部引用：无 ADR/EC 编号、无「见 TRD §x」指针、无代码路径行号、无文档对应关系附录
- [ ] 标题均为克制名词短语（决策小节可带结论）；无栏目腔、导览腔、括号解说词
- [ ] 正文无元叙述手脚架、无助手腔（「值得注意的是」「综上所述」等）、无 ✅❌ 当正文主力
- [ ] 全文是"讲清楚 + 同步已定方案"的语气，无"请拍板/待确认/待批准"类请示栏目，无实现讨论口吻，无「决策顺序/依赖关系」类章节
- [ ] 每个保留的决策都是战略级；每个决策都有选项表 + 明确最终选择；选项均来自源文档，未编造
- [ ] 每决策小节 ≤ 约 20 行；全文 ≤ 约 300 行
- [ ] 硬约束前置（如有），且每个"排除"结论都能挂到约束或读者已知的事实
- [ ] 数字/编号/清单/术语名称与 TRD/PRD 逐条一致，未自造新词（回查记录在工作区）
- [ ] 版本表新增一行，写明本次变更