knowledge-work-plugins 的 system-design Skill 实战：用五步框架驱动可靠的系统架构设计

knowledge-work-plugins 的 system-design Skill 实战：用五步框架驱动可靠的系统架构设计

【免费下载链接】knowledge-work-pluginsOpen source repository of plugins primarily intended for knowledge workers to use in Claude Cowork项目地址: https://gitcode.com/GitHub_Trending/kn/knowledge-work-plugins

在 knowledge-work-plugins 仓库的 engineering 插件 中，system-design是一个面向系统与架构设计场景的领域技能（Skill）：当工程师需要设计新系统、评估架构选型、梳理服务边界或进行 API 与数据建模时，它提供一套可复用的结构化思维框架。读完本文，你将掌握该 Skill 内置的五步设计流程——从需求收集、高层设计、深入设计、扩展与可靠性，到权衡分析——并理解它如何与/architecture命令、ADR 格式及 MCP 连接器配合，把一次模糊的"帮我设计个系统"请求，收敛成一份清晰、可评审、可落地的架构设计文档。

system-design 在 engineering 插件中的定位与触发方式

system-design是 engineering 插件七大领域技能之一，其元信息定义在 engineering/skills/system-design/SKILL.md 的文件头（Front Matter）中：

name: system-design description: Design systems, services, and architectures. Trigger with "design a system for", "how should we architect", "system design for", "what's the right architecture for", or when the user needs help with API design, data modeling, or service boundaries.

从这段描述可以看出两个关键设计意图：

1. 自动触发机制：技能无需手动调用。当对话中出现 "design a system for"、"how should we architect"、"system design for"、"what's the right architecture for" 等措辞，或涉及 API 设计、数据建模、服务边界等话题时，Claude 会自动加载该技能的知识。这与仓库根 README.md 中"Skills fire when relevant"的插件运行机制一致——技能（Skills）编码领域专长与最佳实践，是 Claude 在相关场景自动调用的知识库，而非需要显式执行的命令。
2. 分工协作：system-design负责提供"方法论框架"（即本文要展开的五步流程），而 architecture 技能负责"产出一份 ADR 或评审设计"，后者在文档中明确写到："See thesystem-designskill for detailed frameworks on requirements gathering, scalability analysis, and trade-off evaluation." 也就是说，system-design是思考方法，architecture是产出物格式，两者配套使用。

工程插件本身遵循"Standalone + Supercharged"的使用哲学（见 engineering/README.md）：即使不连接任何外部工具，你也可以用自然语言描述系统现状、粘贴代码或上传文件来使用该技能；接入 MCP 连接器后（如知识库、项目跟踪器），设计过程还能自动检索历史 ADR、关联史诗与工单，详见 CONNECTORS.md 中的~~knowledge base、~~project tracker等类别占位符约定。

框架总览：五步设计流程

system-design的核心是一条从模糊需求到可评审设计的线性主线，每一步都有明确的关注点：

五个步骤的次序本身就有方法论含义：先界定"要解决什么问题"，再给"宏观骨架"，然后"深入关键部件"，接着"验证能否扛住规模与故障"，最后"显式承认每个决策的代价"。下面逐一展开，并结合 engineering 插件中相邻技能（ADR 格式、测试策略、技术债管理）说明如何在实践中落地。

第一步：需求收集——先锁定"做什么"与"做到什么程度"

设计系统最昂贵的错误，是给错误的系统做了正确的架构。第一步要求把三类信息完全显式化：

• 功能需求（Functional requirements）：系统"做什么"。例如：用户能上传 CSV 并触发异步处理；管理员能查看处理进度；系统能导出结果文件。功能需求应当是可以被验收测试逐条覆盖的行为清单。
• 非功能需求（Non-functional requirements）：规模、延迟、可用性、成本。例如：峰值 10K QPS、P99 延迟 < 500ms、可用性 99.9%、月度基础设施预算上限。非功能需求直接决定后续扩展与可靠性章节的取舍方向。
• 约束（Constraints）：团队规模、时间线、现有技术栈。例如：团队只有 4 名后端工程师、必须在 2 周内上线、公司已有 PostgreSQL 与 Kafka 运维能力。约束是权衡分析的"硬边界"，后面会看到它如何塑造答案。

从源码结构看，engineering 插件把"约束先行"沉淀为跨技能的通用技巧：architecture 技能的 Tips 第 1 条就是 "State constraints upfront— 'We need to ship in 2 weeks' or 'Must handle 10K rps' shapes the answer"，第 3 条则是 "Include non-functional requirements— Latency, cost, team expertise, and maintenance burden matter as much as features"（见 architecture/SKILL.md）。这与 system-design 第一步的要素完全同构，说明需求收集不只是"列清单"，而是要让约束和 NFR 成为后续所有设计的输入变量。

第二步：高层设计——先给骨架，再谈细节

高层设计的目标是在 30 分钟内画出系统的"一张总图"，包含四类产物：

