system-design

系统设计（编排器）

将开放式设计问题从模糊的提示词推进到有理有据、经受压力测试的架构——**靠推理，而不是靠回忆图示。**此技能负责方法和路由；实际的组件方案则由它按需调用的专门构建模块技能提供。

最重要的理念，也是以下所有内容的出发点：

不要死记架构；要理解塑造架构的各种力量。不存在唯一正确的解决方案——成功取决于你明确说明的假设。

适用于 1,000 名用户的设计，可能无法应对 1,000,000 名用户。将每种架构都视为一个假设：它在约束条件发生变化前都成立；条件变化时，要做好冷静地重新绘制架构的准备。

推理循环

将这个循环的推理过程清楚地讲出来。这是一个循环，不是检查清单——后面的步骤经常会让你回到前面的步骤，这正是关键所在。

1. 明确需求——将模糊的提示词转化为功能需求、非功能性约束，以及明确的范围外事项。将范围限定在几个核心功能；并说明这一点。→ 技能 requirements-scoping
2. 估算规模——粗略估算 QPS、存储、带宽以及读写比例。数字决定设计；“流量很大”并不能。→ 技能 back-of-the-envelope
3. 提出高层设计——勾勒方框和箭头（客户端、LB、服务、存储、缓存、队列、CDN）以及面向用户的 API。深入细节前先取得认同。→ 技能 api-design，以及下方的构建模块。
4. 评估权衡——针对每个重大选择，说明它解决了什么、会恶化什么，以及什么情况会让你改变选择。提及工具时，必须说明这一点。→ 参考 tradeoff-framework.md
5. 压力测试故障模式——找出单点故障，决定降级方案，并制定恢复计划。假设每个组件都会出故障。→ 技能 resilience-failure
6. 迭代／深入探讨——选择最值得探讨或最脆弱的组件并深入分析；让新的约束（“如果写入量增加 10 倍呢？”“如果失去一个区域呢？”）推动受影响部分的重新设计。

这六个步骤对应 GUIDE 所说的四项活动——提出细化问题 → 处理数据 → 讨论组件 → 讨论权衡——同时将估算和故障测试明确列出。完整演练和时间分配请参阅 references/reasoning-loop.md。

按需调用构建模块

此插件是一套可组合部件的知识库。在讨论过程中，每当涉及某个问题，调用专门的技能（通过 Skill 工具），而不是凭记忆重新构建其方案——加载技能，让其中的选项、权衡表、压力下的行为以及云服务提供商变体直接呈现。这种调用方式就是运行时的组合：下面单独列出的技能名称表示要触发的技能，而不是要读取的文件。随着相关问题出现，逐一调用：

当问题涉及……	使用技能
有哪些功能 / 约束 / 范围？	requirements-scoping
需要多少 QPS、多少存储空间、多少台服务器？	back-of-the-envelope
端点、请求/响应、分页、幂等性	api-design
单体还是微服务、服务边界、网关、服务发现	service-decomposition
SQL 还是 NoSQL、架构、索引、分片、复制	data-storage
缓存什么、淘汰、失效、热点键	caching
流量分发、L4/L7、健康检查	load-balancing
异步工作、队列还是流、交付保证	messaging-streaming
CAP、一致性模型、仲裁、共识、哈希	consistency-coordination
容错、熔断器、降级、限流	resilience-failure
静态内容/媒体分发、边缘节点、地理路由	content-delivery
设计如何随着 10×/100× 的增长演进	scaling-evolution
客户端如何解析服务、地理/故障转移路由	dns
大规模生成唯一 ID（Snowflake/UUID/票据）	sequencer
存储大型/非结构化对象（图像、视频、文件）	blob-store
指标/日志/追踪、健康检查、SLO、告警	observability
大规模日志采集/传输/保留	distributed-logging
全文搜索、倒排索引、自动补全	distributed-search
后台 / 定时 / 周期性任务	task-scheduling
在极高写入速率下统计点赞/浏览量	sharded-counters
绘制/可视化架构	architecture-diagram

完整描述、自底向上的分层，以及“哪个构建模块回答哪个问题”，请参阅 references/building-blocks-index.md（规范的 21 个模块目录）。如果用户只询问其中某个部分，可直接触发相应模块——并非每个问题都需要协调器。

护栏：设计失败的方式

GUIDE 列出了十种失败模式。它们不是关于答案错误，而是关于信号错误。请牢记以下反应（完整列表及应对方法见 references/failure-modes.md）：

