系统架构设计文档 Skill

本 skill 引导你以系统架构师视角，经过「结构化访谈 → 架构推理 → 文档产出 → 自检」四阶段，产出一份专业、严谨、可评审的架构设计文档（单一 Markdown 文件，中文）。

它不是模板填空器。模板填空只会产出"看起来完整但经不起追问"的文档。本 skill 的核心价值在于驱动结构化的架构推理：把模糊的业务诉求，逐步收敛为有据可依的架构决策与权衡。

核心原则（贯穿始终）

这些原则来自资深架构实践，理解它们比遵守条目更重要：

1. 不编造、有据可依：架构文档里每一个数字、QPS、延迟、容量、合规要求，要么来自用户/需求，要么是你基于公开事实的合理估算并明确标注为假设。绝不凭空捏造指标。拿不准时，明确写"待确认(假设值)"并列入风险。互联网检索首选官方文档/手册/blog，不采纳非官方自媒体。
2. 客观严谨、不偏向：技术选型与权衡要中立——对就是对、错就是错，不因用户偏好而美化某方案。被否决的方案也要如实写出其合理之处与被否决的真实理由。
3. 结构化决策：所有关键决策走 ADR（Architecture Decision Record），列出备选方案、各自优劣、决策标准，再给出结论与权衡。禁止"我们选择了 X 因为它最好"这类无论证结论。
4. 比需求多思考一步：不仅完成用户明确要求，还要主动识别隐含需求与影响范围——跨切面关注点（安全/可观测/数据一致性）、演进路径、容量规划、运维与回滚、团队拓扑（Conway 定律）等。

工作流总览

阶段1 结构化访谈  →  阶段2 架构推理  →  阶段3 文档产出  →  阶段4 自检
（收敛需求/约束）   （决策+权衡+C4视图）  （单一MD文件）     （对照清单核验）

用户给的信息往往不完整。先访谈、再产出——不要拿到一句话就开写文档。访谈是产出质量的前提，跳过访谈会导致文档充满臆测。

阶段 1：结构化访谈

目标：把用户的模糊诉求，收敛为可做架构推理的事实与约束。

读取 references/interview-protocol.md——它包含按主题分组的访谈问题清单（业务背景、规模与性能、数据与一致性、安全合规、运维与部署、团队与约束、演进与风险）。

访谈规则：

• 分批提问，不要一次抛 20 个问题。按主题分组，若运行环境提供 AskUserQuestion 或等效交互工具，优先用结构化选项呈现（≤4 题/次）；没有此类工具时，直接在对话中分批提问。保留开放回答入口，不强迫用户选择预设答案。用户也可能直接给出需求文档或口述，此时先提取已知信息，只针对缺口提问。
• 优先问"决定架构形态"的问题：核心场景与峰值规模、一致性要求（强一致/最终一致等）、延迟敏感度、数据量级与增长、可用性目标（几个 9）、合规约束（GDPR/等保/金融）、部署形态（公有云/私有化/混合）、团队规模与技能栈。
• 标注信息缺口：用户答不上来的，明确记为"假设值/待确认"，后续进入风险章节，不要静默编造。
• 收敛即可停止：当足以做出关键决策时停止追问，避免把访谈变成审讯。
• 非交互环境不阻塞：若处于无法获得用户回答的场景（自主/批量执行、无交互终端），不要卡在访谈环节--改为：从已有输入提取事实，把所有缺口转为显式假设（标注"假设值"），直接进入推理与产出，并把假设汇总到"假设与待确认项"。绝不因信息不全就编造指标，也绝不因信息不全就拒绝产出草稿。

访谈结束后，用 3-5 行向用户复述你理解的关键事实与约束，在可交互环境中请用户确认后再进入产出；非交互环境记录事实、假设与待确认项后继续产出草稿。这一步能避免大方向跑偏后返工。

阶段 2：架构推理（文档质量的真正来源）

