architecture-decision

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Architecture Decision

架构决策

Systematically evaluate architecture decisions, document trade-offs, and select appropriate patterns for context. Provides frameworks for pattern selection, ADR creation, and technical debt management.

系统化评估架构决策，记录不同方案的权衡取舍，并结合场景选择合适的模式。提供模式选择、ADR创建以及技术债务管理的相关框架。

When to Use This Skill

何时使用此技能

Use this skill when:

Making technology choices
Evaluating architectural patterns
Creating Architecture Decision Records
Assessing technical debt
Comparing design alternatives

Do NOT use this skill when:

Writing implementation code
Working on requirements (use requirements-analysis)
Doing full system design (use system-design)

使用场景：

进行技术选型
评估架构模式
创建架构决策记录（ADR）
评估技术债务
对比设计备选方案

请勿使用场景：

编写实现代码
处理需求（请使用requirements-analysis技能）
进行完整系统设计（请使用system-design技能）

Core Principle

核心原则

Context drives decisions. No pattern is universally good or bad. The best architecture is not the most elegant—it's the one that best serves its purpose while remaining maintainable and evolvable.

由场景驱动决策。没有放之四海而皆准的模式。最优的架构并非最优雅的架构，而是最能满足业务需求，同时具备可维护性和可演进性的架构。

The Trade-off Triangle

权衡三角

Every architectural decision involves trade-offs:

Vertex	Maximized By	Cost
Simplicity	Monolith, sync communication, single DB	Scalability limits
Flexibility	Microservices, event-driven, plugins	Complexity overhead
Performance	Caching, denormalization, optimized code	Maintainability

Balance Strategies:

Start simple, add complexity as needed
Measure before optimizing
Use abstractions to defer decisions
Evolve incrementally

每一项架构决策都需要权衡取舍：

维度	实现方式	代价
简洁性	Monolith（单体架构）、同步通信、单一数据库	扩展性受限
灵活性	Microservices（微服务）、事件驱动、插件化	复杂度提升
性能	缓存、反规范化、代码优化	可维护性下降

平衡策略：

从简出发，按需增加复杂度
先度量再优化
用抽象延迟决策
逐步演进

Quality Attributes

质量属性

Performance

性能

Metrics: Response time (p50, p95, p99), throughput, resource utilization
Tactics: Caching, load balancing, async processing

指标：响应时间（p50、p95、p99）、吞吐量、资源利用率
策略：缓存、负载均衡、异步处理

Scalability

扩展性

Dimensions: Horizontal, vertical, elastic
Patterns: Stateless services, sharding, event streaming

维度：水平扩展、垂直扩展、弹性扩展
模式：无状态服务、分片、事件流

Reliability

可靠性

Metrics: Uptime, MTBF, MTTR
Patterns: Circuit breakers, retries, redundancy

指标：可用时间、平均故障间隔时间（MTBF）、平均恢复时间（MTTR）
模式：断路器、重试、冗余

Maintainability

可维护性

Factors: Readability, modularity, testability
Patterns: Clean architecture, DDD, SOLID

影响因素：可读性、模块化、可测试性
模式：整洁架构、DDD（领域驱动设计）、SOLID原则

Context-Pattern Mapping

场景-模式映射

Team Context

团队场景

Context	Preferred Patterns	Avoid
Small team	Monolith, vertical slices, shared DB	Microservices, complex abstractions
Multiple teams	Service boundaries, API contracts	Shared state, tight coupling

场景	推荐模式	避免做法
小型团队	Monolith（单体架构）、垂直切片、共享数据库	Microservices（微服务）、复杂抽象
多团队协作	服务边界定义、API契约	共享状态、紧耦合

Scale Context

规模场景

Context	Preferred Patterns	Reasoning
Startup	Monolith first, vertical scaling	Optimize for development speed
Enterprise	Service mesh, horizontal scaling	Optimize for operational scale

场景	推荐模式	原因
初创公司	优先单体架构、垂直扩展	优化开发速度
企业级	服务网格、水平扩展	优化运维规模

Decision Matrix Template

决策矩阵模板

Option	Consistency	Flexibility	Scalability	Complexity	Cost	Total
Option A	5	2	3	2	3	15
Option B	3	5	4	3	3	18
Option C	2	3	5	1	2	13

Weight factors based on context priorities.

选项	一致性	灵活性	扩展性	复杂度	成本	总分
选项A	5	2	3	2	3	15
选项B	3	5	4	3	3	18
选项C	2	3	5	1	2	13

根据场景优先级设置权重系数。

Architecture Decision Record (ADR) Template

架构决策记录（ADR）模板

markdown

undefined

markdown

undefined

ADR-[NUMBER]: [TITLE]

