architecture-advisor

アーキテクチャアドバイザー

基本原則

1. 推奨する前に質問する — プロジェクトを理解せずにアーキテクチャを決めつけてはいけません。まず質問票を実施し、ドメイン、チーム、存続期間、制約について情報を集めます。
2. 適切な規模のアーキテクチャを選ぶ — 最適なアーキテクチャとは、プロジェクトの実際の複雑さに対応できる最もシンプルなものです。CRUD アプリに DDD は必要ありません。スタートアップにクリーンアーキテクチャは必要ありません。目指す姿ではなく、実際の要件に複雑さを合わせます。
3. アーキテクチャは固定ではない — どのアーキテクチャにも進化の道筋があります。まずシンプルに始め、複雑さが求める段階で構造を追加します。チームが進化させる時期を判断できるよう、決定内容を文書化します。
4. サポート対象の4つのアーキテクチャ — dotnet-claude-kit は、Vertical Slice Architecture（VSA）、Clean Architecture（CA）、DDD + Clean Architecture、Modular Monolith のパターンを第一級の機能として提供します。それぞれに固有の強みとトレードオフがあります。

アーキテクチャに関する質問票

アーキテクチャを推奨する前に、次の6つのカテゴリにわたって質問します。すべての質問がすべてのプロジェクトに当てはまるわけではないため、該当しない質問は省略してください。

カテゴリ1：ドメインの複雑さ

#	質問	低い傾向	高い傾向
1	システムが管理する、異なるビジネスエンティティはいくつありますか？	エンティティが10個未満	関連性のあるエンティティが20個以上
2	ビジネスルールでは、複数のエンティティが相互に作用しますか？	ルールはエンティティごとの CRUD	エンティティ群をまたぐ複雑な不変条件
3	複数のステップからなるビジネスワークフローはありますか？	シンプルなリクエスト → レスポンス	サガ、承認チェーン、状態マシン
4	ドメインエキスパートは専門用語を使いますか？	汎用的な用語（作成、更新）	ユビキタス言語（引受審査、裁定）

カテゴリ2：チームと組織

#	質問	低い傾向	高い傾向
5	開発チームの規模はどのくらいですか？	開発者が1～3人	開発者が8人以上、複数のチーム
6	異なるチームがシステムの異なる部分を担当していますか？	すべてを単一チームが担当	ビジネスドメインに沿ってチームを編成
7	チームの .NET 経験レベルはどのくらいですか？	初級者、または経験が混在	上級者、パターンの経験が豊富

カテゴリ3：システムの存続期間と規模

#	質問	低い傾向	高い傾向
8	想定するシステムの存続期間はどのくらいですか？	2年未満、MVP／プロトタイプ	5年以上、長期運用する製品
9	同時ユーザー数、または1秒あたりのリクエスト数はどのくらいですか？	100 RPS 未満	1000 RPS 以上、負荷が変動
10	システムは機能領域ごとに独立してスケールする必要がありますか？	負荷が均一	特定箇所に負荷が集中し、独立したスケーリングが必要

カテゴリ4：規制とコンプライアンス

#	質問	低い傾向	高い傾向
11	監査証跡やコンプライアンス要件はありますか？	基本的なログで十分	完全な監査証跡、SOX/HIPAA/PCI
12	システムの部分ごとにセキュリティ境界が異なりますか？	認証境界は単一	マルチテナント、データ分離

カテゴリ5：既存のコードベース

#	質問	低い傾向	高い傾向
13	新規開発ですか、それとも既存システムの改修ですか？	新規開発、ゼロから開始	既存システムの改修、レガシーから移行
14	チームが従っている既存のアーキテクチャパターンはありますか？	確立されたパターンはない	強固な規約が確立されている

カテゴリ6：統合の複雑さ

#	質問	低い傾向	高い傾向
15	統合する外部システムはいくつありますか？	シンプルな API が0～2個	複雑な契約を持つシステムが5個以上
16	イベント駆動型、または非同期の通信が必要ですか？	同期リクエスト／レスポンス	イベントソーシング、pub/sub、結果整合性

意思決定マトリクス

アンケートの回答をアーキテクチャの推奨案に対応付けます。

