code-analysis

.NET コード分析

診断出力の上限

警告／エラーと簡潔な結果だけを残し、定型的で冗長な出力や診断用のコンソール出力は避けてください。テスト実行時は、ネイティブの進行状況表示／ANSI 表示を保持してください。失敗した場合は、関連する診断とスタックフレームだけを表示し、重複を除いて、応答あたり 80 行／8 KiB を上限としてください。未解決の問題について追加の診断を収集する場合は、モデルコンテキストの外部にサイズ制限付きの成果物として保存し、そのリンクを共有して、サイズ制限内の該当箇所だけを確認してください。ログやレポート全体を出力したり、フィルタリングによってコマンドの終了コードを隠したりしないでください。

次の場合に使用

• リポジトリでファーストパーティの .NET アナライザーが必要な場合
• CI でアナライザー警告によって失敗させる必要がある場合
• チームに AnalysisLevel または AnalysisMode のガイダンスが必要な場合
• リポジトリで Roslyn の警告を段階的に昇格させる方針が必要な場合

次の場合は使用しない

• サードパーティ製アナライザーの選定のみを行う場合
• フォーマットのみを行う場合

入力

• 最も近い AGENTS.md
• プロジェクトファイルまたは Directory.Build.props
• 現在のアナライザーの重大度ポリシー

AI エージェントの必須ルール

交渉の余地はありません。違反すると、ユーザーの明示的な意図を損ないます。

1. プロジェクトで TreatWarningsAsErrors または WarningsAsErrors が設定されている場合、絶対に無効化または削除しないでください。コメントアウトしたり、false に設定したり、条件で囲んだり、ビルドを通すために <TreatWarningsAsErrors>false</TreatWarningsAsErrors> を追加したりしてはいけません。
2. ユーザーがエラーとして扱うことを選択した警告に対して、ユーザーが抑制を明示的に承認しない限り、<NoWarn> または #pragma warning disable を追加してはいけません。
3. ビルドを成功させるために、.editorconfig で重大度をひそかに引き下げてはいけません（例：error を warning または none にする）。
4. 警告をエラーとして扱うことでビルドが失敗する場合は、コードを修正してください。修正の規模が大きすぎる場合は、その警告 ID を延期するかユーザーに確認してください。
5. 警告が多すぎて一度に修正できない場合は、件数とカテゴリをユーザーに報告し、どれから取り組むか確認してください。独断でポリシーを無効化してはいけません。

ワークフロー

flowchart TD
    A[Start] --> B{New or legacy project?}
    B -->|New| C[TreatWarningsAsErrors=true immediately]
    B -->|Legacy| D[dotnet build, count warnings by ID]
    D --> E{"< 30 warnings?"}
    E -->|Yes| F[Fix all, then enable TreatWarningsAsErrors]
    E -->|No| G[Report counts to user, ask which batch first]
    G --> H[Add selected IDs to WarningsAsErrors]
    H --> I[Fix that batch, verify build]
    I --> J{More batches?}
    J -->|Yes| G
    J -->|No| F
    C --> K[Set AnalysisLevel latest-recommended]
    F --> K
    K --> L[Promote security CA3xxx/CA5xxx to error in .editorconfig]
    L --> M[Validate: build + CI green]

1. サードパーティ製パッケージより先に、SDK アナライザーから始めてください。
2. プロジェクトの成熟度を判定してください：新規か、既存／レガシーか。
3. Directory.Build.props で EnableNETAnalyzers、AnalysisLevel、AnalysisMode を有効にしてください。
4. 適切な警告昇格戦略を適用してください（以下を参照）。
5. ルールごとの重大度は、リポジトリルートの .editorconfig に設定してください。
6. CI では dotnet build をアナライザーのゲートとして使用してください。

警告昇格戦略

新規プロジェクト

すぐに Directory.Build.props で次を設定してください。

• TreatWarningsAsErrors = true
• AnalysisLevel = latest-recommended
• .editorconfig で Security カテゴリを error に設定

マージ前にすべての警告を修正してください。

レガシープロジェクト — 段階的な昇格

レガシーコードベースで一律に TreatWarningsAsErrors を設定すると、数百から数千件のエラーが発生します。エージェントが一度にすべて修正することはできず、コンテキストがあふれ、修正の品質が低下します。段階的に昇格してください。

フェーズ 1：軽微な整理（ここから開始）

機械的に行える、最も手間の少ない修正：

• CS8019 — 不要な using ディレクティブ（削除する）
• CS0219 — 代入後に使用されていない変数（削除する）
• CS0168 — 宣言後に使用されていない変数（削除する）
• CS1591 — 公開メンバーに XML コメントがない（コメントを追加するか、内部コードでは無効化する）
• CS0612 — メッセージなしで廃止されたメンバーが使用されている（廃止されていない API に置き換える）
• CS0618 — メッセージ付きで廃止されたメンバーが使用されている（移行ガイダンスに従う）

WarningsAsErrors に CS8019;CS0219;CS0168 を追加してください。すべて修正してから、フェーズ 2 に進みます。