• 组件图（Component diagram）：系统由哪些服务/模块组成，彼此如何调用。可以用 ASCII 图，也可以用一段结构化文字描述，关键是组件边界要清晰。
• 数据流（Data flow）：一条请求从进入系统到完成，经过哪些组件、转换哪些数据。数据流分析往往能暴露循环依赖、热点路径与不必要的串行环节。
• API 契约（API contracts）：组件之间、系统对外暴露的接口形态。契约先行可以防止"各自实现、联调爆炸"。
• 存储选择（Storage choices）：每个数据集的存储引擎及其理由——关系型数据库保证事务、NoSQL 换取水平扩展、对象存储承载大文件、缓存加速读路径等。

这个阶段刻意"只画骨架不钻细节"，是因为骨架阶段的错误（例如把本应异步的流程设计成同步调用）修正成本远高于细节阶段的错误。如果你希望这层设计被正式记录下来，可以交给 architecture 技能，它会以 ADR 的## Context章节承载"现状与受力分析"。

第三步：深入设计——把骨架上的每个关键部件做实

高层设计确定"有哪些部件"，深入设计则要回答"每个部件内部怎么实现"。system-design列出的深入设计关注点覆盖了分布式系统最常见的五个决策维度：

数据模型设计（Data model design）

确定实体、关系、主键与外键策略、索引设计、以及数据生命周期（保留期、归档、清理）。数据模型的改动往往牵一发动全身，因此需要在深入设计阶段就与存储选择（第二步）交叉验证——例如高写入的时序数据放在 PostgreSQL 中可能需要分区表方案。

API 端点设计（REST、GraphQL、gRPC）

选择 API 风格本身就是一次权衡：REST 通用性好、缓存与治理生态成熟；GraphQL 让客户端按需取字段、减少 over-fetching，但引入查询复杂度控制难题；gRPC 在内部服务间提供强类型契约与高性能二进制传输，代价是调试与浏览器端兼容性成本。深入设计需要明确：哪些端点服务于外部客户端（重 REST 语义、版本策略、分页与限流），哪些是内部服务调用（重契约与性能）。

缓存策略（Caching strategy）

回答四个问题：缓存什么（读多写少的数据）、缓存在哪一层（CDN / 网关 / 应用内 / 分布式缓存）、失效策略是什么（TTL、主动失效、写穿透）、缓存击穿/雪崩时如何兜底。缓存是典型的"带来数量级收益、也带来一致性复杂度"的决策，必须在权衡分析章节显式记账。

队列/事件设计（Queue/event design）

识别可以异步化的路径（邮件通知、报表生成、第三方回调、削峰），选择队列或事件总线（如 Kafka、SQS），并明确消息语义（at-least-once 还是 exactly-once、重试与死信队列、事件 Schema 演进）。这一步与第一步的非功能需求强相关：如果对峰值延迟有硬性要求，异步解耦往往是必选项。

错误处理与重试逻辑（Error handling and retry logic）

明确每种失败模式的应对：瞬时故障（指数退避 + 抖动重试）、持久故障（进入死信队列人工介入）、超时策略（客户端超时 + 服务端 deadline）、幂等性（幂等键，避免重试造成重复副作用）。错误处理是"系统在故障下的行为"，它与第四步的可靠性设计直接衔接。

第四步：规模与可靠性——验证设计能否扛住负载与故障

深入设计解决"能不能跑"，这一步解决"跑得快不快、挂了会不会瘫"：

• 负载估算（Load estimation）：由第一步的规模类 NFR 推导出吞吐、存储、带宽、连接数等量化指标，并给出估算公式与假设（例如日均请求 → 峰值系数 → QPS，单条记录大小 → 年存储量）。估算的价值不在精确，而在"给容量决策一个可追溯的推导链"。
• 水平扩展 vs 垂直扩展（Horizontal vs. vertical scaling）：垂直扩展（升级单机配置）简单但存在上限与成本拐点；水平扩展（增加实例）需要无状态化设计、数据分片与路由。设计文档应说明当前阶段选择哪种，以及触发切换的信号。
• 故障转移与冗余（Failover and redundancy）：消除单点——数据库主从与自动切换、多可用区部署、无状态服务多副本、依赖降级与熔断。要显式写出"哪个组件挂了会发生什么、流量如何转移、恢复时间目标是多少"。
• 监控与告警（Monitoring and alerting）：定义黄金信号（错误率、延迟、流量、饱和度）与业务关键指标，设定告警阈值与升级路径。监控不是上线后的补充工作，而是设计阶段的产物——deploy-checklist 技能中"Rollback Triggers"一节（如 Error rate exceeds [X]%、P50 latency exceeds [X]ms）正是把监控阈值前置到发布流程的体现。

第五步：权衡分析——把每个决策的代价显式化

system-design对这一步的要求只有一条，但分量最重："Every decision has trade-offs. Make them explicit."（每个决策都有代价，把它显式化）。推荐的审视维度是五选：

