Back to Details

architecture-design

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

skill:architecture-design — Software Architecture Patterns and System Design

skill:architecture-design — 软件架构模式与系统设计

Version: 1.0.0

版本：1.0.0

Purpose

目标

Design scalable, maintainable software architectures by selecting appropriate patterns for the problem domain, team size, and scale requirements. This skill guides architectural decisions from high-level system decomposition to component-level design, producing Architecture Decision Records (ADRs), component diagrams, and dependency maps.
Use when:
  • Starting a new project and choosing an architecture
  • Evaluating whether to refactor a monolith
  • Designing component boundaries and module structure
  • Creating Architecture Decision Records (ADRs)
  • Reviewing an existing architecture for drift or technical debt
  • Scaling an application beyond its current architecture
针对问题领域、团队规模和扩展性需求，选择合适的模式来设计可扩展、可维护的软件架构。本skill指导从高层系统分解到组件级设计的架构决策，生成架构决策记录（ADRs）、组件图和依赖关系图。
适用场景：
  • 启动新项目并选择架构时
  • 评估是否需要重构单体应用时
  • 设计组件边界和模块结构时
  • 创建架构决策记录（ADRs）时
  • 审查现有架构是否存在漂移或技术债务时
  • 应用需要突破当前架构限制进行扩展时

File Structure

文件结构

skills/architecture-design/
├── SKILL.md (this file)
└── examples.md
skills/architecture-design/
├── SKILL.md (本文档)
└── examples.md

Interface References

接口参考

  • Context: Loaded via ContextProvider Interface
  • Memory: Accessed via MemoryStore Interface
  • Shared Patterns: Shared Loading Patterns
  • Schemas: Validated against context_metadata.schema.json and memory_entry.schema.json
  • Context：通过ContextProvider Interface加载
  • Memory：通过MemoryStore Interface访问
  • 共享模式：Shared Loading Patterns
  • Schema：需符合context_metadata.schema.json和memory_entry.schema.json的验证规范

MANDATORY WORKFLOW (MUST FOLLOW EXACTLY)

强制性工作流程（必须严格遵循）

IMPORTANT: Execute ALL steps in order. Do not skip any step.
重要提示：必须按顺序执行所有步骤，不得跳过任何步骤。

Step 1: Initial Analysis — Understand System Requirements

步骤1：初始分析 — 理解系统需求

YOU MUST:
  1. Identify the system type:
    • Web application (SPA, SSR, hybrid)
    • API/backend service
    • Data pipeline / ETL
    • Real-time system (chat, collaboration, gaming)
    • CLI tool or desktop application
    • Distributed system / platform
  2. Determine quality attribute priorities (pick top 3):
    • Scalability — Handle growing load
    • Maintainability — Easy to modify and extend
    • Performance — Low latency, high throughput
    • Reliability — Fault tolerance, disaster recovery
    • Security — Data protection, access control
    • Testability — Easy to verify correctness
    • Deployability — CI/CD, independent releases
    • Observability — Monitoring, tracing, debugging
  3. Assess constraints:
    • Team size and experience
    • Timeline and budget
    • Existing technology stack
    • Regulatory and compliance requirements
    • Infrastructure limitations
  4. Define scale parameters:
    • Expected users (concurrent and total)
    • Data volume (storage and throughput)
    • Request rate (peak and average)
    • Geographic distribution
DO NOT PROCEED WITHOUT UNDERSTANDING REQUIREMENTS AND CONSTRAINTS
必须完成：
  1. 确定系统类型：
    • Web应用（SPA、SSR、混合模式）
    • API/后端服务
    • 数据管道/ETL
    • 实时系统（聊天、协作、游戏）
    • CLI工具或桌面应用
    • 分布式系统/平台
  2. 确定质量属性优先级（选择前3项）：
    • 可扩展性 — 应对增长的负载
    • 可维护性 — 易于修改和扩展
    • 性能 — 低延迟、高吞吐量
    • 可靠性 — 容错、灾难恢复
    • 安全性 — 数据保护、访问控制
    • 可测试性 — 易于验证正确性
    • 可部署性 — CI/CD、独立发布
    • 可观测性 — 监控、追踪、调试
  3. 评估约束条件：
    • 团队规模和经验
    • 时间线和预算
    • 现有技术栈
    • 法规和合规要求
    • 基础设施限制
  4. 定义扩展参数：
    • 预期用户数（并发和总用户）
    • 数据量（存储和吞吐量）
    • 请求速率（峰值和平均值）
    • 地理分布