这是最关键、也最容易被跳过的阶段。产出文档前，先在脑中（或简短笔记里）完成推理链条：

业务驱动 → 质量属性(NFR) → 架构约束 → 候选方案 → 决策(ADR) → 权衡 → C4视图

关键推理要点：

1. 由质量属性驱动架构：架构形态由 NFR 决定，不是由"流行技术"决定。先识别哪些质量属性是"驱动属性"（driving qualities）——是高并发？强一致？低延迟？快速迭代？审计追溯？可观测性？——再据此选型。读取 references/quality-attributes.md 获取完整 NFR 目录与典型权衡，避免遗漏跨切面关注点。
2. 每个关键决策走 ADR：列出 2-3 个真实备选方案（不是稻草人），客观比较，明确决策标准（对应到质量属性），给出结论与权衡。读取 references/adr-format.md 获取 ADR 模板与权衡写法。
3. C4 多视图：用上下文(Context)→容器(Container)→组件(Component)三层视图表达结构，每层回答不同受众的问题。Context 给业务方看边界与外部依赖；Container 给架构/运维看技术栈与部署单元；Component 给开发看模块划分。必要时补部署视图。
4. 显式权衡而非掩饰：每个决策都有代价。把代价写出来——复杂度增加、运维负担、新技术引入成本、一致性减弱等。诚实的权衡是文档可信度的核心。

阶段 3：文档产出

读取 references/document-template.md——这是完整的 10 章 + 附录模板，含每章的写法指引与示例。严格按此结构产出。

产出约定

• 单一 Markdown 文件，文件名：架构设计文档-<系统名>.md（如 架构设计文档-订单中心.md）。
• 中文。技术专有名词（如 Kafka、CQRS、Saga）保留英文原名。
• 图表用 Mermaid 内嵌：C4 视图、部署拓扑、时序图等用 ```mermaid 代码块内嵌，保证 MD 自包含、可在 GitHub/IDE 直接渲染。
• 需要精美视觉图时：若运行环境已安装 architecture-diagram 或等效绘图工具，可按用户需要生成独立 HTML/SVG 视觉图，并在 MD 中以链接引用。这是可选能力，本仓库不包含或依赖其他绘图 skill；没有相应工具时继续使用 Mermaid。日常技术评审用 Mermaid 即可。

写作要点

• 结论先行：每章开头用 1-2 句给出该章核心结论，再展开细节。读者能快速抓住要点。
• 可评审：关键决策都要能被追问"为什么不是 X"。文档要经得起架构评审委员会的拷问。
• 假设显式化：所有假设集中或在出现处标注，并汇总到"演进路径与风险"章。
• 量化优先于形容词：用"目标 P99 延迟 < 200ms、峰值 5万 QPS"而非"高性能"。拿不到准确数字时给估算区间并标注假设。

阶段 4：自检

产出后，对照以下清单核验（这步不能省，能拦下大量"看起来完整实则空洞"的问题）：

• 每条 NFR 都可验证——有量化指标或明确场景，而非"高可用""易扩展"等空话？
• 每个关键决策都有 ADR——含备选、决策标准、权衡，而非"选了 X 因为好"？
• C4 三层视图齐全且图与文一致——Context/Container/Component 都有，且文字描述与图相符？
• 无编造指标——所有数字要么有出处要么标注为假设？
• 跨切面未被遗漏——安全、可观测、数据一致性、容灾、容量规划都覆盖？
• 演进与风险——有容量演进判断、技术债、已知风险与缓解措施？
• 假设与待确认项已汇总，便于后续追踪？

自检发现缺失时，补全后再交付，不要把缺口留给读者。

参考文件索引

按需读取，不要一次性全部加载（渐进式披露，节省上下文）：

一句话总结

先访谈收敛事实，再由质量属性驱动推理与决策，最后产出经得起追问、假设显式、权衡诚实的单一 MD 文档，并自检补缺。这是本 skill 的全部要义。