software-csharp-backend

C# バックエンドエンジニアリング

クイックリファレンス

判断項目	デフォルト	備考
ランタイム	現行の .NET LTS とその C# バージョン	バージョンを指定する前に、dotnet のサポートポリシーページで現行の LTS とサポート終了日を確認してください。サポート終了まで1年以内のターゲットは、安定した状態ではなく、追跡対象の移行として扱ってください。デフォルトでは現行の LTS を選択し、チームが毎年アップグレードする場合に限り、より新しい STS を選択してください
API スタイル	新しいエンドポイントには Minimal API	フィルターやアクション結果が多数ある大規模な CQRS のサーフェスにはコントローラー
永続化（SQL、書き込み中心）	EF Core	クエリの形状が複雑で、手作業で調整した SQL が有効な場合は Dapper を使用してください
永続化（SQL、クエリ中心）	Dapper	アグリゲートがある場合は、書き込みパスに EF Core を組み合わせてください
永続化（ドキュメント）	MongoDB ドライバー	スキーマの多様性が実際に必要な場合に使用し、慣習的に使わないでください
バックグラウンドワーカー	IHostedService / BackgroundService	最初からリース、グレースフルシャットダウン、ポイズンメッセージ処理を追加してください
レジリエンス	Microsoft.Extensions.Resilience (Polly v8)	AddStandardResilienceHandler() は5つの戦略を外側から順に実行します：レートリミッター → 合計タイムアウト → 再試行 → サーキットブレーカー → 試行タイムアウト。デフォルトではすべての HTTP メソッドを再試行します。安全でないメソッドや厳しい期限には、デフォルトを上書きしてください。再試行は1つのレイヤーだけで行ってください。たとえば、ConfigureHttpClientDefaults（サービスのデフォルト設定など）ですでにラップされているクライアントに追加したハンドラーや、再試行するクライアントまたは EF の実行戦略を囲むアプリケーションレベルの再試行では、試行回数が乗算されます。references/resilience-policy-defaults.md を参照してください
OpenAPI	組み込みの ASP.NET Core OpenAPI (Microsoft.AspNetCore.OpenApi)	リポジトリですでに使用している場合を除き、Swashbuckle を追加しないでください

その他のタスクの振り分け先：

• NUnit フィクスチャの設計、WireMock/Testcontainers のセットアップ、またはフレークの削減 → $qa-testing-nunit
• nuke/Build.cs、CI ターゲットの順序付け、またはアーティファクトの公開 → $ops-nuke-cicd
• レガシーな ILogger または Serilog の書き換え自動化 → $dev-structured-logs

このスキルを使用する場面

• C# / .NET バックエンドサービスの構築またはレビュー（このスキルはライブラリの C#/.NET を担当します。software-backend は .NET の作業をここに振り分けます）
• ASP.NET Core の API スタイル（コントローラー、Minimal API、バックグラウンドワーカー）の選択
• EF Core、Dapper、または MongoDB を使ったデータアクセスの実装
• .NET サービスへのレジリエンス、オブザーバビリティ、またはセキュリティのベースラインの追加
• .NET バックエンドコードのリファクタリング、または一般的なアンチパターンの検出

このスキルを使用しない場面

• 一般的なバックエンドのパターン（Node.js、Python、Go、Rust） → software-backend
• NUnit フィクスチャの設計とテストインフラストラクチャ → qa-testing-nunit
• NUKE パイプラインのターゲットと CI/CD → ops-nuke-cicd
• ILogger/Serilog の移行自動化 → dev-structured-logs
• 単一サービスの範囲を超えるシステムアーキテクチャ → software-architecture-design
• セキュリティ監査と脅威モデリング → software-security-appsec

ワークフロー

1. 依頼された変更を分類します（新機能、リファクタリング、バグ修正、レビュー）。
2. 実装の詳細に入る前に、ランタイムの形態を選択します。ターゲットフレームワークの制約、マルチターゲット、レガシーシステムの移行については、references/version-compatibility-notes.md を読み込みます。 references/scenario-guides.md を読み込み、HTTP サービスの場合は references/aspnet-core-api-patterns.md も読み込みます。
3. 言語とコーディングの標準を適用します。 references/csharp-language-practices.md と references/dotnet-coding-standards.md を読み込みます。
4. 内部を編集する前に、アーキテクチャと境界を確認します。 references/backend-architecture-principles.md と references/modular-architecture-principles.md を読み込みます。
5. クエリ／書き込みの形式に基づいて、永続化と一貫性の戦略を選択します。 references/data-access-patterns.md を読み込みます。EF Core を選択した場合は、references/efcore-persistence-patterns.md も読み込みます。
6. 外部 I/O と長時間実行される処理に、回復性の動作を追加します。 references/reliability-and-resilience.md と references/resilience-policy-defaults.md を読み込みます。
7. リスクと境界に基づいてテストを定義します。 references/testing-practices.md を読み込みます。新しい NUnit コンポーネントテストのフィクスチャを作成する場合は、assets/test-fixture-template-nunit.cs を起点にします。
8. ログ、トレース、メトリクス、ヘルスプローブ、運用性のデフォルトを追加します。 references/observability-standards.md を読み込みます。また、API／ランタイムのデプロイ時のデフォルトについては、references/runtime-ops-checklist.md を読み込みます。サービスが分散型またはクラウドネイティブとして設計されている場合は、Aspire 向けプロファイルについて references/scenario-guides.md も読み込みます。
9. 認証、検証、シークレットの取り扱いを確認します。 references/security-baseline.md を読み込みます。
10. 変更した動作について、フィードバックループ検証を実行します。 リポジトリ独自のビルド、ユニットテスト、API テストのターゲットを実行します（NUKE ベースのリポジトリでは、定義されているビルドターゲットを実行します）。パイプラインのターゲットを編集する場合は、$ops-nuke-cicd を使用します。
11. アンチパターンのチェックリストに照らして、最終レビューを実施します。 references/code-review-checklist.md を読み込みます。

