ddd-architecture-doc

DDD アーキテクチャドキュメント

包括的な DDD アーキテクチャドキュメントを生成します。C4 モデル図（L1～L4）、ADR、ドメインモデルのドキュメント、API ドキュメント、意思決定ログ、チームコミュニケーション用テンプレートを作成します。

ワークフロー

アーキテクチャドキュメントを生成する際は、以下の 5 ステップのワークフローに従ってください。

Step 1: Understand Context — Project size, team, tech stack, domain
Step 2: Identify Audiences — Business / dev / ops
Step 3: Select C4 Level — L1 for business, L2 for ops, L3 for dev team
Step 4: Check Decisions — Any existing ADRs? Need to create new ones?
Step 5: Generate Output — Combine diagrams + ADRs + templates into one doc

情報が不足している場合：まず一般的なパターン（例：E コマース）に基づく最善の推定を提示し、そのうえで不足している具体的な情報を一覧にしてください。「请提供更多信息」とだけ答えることは避けてください。

対応範囲

✅ 得意なこと

1. C4 モデル図の生成 — L1 システムコンテキスト／L2 コンテナー／L3 コンポーネント／L4 コード（Mermaid）
2. ADR（アーキテクチャ決定記録） — テンプレート + インデックス + ステータス追跡
3. ドメインモデルのドキュメント — 集約の説明 + エンティティ／値オブジェクト／イベントの一覧
4. API ドキュメント — CQRS のコマンド／クエリ分離に基づく API 仕様

⚠️ 条件が必要なこと

1. 既存のアーキテクチャ上の決定 — ADR に記録するには、まず決定が必要です
2. 識別済みの限界づけられたコンテキスト — C4 L1 図を作成するには、少なくともシステムにどの BC があるかを把握している必要があります
3. 既知の技術スタック — L2 コンテナー図を生成するには、フレームワーク／データベース／ミドルウェアを把握している必要があります

❌ 対象外（適用されない状況）

1. アーキテクチャ上の決定がない場合 → まず決定し、その後ドキュメントを作成（ddd-architecture-selector にルーティング）
2. 個人プロジェクト → README とインラインコメントで十分です
3. アーキテクチャの選定が必要な場合 → ddd-architecture-selector
4. コードレビューが必要な場合 → ddd-code-reviewer

対象読者

このスキルは、バックエンド開発者（DDD アーキテクチャを実装する方）、ソフトウェアアーキテクト（パターンを評価・選定する方）、テックリード（チームの実装をレビューする方）、DDD 初心者（ドメイン駆動設計の基礎を学ぶ方）を対象としています。

ルール

1. すべてのアーキテクチャ上の決定を ADR として記録する必要があります。
2. C4 図はレベル 1→4 の階層に従う必要があります。
3. ドメインモデルのドキュメントでは、限界づけられたコンテキストを参照する必要があります。
4. すべての意思決定ログに日付、コンテキスト、選択肢、根拠を含める必要があります。

C4 モデルの 4 つのレベル

DDD → C4 のマッピング

C4 Level     | DDD Context                   | Audience
─────────────┼───────────────────────────────┼────────────────
L1 Context   | All bounded contexts + externals | Business, Architects
L2 Container | Per-BC deployment units        | Architects, DevOps
L3 Component | BC internal layers (Adapter/App/Domain/Infra) | Dev Team
L4 Code      | Aggregate internals (entities, VOs, events) | Developers

L1：システムコンテキスト — システムと外部との関係を示す

graph TB
    Customer["👤 Customer"] --> BC1["Bounded Context 1"]
    Customer --> BC2["Bounded Context 2"]
    Admin["👤 Admin"] --> BC3["Bounded Context 3"]
    BC1 --> PaymentGW["💳 Payment Gateway"]

L2：コンテナー — 1 つの BC のデプロイ単位

graph TB
    Web["Web App"] --> API["API (Spring Boot)"]
    API --> DB[("Database (PostgreSQL)")]
    API --> Queue["Event Queue (RabbitMQ)"]

