software-architecture-design

软件架构设计

如果问题从业务工作流、系统格局、目标状态或分阶段跨系统迁移入手，请先使用 ../software-solution-architecture/SKILL.md，再到这里深入了解运行时、分解和可运维性。

将系统资产现代化、平台工程和 AI 原生互操作性视为可选的深入主题。只有在用户明确提出相关需求时，才加载这些内容。

快速参考

任务	模式/工具	关键资源	适用场景
选择架构风格	模块化单体（默认；参见下方的决策因素）；明确独立部署/所有权需求后，再考虑分层、微服务、事件驱动或无服务器架构	modern-patterns.md	全新项目、大型重构
决定 API 边界策略（架构层面）	契约策略和版本控制策略，而非端点设计	api-gateway-service-mesh.md	服务间契约决策属于架构决策
设计可扩展性	负载均衡、缓存、分片、只读副本	scalability-reliability-guide.md	高流量系统、性能目标
确保弹性	断路器、重试、舱壁、优雅降级	scalability-reliability-guide.md	分布式系统、外部依赖
记录决策	架构决策记录（ADR）	adr-template.md	重大技术决策、权衡分析
定义服务边界	领域驱动设计（DDD）、限界上下文	microservices-template.md	微服务分解
建模数据一致性	ACID 与 BASE、事件溯源、CQRS、Saga 模式	data-architecture-patterns.md	多服务事务
规划可观测性	SLI/SLO/SLA、分布式追踪、指标、日志	architecture-blueprint.md	生产就绪
从单体迁移	绞杀者无花果模式、数据库分解、影子流量	migration-modernization-guide.md	遗留系统现代化
设计服务间通信	API 网关、服务网格、BFF 模式	api-gateway-service-mesh.md	微服务网络
设计交付平台	IDP、黄金路径、适应度函数	fitness-functions-governance.md	多团队平台、治理
精简服务蔓延	限界上下文平台、仓库与运行时矩阵、平台评分卡	estate-modernization.md	20 个以上仓库、服务过多、平台成熟度参差不齐
规划系统资产现代化	平台优先的迁移批次、整合、兼容性边界	estate-modernization-blueprint.md	多仓库系统资产、受监管的迁移、遗留系统精简
设计 AI 原生系统	RAG 边界、工具网关、Agent 互操作性、MCP、A2A	architecture-trends.md	由大模型驱动的产品，且主要问题在于架构而非实现

不应使用此技能的情况

以下情况请改用其他技能：

• 跨系统解决方案设计（业务流程、目标状态、集成版图、跨系统分阶段转型）→ software-solution-architecture
• 单个服务的实现（路由、控制器、业务逻辑）→ software-backend
• API 端点设计（REST 规范、GraphQL 架构）→ dev-api-design
• 安全实现（身份验证、加密、OWASP）→ software-security-appsec
• 前端组件架构 → software-frontend
• 数据库查询优化 → data-sql-optimization
• Agent 工作流实现 / MCP 服务实现 → ai-agents、agents-mcp

边界规则

• 此技能负责运行时边界、可部署单元的决策、数据一致性权衡、弹性机制内部实现及平台默认设置。
• 从满足约束条件的最简单架构着手；没有明确证据时，不要默认采用微服务、事件溯源、服务网格或多 Agent 拆分。
• 如果尚未解决的问题仍是“哪些系统参与其中、哪个系统是记录系统，或目标状态的系统版图是什么？”，请转回 software-solution-architecture。
• 如果尚未解决的问题涉及 Agent 协议、工具服务端或特定运行时集成的实现，请转至 ai-agents 或 agents-mcp。
• 迁移边界：此技能负责在单个系统内部进行抽取或拆分的具体机制——绞杀者模式步骤、数据库拆分、影子流量（migration-modernization-guide.md、estate-modernization.md）。它不负责跨系统的迁移波次计划（哪些系统共存、按什么顺序进行，以及采用哪些回滚 / 退役标准）——这属于 ../software-solution-architecture/SKILL.md 的 transition-architecture.md。

决策树：选择架构模式