未理解需求和约束条件不得继续

Step 2: Load Memory

步骤2：加载内存

Follow Standard Memory Loading with 
skill="architecture-design"
and 
domain="engineering"
.
YOU MUST:
  1. Use 
    memoryStore.getSkillMemory("architecture-design", "{project-name}")
    to load existing architecture context
  2. Use 
    memoryStore.getByProject("{project-name}")
    for cross-skill insights
  3. If memory exists, honor existing architectural decisions and constraints
  4. If no memory exists, proceed and create it in Step 8
遵循Standard Memory Loading，设置
skill="architecture-design"
和
domain="engineering"
。
必须完成：
  1. 使用
    memoryStore.getSkillMemory("architecture-design", "{project-name}")
    加载现有架构上下文
  2. 使用
    memoryStore.getByProject("{project-name}")
    获取跨skill的洞察
  3. 若存在内存数据，需遵循已有的架构决策和约束条件
  4. 若不存在内存数据，继续执行并在步骤8中创建

Step 3: Load Context

步骤3：加载上下文

Follow Standard Context Loading for the 
engineering
domain. Stay within the file budget declared in frontmatter.
针对
engineering
领域，遵循Standard Context Loading。需遵守前置声明的文件预算。

Step 4: Select Architecture Pattern

步骤4：选择架构模式

YOU MUST evaluate and recommend from:
必须从以下选项中评估并推荐：

Pattern Catalog

模式目录

PatternBest ForTeam SizeComplexity
LayeredCRUD apps, admin panels1–5Low
Modular MonolithMost applications, growing teams3–15Medium
Hexagonal (Ports & Adapters)Domain-heavy apps, high testability3–10Medium
Clean ArchitectureComplex business logic, long-lived systems5–15Medium–High
Event-DrivenAsync workflows, decoupled systems5–20High
| CQRS | Read/write asymmetry, complex queries | 5–15 | High | | Microservices | Large orgs, independent deployment needs | 15+ | Very High | | Serverless | Event-triggered workloads, variable traffic | 1–10 | Medium |
Selection criteria:
  1. Start simple — choose the least complex pattern that satisfies requirements
  2. Consider team experience — an unfamiliar pattern adds risk
  3. Monolith first — unless there's a clear reason for distribution
  4. Pattern combinations — e.g., Hexagonal + CQRS, Modular Monolith + Event-Driven
模式最佳适用场景团队规模复杂度
分层架构CRUD应用、管理面板1–5人低
模块化单体架构大多数应用、成长型团队3–15人中
六边形架构（端口与适配器）领域驱动型应用、高可测试性需求3–10人中
整洁架构复杂业务逻辑、长期维护的系统5–15人中–高
事件驱动架构异步工作流、解耦系统5–20人高
| CQRS | 读写不对称、复杂查询 | 5–15人 | 高 | | 微服务架构 | 大型组织、独立部署需求 | 15+人 | 极高 | | Serverless | 事件触发的工作负载、流量波动大的场景 | 1–10人 | 中 |
选择标准：
  1. 从简出发 — 选择满足需求的最复杂程度最低的模式
  2. 考虑团队经验 — 不熟悉的模式会增加风险
  3. 优先单体架构 — 除非有明确的分布式需求
  4. 模式组合 — 例如：六边形架构+CQRS、模块化单体架构+事件驱动架构

Step 5: Design Component Structure

步骤5：设计组件结构