プロファイル	推奨アーキテクチャ	理由
ドメインの複雑さが低く、チームが小規模で、ライフタイムが短い	垂直スライスアーキテクチャ	儀式的な作業が最小限で、機能を素早く提供でき、理解しやすい
ドメインの複雑さが低～中程度で、チームの規模を問わず、API を中心とする	垂直スライスアーキテクチャ	機能の凝集性が高く、操作ごとに 1 ファイルで構成でき、Minimal API に自然に適合する
ドメインの複雑さが中程度で、チームが中規模で、ライフタイムが長い	クリーンアーキテクチャ	プロジェクト参照によって境界を強制し、テスト可能なドメインと明確な依存関係の方向を実現する
ドメインの複雑さが高く、専門的な語彙があり、不変条件が複雑	DDD + クリーンアーキテクチャ	集約が不変条件を保護し、値オブジェクトがドメインの概念をモデル化し、ドメインイベントが副作用を疎結合にする
複数の境界づけられたコンテキストがあり、ドメインごとにチームが分かれ、独立デプロイの可能性がある	モジュラーモノリス	モジュールの分離、独立したデータストア、マイクロサービスへの進化経路を実現する
既存のレイヤードアーキテクチャを持つブラウンフィールド	クリーンアーキテクチャ	N 層アーキテクチャを使ってきたチームにとって馴染みがあり、依存関係の方向を改善しながらレイヤー分離を維持する

判断材料が食い違う場合

判断材料が異なるアーキテクチャを示している場合：

1. よりシンプルなものを選ぶ — 判断に迷ったら、VSA から始めて進化させます
2. ドメインの複雑さを優先する — ドメインの複雑さが高い場合、チームの規模やライフタイムに関する判断材料より優先します
3. チームの慣れも重要 — CA に習熟したチームは、技術的には VSA のほうがシンプルでも、VSA を学ぶより CA を使うほうが生産性を高められます
4. コンプライアンス要件が構造を決める — 規制要件によって、より厳格な境界（CA または DDD）が求められることがよくあります

パターン

垂直スライスアーキテクチャ（VSA）

レイヤーではなく、機能ごとに構成します。各操作は自己完結したスライスです。

src/MyApp.Api/
  Features/
    Orders/CreateOrder.cs    # Request + Handler + Response + Endpoint
    Orders/GetOrder.cs
  Common/
    Behaviors/ValidationBehavior.cs
    Persistence/AppDbContext.cs

最適な用途： CRUD 中心のアプリ、API、MVP、小～中規模のチーム、短～中程度のライフタイム。 スキルを読み込む： vertical-slice

クリーンアーキテクチャ（CA）

依存関係逆転を取り入れた同心円状のレイヤーです。中心にドメインを置き、外縁にインフラストラクチャを配置します。

src/
  MyApp.Domain/              # Entities, interfaces, domain logic
  MyApp.Application/         # Use cases, DTOs, validation
  MyApp.Infrastructure/      # EF Core, external services
  MyApp.Api/                 # Endpoints, middleware

最適な用途： 複雑さが中程度で、長期間運用するシステム、レイヤードパターンに習熟したチーム。 スキルを読み込む： clean-architecture

DDD + クリーンアーキテクチャ

集約、値オブジェクト、ドメインイベントなどの戦術的 DDD パターンを取り入れたクリーンアーキテクチャです。

src/
  MyApp.Domain/              # Aggregates, value objects, domain events, domain services
  MyApp.Application/         # Use cases orchestrating aggregates
  MyApp.Infrastructure/      # Persistence, external service adapters
  MyApp.Api/                 # Thin endpoints

最適な用途： 複雑なドメイン、専門的な語彙、厳格な不変条件、経験豊富なチーム。 スキルを読み込む： ddd + clean-architecture

モジュラーモノリス

単一のデプロイ可能なユニット内に独立したモジュールを配置し、それぞれの内部で独自のアーキテクチャを採用します。

src/
  MyApp.Host/                # Wires modules together
  Modules/
    Orders/                  # Own features, own DbContext, own architecture
    Catalog/                 # Can use VSA, CA, or DDD internally
  MyApp.Shared/              # Integration event contracts only