Primary question: [What kind of architecture problem is this?]
    ├─ Large estate with many repos/services and rising cognitive load?
    │   ├─ Runtime count is the main problem → Bounded-context platforms + selective consolidation
    │   ├─ Delivery inconsistency is the main problem → IDP + golden paths + scorecards
    │   └─ Both are true → Platform-first modernization, then consolidate low-value runtime units
    │
    ├─ Deterministic workflow, known steps?
    │   ├─ Single deployable acceptable → Modular Monolith
    │   ├─ Independent teams/capabilities required → Sequential or event-driven services
    │   └─ Burst-driven or edge-triggered workload → Serverless / event-driven
    │
    ├─ Adaptive workflow with tool use and reasoning?
    │   ├─ One agent can own the task → Single-agent system
    │   ├─ Specialized roles truly needed → Multi-agent with explicit stop conditions
    │   └─ High stakes / regulated workflow → Human-in-the-loop + audit trail
    │
    ├─ Strong consistency inside one domain boundary?
    │   ├─ Keep data and writes together → Monolith or Modular Monolith
    │   └─ Split only at stable bounded contexts → Microservices with owned data
    │
    └─ Need platform-level consistency across many teams?
        ├─ Repeated service creation / compliance needs → IDP + golden paths
        └─ Cross-agent or cross-vendor interoperability → MCP for tools/context, A2A for agent-to-agent

决策因素：

• 默认取向：除非独立部署、所有权和可运维性方面的优势明确，否则优先选择模块化单体，而非微服务——请参阅 modern-patterns.md § 模块化单体与微服务 中明确的团队规模、发布节奏和运维成熟度门槛
• 系统群取向：优先减少运行时单元，而非减少仓库；仓库是协作单元，运行时是运维成本中心
• Agent 取向：引入多 Agent 协调之前，优先考虑确定性工作流或单个 Agent
• 连接性取向：在 mTLS、流量策略或共享遥测需求足以证明网格复杂性合理之前，优先采用网关加应用库模式
• 团队结构（康威定律）——架构映射组织结构
• 部署独立性需求
• 一致性和故障域边界
• 运维成熟度（监控、编排）
• 互操作性需求（协议、契约、外部系统）

拆分位置：断裂面（Skelton 和 Pais，《Team Topologies》，第 2 版，2025 年）。断裂面是“软件系统中的自然接缝，可让系统轻松拆分成两个或更多部分”——这是石匠的比喻。候选断裂面包括：业务领域限界上下文（默认选择，也是大多数拆分应对应的断裂面）、法规合规性、变更节奏、团队位置、风险、性能隔离、技术和用户画像。

• 试金石，原文引用：“最终架构是否支持更自主的团队（依赖更少的团队），并降低认知负担（职责分散程度更低）？”具体来说：拆分之后，每个团队能否在不与其他团队协调的情况下构建、测试和部署自己的部分？
• 组合规则：实际边界通常结合多个断裂面——“我们可以也应该通过组合不同类型的断裂面来拆解单体”，并且“通常需要组合多个断裂面”。
• 分布式单体警示：拆分软件却不让边界与团队及其发布路径保持一致，只会带来分布式成本，却没有任何自主性。书中引用 Amy Phillips 的话：“如果你有微服务，但发布前要等待对它们的组合进行端到端测试，那么你拥有的就是一个分布式单体。”耦合也会渗透到服务边界之下——共享数据库、耦合的构建和发布。
• 让软件分段与团队规模相匹配：“必须让软件分段与团队规模相匹配，这样团队才能有效地拥有并以可持续的方式演进其软件。”

详细的模式说明请参阅 references/modern-patterns.md；要检查建议的接缝是否会让强耦合跨越边界，请参阅 references/modern-patterns.md § 共因性。

输出指南

此技能中的参考资料是供你吸收并融会贯通的背景知识。请将其中的模式转化为自己的专业知识来呈现。不要在面向用户的输出中引用内部参考文件名（例如，“来自 data-architecture-patterns.md”）。用户并不知道这些文件的存在。

每项架构建议都必须涵盖以下内容；只有明确说明理由时，才能跳过某项：

• 足够简单的拓扑 — 说明满足需求的最简单架构
• 具体技术选型 — 指明具体技术（例如，“使用 Temporal.io 进行工作流编排”，而不只是“使用编排器”）
• 推荐方案 + 被否决的替代方案 — 说明考虑过哪些方案，以及替代方案落选的原因
• 不应构建的内容 — 明确推迟或排除尚不成熟的范围
• 团队与流程对齐 — CODEOWNERS、部署职责、值班边界
• 代码仓库与运行时模型 — 对于多仓库体系，区分仓库数量与可部署单元数量
• 可运维性模型 — 部署拓扑、故障域、回滚点、SLO 归属、事件边界
• 迁移路径 — 步骤安排、切换策略、可逆性（适用于重构或新子系统）
• 关键风险与故障模式 — 指出明确的故障点，以及如何尽早发现
• 成功指标 — 服务 SLO，以及相关的 DORA 五项交付指标：部署频率、变更前置时间、部署失败恢复时间、变更失败率和部署返工率；分别与各自的基线进行比较