YOU MUST define:
  1. Component boundaries:
    • Identify bounded contexts (DDD) or functional modules
    • Define public interfaces between components
    • Establish dependency rules (what depends on what)
  2. Layer definitions (if layered):
    • Presentation / API layer
    • Application / orchestration layer
    • Domain / business logic layer
    • Infrastructure / persistence layer
  3. Communication patterns:
    • Synchronous: Direct calls, REST, gRPC
    • Asynchronous: Events, message queues, pub/sub
    • Data sharing: Shared database, API calls, event sourcing
  4. Cross-cutting concerns:
    • Authentication and authorization
    • Logging and observability
    • Error handling and resilience
    • Configuration management
    • Caching strategy
必须定义：
  1. 组件边界：
    • 识别限界上下文（DDD）或功能模块
    • 定义组件间的公共接口
    • 建立依赖规则（明确谁依赖谁）
  2. 分层定义（若采用分层架构）：
    • 表现层/API层
    • 应用层/编排层
    • 领域层/业务逻辑层
    • 基础设施层/持久化层
  3. 通信模式：
    • 同步：直接调用、REST、gRPC
    • 异步：事件、消息队列、发布/订阅
    • 数据共享：共享数据库、API调用、事件溯源
  4. 横切关注点：
    • 认证与授权
    • 日志与可观测性
    • 错误处理与弹性
    • 配置管理
    • 缓存策略

Step 6: Define Architecture Decisions (ADRs)

步骤6：定义架构决策（ADRs）

YOU MUST produce at least one ADR for each significant decision:
markdown
undefined
必须为每个重要决策生成至少一份ADR：
markdown
undefined

ADR-{NNN}: {Title}

ADR-{NNN}: {标题}

Status: Proposed | Accepted | Deprecated | Superseded Date: YYYY-MM-DD Deciders: {who}
状态：提议 | 已接受 | 已弃用 | 已取代 日期：YYYY-MM-DD 决策者：{人员}

Context

背景

{What is the issue and why does it matter?}
{问题是什么，为什么重要？}

Decision

决策

{What was decided and why this option?}
{做出了什么决定，为什么选择该方案？}

Consequences

影响

Positive

积极影响

  • {benefit 1}
  • {优势1}

Negative

消极影响

  • {tradeoff 1}
  • {权衡1}

Risks

风险

  • {risk 1 with mitigation}
  • {风险1及缓解措施}

Alternatives Considered

备选方案

  1. {alternative with reason for rejection}
undefined
  1. {备选方案及被否决的原因}
undefined

Step 7: Generate Output

步骤7：生成输出

  • Save output to 
    /claudedocs/architecture-design_{project}_{YYYY-MM-DD}.md
  • Follow naming conventions in 
    ../OUTPUT_CONVENTIONS.md
  • Include:
    • Architecture overview with pattern selection rationale
    • Component diagram (ASCII or Mermaid)
    • Dependency map showing allowed and forbidden dependencies
    • ADRs for each significant decision
    • Technology recommendations
    • Migration path (if evolving from existing architecture)
  • 将输出保存至
    /claudedocs/architecture-design_{project}_{YYYY-MM-DD}.md
  • 遵循
    ../OUTPUT_CONVENTIONS.md
    中的命名规范
  • 输出内容需包含：
    • 架构概述及模式选择依据
    • 组件图（ASCII或Mermaid格式）
    • 依赖关系图（展示允许和禁止的依赖）
    • 每个重要决策对应的ADRs
    • 技术选型建议
    • 迁移路径（若从现有架构演进）

Step 8: Update Memory

步骤8：更新内存

Follow Standard Memory Update for 
skill="architecture-design"
.
Store:
  1. architecture_decisions.md: ADRs, pattern selection rationale, key constraints
  2. project_overview.md: System type, quality attributes, components, dependencies, technology stack
遵循Standard Memory Update，设置
skill="architecture-design"
。
存储以下内容：
  1. architecture_decisions.md：ADRs、模式选择依据、关键约束条件
  2. project_overview.md：系统类型、质量属性、组件、依赖关系、技术栈

