dotnet-exception-handling

.NET の例外処理品質の改善

目的

.NET の例外処理におけるアンチパターンを体系的に調査し、修正します。.NET アプリケーションでよく見られる例外処理の誤り10項目を検出、記録し、修正します。

次の場合に使用：本番環境への移行前、コード品質監査、セキュリティレビュー、または .NET コードベースへの参加時。

使用方法

# Investigation only (default)
/dotnet-exception-handling <path-to-dotnet-project>

# Filter by severity
/dotnet-exception-handling <project-path> --priority critical

# Auto-implement all fixes
/dotnet-exception-handling <project-path> --fix-all

引数：

• project-path：.csproj または .sln を含むディレクトリ（デフォルト：現在のディレクトリ）
• --priority：critical | high | medium | low | all（デフォルト：all）
• --fix-all：修正を自動的に実装します（デフォルト：調査のみ）

よくある10の誤り

1. Exception を広範囲に捕捉する - 特定の型ではなく基底の Exception を捕捉する
2. 例外を黙って握りつぶす - エラーを隠す空の catch ブロック
3. throw ex; を使用する - スタックトレースをリセットする（throw; を使用）
4. すべてを try/catch で囲む - 防御的なコードによる煩雑化
5. 制御フローに例外を使用する - 想定される条件に対してパフォーマンスのオーバーヘッドが発生する
6. 非同期処理の await を忘れる - バックグラウンドスレッドで未処理の例外が発生する
7. バックグラウンドタスクの例外を無視する - ファイア・アンド・フォーゲットによりエラーが失われる
8. 汎用的な例外型を使用する - 特定の型ではなく、曖昧な new Exception() を使用する
9. 内部例外を失う - 例外チェーンを壊す
10. グローバルハンドラーがない - 一元的なエラー処理がなく、スタックトレースが露出する

詳細な説明、検出パターン、修正テンプレート → reference.md を参照

実行ワークフロー

フェーズ 1：調査（6 ステップ）

ステップ 1：プロジェクトの検出

• .csproj、.sln ファイルをスキャンする
• プロジェクトの種類（ASP.NET Core、ワーカーサービス、ライブラリ）を特定する
• 対象範囲を見積もるために C# ファイルの数を数える

ステップ 2：並列分析

• 専門エージェントを5つ起動する：
  • バックグラウンドワーカーの専門家
  • API レイヤーの専門家
  • サービスレイヤーの専門家
  • データレイヤーの専門家
  • インフラストラクチャの専門家

ステップ 3：違反の検出

• パターンマッチングには rg -P（ripgrep の PCRE モード）を使用する：

  # Mistake #1: Broad catches
  rg -P 'catch\s*\(Exception\b' --glob '*.cs'
  
  # Mistake #2: Empty catches
  rg -P 'catch[^{]*\{\s*(//[^\n]*)?\s*\}' --glob '*.cs'
  
  # Mistake #3: throw ex
  rg 'throw\s+ex;' --glob '*.cs'
  

• パターンの完全な一覧は reference.md を参照

ステップ 4：重大度の分類

• CRITICAL：セキュリティ（スタックトレースの露出、グローバルハンドラーの欠如）
• HIGH：信頼性（例外の握りつぶし、広範囲の捕捉）
• MEDIUM：コード品質（過剰な try/catch）
• LOW：スタイル上の問題

ステップ 5：調査結果のレポート

• ファイル名と行番号への参照を含む Markdown を生成する
• コードスニペットと推奨される修正
• 優先度に基づくロードマップ

ステップ 6：ナレッジの記録

• .claude/runtime/logs/EXCEPTION_INVESTIGATION_YYYY-MM-DD.md に保存する
• プロジェクトのメモリを更新する

フェーズ 2：開発（--fix-all の場合）

ステップ 7：デフォルトのワークフローを調整

• 調査結果を含む GitHub issue を作成する
• 修正用の worktree を設定する
• GlobalExceptionHandler、Result などを実装する
• 包括的なテストを作成する（TDD）
• 3エージェントによるレビュー（レビュアー、セキュリティ、設計思想）

ステップ 8：検証

• すべてのテストに合格する
• セキュリティ：スタックトレースがゼロであること
• パフォーマンス：p99 のオーバーヘッドが <5ms であること

クイックスタートの例

例 1：調査のみ

/dotnet-exception-handling ./src/MyApi

出力：違反23件の調査レポート（CRITICAL 1件、HIGH 8件、MEDIUM 12件、LOW 2件）

例 2：重大な問題のみ修正