工作流（系统级）

当用户请求架构建议、分解方案或重大平台决策时，使用此工作流。

1. 澄清：问题陈述、非目标、约束和成功指标
2. 梳理质量属性：可用性、延迟、吞吐量、持久性、一致性、安全性、合规性、成本
3. 判断工作负载类型：确定性工作流、单 Agent 或多 Agent；同步还是异步
4. 提出 2–3 个候选架构，并比较权衡
5. 优先采用满足需求的最简单可行拓扑，再论证采用更分布式模式的理由
6. 对于包含 20 个以上仓库的体系，将每个仓库归类为运行时、适配器、库、渠道、平台、工具或待吸收项
7. 明确边界：限界上下文、所有权、API/事件、协议契约、互操作需求
8. 确定数据策略：存储、一致性模型、模式演进、迁移
9. 面向运维进行设计：SLO、故障模式、可观测性、部署、灾难恢复、事件处理手册
10. 设计治理与安全机制：策略执行、可审计性、评估门禁、回滚控制
11. 明确范围限制：目前不应构建的内容、需要推迟的事项，以及购买还是自建
12. 记录决策：当某项选择会改变可部署边界、一致性或故障模型、平台契约，或难以逆转且成本高昂的约束时，编写 ADR。在ADR 模板中记录背景、选项、后果、负责人和替代链接；MADR 是一种精简格式。对于局部实现选择，使用更轻量的记录。

推荐交付物（根据请求选择合适的内容）：

• 架构蓝图：assets/planning/architecture-blueprint.md
• 体系现代化蓝图：assets/planning/estate-modernization-blueprint.md
• 决策记录：assets/planning/adr-template.md
• 模式深入解析：references/modern-patterns.md、references/scalability-reliability-guide.md

决策证据关卡

对于每个拟议的边界或新部署单元，明确指出其必要性所基于的实际压力：独立的发布节奏、不同的扩缩容模式、故障隔离、数据主权或所有权独立。记录基线，以及能够证伪这一选择的实验。如果这种压力只是设想，或者可以在现有运行时中处理，就让边界保持逻辑上的划分，并推迟运营层面的拆分。

已知陷阱

• 仅仅因为现有代码库很多就选择微服务，尽管真正的问题是运行时泛滥和所有权不明。
• 绘制目标状态图，却没有迁移顺序、回滚边界，或新旧路径之间的兼容性方案。
• 在所有权、值班和部署权限尚未准备好应对额外工作面的情况下，就拆分领域。
• 尚未确定哪些路径确实需要解耦，就在每个边界引入异步和事件驱动工作流。
• 黄金路径仍是可选的、不一致的或缺乏明确负责方时，却称之为平台工程。

常见反模式

• 将可部署服务作为默认的拆分单位，而非有界上下文、团队所有权和运营成本。
• 将超大规模云服务商或供应商的参考架构照搬到不具备同等规模、工具或平台人员配置的团队中。
• 为当前吞吐量、故障、合规和变更管理约束之外的潜在未来高峰需求进行设计。
• 明知每个代码库和运行时都会带来协调与治理成本，却仍以它们各自“有点价值”为由全部保留。
• 将“现代”等同于“更加分布式”，将“AI 原生”等同于“默认采用多 Agent”。

导航

核心参考资料

每个问题最多阅读 2–3 份参考资料——选择与具体问题最相关的资料。不要全部阅读。