L3／L4 の完全な Mermaid コード例は references/01-c4-examples.md を参照してください。

各レベルの使いどころ：L1 はプロジェクトのキックオフ、L2 は運用チームへの引き継ぎ、L3 は日常的な開発の参照用、L4 は複雑な集約に限って使用します。

ADR（アーキテクチャ決定記録）

ADR テンプレート

# ADR-{NNN}: {Short Title}

## Status
{Proposed / Accepted / Deprecated / Superseded}

## Context / Decision / Alternatives / Consequences
- **Context**: Why is this decision needed?
- **Decision**: What did we decide?
- **Alternatives**: Options considered with pros/cons, mark chosen
- **Consequences**: Positive + negative impacts
- **Related**: ADR-{NNN}: {related}

ADR ステータス追跡テーブル

| ADR# | Title | Status | Date | Superseded By |
|------|-------|:------:|:----:|:----:|
| 001 | Choose COLA Architecture | Accepted | 2024-03-15 | — |
| 002 | CQRS Strategy L2 | Accepted | 2024-03-20 | — |
| 003 | MySQL over PostgreSQL | Deprecated | 2024-02-01 | ADR-005 |

ドメインモデルのドキュメント

各集約を記録します。

## Aggregate: {Name}
- **Root**: {ClassName} | **Id**: {IdType}
- **Entities**: Table of entity / owner / lifecycle
- **Value Objects**: Table of VO / fields / immutable
- **Domain Events**: Table of event / trigger / consumer
- **Invariants**: 1. {Invariant 1}
- **State Machine**: ```mermaid stateDiagram-v2```

API ドキュメント — CQRS のコマンド／クエリ分離

API タイプ	メソッド	例	CQRS モデル
コマンド	POST/PUT/DELETE	POST /orders	コマンドモデル
クエリ	GET	GET /orders?status=PAID	クエリモデル

コマンド API：ドメインの振る舞いをトリガーし、ドメインイベントを発行します。冪等性キーが必要です。 クエリ API：クエリモデルから読み取ります（読み取り専用 DB が別に存在する場合があります）。副作用はありません。

アーキテクチャ意思決定ログ

中央インデックスを管理します。

docs/adrs/
├── README.md          ← Auto-generated ADL index
├── ADR-001-title.md
└── ...

ベストプラクティス：ADR ファイル 1 つにつき決定 1 つとします。ADR はコードと同じリポジトリに置きます。CI でインデックスを自動生成します。

ドキュメントのメンテナンスポリシー

ポリシー	頻度	担当者
PR 時に ADR と図を合わせて更新	コード変更のたび	開発者
C4 図の四半期監査	四半期ごと	アーキテクト
ADL インデックスの自動生成	ADR 変更のたび	CI
アーキテクチャドキュメント全体のレビュー	毎月	アーキテクチャチーム

基本原則：コードによってアーキテクチャが変わる場合、同じ PR でドキュメントも変更します。

注意点 — よくある落とし穴

1. C4 のレベルを誤って使う — 各レベルには明確な定義があります。混同しないでください。
2. ADR の記録が遅すぎる — 決定と同時に記録してください。一言だけでも構いません。
3. ドキュメントとコードが同期していない — アーキテクチャを変更するたびに更新する必要があります。
4. 決定理由を書かずに図だけを描く — C4 は What を示し、ADR は Why を説明します。
5. 図が複雑すぎる — 1 枚あたり 5～7 ノードを上限とします。
6. ドキュメントの作りすぎ —「開発するうえで他の人が知る必要のあること」に焦点を当てます。
7. ADR に代替案を書かない — 他の案を選ばなかった理由を必ず記録します。
8. 対象読者を考慮しない — 対象読者に応じて異なる C4 レベルを使用します。

FAQ

Q1：ドキュメントにはどのツールを使うべきですか？ まず Mermaid を使い、複雑さが増したら Structurizr を検討してください。

