arc42-documentation

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

arc42 Documentation Skill

arc42文档技能

When to Use This Skill

何时使用此技能

Use this skill when:

Arc42 Documentation tasks - Working on arc42 architecture documentation template and guidance
Planning or design - Need guidance on Arc42 Documentation approaches
Best practices - Want to follow established patterns and standards

在以下场景使用此技能：

arc42文档任务 - 处理arc42架构文档模板与相关指南工作
规划或设计阶段 - 需要arc42文档撰写方法的指导
最佳实践 - 希望遵循已确立的模式与标准

Overview

概述

Create comprehensive architecture documentation using the arc42 template.

使用arc42模板创建全面的架构文档。

MANDATORY: Documentation-First Approach

强制要求：文档优先方法

Before creating arc42 documentation:

Invoke
docs-management
skill for architecture documentation patterns
Verify arc42 current version via MCP servers (perplexity)
Base guidance on official arc42 template

创建arc42文档前：

调用
```
docs-management
```
技能获取架构文档模式
通过MCP服务器（perplexity）确认arc42当前版本
基于官方arc42模板提供指导

arc42 Template Structure

arc42模板结构

text

arc42 Template (12 Sections):

┌─────────────────────────────────────────────────────────────────────────────┐
│  1. Introduction and Goals                                                   │
│     Requirements overview, quality goals, stakeholders                       │
├─────────────────────────────────────────────────────────────────────────────┤
│  2. Architecture Constraints                                                 │
│     Technical, organizational, and convention constraints                    │
├─────────────────────────────────────────────────────────────────────────────┤
│  3. System Scope and Context                                                 │
│     Business context, technical context                                      │
├─────────────────────────────────────────────────────────────────────────────┤
│  4. Solution Strategy                                                        │
│     Technology decisions, top-level decomposition, quality approaches        │
├─────────────────────────────────────────────────────────────────────────────┤
│  5. Building Block View                                                      │
│     Static decomposition: whitebox/blackbox at multiple levels               │
├─────────────────────────────────────────────────────────────────────────────┤
│  6. Runtime View                                                             │
│     Important scenarios, interactions, behaviors                             │
├─────────────────────────────────────────────────────────────────────────────┤
│  7. Deployment View                                                          │
│     Technical infrastructure, mapping of building blocks                     │
├─────────────────────────────────────────────────────────────────────────────┤
│  8. Cross-cutting Concepts                                                   │
│     Recurring patterns, approaches, principles                               │
├─────────────────────────────────────────────────────────────────────────────┤
│  9. Architecture Decisions                                                   │
│     Important decisions with rationale (may link to ADRs)                    │
├─────────────────────────────────────────────────────────────────────────────┤
│ 10. Quality Requirements                                                     │
│     Quality tree, quality scenarios                                          │
├─────────────────────────────────────────────────────────────────────────────┤
│ 11. Risks and Technical Debt                                                 │
│     Known risks, technical debt items                                        │
├─────────────────────────────────────────────────────────────────────────────┤
│ 12. Glossary                                                                 │
│     Important domain and technical terms                                     │
└─────────────────────────────────────────────────────────────────────────────┘

text

arc42 Template (12 Sections):

┌─────────────────────────────────────────────────────────────────────────────┐
│  1. Introduction and Goals                                                   │
│     Requirements overview, quality goals, stakeholders                       │
├─────────────────────────────────────────────────────────────────────────────┤
│  2. Architecture Constraints                                                 │
│     Technical, organizational, and convention constraints                    │
├─────────────────────────────────────────────────────────────────────────────┤
│  3. System Scope and Context                                                 │
│     Business context, technical context                                      │
├─────────────────────────────────────────────────────────────────────────────┤
│  4. Solution Strategy                                                        │
│     Technology decisions, top-level decomposition, quality approaches        │
├─────────────────────────────────────────────────────────────────────────────┤
│  5. Building Block View                                                      │
│     Static decomposition: whitebox/blackbox at multiple levels               │
├─────────────────────────────────────────────────────────────────────────────┤
│  6. Runtime View                                                             │
│     Important scenarios, interactions, behaviors                             │
├─────────────────────────────────────────────────────────────────────────────┤
│  7. Deployment View                                                          │
│     Technical infrastructure, mapping of building blocks                     │
├─────────────────────────────────────────────────────────────────────────────┤
│  8. Cross-cutting Concepts                                                   │
│     Recurring patterns, approaches, principles                               │
├─────────────────────────────────────────────────────────────────────────────┤
│  9. Architecture Decisions                                                   │
│     Important decisions with rationale (may link to ADRs)                    │
├─────────────────────────────────────────────────────────────────────────────┤
│ 10. Quality Requirements                                                     │
│     Quality tree, quality scenarios                                          │
├─────────────────────────────────────────────────────────────────────────────┤
│ 11. Risks and Technical Debt                                                 │
│     Known risks, technical debt items                                        │
├─────────────────────────────────────────────────────────────────────────────┤
│ 12. Glossary                                                                 │
│     Important domain and technical terms                                     │
└─────────────────────────────────────────────────────────────────────────────┘