フェーズ 2：コード品質（どのカテゴリに取り組むかユーザーに確認）

• CA2000 — スコープを抜ける前にオブジェクトを破棄する（信頼性）
• CA1062 — 公開メソッドの引数を検証する（設計）
• CA1822 — メンバーを static としてマークする（パフォーマンス）
• CA1860 — 長さの確認に Enumerable.Any() を使用しない（パフォーマンス）
• CA1861 — 引数に定数配列を使用しない（パフォーマンス）
• CA2007 — ConfigureAwait の呼び出しを検討する（信頼性）
• CS8600–CS8610 — null 許容参照型の警告（null 許容性）

「次はどのカテゴリにしますか？――Nullability、Performance、Reliability のいずれかです」と確認してください。選択された ID を WarningsAsErrors に追加し、修正して繰り返してください。

フェーズ 3：セキュリティ（常に早期に昇格させる）

プロジェクトの成熟度にかかわらず、.editorconfig に設定します：

[*.cs]
dotnet_analyzer_diagnostic.category-Security.severity = error

CA3001（SQL インジェクション）、CA3002（XSS）、CA3003（パスインジェクション）、CA3075（安全でない DTD）、CA5350/CA5351（脆弱な暗号化）、CA5394（安全でない乱数）に対応します。

フェーズ 4：完全なカバレッジ

すべてのバッチが通過したら、次の設定に移行します：

<TreatWarningsAsErrors>true</TreatWarningsAsErrors>
<WarningsNotAsErrors>CA1707</WarningsNotAsErrors> 

対話プロトコル（レガシーなコードベース）

1. dotnet build を実行し、警告を ID ごとに数えます。
2. 概要を報告します：「CS8019 が 47 件、CA1822 が 23 件、CA2000 が 12 件、CS8600 が 8 件見つかりました。」
3. どのバッチに取り組むかを尋ねます。フェーズ 1 から始めることを推奨します。
4. 選択されたバッチを修正し、ビルドを検証します。
5. それらの ID を WarningsAsErrors に追加します。
6. 結果を報告し、次のバッチについて尋ねます。

確認のステップを決して省略しないでください。進めるペースはユーザーが決めます。

設定がない場合の初期設定

1. 現在の状態を検出します：
   • dotnet --info
   • rg -n "EnableNETAnalyzers|AnalysisLevel|AnalysisMode|TreatWarningsAsErrors|WarningsAsErrors" -g '*.csproj' -g 'Directory.Build.*' .
   • dotnet build SOLUTION_OR_PROJECT 2>&1 — 警告を ID ごとに数えます
2. 新規（警告が少ない／ゼロ）かレガシー（警告が多い）かを分類します。
3. MSBuild の設定で EnableNETAnalyzers、AnalysisLevel、AnalysisMode を有効にします。
4. プロジェクトの成熟度に合った昇格戦略を適用します。
5. リポジトリのルートにある .editorconfig でルールごとの重大度を設定します。
6. dotnet build を実行し、status: configured または status: improved を返します。
7. リポジトリがアナライザーポリシーを別のビルドレイヤーに委ねている場合は、status: not_applicable を返します。

提供内容

• 明示的でレビュー可能な、ファーストパーティアナライザーのポリシー
• CI でのビルド時アナライザー実行
• プロジェクトの成熟度に合った警告昇格プラン

検証

• アナライザーの動作が IDE のデフォルトではなく、リポジトリの設定によって決まる
• CI でローカルと同じ警告／エラーが再現される
• ユーザーの承認なしに TreatWarningsAsErrors、WarningsAsErrors、重大度設定が削除または弱められていない
• 昇格された警告が、IDE のヒントにとどまらずビルドエラーになる

Ralph ループ

1. 計画：状態を分析し、目標、制約、リスク、実行計画、検証手順を定めます。
2. 1 つのステップを実行し、具体的な変更を作成します。
3. 結果をレビューし、判明したことを記録します。
4. 小さなバッチで修正を適用し、チェックを再実行します。
5. 各反復の後に計画を更新します。
6. 許容できる状態になるか、明示的な例外のみが残るまで繰り返します。
7. 依存関係が不足している場合は、初期設定を行うか、status: not_applicable を返します。

必須の結果形式

• status：complete | clean | improved | configured | not_applicable | blocked
• plan：簡潔な計画と現在のステップ
• actions_taken：具体的な変更
• validation_skills：最後に実行したスキル、または理由を添えてスキップしたスキル
• verification：コマンド、チェック、またはレビューの証拠
• remaining：未解決の項目、または none

リファレンスの読み込み

• references/rules.md
• references/config.md
• references/code-analysis.md

リクエストの例

• 「組み込みの .NET アナライザーを有効にしてください。」
• 「アナライザーの警告でビルドが失敗するようにしてください。」
• 「このリポジトリに適切な AnalysisLevel を設定してください。」
• 「未使用の using と未使用の変数をエラーとして扱うようにしてください。」
• 「レガシープロジェクトで Roslyn の警告を段階的に昇格させるのを手伝ってください。」
• 「次にエラーへ昇格させるべき警告はどれですか？」