用途
该技能用于为工程团队撰写或重写架构子系统文档、ADR（架构决策记录）以及参考资料。适用场景包括在 docs/architecture docs/subsystems/ 等目录下创建、更新或审阅文档。
目标读者
仓库中的架构文档服务两类读者：正在开发该系统的团队成员（需要精确的参考材料）以及寻求背景信息的团队成员（需要易于理解的叙述）。文档必须同时满足两者，且不要求读者具备项目既有上下文。
写作前准备
- 阅读同一目录下至少两篇同类文档（例如 docs/architecture docs/subsystems/ 下的其他子系统文档），据此校准语气、结构与细节程度。
- 阅读将要引用的 ADR。不要只是链接它们——要理解到足以在正文中内联概括其核心思想，使读者无需跳转链接即可理解文档。
语气与框架
- 描述系统，而非项目。这些文档描述我们所知的预期系统，不是项目回顾、冲刺总结或 PoC 报告。
- 陈述事实：例如“执行管线在各数据族之间通用”，而非“PoC 验证了执行管线可以通用”。
- 避免临时性项目引用：不要使用“工作流”“PoC”“冲刺”“里程碑”“正在验证”“当前工作”等表述。
- 不做产品对比：不要引用其他产品或先前版本。描述系统是什么，而非它改进了什么。
- 非目标属于架构边界，而非“尚未完成”的事项。不要加“（当前）”之类的限定词。
- 面向没有先前上下文的开发者写作。设想一位新加入团队的成员把这篇文档作为接触该系统这一部分的首次阅读材料。
- 先讲原因，再讲内容。在引入“模型归属”这类概念前，先解释它解决的问题，例如：“在 SQL 中，相关数据存放在不同的表里，在查询时进行连接。在 MongoDB 中，惯用模式是把相关数据存储在父文档内部。”
- 让概念有呼吸空间。不要把三个概念压缩进一句话。如果一句话需要读者已经理解三件事才能解析，就把它拆开。
- 使用具体示例——代码片段、JSON 片段、“开发者写 X 时底层得到 Y”。抽象描述难以锚定理解。
结构
- 以锚定示例开头。在文档靠前位置（概述之后）放置一个具体、完整的代码片段、JSON 示例或图示，让读者在阅读时有一个可视参照来锚定理解。用简短标注预览关键概念（例如“注意 storage: {} 表示该模型是内嵌的”）。后续详细章节再展开读者已经看到的内容。
- 尽早阐明设计原则。如果子系统的设计由一组原则或不变量塑造，在锚定示例之后、详细章节之前明确陈述它们。这为读者提供理解具体决策背后理由的推理框架。每条原则用一两句平实语言，不用术语。后续章节可用编号引用原则（例如“见设计原则 #5”），把具体决策与其理由关联起来。
- 叙事流。引导读者从一个概念走向下一个概念。不要先列出一组问题再单独列出一组解决方案——把每个问题与其解决方案配对，让读者逐步建立理解。
- 概述章节。用平实语言开头，说明系统这一部分是什么以及为何存在。第一句话应能被任何工程师立即理解。技术细节留到后续章节。
- 好：“Prisma Next 支持多个数据库族。SQL 是第一个；MongoDB 是第二个。”
- 差：“MongoDB 是 Prisma Next 中的一个数据库族。契约、ORM、执行管线和插件框架都在根本不同的数据模型之间通用——相同的 ContractBase 领域结构、相同的 Collection 链式 API 和相同的插件生命周期对 SQL 和 MongoDB 都适用。”
- 内联概括并附 ADR 链接。引用 ADR 时，在正文中概括其核心思想并附上链接以供深入阅读。文档应无需点击任何链接即可理解。
- 好：“归属模型声明 owner: "User"——这是关于聚合成员关系的领域事实。其数据存放在所有者存储内。见 ADR 177。”
- 差：“关于内嵌如何工作，见 ADR 177。”
- 参考资料章节。按持久性组织：
- 架构决策（ADR）——最先
- 持久参考材料——其次
- 历史背景（规划文档）——最后，并标注为历史资料
反模式
- 压缩式摘要。读起来像把项目符号列表塞进散文的段落。如果要列举，就用列表。
- 未加介绍的术语。不要使用“聚合根”“判别器收窄”或“STI”等术语而不解释其在上下文中的含义。
- 以 ADR 代替解释。指向 ADR 而不解释概念。ADR 链接用于深入阅读；文档必须能独立成立。
- 项目过程叙述。“我们构建了 X，然后发现 Y，进而导致 Z。”描述系统是什么，而非我们如何到达这里。
- 简略概述加详细正文。概述应是文档中最易理解的部分，而非最压缩的部分。
质量检查
完成前，以从未见过该文档的开发者视角重读全文。对每一段自问：
- 我能否在不依赖本文档之外上下文的情况下理解它？
- 它是否先讲原因再讲内容？
- 这里加一个具体示例会有帮助吗？
- 我是在陈述关于系统的事实，还是在叙述项目？