arc42-documentation

arc42 ドキュメント作成スキル

このスキルを使用する場面

次のような場合に、このスキルを使用します。

• Arc42 ドキュメント作成タスク - arc42 アーキテクチャドキュメントのテンプレートとガイダンスを扱う場合
• 計画または設計 - Arc42 ドキュメント作成のアプローチに関するガイダンスが必要な場合
• ベストプラクティス - 確立されたパターンと標準に従いたい場合

概要

arc42 テンプレートを使用して、包括的なアーキテクチャドキュメントを作成します。

必須：ドキュメントを優先するアプローチ

arc42 ドキュメントを作成する前に、次の手順を実行します。

1. アーキテクチャドキュメントのパターンについて、docs-management スキルを呼び出します
2. MCP サーバー（perplexity）を通じて arc42 の現行バージョンを確認します
3. 公式の 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 Gateway	リクエストのルーティング、認証、レート制限
Web Application	ユーザーインターフェースとプレゼンテーション
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 E2E テスト： 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. コンテキストから始める：セクション 1～3 で「何を」「なぜ」を明確にします
2. 決定を文書化する：セクション 4 で戦略的な選択を記録します
3. 構造を詳述する：セクション 5 で構築方法を示します
4. 動作を示す：セクション 6 で動作方法を説明します
5. インフラストラクチャに対応付ける：セクション 7 で実行場所を示します
6. パターンを記録する：セクション 8 で繰り返し利用されるソリューションを文書化します
7. 決定を記録する：セクション 9 で ADR へのリンクを記載します
8. 品質を定義する：セクション 10 で期待事項を設定します
9. リスクを認識する：セクション 11 でリスクを把握していることを示します
10. 用語を定義する：セクション 12 で共通の理解を確保します

参考資料

詳細なガイダンスについては、以下を参照してください。

---

最終更新日： 2025-12-26