| 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 は目的に対して必要な範囲で適用し、儀式的な
プロジェクト分割や抽象化を増やさない。
- 既存の未コミット変更は保持し、対象外のファイルを変更しない。
ワークフロー
- 依頼を分類する。
- 新規方針: 現状の制約を調査して設計方針と未決定事項を作成する。
- 既存方針のレビュー: 実装と文書を比較し、違反、リスク、改善案を優先度付きで示す。
- 決定の変更:
adr-design に委譲し、旧決定を残した後継 ADR として記録する。
- 現在の構成の説明・整理:
design-document と連携し、スナップショットを更新する。
- リポジトリを調査する。
.sln、.csproj、Program.cs、API エンドポイント、
Application/Domain/Infrastructure 相当のコード、永続化、設定、テスト、README、
既存 ADR・設計書を確認する。実装がない場合は、設計前提を仮定として明示する。
- 境界を定義する。 次の責務を、実際のプロジェクト名または論理境界に対応付ける。
- Domain: エンティティ、値オブジェクト、集約、ドメインサービス、
不変条件。HTTP、EF Core、SDK、設定、ログに依存しない。
- Application: ユースケース、入力・出力モデル、ポート、トランザクション境界、
認可の判断。Domain を使うが、データベースや外部 SDK の実装を参照しない。
- Infrastructure: EF Core、外部 API、メッセージング、ファイル、キャッシュ、
認証プロバイダーなどのアダプター。Application のポートを実装する。
- API/Presentation: HTTP、ルーティング、モデルバインディング、形式変換、
HTTP ステータス、認証ミドルウェア。ユースケースを呼び、業務ルールを持たない。
- 依存方向を検証する。 依存は
API → Application → Domain、
Infrastructure → Application/Domain を基本とし、Domain から外側へ向けない。
Infrastructure の実装を Application が直接 new していないこと、API が DbContext や
外部 SDK を直接操作していないことを確認する。DI の Composition Root は外側に置く。
- ユースケースとデータフローを記述する。 代表的な読み取り・書き込み・失敗経路
について、HTTP 入力 → Application → Domain → ポート → アダプター → 応答の流れ、
トランザクション、整合性、再試行、キャンセル、冪等性を記録する。
- 横断方針を決める。 事実に基づいて、次を設計書に含める。
- API のバージョニング、入力検証、ページング、エラー形式、Problem Details。
- 認証と認可の境界、テナント分離、機密情報の扱い。
- 永続化モデルと Domain モデルの分離、マイグレーション、競合制御。
- 外部連携のタイムアウト、リトライ、サーキットブレーカー、Outbox 等の要否。
- 構造化ログ、トレース、メトリクス、相関 ID、個人情報のマスキング。
- Domain/Application の単体テスト、API・Infrastructure の統合テスト、
契約テスト、テスト用ポート実装。
- 過剰設計を確認する。 抽象化が一実装の単なるラッパーになっていないか、
CQRS・Mediator・イベント駆動が要件上必要か、分割が運用コストに見合うかを確認する。
採用しない案も理由とともに短く記録する。
- 成果物を更新する。 現在の構成は
design-document の docs/design.md に、
長期的で代替案のある決定は adr-design の ADR に記録する。方針だけを新規作成
する場合は BACKEND_ARCHITECTURE_TEMPLATE.md
を使う。
- 整合性を検証する。 プロジェクト参照、namespace、依存方向、文書リンク、
テスト境界、未決定事項が実装・設定と矛盾しないことを確認する。矛盾が解消できない
場合は、確定事項として書かず要確認として残す。
設計レビューの判定基準
重大な違反を先に報告する。特に Domain から Infrastructure への依存、API からの
直接 DB 操作、認証認可の欠落、機密情報のログ出力、リトライによる二重実行、
トランザクション境界の不明確さは高優先度とする。単なる命名やフォルダー配置は、
依存方向や責務に影響しない限り問題として扱わない。
出力形式
作業完了時は次の順で簡潔に報告する。
- 設計判断: 採用する境界、依存方向、主要な横断方針。
- 成果物: 作成・更新した設計書または ADR のパスと変更内容。
- レビュー結果: 該当する場合、
重大度 / 場所 / 問題 / 根拠 / 改善案 の表。
- 前提と未決定事項: リポジトリから確認できない事項、ユーザー確認が必要な事項。
- 次の実装境界: コード変更を行わず、実装時に守るべき短いチェック項目。
エラー処理
| 状況 | 必須の対応 |
|---|
| 対象の .NET プロジェクトが見つからない | 推測で設計せず、汎用方針として書き、未確認であることを明記する。 |
| 既存コードと設計書が矛盾する | 実装と文書の差分を分けて示し、勝手に履歴を改変しない。 |
| Clean Architecture の適用範囲が曖昧 | 1つの確認質問で対象サービス・移行範囲・制約を確認する。 |
| 技術選択に複数の妥当案がある | 判断基準、採用案、不採用案、未決定事項を ADR または方針に記録する。 |
| 依存方向を静的に確認できない | プロジェクト参照と代表的なコード箇所を根拠にし、未検証の範囲を明示する。 |
| 既存の未コミット変更がある | 上書きせず、要求対象の文書だけを慎重に更新する。 |
References
Post-Run Reflection
複数ステップのワークフロー完了後は、core § 5 Post-Run Reflection の手順に従う。