• 设计前先澄清。 急于给出方案，传递的是死记硬背的信号。
• 选择前先量化。 先把“流量很大”转换成具体数字。
• 为每个组件给出理由。 每项选择都要回答三个问题：解决什么 / 恶化什么 / 何时更换。“业界标准”不是理由。
• 展示构建模块的工作方式，而不是只说出名称。 了解缓存、队列或数据库在压力下的行为——而不只是它叫什么。
• 为故障而设计。 “增加更多重试”通常会加剧故障。
• 明确接口。 如果你写不出请求、响应和主键，图表就只是猜测。
• 把架构视为假设。 如果一个小小的约束变化就能让整个设计崩溃，那它就是死记硬背的，而非经过推理得出的。

协作，而非单方面讲解

设计讨论是协作环节，而不是讲座。提出方案、邀请批评，并实时调整。约束发生变化时，指出它使哪个先前假设失效，并重新设计相关部分——为已投入的设计辩护，比第一个想法有缺陷更能传递糟糕的信号。关于如何阐述思路、应对突发变化和调整方向，请参阅 references/collaboration-playbook.md。

如果需求确实含糊，而且答案会改变设计，请向用户提出澄清问题，而不是默默猜测。

输出设计方案

• 明确范围：填写 assets/requirements-template.md（功能需求 / 非功能需求 / 范围之外 / 假设）。
• 编写设计文档：使用 assets/design-doc-template.md——它贯穿整个推理循环，因此权衡取舍和失败情形都是核心内容，而非脚注。
• 绘制图表：使用插件内置的 architecture-diagram 技能——这是随插件提供的独立深色主题 HTML+SVG 生成器（无外部依赖）。早期构思时，快速画个 ASCII 草图即可；设计明确后，再正式生成图表。请参阅 references/diagramming.md，了解每个步骤要画什么，以及如何向该技能描述图表。
• 持久保存，确保成果在对话结束后仍然保留：将需求和设计文档写入文件（建议使用 docs/design/<system>.md；如果不确定，询问用户将文件保存在哪里）。将权衡探索和约束条件的来回讨论留在对话中；将已确定的成果（范围、设计、关键决策、数据模型、图表）提交到文件中。
• 评分与诊断：结束前，按照质量标准为设计评分，并运行 references/failure-modes.md 中的 Quick Diagnostic，然后指出最薄弱的维度，以及如何提升它。

回复要求

用户看到的内容必须展示推理过程，而不只是包含推理结果。每份设计答复（首次设计或修订）都必须在回复中包含：

• 决策表——每个主要选择占一行（完整设计至少包含三个选择）：决策 | 解决的问题 | 带来的问题 | 何时改变……。最后一列必须是具体触发条件，即数字或可观察的信号（例如“单个分片的写入 QPS > 50k”“第二个团队需要独立部署”），不能写“需要时”。
• 结尾指出最薄弱环节——说明随着负载或需求增长，设计中哪部分会最先出现问题，以及届时会采取什么措施。

仅列出优缺点，或只讨论一个选择的权衡，均不符合要求。

将其作为工作流运行

两个入口可将此技能作为可重复流程运行：

• /design <system>——运行完整问题处理流程的斜杠命令。
• system-design-orchestrator——由该命令调度的 Agent；它会加载此技能，然后根据具体问题调用各个构建块技能。

两者都会组合使用上文列出的相同模块——在相关问题出现时调用对应的模块技能，而不是凭记忆重新构建其流程。

参考资料

• references/reasoning-loop.md——深入介绍六步循环，包含新闻动态信息流示例和 45 分钟的时间预算。运行完整设计流程时请阅读。
• references/failure-modes.md——介绍十种失败模式及其应对方法。请阅读以自查设计，或诊断设计为何未能奏效。
• references/tradeoff-framework.md——介绍解决问题 / 带来问题 / 何时改变的方法，以及常见维度间的权衡（延迟↔吞吐量、一致性↔可用性、成本↔复杂性）。请在步骤 4 阅读。
• references/building-blocks-index.md——完整的 Wiki 索引：列出每个模块、它解决的问题，以及模块如何组合。请阅读以确定调用路径。
• references/collaboration-playbook.md——介绍如何讲解推理、应对突发状况，以及在约束变化时调整方向。讨论出现对抗性时请阅读。
• references/diagramming.md——介绍每个循环步骤要画什么，以及如何向 architecture-diagram 技能描述图表。绘图时请阅读。
• references/worked-example-news-feed.md——完整展示一次循环流程，并以推理过程呈现（不是供人死记硬背的模板）。

资源

• assets/requirements-template.md——用于记录功能需求 / 非功能需求 / 范围 / 假设。
• assets/design-doc-template.md——按照推理循环组织设计文档。