dotnet-backend-architecture

# .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](references/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](references/BACKEND_ARCHITECTURE_TEMPLATE.md) | 方針文書の章立てと設計判断の記録 | | [CLEAN_ARCHITECTURE_CHECKLIST.md](references/CLEAN_ARCHITECTURE_CHECKLIST.md) | 設計レビュー時の境界・依存・横断関心事の確認 | | [adr-design](../adr-design/SKILL.md) | 意思決定履歴、後継 ADR、設計スナップショットとの連携 | | [design-document](../design-document/SKILL.md) | 現在の設計ドキュメントの作成・整理 | ## Post-Run Reflection 複数ステップのワークフロー完了後は、[core § 5 Post-Run Reflection](../core/SKILL.md#5-post-run-reflection-continuous-improvement) の手順に従う。