Architecture Principles

架构原则

PrincipleGuideline
Simplicity firstThe right architecture is the simplest one that satisfies requirements
Dependency inversionHigh-level modules must not depend on low-level modules; both depend on abstractions
Single responsibilityEach component has one reason to change
Explicit boundariesComponent interfaces are deliberate, not accidental
Evolutionary designArchitecture should support incremental change, not require big-bang rewrites
Conway's Law awarenessArchitecture will mirror team structure — design both together
原则指导方针
简洁优先合适的架构是满足需求的最简单架构
依赖倒置高层模块不得依赖低层模块；两者都应依赖抽象
单一职责每个组件只有一个变更理由
明确边界组件接口是刻意设计的，而非偶然形成的
演进式设计架构应支持增量式变更，无需大爆炸式重写
康威定律意识架构将反映团队结构 — 需同时设计两者

Common Anti-Patterns to Prevent

需避免的常见反模式

Anti-PatternCorrect Approach
Distributed monolithUse modular monolith first; split only when needed
Big ball of mudDefine explicit module boundaries with enforced dependency rules
Golden hammerChoose patterns based on requirements, not familiarity
Premature optimizationDesign for current scale with clear scaling strategy
Shared mutable stateUse events or explicit data ownership
Circular dependenciesEnforce acyclic dependency graph; use dependency inversion
Resume-driven developmentChoose boring technology unless novel tech solves a real problem
反模式正确做法
分布式单体优先使用模块化单体架构；仅在必要时拆分
大泥球定义明确的模块边界并强制执行依赖规则
金锤子根据需求选择模式，而非基于熟悉程度
过早优化针对当前规模进行设计，并制定清晰的扩展策略
共享可变状态使用事件或明确的数据所有权
循环依赖强制执行无环依赖图；使用依赖倒置
简历驱动开发除非新技术能解决实际问题，否则选择成熟技术

Compliance Checklist

合规检查清单

Before completing, verify:
  • Step 1: System type, quality attributes, constraints, and scale parameters identified
  • Step 2: Standard Memory Loading pattern followed
  • Step 3: Standard Context Loading pattern followed
  • Step 4: Architecture pattern selected with rationale
  • Step 5: Component boundaries, layers, communication patterns, and cross-cutting concerns defined
  • Step 6: ADRs produced for each significant decision
  • Step 7: Output saved with standard naming convention
  • Step 8: Standard Memory Update pattern followed
FAILURE TO COMPLETE ALL STEPS INVALIDATES THE DESIGN
完成前，请验证：
  • 步骤1：已确定系统类型、质量属性、约束条件和扩展参数
  • 步骤2：已遵循标准内存加载模式
  • 步骤3：已遵循标准上下文加载模式
  • 步骤4：已选择架构模式并说明依据
  • 步骤5：已定义组件边界、分层、通信模式和横切关注点
  • 步骤6：已为每个重要决策生成ADRs
  • 步骤7：已按标准命名规范保存输出
  • 步骤8：已遵循标准内存更新模式
未完成所有步骤的设计视为无效

Further Reading

延伸阅读

  • Clean Architecture by Robert C. Martin
  • Fundamentals of Software Architecture by Mark Richards & Neal Ford
  • Domain-Driven Design by Eric Evans
  • Building Evolutionary Architectures by Neal Ford, Rebecca Parsons, Patrick Kua
  • C4 Model: https://c4model.com/
  • Clean Architecture by Robert C. Martin
  • Fundamentals of Software Architecture by Mark Richards & Neal Ford
  • Domain-Driven Design by Eric Evans
  • Building Evolutionary Architectures by Neal Ford, Rebecca Parsons, Patrick Kua
  • C4 Model：https://c4model.com/

Version History

版本历史

VersionDateChanges
1.0.02026-02-12Initial release — pattern catalog, ADR framework, component design, anti-patterns
版本日期变更
1.0.02026-02-12初始版本 — 包含模式目录、ADR框架、组件设计、反模式