参考资料	内容	何时阅读
modern-patterns.md	架构模式与决策树，包括模块化单体与微服务的决策关卡，以及基于单元的架构	选择或比较模式时
scalability-reliability-guide.md	CAP 定理、数据库扩展、缓存、熔断器、SRE	讨论扩展或可靠性问题时
data-architecture-patterns.md	CQRS 变体、事件溯源、数据网格、Saga、一致性	讨论跨服务的数据流时
migration-modernization-guide.md	绞杀者模式、数据库拆分、功能标志、风险评估	重构单体时
api-gateway-service-mesh.md	网关模式、服务网格、mTLS、可观测性	讨论服务间通信时
fitness-functions-governance.md	适应度函数分类（六个维度）、架构与领域以及监控与告警的检验标准、ArchUnit/NetArchTest/linter 规则、模块化单体边界实施、趋同阈值、耦合与复杂度指标、由编码 Agent 修改的代码库	自动化架构治理、让原则可执行、确保代码库适合接受由 Agent 编写的差异时
architecture-trends.md	平台工程、环境式网格、AI 原生系统、MCP/A2A	仅了解当前趋势时
estate-modernization.md	运行时与代码库的合理化、有界上下文平台、整合启发式方法	处理多代码库系统和服务泛滥时
operational-playbook.md	架构问题框架、拆分启发式方法	梳理设计讨论时

模板

规划与文档（assets/planning/）：

• architecture-blueprint.md — 服务蓝图（依赖关系、SLA、数据流、弹性、安全性、可观测性）
• estate-modernization-blueprint.md — 系统资产蓝图（代码仓库／运行时分类、目标平台映射、迁移批次、评分卡）
• adr-template.md — 用于权衡分析的架构决策记录

架构模式（assets/patterns/）：

• microservices-template.md — 微服务设计（API 契约、弹性、部署、测试）
• event-driven-template.md — 事件驱动架构（事件模式、Saga 模式、事件溯源）

运维（assets/operations/）：

• scalability-checklist.md — 可扩展性清单（数据库扩展、缓存、负载测试、自动扩缩容、灾难恢复）

验证

• evals/evals.json — 此技能的触发、非触发和临界行为检查

应用型配方工具包

• references/decision-theory-applied.md — 面向架构的决策理论应用型配方：结合 EU 与敏感性分析的 ADR、针对不可逆选择的实物期权、用于快速验证的 VoI。
• references/queueing-theory-applied.md — 面向架构的排队论应用型配方：服务容量规划、背压拓扑、尾延迟预算。
• references/theory-of-constraints-applied.md — 面向架构的 TOC 应用型配方：系统级瓶颈排查、重构范围、稳定性与速度权衡 ADR。
• references/distributed-systems-applied.md — 应用于架构的分布式系统原语：考虑 CAP 的服务边界、共识算法选择、API 接口的幂等性、通过隔离令牌保护领导者选举作业的租约、仲裁配置、用于权衡一致性与延迟的 ADR 模板。
• references/reliability-theory-applied.md — 应用于软件架构设计的可靠性原语（MTBF／MTTR、可用性、FMEA、错误预算）。

相关技能

• software-solution-architecture — 端到端解决方案设计、系统全景、目标状态和迁移架构
• software-backend — 后端工程、API 实现、数据层
• software-frontend — 前端架构、微前端、状态管理
• dev-api-design — REST、GraphQL、gRPC 设计模式
• ops-devops-platform — CI/CD、部署策略、IaC
• qa-observability — 监控、追踪、告警、SLO
• software-security-appsec — 威胁建模、身份验证、安全设计
• data-sql-optimization — 在现有架构上进行查询调优和优化
• software-database-design — 架构设计、迁移和数据建模
• docs-codebase — 架构文档、文档即代码结构
• docs-diagram-design — 判断图表是否有必要，以及必须展示哪些内容
• 对于 C4 上下文图/容器图、arc42 文档结构或图表即代码，使用 docs-diagram-design 选择最精简且实用的视图，并在 docs-codebase 中维护其所有权和更新流程。
• ai-agents — Agent 系统设计、编排、评估
• agents-mcp — MCP 服务/客户端模式和集成

时效性协议

当问题与版本有关（当前趋势、“X 是否仍受推荐？”，供应商限制、托管服务能力、AI 原生互操作性）时，回答前请依据 data/sources.json 中的主要来源进行核实。无法实时访问时，请提供持久适用的模式，并说明哪些假设可能发生变化。触发条件、核查步骤和来源类别：references/operational-playbook.md#freshness-protocol。趋势深入分析：architecture-trends.md、estate-modernization.md。

经验反馈循环

如果先前的决策或陷阱与当前问题相关，请在存在时查阅 learnings.consolidated.md；仅在需要了解历史或它是唯一可用选项时使用 learnings.md。否则跳过这两个文件。

应用经验后，如果遇到值得记录的模式、值得防止的错误，或令人意外的领域事实，请通过 agents-skills-feedback-loop/scripts/append_learning.py 向 learnings.md 追加一条注明日期的条目。不要修改 SKILL.md 本身。