跳到主要内容

第N节 — <章节标题>

这一节回答：<一句话，明确本节解决什么实施者疑问 — 如不写这句，本节不该存在>

<小节 1 标题>​

<内容>

<子小节>（如需要）​

<内容>

关于图（如本节含图）​

这张图表达什么：<2-3 句>

这张图特意不表达什么：<2-3 句 — 防止读者误推>

怎么读这张图：<2-3 句 — 必要时给方向 / 节点含义 / 边的语义>

<小节 2 标题>​

<内容>

与其他章节的关系​

  • <概念 / 决策 / 流程> → CHAP- <章节名>
  • <概念 / 决策 / 流程> → CHAP- <章节名>
  • <概念 / 决策 / 流程> → ADR-

章节写作纪律（来自 commons/playbooks/architecture-document-rewrite.md）：

  • 内容 > 形式：每个段落 / 表格 / 图服务实施者具体疑问，不为模板齐整堆砌
  • 建设型而非防御型：重点说"是什么 / 做什么 / 怎么做"，不变成"不许什么 / 不是什么"清单
  • 不解释方法论：方法论选择放 ADR，主架构文档只引结论
  • 抽象 vs 具体：优先用项目实际场景说明，少用"系统应该 / 工程上应当"
  • 图配三段说明：图表达什么 / 图特意不表达什么 / 怎么读这张图
  • 专有名词第一次出现给一句话解释
  • 不堆术语：能用普通中文表达的不用英文缩写
  • "与其他章节的关系"段在每章末尾必须有（即使只有 2-3 条）

频繁出错的反模式：

  • 把方法论评分对比写进主文档（搬到 ADR）
  • 把"什么是好的设计"的方法论展开（删除，只列结论）
  • 防御型清单超过半页（建设型重写）
  • 图节点 label 含双引号（Mermaid 解析错误 — 用单引号或去引号）
  • 跨章引用用相对路径（用 §N 形式）