最適な用途： 複数の境界づけられたコンテキスト、ドメインごとに分かれたチーム、将来的なマイクロサービスへの切り出し。 テンプレートを読み込む： modular-monolith

進化の道筋

アーキテクチャは一度決めたら終わりではありません。システムは進化します。ここでは一般的な移行経路を紹介します。

移行元	移行先	きっかけ	方法
VSA	CA	ハンドラーを超えてドメインロジックが増大する	Domain レイヤーと Application レイヤーを抽出し、機能はユースケースとして維持する
VSA	モジュラーモノリス	複数の境界づけられたコンテキストが出現する	機能をモジュールにまとめ、モジュール境界を追加する
CA	DDD + CA	不変条件が複雑化し、プリミティブ型への固執が強まる	集約、値オブジェクト、ドメインイベントを導入する
モノリス	モジュラーモノリス	チーム間の競合や、共有データベースへの密結合が発生する	独自の DbContexts とスキーマを持つモジュールに分割する
モジュラーモノリス	マイクロサービス	独立したスケーリングや独立デプロイが必要になる	モジュールを個別にデプロイ可能なサービスに切り出す

アンチパターン

CRUD アプリにクリーンアーキテクチャを選ぶ

// BAD — 4 projects, 6+ files per feature for simple CRUD
src/MyApp.Domain/Entities/Product.cs
src/MyApp.Application/Products/CreateProduct/CreateProductCommand.cs
src/MyApp.Application/Products/CreateProduct/CreateProductHandler.cs
src/MyApp.Application/Products/CreateProduct/CreateProductValidator.cs
src/MyApp.Infrastructure/Persistence/ProductRepository.cs
src/MyApp.Api/Endpoints/ProductEndpoints.cs

// GOOD — VSA: 1 file for a simple CRUD feature
src/MyApp.Api/Features/Products/CreateProduct.cs

あらゆる場所で DDD を使う

// BAD — value objects and aggregates for a settings table
public class UserSettings : AggregateRoot  // overkill
{
    public ThemeName Theme { get; private set; }  // value object for "dark"/"light"?
    public void ChangeTheme(ThemeName theme) { /* domain event? really? */ }
}

// GOOD — simple entity for simple data
public class UserSettings
{
    public Guid UserId { get; init; }
    public string Theme { get; set; } = "light";
}

時期尚早なマイクロサービス化

// BAD — splitting into 5 microservices on day one with 2 developers
OrderService (own repo, own DB, own CI/CD)
CatalogService (own repo, own DB, own CI/CD)
IdentityService (own repo, own DB, own CI/CD)
NotificationService (own repo, own DB, own CI/CD)
GatewayService (own repo, own CI/CD)

// GOOD — start as a modular monolith, extract when you have evidence
src/
  Modules/Orders/
  Modules/Catalog/
  Modules/Identity/
  Modules/Notifications/

アンケートを省略する

// BAD — "I always use Clean Architecture"
User: "Set up a new project for a todo app"
Agent: *immediately scaffolds 4-project CA solution*

// GOOD — ask first, then recommend
User: "Set up a new project for a todo app"
Agent: "Let me ask a few questions about your project to recommend the best architecture..."
Agent: *runs questionnaire, recommends VSA for low-complexity app*

選定ガイド

シナリオ	推奨
新規プロジェクトで、要件が不明な場合	質問票を実施します
シンプルな CRUD API で、開発者が 1〜3 人の場合	VSA
複雑さが中程度で、長期運用を想定し、経験豊富なチームがある場合	Clean Architecture
複雑なドメインで、専門用語が使われる場合	DDD + Clean Architecture
複数の境界づけられたコンテキストがあり、複数のチームで開発する場合	Modular Monolith
既存の N 階層コードベースをモダナイズする必要がある場合	Clean Architecture（慣れ親しんだ移行方式）
MVP／スタートアップで、スピードを優先する場合	VSA
規制やコンプライアンスへの対応が重視される場合	Clean Architecture または DDD（境界を徹底）
将来的に独立したスケーリングが必要になる場合	Modular Monolith（抽出に対応可能）