Complete arc42 Template

完整arc42模板

markdown

undefined

markdown

undefined

Architecture Documentation: [System Name]

架构文档：[系统名称]

Version: 1.0 Date: [Date] Status: Draft | Review | Final

版本： 1.0 日期： [日期] 状态： 草稿 | 评审中 | 最终版

1. Introduction and Goals

1. 引言与目标

1.1 Requirements Overview

1.1 需求概述

[Brief description of the system and its purpose. What business problem does it solve? Who are the main users?]

Key Features:

[Feature 1]
[Feature 2]
[Feature 3]

[系统及其用途的简要描述。它解决了什么业务问题？主要用户是谁？]

核心功能：

[功能1]
[功能2]
[功能3]

1.2 Quality Goals

1.2 质量目标

Priority	Quality Goal	Description
1	[Goal]	[Description]
2	[Goal]	[Description]
3	[Goal]	[Description]

优先级	质量目标	描述
1	[目标]	[描述]
2	[目标]	[描述]
3	[目标]	[描述]

1.3 Stakeholders

1.3 利益相关方

Role	Name/Team	Expectations
Product Owner	[Name]	[Expectations]
Development Team	[Team]	[Expectations]
Operations	[Team]	[Expectations]
Security	[Team]	[Expectations]

角色	姓名/团队	期望
产品负责人	[姓名]	[期望]
开发团队	[团队]	[期望]
运维团队	[团队]	[期望]
安全团队	[团队]	[期望]

2. Architecture Constraints

2. 架构约束

2.1 Technical Constraints

2.1 技术约束

Constraint	Description	Background
[TC-1]	[Description]	[Why this constraint exists]
[TC-2]	[Description]	[Why this constraint exists]

约束	描述	背景
[TC-1]	[描述]	[约束存在的原因]
[TC-2]	[描述]	[约束存在的原因]

2.2 Organizational Constraints

2.2 组织约束

Constraint	Description	Background
[OC-1]	[Description]	[Why this constraint exists]
[OC-2]	[Description]	[Why this constraint exists]

约束	描述	背景
[OC-1]	[描述]	[约束存在的原因]
[OC-2]	[描述]	[约束存在的原因]

2.3 Conventions

2.3 规范

Convention	Description
[CON-1]	[Description]
[CON-2]	[Description]

规范	描述
[CON-1]	[描述]
[CON-2]	[描述]

3. System Scope and Context

3. 系统范围与上下文

3.1 Business Context

3.1 业务上下文

[Diagram showing the system in its business environment, with actors and external systems it interacts with.]

mermaid

C4Context
    title System Context Diagram

    Person(user, "User", "End user of the system")
    System(system, "System Name", "System description")
    System_Ext(ext1, "External System 1", "Description")
    System_Ext(ext2, "External System 2", "Description")

    Rel(user, system, "Uses")
    Rel(system, ext1, "Calls API")
    Rel(system, ext2, "Sends events")

Actor/System	Description	Communication
[Actor 1]	[Description]	[Protocol/Format]
[External System 1]	[Description]	[Protocol/Format]

[展示系统在业务环境中的示意图，包含交互的参与者与外部系统。]

mermaid

C4Context
    title System Context Diagram

    Person(user, "User", "End user of the system")
    System(system, "System Name", "System description")
    System_Ext(ext1, "External System 1", "Description")
    System_Ext(ext2, "External System 2", "Description")

    Rel(user, system, "Uses")
    Rel(system, ext1, "Calls API")
    Rel(system, ext2, "Sends events")

参与者/系统	描述	通信方式
[参与者1]	[描述]	[协议/格式]
[外部系统1]	[描述]	[协议/格式]

3.2 Technical Context

3.2 技术上下文

