software-architecture-design

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Software Architecture Design — Quick Reference

软件架构设计——快速参考

Use this skill for system-level design decisions rather than implementation details within a single service or component.

本技能适用于系统级设计决策，而非单一服务或组件内的实现细节。

Quick Reference

快速参考

Task	Pattern/Tool	Key Resources	When to Use
Choose architecture style	Layered, Microservices, Event-driven, Serverless	modern-patterns.md	Greenfield projects, major refactors
Design for scale	Load balancing, Caching, Sharding, Read replicas	scalability-reliability-guide.md	High-traffic systems, performance goals
Ensure resilience	Circuit breakers, Retries, Bulkheads, Graceful degradation	modern-patterns.md	Distributed systems, external dependencies
Document decisions	Architecture Decision Record (ADR)	adr-template.md	Major technical decisions, tradeoff analysis
Define service boundaries	Domain-Driven Design (DDD), Bounded contexts	microservices-template.md	Microservices decomposition
Model data consistency	ACID vs BASE, Event sourcing, CQRS, Saga patterns	event-driven-template.md	Multi-service transactions
Plan observability	SLIs/SLOs/SLAs, Distributed tracing, Metrics, Logs	architecture-blueprint.md	Production readiness

任务	模式/工具	核心资源	适用场景
选择架构风格	Layered、Microservices、Event-driven、Serverless	modern-patterns.md	全新项目、重大重构
可扩展性设计	负载均衡、缓存、分片、只读副本	scalability-reliability-guide.md	高流量系统、性能优化目标
确保韧性	断路器、重试、舱壁、优雅降级	modern-patterns.md	分布式系统、外部依赖场景
记录决策	Architecture Decision Record (ADR)	adr-template.md	重大技术决策、权衡分析
定义服务边界	Domain-Driven Design (DDD)、限界上下文	microservices-template.md	微服务拆分
数据一致性建模	ACID vs BASE、事件溯源、CQRS、Saga模式	event-driven-template.md	多服务事务场景
可观测性规划	SLIs/SLOs/SLAs、分布式追踪、指标、日志	architecture-blueprint.md	生产环境就绪准备

When to Use This Skill

何时使用本技能

Invoke when working on:

System decomposition: Deciding between monolith, modular monolith, microservices
Architecture patterns: Event-driven, CQRS, layered, hexagonal, serverless
Data architecture: Consistency models, sharding, replication, CQRS patterns
Scalability design: Load balancing, caching strategies, database scaling
Resilience patterns: Circuit breakers, retries, bulkheads, graceful degradation
API contracts: Service boundaries, versioning, integration patterns
Architecture decisions: ADRs, tradeoff analysis, technology selection

在以下场景调用本技能：

系统拆分：在单体、模块化单体、微服务之间做选择
架构模式：事件驱动、CQRS、分层、六边形、无服务器
数据架构：一致性模型、分片、复制、CQRS模式
可扩展性设计：负载均衡、缓存策略、数据库扩容
韧性模式：断路器、重试、舱壁、优雅降级
API契约：服务边界、版本控制、集成模式
架构决策：ADR、权衡分析、技术选型

When NOT to Use This Skill

何时不使用本技能

Use other skills instead for:

Single-service implementation (routes, controllers, business logic) → software-backend
API endpoint design (REST conventions, GraphQL schemas) → dev-api-design
Security implementation (auth, encryption, OWASP) → software-security-appsec
Frontend component architecture → software-frontend
Database query optimization → data-sql-optimization

以下场景请使用其他技能：

单一服务实现（路由、控制器、业务逻辑）→ software-backend
API端点设计（REST规范、GraphQL schema）→ dev-api-design
安全实现（认证、加密、OWASP）→ software-security-appsec
前端组件架构 → software-frontend
数据库查询优化 → data-sql-optimization

Decision Tree: Choosing Architecture Pattern

决策树：选择架构模式

text

Project needs: [New System or Major Refactor]
    ├─ Single team, evolving domain?
    │   ├─ Start simple → Modular Monolith (clear module boundaries)
    │   └─ Need rapid iteration → Layered Architecture
    │
    ├─ Multiple teams, clear bounded contexts?
    │   ├─ Independent deployment critical → Microservices
    │   └─ Shared data model → Modular Monolith with service modules
    │
    ├─ Event-driven workflows?
    │   ├─ Asynchronous processing → Event-Driven Architecture (Kafka, queues)
    │   └─ Complex state machines → Saga pattern + Event Sourcing
    │
    ├─ Variable/unpredictable load?
    │   ├─ Pay-per-use model → Serverless (AWS Lambda, Cloudflare Workers)
    │   └─ Batch processing → Serverless + queues
    │
    └─ High consistency requirements?
        ├─ Strong ACID guarantees → Monolith or Modular Monolith
        └─ Distributed data → CQRS + Event Sourcing