Q2：どの C4 レベルの図を作成する必要がありますか？ L1 + L2 は必須です。L3 はチームの規模に応じて作成します（5 人超のチームには推奨）。

Q3：ドキュメントを最新に保つにはどうすればよいですか？ PR のチェックボックス、ADR の整合性を確認する CI、月次レビューを組み合わせます。

Q4：レガシーシステムにドキュメントがない場合はどうすればよいですか？ まず AS-IS の L1 図を描き、重要な ADR を記録し、各 sprint で 1 つの BC を完成させていきます。

Q5：ADR はどの程度詳しく書く必要がありますか？ 少なくとも背景、決定、代替案（2 つ以上）、影響を含めてください。

Q6：複数人が同じ BC のドキュメントを同時に変更する場合、どうすればよいですか？ Git の競合解決の仕組みで対応できます。PR Review ではドキュメントも合わせてレビューしてください。

セキュリティと安全性

このスキルはドキュメント作成のみを行います。ユーザーデータを収集せず、外部サービスやネットワークにもアクセスせず、実行可能なスクリプトも含みません。

キーワード

• キーワード：architecture documentation, アーキテクチャドキュメント, ADR, C4 diagram, C4 モデル, architecture decision record, アーキテクチャ決定記録, domain model doc, ドメインモデルのドキュメント, 技術ドキュメント, アーキテクチャ図, system context, container diagram, component diagram, code diagram, アーキテクチャレビュー, ドキュメントテンプレート, architecture decision log

リファレンス

ファイル	内容	参照する場面
references/01-c4-examples.md	EC 向けの C4 L1～L4 Mermaid の完全な例	コピーして使える C4 図が必要な場合
references/02-adr-templates.md	3 種類の ADR テンプレート（標準、軽量、技術）	新しい ADR を作成する場合
references/03-doc-templates.md	3 種類のアーキテクチャドキュメントテンプレート（完全版、軽量、オンボーディング）	文書を作成するための構成が必要な場合
references/04-toolchain.md	ツールの推奨事項（Structurizr、Mermaid、PlantUML、ArchUnit）	ツールや自動化について質問された場合
references/05-team-templates.md	チーム内コミュニケーションのテンプレート（レビュー依頼、変更通知）	チームへの通知やレビュー依頼が必要な場合
references/06-arch-decision-log.md	ADL インデックス形式と CI 自動化	ADR の追跡を維持または自動化する場合
references/07-domain-model-doc.md	集約／BC のドキュメント作成パターン	ドメインモデルを文書化する場合
references/08-api-doc-patterns.md	CQRS API ドキュメント作成パターンと OpenAPI 仕様	CQRS を使用した API を文書化する場合
references/09-trace-anti-patterns.md	アーキテクチャドキュメントのアンチパターン（5 カテゴリ）	よくあるドキュメント作成の誤りを避けたい場合
references/10-faq-deep.md	詳細な FAQ（マイクロサービスの ADR、レガシーシステム、セキュリティ）	高度な質問や特殊なケースについて質問された場合

関連スキル

• ddd-architecture-selector — アーキテクチャの選定（文書化する前に、意思決定を行います）。インストール：npx skills add full-stack-skills/ddd-skills --skill ddd-architecture-selector。
• ddd-architecture-evaluator — アーキテクチャの定期的な健全性チェック。インストール：npx skills add full-stack-skills/ddd-skills --skill ddd-architecture-evaluator。
• ddd-code-reviewer — コードレベルでの DDD 準拠チェック。インストール：npx skills add full-stack-skills/ddd-skills --skill ddd-code-reviewer。
• ddd-cqrs-architecture — API ドキュメント作成に関する CQRS の詳細。インストール：npx skills add full-stack-skills/ddd-skills --skill ddd-cqrs-architecture。
• ddd-architecture-awesome — DDD の概念の概要。インストール：npx skills add full-stack-skills/ddd-skills --skill ddd-architecture-awesome。