[Technical details of integration: protocols, data formats, interfaces.]

Interface	Technology	Description
[API 1]	REST/JSON	[Description]
[Queue 1]	Kafka	[Description]
[File 1]	SFTP/CSV	[Description]

[集成的技术细节：协议、数据格式、接口。]

接口	技术	描述
[API 1]	REST/JSON	[描述]
[队列1]	Kafka	[描述]
[文件1]	SFTP/CSV	[描述]

4. Solution Strategy

4. 解决方案策略

4.1 Technology Decisions

4.1 技术决策

Decision	Technology	Rationale
Programming Language	C# (.NET 10)	[Rationale]
Database	PostgreSQL	[Rationale]
Message Broker	Kafka	[Rationale]
Cloud Platform	Azure	[Rationale]

决策	技术	理由
编程语言	C# (.NET 10)	[理由]
数据库	PostgreSQL	[理由]
消息中间件	Kafka	[理由]
云平台	Azure	[理由]

4.2 Top-Level Decomposition

4.2 顶层分解

[High-level description of how the system is structured.]

Approach: [Microservices / Modular Monolith / etc.]

Key Modules:

[系统结构的高层描述。]

架构方式： [微服务 / 模块化单体 / 其他]

核心模块：

4.3 Approaches to Achieve Quality Goals

4.3 质量目标实现方法

Quality Goal	Approach
Performance	Caching, async processing, optimized queries
Reliability	Redundancy, circuit breakers, retry patterns
Security	Defense in depth, encryption, audit logging

质量目标	实现方法
性能	缓存、异步处理、优化查询
可靠性	冗余、断路器、重试模式
安全性	纵深防御、加密、审计日志

5. Building Block View

5. 构建块视图

5.1 Level 1: Whitebox Overall System

5.1 第一层：系统整体白盒视图

mermaid

C4Container
    title Container Diagram

    Container(api, "API Gateway", "Kong", "Routes and secures API calls")
    Container(web, "Web Application", "Blazor", "User interface")
    Container(svc1, "Service 1", ".NET", "Business logic")
    Container(svc2, "Service 2", ".NET", "Business logic")
    ContainerDb(db, "Database", "PostgreSQL", "Stores data")
    ContainerQueue(queue, "Message Queue", "Kafka", "Async messaging")

    Rel(web, api, "Calls", "HTTPS")
    Rel(api, svc1, "Forwards", "gRPC")
    Rel(api, svc2, "Forwards", "gRPC")
    Rel(svc1, db, "Reads/Writes")
    Rel(svc1, queue, "Publishes")
    Rel(svc2, queue, "Subscribes")

Contained Building Blocks:

Building Block	Purpose
API Gateway	Request routing, authentication, rate limiting
Web Application	User interface and presentation
Service 1	[Core business function]
Service 2	[Core business function]

mermaid

C4Container
    title Container Diagram

    Container(api, "API Gateway", "Kong", "Routes and secures API calls")
    Container(web, "Web Application", "Blazor", "User interface")
    Container(svc1, "Service 1", ".NET", "Business logic")
    Container(svc2, "Service 2", ".NET", "Business logic")
    ContainerDb(db, "Database", "PostgreSQL", "Stores data")
    ContainerQueue(queue, "Message Queue", "Kafka", "Async messaging")

    Rel(web, api, "Calls", "HTTPS")
    Rel(api, svc1, "Forwards", "gRPC")
    Rel(api, svc2, "Forwards", "gRPC")
    Rel(svc1, db, "Reads/Writes")
    Rel(svc1, queue, "Publishes")
    Rel(svc2, queue, "Subscribes")

包含的构建块：

构建块	用途
API网关	请求路由、认证、限流
Web应用	用户界面与展示层
服务1	[核心业务功能]
服务2	[核心业务功能]

5.2 Level 2: [Building Block Name]

5.2 第二层：[构建块名称]

[Whitebox description of a specific building block, showing its internal structure.]

Responsibility: [What this block does]

Interfaces:

Internal Structure:

Component	Responsibility
[Component 1]	[Description]
[Component 2]	[Description]

[特定构建块的白盒描述，展示其内部结构。]

职责： [该构建块的功能]

接口：

内部结构：

组件	职责
[组件1]	[描述]
[组件2]	[描述]

6. Runtime View

6. 运行时视图

6.1 Scenario: [User Creates Order]

6.1 场景：[用户创建订单]