実施すること／避けること

キャンセルと期限の契約。

キャンセル可能なすべてのリクエストおよびワーカーの境界で CancellationToken を受け取り、データベース、HTTP、キュー、遅延処理の呼び出しまで伝播させます。親の期限がある場合は、残り時間から子のタイムアウトを導出します。キュー処理やスケジュール済み処理では、操作の期限を定義し、ホストのシャットダウンによるキャンセルと組み合わせます。キャンセルに対応できない依存関係については、文書に記載します。クライアントの切断や期限切れを汎用的な 500 エラーに変換しないでください。テストでは外部呼び出し中にキャンセルし、部分的な変更をコミットせず、バックグラウンドタスクもリークせずに処理が停止することを確認します。

ルール：Claude が該当するファイルを編集するとき、この不変条件は rules/dotnet/csharp.md によって読み込まれます。

実施すること	避けること
アプリケーションサービスを小規模に保ち、依存関係を明示する	ドメインロジックを HTTP、DB ドライバーの型、またはフレームワーク固有のクラスに直接結合する
想定される失敗に対して、決定論的なドメイン／アプリケーションの結果を返す	例外を握りつぶしたり、根本原因を曖昧なエラーメッセージに置き換えたりする
すべての非同期レイヤーと外部呼び出しに CancellationToken を渡す	コントローラーでキャンセルを止め、下流の呼び出しを続行させる
IOptions<T> の検証を使ってオプションをモデル化し、無効な起動時設定は速やかに失敗させる	オプションを検証せず、設定をサービスに直接バインドする
API スタイルを意図的に選び、ミドルウェアの順序を明示する	明確なエラー形式の方針なしに、Minimal API、コントローラー、独自のエンドポイントフレームワークを混在させる
サードパーティ製ラッパーを追加する前に、組み込みの ASP.NET Core OpenAPI と ProblemDetails を使う	組み込み機能で十分なのに、Swashbuckle や MediatR を追加する
チームの慣習ではなく、ユースケースの形状に合わせて永続化方式を選ぶ	タイムアウトと冪等性が保証されていないリトライを使う
テレメトリとセキュリティチェックを完了の定義に含める	構造化ログ、トレース、メトリクス、ヘルスシグナルなしでエンドポイントをリリースする
単体テストと統合テストをそれぞれ別の境界で記述する	単体テストと統合テストの関心事を同じテストフィクスチャに混在させる
—	イベントハンドラー以外で async void を使う
—	複数の並行操作／スレッド間で同じ DbContext インスタンスを共有する
—	キャプティブ依存関係（スコープ付きサービスに依存するシングルトン）

既知の落とし穴

