arc42-documentation

Name: arc42-documentation
Author: melodic-software

github.com/melodic-software开发2851 次安装今天更新

代码仓库

关于 arc42-documentation

arc42-documentation 是用于编写软件架构文档的技能，面向需要依据 arc42 模板开展规划和设计的团队。它提供 12 个章节的文档结构及逐步编写流程。

主要功能

01覆盖 arc42 的 12 个章节
02提供章节纳入建议
03按工作流组织文档编写
04包含 Mermaid 架构图示例

适用场景

01为新系统创建架构文档
02记录系统结构与运行场景
03整理部署、质量和风险信息

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/melodic-software/claude-code-plugins --skill arc42-documentation

安装后在 Claude Code 中输入/arc42-documentation确认已加载。

详细介绍

arc42 文档技能

何时使用此技能

适用于以下情况：

Arc42 文档任务 - 编写 arc42 架构文档模板和指南
规划或设计 - 需要 Arc42 文档编写方法的指导
最佳实践 - 希望遵循成熟的模式和标准

概述

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

强制要求：文档优先

创建 arc42 文档之前：

调用 docs-management 技能，了解架构文档模式
通过 MCP 服务（perplexity）核实 arc42 的当前版本
以 arc42 官方模板为指导

arc42 模板结构

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                                     │
└─────────────────────────────────────────────────────────────────────────────┘

完整的 arc42 模板

# Architecture Documentation: [System Name]

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

---

## 1. Introduction and Goals

### 1.1 Requirements Overview

[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 Quality Goals

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

### 1.3 Stakeholders

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

---

## 2. Architecture Constraints

### 2.1 Technical Constraints

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

### 2.2 Organizational Constraints

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

### 2.3 Conventions

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

---

## 3. System Scope and Context

### 3.1 Business Context

[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 1]	[Description]	[Protocol/Format]
[External System 1]	[Description]	[Protocol/Format]

3.2 技术上下文

[集成技术详情：协议、数据格式、接口。]

接口	技术	描述
[API 1]	REST/JSON	[Description]
[Queue 1]	Kafka	[Description]
[File 1]	SFTP/CSV	[Description]

4. 解决方案策略

4.1 技术决策

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

4.2 顶层分解

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

方法： [微服务 / 模块化单体 / 等]

关键模块：

4.3 实现质量目标的方法

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

5. 构建块视图

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

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 应用程序	用户界面和呈现
Service 1	[Core business function]
Service 2	[Core business function]

5.2 第 2 层：[Building Block Name]

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

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

接口：

内部结构：

组件	职责
[Component 1]	[Description]
[Component 2]	[Description]

6. 运行时视图

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

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 场景：[另一个重要场景]

[类似结构...]

7. 部署视图

7.1 基础设施第 1 层

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 基础设施元素

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

8. 横切概念

8.1 领域模型

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

8.2 安全性

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

8.3 错误处理

策略： 使用关联 ID 的结构化错误响应 日志记录： 带严重性级别的结构化日志 监控： 使用 OpenTelemetry 进行分布式追踪

8.4 可测试性

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

9. 架构决策

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

[详细 ADR 文档链接]

10. 质量要求

10.1 质量树

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

10.2 质量场景

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

11. 风险和技术债务

11.1 风险

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

11.2 技术债务

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

12. 术语表

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

各章节指南

各章节的适用条件

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

工作流

创建 arc42 文档时：

从上下文开始：第 1 至 3 节阐明“是什么”和“为什么”
记录决策：第 4 节概述战略选择
详述结构：第 5 节展示其构建方式
展示行为：第 6 节说明其工作方式
映射到基础设施：第 7 节展示其运行位置
记录模式：第 8 节记录反复出现的解决方案
记录决策：第 9 节链接到 ADR
定义质量：第 10 节设定预期
说明风险：第 11 节体现风险意识
定义术语：第 12 节确保理解一致

参考资料

详细指南：

最后更新： 2025-12-26

支持 Markdown

登录后评论

基本信息

作者: melodic-software
仓库: melodic-software/claude-code-plugins
分类: 开发
安装次数: 51
GitHub Stars: 28

报告问题