mermaid

sequenceDiagram
    participant U as User
    participant W as Web App
    participant A as API Gateway
    participant O as Order Service
    participant I as Inventory Service
    participant D as Database
    participant Q as Message Queue

    U->>W: Submit order
    W->>A: POST /orders
    A->>O: CreateOrder
    O->>I: CheckInventory
    I->>D: Query stock
    D-->>I: Stock levels
    I-->>O: Available
    O->>D: Save order
    O->>Q: Publish OrderCreated
    O-->>A: Order confirmed
    A-->>W: 201 Created
    W-->>U: Order confirmation

Description: [Explanation of the scenario and any important details]

mermaid

sequenceDiagram
    participant U as User
    participant W as Web App
    participant A as API Gateway
    participant O as Order Service
    participant I as Inventory Service
    participant D as Database
    participant Q as Message Queue

    U->>W: Submit order
    W->>A: POST /orders
    A->>O: CreateOrder
    O->>I: CheckInventory
    I->>D: Query stock
    D-->>I: Stock levels
    I-->>O: Available
    O->>D: Save order
    O->>Q: Publish OrderCreated
    O-->>A: Order confirmed
    A-->>W: 201 Created
    W-->>U: Order confirmation

描述： [场景说明及重要细节]

6.2 Scenario: [Another Important Scenario]

6.2 场景：[其他重要场景]

[Similar structure...]

[类似结构...]

7. Deployment View

7. 部署视图

7.1 Infrastructure Level 1

7.1 基础设施第一层

mermaid

C4Deployment
    title Deployment Diagram

    Deployment_Node(cloud, "Azure", "Cloud Platform") {
        Deployment_Node(aks, "AKS Cluster", "Kubernetes") {
            Container(api, "API Pods", "3 replicas")
            Container(svc, "Service Pods", "3 replicas")
        }
        Deployment_Node(data, "Data Tier") {
            ContainerDb(db, "Azure PostgreSQL", "Managed database")
            ContainerDb(redis, "Azure Redis", "Caching")
        }
    }

mermaid

C4Deployment
    title Deployment Diagram

    Deployment_Node(cloud, "Azure", "Cloud Platform") {
        Deployment_Node(aks, "AKS Cluster", "Kubernetes") {
            Container(api, "API Pods", "3 replicas")
            Container(svc, "Service Pods", "3 replicas")
        }
        Deployment_Node(data, "Data Tier") {
            ContainerDb(db, "Azure PostgreSQL", "Managed database")
            ContainerDb(redis, "Azure Redis", "Caching")
        }
    }

7.2 Infrastructure Elements

7.2 基础设施元素

Element	Technology	Description
Kubernetes Cluster	AKS	Container orchestration
Load Balancer	Azure LB	Traffic distribution
Database	Azure PostgreSQL	Persistent storage
Cache	Azure Redis	In-memory caching

元素	技术	描述
Kubernetes集群	AKS	容器编排
负载均衡器	Azure LB	流量分发
数据库	Azure PostgreSQL	持久化存储
缓存	Azure Redis	内存缓存

8. Cross-cutting Concepts

8. 横切关注点

8.1 Domain Model

8.1 领域模型

[Core domain entities and their relationships]

[核心领域实体及其关系]

8.2 Security

8.2 安全性

Authentication: OAuth 2.0 / OpenID Connect Authorization: Role-based access control (RBAC) Data Protection: Encryption at rest (AES-256), in transit (TLS 1.3)

认证： OAuth 2.0 / OpenID Connect 授权： 基于角色的访问控制（RBAC） 数据保护： 静态加密（AES-256）、传输加密（TLS 1.3）

8.3 Error Handling

8.3 错误处理

Strategy: Structured error responses with correlation IDs Logging: Structured logging with severity levels Monitoring: Distributed tracing with OpenTelemetry

策略： 带关联ID的结构化错误响应 日志： 带严重级别的结构化日志 监控： 基于OpenTelemetry的分布式链路追踪

8.4 Testability

8.4 可测试性

Unit Testing: xUnit, Moq, FluentAssertions Integration Testing: TestContainers E2E Testing: Playwright

单元测试： xUnit, Moq, FluentAssertions 集成测试： TestContainers 端到端测试： Playwright

9. Architecture Decisions

9. 架构决策

ID	Decision	Status	Date
ADR-001	[Decision title]	Accepted	[Date]
ADR-002	[Decision title]	Accepted	[Date]