• 明確な契約戦略やエラー形式のポリシーがないまま、最小限の API、コントローラー、独自のエンドポイントフレームワークを混在させること。
• キャンセルをコントローラーの境界で止めてしまい、その後の HTTP、EF Core、キュー、キャッシュの呼び出しが実行され続けること。
• EF Core の既定値を高負荷時も安全だとみなすこと。遅延読み込み、暗黙の追跡、クエリの整形不足は、隠れたコストを頻繁に生みます。1つのクエリで2つ以上のコレクションに Include を使うと、行数が増加します（デカルト積の爆発）。references/efcore-persistence-patterns.md を参照してください。
• 重複排除やタイムアウトの調整を行わず、べき等でないハンドラー、トランザクションスコープ、サードパーティへの呼び出しに対してリトライを使用すること。
• グレースフルシャットダウン、リースやロックの所有権、ポイズンメッセージの処理を備えずにバックグラウンドワーカーをリリースすること。
• オプションの検証、起動時の失敗チェック、明示的なシークレットの取り扱いをせずに、構成をサービスへ直接バインドすること。
• 対象とする EF Core バージョンの NativeAOT のサポートと制限、シリアライザーのメタデータ、動的読み込みの要件を確認する前に、Native AOT を選ぶこと。通常の Dapper はランタイムリフレクションと IL emit を使用するため、AOT セーフではありません。AOT では、生の ADO.NET または Dapper.AOT を使用してください。実際に発行して各依存関係のトリミング／AOT サポートを確認し、IL2xxx／IL3xxx のトリミング／AOT 警告が出た場合は発行を失敗させてください。そうでなければ、標準ランタイムを維持してください。
• リクエストごとに所有権を持つ HttpClient／ハンドラーを作成して破棄し、ポートを使い果たすこと。既定では、有効期間の短いファクトリークライアントを使用してください。想定される DNS の変更に合わせて SocketsHttpHandler.PooledConnectionLifetime を設定した長寿命のクライアントも有効です。Cookie に依存するセッションでは、ファクトリーを使用する前にハンドラーのプーリングと Cookie の分離を確認してください（Microsoft の有効期間に関するガイダンス）。
• デプロイ形態に応じた GC モードの検討を怠ること。net8 では、Server GC（ASP.NET Core の既定）は認識されているプロセッサ数に合わせてヒープのサイズを調整するため、小規模なコンテナーや共有コンテナーでは過剰に割り当てることがあります。その場合は、DATAS（Dynamic Adaptation to Application Sizes）、DOTNET_GCHeapHardLimit、または Workstation GC の利用を検討してください。net9 以降では、DATAS はすでに既定で有効です。専用のスループット重視のポッドでは、まず測定し、データで裏付けられる場合に限って DATAS を無効にしてください。対象フレームワークでの現在の動作は、DATAS のドキュメントページで確認してください。

よくあるアンチパターン

• 境界やポリシーとしての価値がない、ほぼ単なる中継ラッパーで構成された「クリーンアーキテクチャ」レイヤーを構築すること。
• 想定されるドメイン上の結果に対して、明示的な結果やエラーの契約ではなく、例外を返すこと。
• 実際に必要なのが、特化したクエリハンドラーや集約の永続化境界だけである場合でも、あらゆる場所でリポジトリ抽象化を共有すること。
• ミドルウェア、フィルター、オプション、またはレジリエンスハンドラーを意図的に使わず、その場しのぎのヘルパーに横断的な振る舞いを隠すこと。
• ユニットテストの接合点、フェイク時間、決定論的な失敗ケースを未検証のままにして、統合テストだけを安全策とすること。

ナビゲーション

参考資料

• C# 言語プラクティス
• Dotnet コーディング標準
• バックエンドアーキテクチャの原則
• モジュラーアーキテクチャの原則
• ASP.NET Core API パターン
• データアクセスパターン
• EF Core 永続化パターン
• シナリオガイド
• 信頼性とレジリエンス
• レジリエンスポリシーのデフォルト設定
• テストプラクティス
• オブザーバビリティ標準
• ランタイム運用チェックリスト
• バージョン互換性に関する注意事項
• セキュリティベースライン
• コードレビューのチェックリスト
• スキルのソース：厳選した一次資料とモジュラーアーキテクチャを補足する参考資料です。

テンプレート

• API ホストテンプレート
• サービスクラステンプレート
• オプション設定テンプレート
• レジリエント HTTP クライアントテンプレート
• Dapper クエリハンドラーテンプレート
• Mongo リポジトリテンプレート
• テストデータビルダーテンプレート
• NUnit テストフィクスチャテンプレート
• プルリクエストチェックリストテンプレート

関連スキル

• software-backend → 一般的なバックエンドパターンと複数言語に関するガイダンス
• software-architecture-design → システムレベルの設計と分解
• software-security-appsec → セキュリティ監査と脅威モデリング
• software-code-review → レビューワークフローと判断パターン
• qa-testing-nunit → NUnit フィクスチャの設計とテストインフラストラクチャ
• ops-nuke-cicd → NUKE ビルドパイプラインと CI/CD ターゲット
• dev-structured-logs → 構造化ログへの移行

既知のバグ、リグレッション、フレームワーク／コンパイラ／ランタイムの落とし穴、バージョン固有のクラッシュや回避策に関するガイダンスは、現行の事実として扱う前に、最新の一次ウェブソースで検証する必要があります。まず data/sources.json を確認し、バージョンとサポート期間についてはブログよりも Microsoft の公式ドキュメントを優先してください。

学びのループ

過去の判断や落とし穴が関係する場合は、learnings.consolidated.md があれば参照してください。必要な履歴を確認する場合、または利用可能な代替資料としてのみ、learnings.md を使用してください。それ以外の場合は、どちらも参照しないでください。

適用後、覚えておく価値のあるパターン、防止すべき間違い、または意外だった分野の事実に遭遇した場合は、agents-skills-feedback-loop/scripts/append_learning.py を使って、日付入りの箇条書きを 1 件 learnings.md に追記してください。SKILL.md 自体は変更しないでください。