Status

[Proposed | Accepted | Deprecated | Superseded]

Context

[What is the situation requiring a decision?]

Requirements

[Requirement 1]
[Requirement 2]

[Requirement 1]
[Requirement 2]

Constraints

[Constraint 1]
[Constraint 2]

[Constraint 1]
[Constraint 2]

Decision

[What is the decision?]

Justification

[Reason 1]
[Reason 2]

[Reason 1]
[Reason 2]

Consequences

Positive

[Benefit 1]
[Benefit 2]

[Benefit 1]
[Benefit 2]

Negative

[Drawback 1]
[Drawback 2]

[Drawback 1]
[Drawback 2]

Alternatives Considered

[Alternative 1]

Reason rejected: [Why]

[Alternative 2]

Reason rejected: [Why]

undefined

Reason rejected: [Why]

undefined

Architectural Refactoring Patterns

架构重构模式

Branch by Abstraction

抽象分支法

Create abstraction over current implementation
Implement new solution behind abstraction
Switch to new implementation
Remove old implementation

为现有实现创建抽象层
在抽象层后实现新方案
切换到新实现
移除旧实现

Strangler Fig

绞杀者模式

Identify boundary
Implement new solution for new features
Gradually migrate old features
Retire old system

识别边界
为新功能实现新方案
逐步迁移旧功能
停用旧系统

Parallel Run

并行运行模式

Implement new solution
Run both old and new
Compare results
Switch when confident

实现新方案
同时运行新旧系统
对比运行结果
确认无误后切换

Technical Debt Management

技术债务管理

Debt Categories

债务分类

Type	Examples	Payment Strategy
Design	Missing abstractions, tight coupling	Refactoring sprints
Code	Duplication, complexity, poor naming	Continuous cleanup
Test	Missing tests, flaky tests	Test improvement
Documentation	Missing docs, outdated diagrams	Documentation sprints

类型	示例	偿还策略
设计类	缺少抽象层、紧耦合	重构迭代
代码类	代码重复、复杂度高、命名不佳	持续清理
测试类	缺少测试、不稳定测试	测试优化
文档类	文档缺失、图表过时	文档迭代

Metrics

度量指标

Debt ratio: Debt work / Total work (target < 20%)
Interest rate: Extra effort due to debt
Debt ceiling: Maximum acceptable debt

债务比率：债务工作量 / 总工作量（目标值 < 20%）
利率：因债务增加的额外工作量
债务上限：可接受的最大债务量

Anti-Patterns

反模式

Big Ball of Mud

大泥球模式

Symptoms: No clear structure, everything depends on everything Remedy: Identify boundaries, extract modules, establish interfaces

症状：无清晰结构，所有模块相互依赖 解决方法：识别边界，提取模块，定义接口

Distributed Monolith

分布式单体

Symptoms: Services must deploy together, sync chains, shared DBs Remedy: Merge related services, async communication, separate DBs

症状：服务必须一起部署、同步调用链、共享数据库 解决方法：合并相关服务、采用异步通信、分离数据库

Golden Hammer

金锤子模式

Symptoms: One solution for all problems, force-fitting patterns Remedy: Learn alternatives, evaluate objectively, prototype options

症状：用单一方案解决所有问题，强行套用模式 解决方法：了解备选方案，客观评估，制作原型验证

architecture-decision

Original

Translation

Architecture Decision

架构决策

When to Use This Skill

何时使用此技能

Core Principle

核心原则

The Trade-off Triangle

权衡三角

Quality Attributes

质量属性

Performance

性能

Scalability

扩展性

Reliability

可靠性

Maintainability

可维护性

Context-Pattern Mapping

场景-模式映射

Team Context

团队场景

Scale Context

规模场景

Decision Matrix Template

决策矩阵模板

Architecture Decision Record (ADR) Template

架构决策记录（ADR）模板

ADR-[NUMBER]: [TITLE]

ADR-[NUMBER]: [TITLE]

Status

Status

Context

Context

Requirements

Requirements

Constraints

Constraints

Decision

Decision

Justification

Justification

Consequences

Consequences

Positive

Positive

Negative

Negative

Alternatives Considered

Alternatives Considered

[Alternative 1]

[Alternative 1]

[Alternative 2]

[Alternative 2]

Architectural Refactoring Patterns

架构重构模式

Branch by Abstraction

抽象分支法

Strangler Fig

绞杀者模式

Parallel Run

并行运行模式

Technical Debt Management

技术债务管理

Debt Categories

债务分类

Metrics

度量指标

Anti-Patterns

反模式

Big Ball of Mud

大泥球模式

Distributed Monolith

分布式单体

Golden Hammer

金锤子模式

Related Skills