dotnet-backend-architecture

name	dotnet-backend-architecture
description	.NET バックエンドの設計方針を Clean Architecture を中心に作成・レビューする。 ユーザーが .NET API、ASP.NET Core、Clean Architecture、レイヤー分割、 ドメイン駆動設計、Application/Domain/Infrastructure、依存方向、設計方針、 バックエンド設計書、または .NET のアーキテクチャレビューに言及した場合は、 skill 名を明示しなくても必ず使用する。設計書・ADR の作成とレビューを対象とし、 コード生成や大規模リファクタリングは行わない。トリガー: .NET バックエンド、 ASP.NET Core、Clean Architecture、レイヤードアーキテクチャ、DDD、依存関係、 API設計、設計方針、バックエンドアーキテクチャ。

.NET バックエンド設計方針

.NET バックエンドの現在の設計または新しい設計方針を、依存方向と責務境界が 明確な設計書・ADRとして整理する。Clean Architecture はフォルダー名の規則では なく、内側のビジネスルールが外側の技術詳細に依存しないことを中心に適用する。

対象範囲

• 設計書、ADR、アーキテクチャレビューの作成・更新。
• ASP.NET Core API の境界、ユースケース、ドメイン、永続化、外部連携、 認証認可、エラー、テスト、可観測性に関する設計判断。
• 実装を読んで、方針との整合性、依存方向、責務の漏れを指摘すること。

次は対象外とする。ユーザーが明示しない限り、コード生成、プロジェクト雛形の作成、 大規模リファクタリング、実際の Azure リソースの作成、ライブラリの導入。

前提

• 実装・設定・既存ドキュメントを先に確認し、事実、ユーザーの決定、仮定、 未決定事項を分ける。
• ASP.NET Core、EF Core、メッセージング、クラウドサービスなどは、リポジトリで 確認できない限り採用済みと断定しない。
• Clean Architecture、DDD、CQRS は目的に対して必要な範囲で適用し、儀式的な プロジェクト分割や抽象化を増やさない。
• 既存の未コミット変更は保持し、対象外のファイルを変更しない。

ワークフロー

1. 依頼を分類する。
   • 新規方針: 現状の制約を調査して設計方針と未決定事項を作成する。
   • 既存方針のレビュー: 実装と文書を比較し、違反、リスク、改善案を優先度付きで示す。
   • 決定の変更: adr-design に委譲し、旧決定を残した後継 ADR として記録する。
   • 現在の構成の説明・整理: design-document と連携し、スナップショットを更新する。
2. リポジトリを調査する。 .sln、.csproj、Program.cs、API エンドポイント、 Application/Domain/Infrastructure 相当のコード、永続化、設定、テスト、README、 既存 ADR・設計書を確認する。実装がない場合は、設計前提を仮定として明示する。
3. 境界を定義する。 次の責務を、実際のプロジェクト名または論理境界に対応付ける。
   • Domain: エンティティ、値オブジェクト、集約、ドメインサービス、 不変条件。HTTP、EF Core、SDK、設定、ログに依存しない。
   • Application: ユースケース、入力・出力モデル、ポート、トランザクション境界、 認可の判断。Domain を使うが、データベースや外部 SDK の実装を参照しない。
   • Infrastructure: EF Core、外部 API、メッセージング、ファイル、キャッシュ、 認証プロバイダーなどのアダプター。Application のポートを実装する。
   • API/Presentation: HTTP、ルーティング、モデルバインディング、形式変換、 HTTP ステータス、認証ミドルウェア。ユースケースを呼び、業務ルールを持たない。
4. 依存方向を検証する。 依存は API → Application → Domain、 Infrastructure → Application/Domain を基本とし、Domain から外側へ向けない。 Infrastructure の実装を Application が直接 new していないこと、API が DbContext や 外部 SDK を直接操作していないことを確認する。DI の Composition Root は外側に置く。
5. ユースケースとデータフローを記述する。 代表的な読み取り・書き込み・失敗経路 について、HTTP 入力 → Application → Domain → ポート → アダプター → 応答の流れ、 トランザクション、整合性、再試行、キャンセル、冪等性を記録する。
6. 横断方針を決める。 事実に基づいて、次を設計書に含める。
   • API のバージョニング、入力検証、ページング、エラー形式、Problem Details。
   • 認証と認可の境界、テナント分離、機密情報の扱い。
   • 永続化モデルと Domain モデルの分離、マイグレーション、競合制御。
   • 外部連携のタイムアウト、リトライ、サーキットブレーカー、Outbox 等の要否。
   • 構造化ログ、トレース、メトリクス、相関 ID、個人情報のマスキング。
   • Domain/Application の単体テスト、API・Infrastructure の統合テスト、 契約テスト、テスト用ポート実装。
7. 過剰設計を確認する。 抽象化が一実装の単なるラッパーになっていないか、 CQRS・Mediator・イベント駆動が要件上必要か、分割が運用コストに見合うかを確認する。 採用しない案も理由とともに短く記録する。
8. 成果物を更新する。 現在の構成は design-document の docs/design.md に、 長期的で代替案のある決定は adr-design の ADR に記録する。方針だけを新規作成 する場合は BACKEND_ARCHITECTURE_TEMPLATE.md を使う。
9. 整合性を検証する。 プロジェクト参照、namespace、依存方向、文書リンク、 テスト境界、未決定事項が実装・設定と矛盾しないことを確認する。矛盾が解消できない 場合は、確定事項として書かず要確認として残す。

設計レビューの判定基準

重大な違反を先に報告する。特に Domain から Infrastructure への依存、API からの 直接 DB 操作、認証認可の欠落、機密情報のログ出力、リトライによる二重実行、 トランザクション境界の不明確さは高優先度とする。単なる命名やフォルダー配置は、 依存方向や責務に影響しない限り問題として扱わない。

出力形式

作業完了時は次の順で簡潔に報告する。

1. 設計判断: 採用する境界、依存方向、主要な横断方針。
2. 成果物: 作成・更新した設計書または ADR のパスと変更内容。
3. レビュー結果: 該当する場合、重大度 / 場所 / 問題 / 根拠 / 改善案 の表。
4. 前提と未決定事項: リポジトリから確認できない事項、ユーザー確認が必要な事項。
5. 次の実装境界: コード変更を行わず、実装時に守るべき短いチェック項目。

エラー処理

状況	必須の対応
対象の .NET プロジェクトが見つからない	推測で設計せず、汎用方針として書き、未確認であることを明記する。
既存コードと設計書が矛盾する	実装と文書の差分を分けて示し、勝手に履歴を改変しない。
Clean Architecture の適用範囲が曖昧	1つの確認質問で対象サービス・移行範囲・制約を確認する。
技術選択に複数の妥当案がある	判断基準、採用案、不採用案、未決定事項を ADR または方針に記録する。
依存方向を静的に確認できない	プロジェクト参照と代表的なコード箇所を根拠にし、未検証の範囲を明示する。
既存の未コミット変更がある	上書きせず、要求対象の文書だけを慎重に更新する。

References

Reference	用途
BACKEND_ARCHITECTURE_TEMPLATE.md	方針文書の章立てと設計判断の記録
CLEAN_ARCHITECTURE_CHECKLIST.md	設計レビュー時の境界・依存・横断関心事の確認
adr-design	意思決定履歴、後継 ADR、設計スナップショットとの連携
design-document	現在の設計ドキュメントの作成・整理

Post-Run Reflection

複数ステップのワークフロー完了後は、core § 5 Post-Run Reflection の手順に従う。