/dotnet-exception-handling ./src/MyApi --priority critical --fix-all

出力：GitHub issue と、GlobalExceptionHandler を実装する PR（テスト15件を含む）

例 3：完全な修正

/dotnet-exception-handling ./src/MyApi --fix-all

出力：違反23件を修正、テスト67件、PR の準備完了（CI 通過）

コアアーキテクチャパターン

GlobalExceptionHandler（IExceptionHandler）

ASP.NET Core 向けの例外から HTTP への一元的なマッピング：

public class GlobalExceptionHandler : IExceptionHandler
{
    public async ValueTask<bool> TryHandleAsync(
        HttpContext httpContext,
        Exception exception,
        CancellationToken cancellationToken)
    {
        var (statusCode, title) = exception switch
        {
            ArgumentException => (400, "Invalid request"),
            NotFoundException => (404, "Not found"),
            ConflictException => (409, "Conflict"),
            _ => (500, "Internal server error")
        };

        httpContext.Response.StatusCode = statusCode;
        await httpContext.Response.WriteAsJsonAsync(new ProblemDetails
        {
            Status = statusCode,
            Title = title,
            Detail = statusCode >= 500
                ? "An error occurred"
                : exception.Message
        }, cancellationToken);

        return true;
    }
}

// Registration in Program.cs
builder.Services.AddExceptionHandler<GlobalExceptionHandler>();
app.UseExceptionHandler();

メリット：スタックトレースがゼロ、一貫性のあるレスポンス、コントローラー内で try/catch が不要

Result パターン

検証のためのレールウェイ指向プログラミング（想定される条件に例外を使用しない）：

public Result<Order> ValidateOrder(CreateOrderDto dto)
{
    if (dto.Items.Count == 0)
        return Result<Order>.Failure("Order must have items");

    return Result<Order>.Success(new Order(dto));
}

// Controller usage
var result = await _service.ValidateOrder(dto);
return result.Match(
    onSuccess: order => Ok(order),
    onFailure: error => BadRequest(error)
);

メリット：例外より100倍高速、明示的なエラー処理、より優れた合成

完全な実装例 → examples.md を参照

ナビゲーションガイド

補足ファイルを読むタイミング

reference.md - 次の情報が必要なときに読みます。

• 10種類すべての例外処理ミスの詳細な説明
• ripgrep/grep 用の完全な検出パターン
• 各ミスタイプの修正テンプレート
• セキュリティに関する考慮事項（OWASP 準拠、スタックトレースの漏えい防止）
• 重大度分類の参考情報
• 統合パターン（Azure SDK、EF Core、Service Bus）

examples.md - 次の情報が必要なときに読みます。

• 各ミスの修正前と修正後のコード例
• 完全に動作する実装（GlobalExceptionHandler、Result、DbContextExtensions）
• 実際のシナリオ（注文処理、決済システム）
• 単体テストと統合テストのパターン
• コピーしてすぐに使えるコード

patterns.md - 次の情報が必要なときに読みます。

• アーキテクチャの判断フローチャート（グローバルハンドラーと try/catch、Result と例外）
• バックグラウンドワーカーの例外処理パターン
• Azure SDK の例外変換パターン
• EF Core の同時実行制御とトランザクションのパターン
• パフォーマンスのベンチマーク（Result と例外）
• 避けるべきアンチパターン

ワークフローの統合

このスキルは、次の2つの標準的なワークフローを統括します。

1. 調査ワークフロー（フェーズ1）：範囲の決定 → 調査 → 分析 → 分類 → 報告 → 記録
2. デフォルトワークフロー（フェーズ2、--fix-all の場合）：要件 → アーキテクチャ → TDD → 実装 → レビュー → CI/CD

参考資料

• 記事：.NET における例外処理のよくある10のミス
• Microsoft：例外に関するベストプラクティス
• ASP.NET Core：Web API でのエラー処理
• 調査ワークフロー：~/.amplihack/.claude/workflow/INVESTIGATION_WORKFLOW.md
• デフォルトワークフロー：~/.amplihack/.claude/workflow/DEFAULT_WORKFLOW.md

バージョン履歴

• v1.0.0 (2026-02-10)：CyberGym の調査に基づく初期実装（52件の違反を修正、87件のテスト）

既知の制限事項

• IExceptionHandler には .NET 6+ が必要です
• Result パターンは C# 7.0+ を対象とします（読み取り専用構造体、式形式のメンバー）
• パターンは ASP.NET Core 固有です（クラスライブラリには適用できない場合があります）