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（过程记录，正文不留指针）。

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

执行流程

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

取材：定意图、圈边界

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

写初稿

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

派独立子代理核查

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

修订与交付

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

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

# <主题>关键决策

**文档类型**：技术战略决策报告（向领导汇报用）
**关联文档**：<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 逐条一致，未自造新词（回查记录在工作区）
• 版本表新增一行，写明本次变更