• 复杂度（Complexity）：引入分布式事务、缓存、事件总线的运维与心智负担
• 成本（Cost）：基础设施、人力、时间成本
• 团队熟悉度（Team familiarity）：用团队没掌握的技术栈，隐性风险是交付速度与质量
• 上市时间（Time to market）：先交付再演进 vs 一步到位
• 可维护性（Maintainability）：未来的排障、变更与扩展成本

从 architecture/SKILL.md 的 ADR 输出模板可以看到，这套权衡维度已被固化为可填写的评估表：每个候选方案（Option A / Option B...）都要在 Complexity、Cost、Scalability、Team familiarity 等维度上给出 Low/Med/High 或定性评估，并分别列出 Pros/Cons，最后以## Trade-off Analysis章节给出"选项之间的关键取舍与清晰理由"，以## Consequences明确"什么变容易、什么变难、未来需要重新审视什么"。这正是 system-design 第五步在产出物层面的直接体现。

输出规范：一份可评审的系统设计文档长什么样

system-design对最终产出有明确约束——"Produce clear, structured design documents with diagrams (ASCII or described), explicit assumptions, and trade-off analysis. Always identify what you'd revisit as the system grows."（产出清晰、结构化的设计文档，附图表（ASCII 或文字描述）、显式假设与权衡分析，并始终指出随系统增长需要重新审视的点）。拆解开来是四类必含元素：

1. 图表（ASCII 或文字描述）：组件图、时序/数据流图不必依赖绘图工具，ASCII 图或分点描述同样满足要求，关键是让读者无需脑补就能理解拓扑与调用关系。
2. 显式假设（Explicit assumptions）：负载估算用了什么系数、假设了怎样的流量模型、默认了哪些现有组件可用。假设越显式，评审越容易提出"假设不成立怎么办"的有效质疑。
3. 权衡分析：每个关键决策（存储选型、同步 vs 异步、缓存方案、扩展方式）都要有"为什么选它 / 放弃了什么"的记录，而不是只写结论。
4. 增长重访清单（What to revisit as the system grows）：明确写下"当数据量达到 X 时需要重新评估分片方案""当 QPS 超过 Y 时需要引入缓存层"这类触发器。这使设计文档从"一次性快照"变成"可持续演进的路线图"，也与 tech-debt 技能中把架构债（如"Monolith that should be split, wrong data store"）显式登记、按 Impact/Risk/Effort 打分排期的理念一脉相承——设计时预留的重访点，正是未来技术债清单的早期来源。

与相邻技能配合：一个完整的架构决策工作流

把 engineering 插件内的技能串联起来，可以得到一个从问题到落地的完整工作流：

1. system-design（本文主题）：按五步框架把需求收敛成高层设计、深入设计与权衡分析；
2. architecture：将关键决策固化为 ADR——支持三种模式（创建 ADR / 评审现有设计 / 全新系统设计），产出含 Status、Options Considered 评估表、Trade-off Analysis、Consequences 与 Action Items 的结构化文档；
3. testing-strategy：按测试金字塔为设计中的组件分层制定测试计划——API 端点做业务逻辑单元测试 + HTTP 层集成测试 + 消费者契约测试，数据管道补输入校验、转换正确性与幂等性测试；
4. tech-debt：把设计中"未来重访点"和"妥协方案"登记为技术债，按Priority = (Impact + Risk) × (6 - Effort)排序，安排在与特性开发并行的节奏里偿还。

若已接入 MCP 连接器，architecture 技能还会自动检索知识库中的历史 ADR 与设计文档、在项目跟踪器中关联史诗与工单（详见 CONNECTORS.md 中~~knowledge base、~~project tracker两类占位符的说明），使设计过程与团队既有资产打通。

使用建议：让每次设计会话更有效

综合system-design框架本身与 engineering 插件各技能的通用技巧，实践中建议做到三点：

1. 把约束与非功能需求写在最前面：一句"2 周内上线"或"必须扛住 10K rps"就能让后续所有方案收敛，避免为不存在的高并发设计过度复杂的架构。
2. 永远给出候选方案而非单个答案：即使你已有倾向，也要显式命名至少两个选项并逐维评估——"更平衡的分析"通常能暴露你未考虑的代价（见 architecture/SKILL.md 的 Tips）。
3. 让"重访清单"成为设计文档的固定章节：它既服务当下的评审，也为未来的技术债管理和容量规划留下可执行的触发器，让设计文档在系统增长后依然保持价值。

对于希望把该技能接入自己工程工作流的团队，直接查看本仓库 engineering/skills/system-design/SKILL.md 原文，并结合 architecture 的 ADR 模板与 engineering/README.md 的安装说明（claude plugins add knowledge-work-plugins/engineering）即可快速上手——无需任何代码或构建步骤，整个插件体系都是纯 Markdown 与 JSON 文件。

【免费下载链接】knowledge-work-pluginsOpen source repository of plugins primarily intended for knowledge workers to use in Claude Cowork项目地址: https://gitcode.com/GitHub_Trending/kn/knowledge-work-plugins