Decision Factors:

Team size threshold: <10 developers → modular monolith typically outperforms microservices (operational overhead)
Team structure (Conway's Law) — architecture mirrors org structure
Deployment independence needs
Consistency vs availability tradeoffs (CAP theorem)
Operational maturity (monitoring, orchestration)

See references/modern-patterns.md for detailed pattern descriptions.

text

Project needs: [New System or Major Refactor]
    ├─ Single team, evolving domain?
    │   ├─ Start simple → Modular Monolith (clear module boundaries)
    │   └─ Need rapid iteration → Layered Architecture
    │
    ├─ Multiple teams, clear bounded contexts?
    │   ├─ Independent deployment critical → Microservices
    │   └─ Shared data model → Modular Monolith with service modules
    │
    ├─ Event-driven workflows?
    │   ├─ Asynchronous processing → Event-Driven Architecture (Kafka, queues)
    │   └─ Complex state machines → Saga pattern + Event Sourcing
    │
    ├─ Variable/unpredictable load?
    │   ├─ Pay-per-use model → Serverless (AWS Lambda, Cloudflare Workers)
    │   └─ Batch processing → Serverless + queues
    │
    └─ High consistency requirements?
        ├─ Strong ACID guarantees → Monolith or Modular Monolith
        └─ Distributed data → CQRS + Event Sourcing

决策因素：

团队规模阈值：<10名开发人员 → 模块化单体通常优于微服务（运维开销更低）
团队结构（康威定律）—— 架构会映射组织架构
部署独立性需求
一致性与可用性的权衡（CAP定理）
运维成熟度（监控、编排）

详细的模式说明请参考 references/modern-patterns.md。

Workflow (System-Level)

工作流（系统级）

Use this workflow when a user asks for architecture recommendations, decomposition, or major platform decisions.

Clarify: problem statement, non-goals, constraints, and success metrics
Capture quality attributes: availability, latency, throughput, durability, consistency, security, compliance, cost
Propose 2–3 candidate architectures and compare tradeoffs
Define boundaries: bounded contexts, ownership, APIs/events, integration contracts
Decide data strategy: storage, consistency model, schema evolution, migrations
Design for operations: SLOs, failure modes, observability, deployment, DR, incident playbooks
Document decisions: write ADRs for key tradeoffs and irreversible choices

Preferred deliverables (pick what fits the request):

Architecture blueprint:

assets/planning/architecture-blueprint.md

Decision record:
```
assets/planning/adr-template.md
```

Pattern deep dives:

references/modern-patterns.md

references/scalability-reliability-guide.md

当用户请求架构建议、系统拆分或重大平台决策时，使用以下工作流：

明确：问题陈述、非目标、约束条件和成功指标
捕获质量属性：可用性、延迟、吞吐量、持久性、一致性、安全性、合规性、成本
提出2-3个候选架构并对比权衡
定义边界：限界上下文、所有权、API/事件、集成契约
确定数据策略：存储、一致性模型、 schema 演进、迁移
运维设计：SLO、故障模式、可观测性、部署、灾难恢复、事件响应手册
记录决策：为关键权衡和不可逆选择编写ADR

推荐交付物（根据请求选择）：

架构蓝图：

assets/planning/architecture-blueprint.md

决策记录：
```
assets/planning/adr-template.md
```

模式深度解析：

references/modern-patterns.md

、

references/scalability-reliability-guide.md

2026 Considerations (Load Only When Relevant)

2026年相关考量（仅在相关时使用）

For ecosystem-sensitive questions (current vendor constraints, shifting best practices), use

data/sources.json

as the starting index:

2026 trends overview:
```
references/architecture-trends-2026.md
```
Platform engineering / IDPs:
```
.platform_engineering_2026
```
Data mesh and analytics architecture:
```
.scalability_reliability
```
(data mesh entries)
AI-native systems (RAG, agents, MCP/A2A):
```
.optional_ai_architecture
```

If fresh web access is not available, answer with best-known patterns and explicitly call out assumptions.

对于生态敏感型问题（当前供应商约束、不断变化的最佳实践），以

data/sources.json

作为起始索引：

2026年趋势概览：
```
references/architecture-trends-2026.md
```
平台工程/内部开发平台（IDP）：
```
.platform_engineering_2026
```
数据网格与分析架构：
```
.scalability_reliability
```
（数据网格条目）
AI原生系统（RAG、Agent、MCP/A2A）：
```
.optional_ai_architecture
```

如果无法访问实时网络，请使用已知最佳模式作答，并明确说明假设条件。

Navigation

references/modern-patterns.md — 10 contemporary architecture patterns with decision trees (microservices, event-driven, serverless, CQRS, modular monolith, service mesh, edge computing)
references/scalability-reliability-guide.md — CAP theorem, database scaling, caching strategies, circuit breakers, SRE patterns, observability
references/architecture-trends-2026.md — Platform engineering, data mesh, AI-native systems (load only when relevant)
data/sources.json — 60 curated external resources (AWS, Azure, Google Cloud, Martin Fowler, microservices.io, SRE books, multi-agent patterns, MCP/A2A protocols, platform engineering 2026)

references/modern-patterns.md — 10种当代架构模式及决策树（微服务、事件驱动、无服务器、CQRS、模块化单体、服务网格、边缘计算）
references/scalability-reliability-guide.md — CAP定理、数据库扩容、缓存策略、断路器、SRE模式、可观测性
references/architecture-trends-2026.md — 平台工程、数据网格、AI原生系统（仅在相关时加载）
data/sources.json — 60个精选外部资源（AWS、Azure、Google Cloud、Martin Fowler、microservices.io、SRE书籍、多Agent模式、MCP/A2A协议、2026年平台工程）

Templates

模板

Planning & Documentation (assets/planning/):

assets/planning/architecture-blueprint.md — Service blueprint template (dependencies, SLAs, data flows, resilience, security, observability)
assets/planning/adr-template.md — Architecture Decision Record (ADR) for documenting design decisions with tradeoff analysis

Architecture Patterns (assets/patterns/):

assets/patterns/microservices-template.md — Complete microservices design template (API contracts, resilience, deployment, testing, cost optimization)
assets/patterns/event-driven-template.md — Event-driven architecture template (event schemas, saga patterns, event sourcing, schema evolution)

Operations & Scalability (assets/operations/):

assets/operations/scalability-checklist.md — Comprehensive scalability checklist (database scaling, caching, load testing, auto-scaling, DR)

规划与文档 (assets/planning/):

assets/planning/architecture-blueprint.md — 服务蓝图模板（依赖关系、SLA、数据流、韧性、安全性、可观测性）
assets/planning/adr-template.md — 架构决策记录（ADR）模板，用于记录设计决策及权衡分析

架构模式 (assets/patterns/):

assets/patterns/microservices-template.md — 完整的微服务设计模板（API契约、韧性、部署、测试、成本优化）
assets/patterns/event-driven-template.md — 事件驱动架构模板（事件Schema、Saga模式、事件溯源、Schema演进）

运维与可扩展性 (assets/operations/):

assets/operations/scalability-checklist.md — 全面的可扩展性检查清单（数据库扩容、缓存、负载测试、自动扩容、灾难恢复）

Related Skills

Freshness Protocol (When the Question Depends on "Now")

时效性规则（当问题依赖当前信息时使用）

Use this when the user is asking for current best practices, vendor-specific constraints, or trend-sensitive recommendations.

If live web access is available, consult 2–3 authoritative sources from
```
data/sources.json
```
(cloud frameworks, SRE, pattern catalogs) and fold new constraints into the recommendation.
If live web access is not available, answer with durable patterns and explicitly state assumptions that could change (vendor limits, pricing, managed-service capabilities, ecosystem maturity).

当用户询问当前最佳实践、供应商特定约束或趋势敏感型建议时，遵循以下规则：

如果可以访问实时网络，从
```
data/sources.json
```
中选取2-3个权威来源（云框架、SRE、模式目录），并将新约束整合到建议中。
如果无法访问实时网络，使用已确认的最佳模式作答，并明确说明可能会变化的假设条件（供应商限制、定价、托管服务能力、生态成熟度）。

Operational Playbooks

运维手册

Shared Foundation

../software-clean-code-standard/references/clean-code-standard.md - Canonical clean code rules (
```
CC-*
```
) for citation
Legacy playbook: ../software-clean-code-standard/references/code-quality-operational-playbook.md -
```
RULE-01
```
–
```
RULE-13
```
, operational procedures, and design patterns
../software-clean-code-standard/references/design-patterns-operational-checklist.md - GoF pattern triggers and guardrails, when to apply vs avoid patterns

Architecture-Specific

references/operational-playbook.md — Detailed architecture questions, decomposition patterns, security layers, and external references

通用基础

../software-clean-code-standard/references/clean-code-standard.md - 标准整洁代码规则（
```
CC-*
```
），用于引用
遗留系统手册：../software-clean-code-standard/references/code-quality-operational-playbook.md -
```
RULE-01
```
–
```
RULE-13
```
、运维流程、设计模式
../software-clean-code-standard/references/design-patterns-operational-checklist.md - GoF模式触发条件与约束，何时适用与避免模式

架构特定

references/operational-playbook.md — 详细的架构问题、拆分模式、安全层及外部参考