[Link to detailed ADR documents]

ID	决策	状态	日期
ADR-001	[决策标题]	已接受	[日期]
ADR-002	[决策标题]	已接受	[日期]

[指向详细ADR文档的链接]

10. Quality Requirements

10. 质量需求

10.1 Quality Tree

10.1 质量树

mermaid

mindmap
    root((Quality))
        Performance
            Response Time
            Throughput
        Reliability
            Availability
            Recoverability
        Security
            Confidentiality
            Integrity
        Maintainability
            Modifiability
            Testability

mermaid

mindmap
    root((Quality))
        Performance
            Response Time
            Throughput
        Reliability
            Availability
            Recoverability
        Security
            Confidentiality
            Integrity
        Maintainability
            Modifiability
            Testability

10.2 Quality Scenarios

10.2 质量场景

ID	Scenario	Attribute	Target
QS-1	API response under load	Performance	P95 < 200ms
QS-2	System availability	Reliability	99.9%
QS-3	Add new payment provider	Modifiability	< 5 days

ID	场景	属性	目标
QS-1	高负载下的API响应	性能	P95 < 200ms
QS-2	系统可用性	可靠性	99.9%
QS-3	添加新支付提供商	可修改性	< 5天

11. Risks and Technical Debt

11. 风险与技术债务

11.1 Risks

11.1 风险

ID	Risk	Impact	Probability	Mitigation
R-1	[Risk description]	High	Medium	[Mitigation]
R-2	[Risk description]	Medium	Low	[Mitigation]

ID	风险描述	影响	概率	缓解措施
R-1	[风险描述]	高	中	[缓解措施]
R-2	[风险描述]	中	低	[缓解措施]

11.2 Technical Debt

11.2 技术债务

ID	Debt Item	Impact	Priority
TD-1	[Debt description]	[Impact]	High
TD-2	[Debt description]	[Impact]	Medium

ID	债务项	影响	优先级
TD-1	[债务描述]	[影响]	高
TD-2	[债务描述]	[影响]	中

12. Glossary

12. 术语表

Term	Definition
[Term 1]	[Definition]
[Term 2]	[Definition]
[Term 3]	[Definition]

text

undefined

术语	定义
[术语1]	[定义]
[术语2]	[定义]
[术语3]	[定义]

text

undefined

Section Guidelines

各节指南

When to Include Each Section

何时包含各节

Section	Always Include	Include If...
1. Introduction	✓	-
2. Constraints	✓	-
3. Context	✓	-
4. Solution Strategy	✓	-
5. Building Blocks	✓	-
6. Runtime		Important scenarios exist
7. Deployment	✓	-
8. Cross-cutting	✓	-
9. Decisions	✓	-
10. Quality		Quality requirements defined
11. Risks		Known risks exist
12. Glossary		Domain-specific terms

章节	必须包含	按需包含场景
1. 引言	✓	-
2. 约束	✓	-
3. 上下文	✓	-
4. 解决方案策略	✓	-
5. 构建块	✓	-
6. 运行时		存在重要场景时
7. 部署	✓	-
8. 横切关注点	✓	-
9. 架构决策	✓	-
10. 质量需求		已定义质量需求时
11. 风险		存在已知风险时
12. 术语表		存在领域特定术语时

Workflow

工作流程

When creating arc42 documentation:

Start with context: Sections 1-3 establish the "what" and "why"
Document decisions: Section 4 captures strategic choices
Detail structure: Section 5 shows how it's built
Show behavior: Section 6 demonstrates how it works
Map to infrastructure: Section 7 shows where it runs
Capture patterns: Section 8 documents recurring solutions
Record decisions: Section 9 links to ADRs
Define quality: Section 10 sets expectations
Acknowledge risks: Section 11 shows awareness
Define terms: Section 12 ensures shared understanding

创建arc42文档时：

从上下文开始：第1-3节明确“是什么”和“为什么”
记录决策：第4节捕获战略选择
细化结构：第5节展示系统构建方式
展示行为：第6节演示系统运行机制
映射到基础设施：第7节说明部署位置
记录模式：第8节文档化通用解决方案
归档决策：第9节关联到ADR文档
定义质量：第10节设定质量期望
识别风险：第11节体现风险意识
统一术语：第12节确保共识理解

References

参考资料

For detailed guidance:

Last Updated: 2025-12-26

如需详细指导：

最后更新： 2025-12-26