GitHub Copilot の最新化に関するトラブルシューティング

この記事では、カテゴリ別に整理GitHub Copilot.NETの最新化を使用する場合に発生する可能性がある一般的な問題について説明します。 各エントリは、問題、原因、および解決策の形式に従って、問題をすばやく見つけて解決できます。

ワークフローの問題

これらの問題は、シナリオの検出、再開作業、タスクの状態に関連しています。

エージェントが「シナリオが見つかりません」と言っている

Cause: エージェントはワークスペースを.NET プロジェクトとして認識しません。

Solution:

1. ワークスペースルートに .sln、 .csproj、または .vbproj ファイルが含まれていることを確認します。
2. エージェントに「どのソリューションまたはプロジェクト ファイルを使用していますか?」と尋ねます。
3. ソリューションまたはプロジェクト ファイルがサブディレクトリ内にある場合は、そのディレクトリをワークスペース ルートとして開くか、エージェントをファイルに明示的にポイントします。

エージェントが前の作業を再開できない

原因： エージェントがすべての状態を格納する .github/upgrades/ フォルダーが見つからないか、破損しています。

Solution:

1. .github/upgrades/ フォルダーがリポジトリ ルートに存在するかどうかを確認します。
2. 誤ってフォルダーを削除した場合は、シナリオを新たに開始します。 エージェントは、状態ファイルなしでは復旧できません。
3. フォルダーが存在するが、ファイルが破損しているように見える場合は、再生成するために エージェントに "再評価と再計画" を依頼します。

進行中のタスクが停止している

原因： 前のセッションは、エージェントがタスクの途中で終了しました。

Solution:

1. エージェントは、ほとんどの場合、古いタスクを自動検出します。 エージェントに "再開" または "現在のタスクを再起動する" ことを伝えます。
2. スタック状態が続く場合は、エージェントに「現在のタスクを保留中としてマークして再起動する」または「最後に完了したステップから再評価して続行する」ことを伝えます。
3. 前のセッションが停止した場所を理解するには、対応する progress-details.md ファイルを確認します。

エージェントが間違ったシナリオを提案し続ける

原因： エージェントの分析では、予期しないプロジェクトの特性が取得され、意図したシナリオとは異なるシナリオが推測されました。

Solution:

必要な内容を明示的に指定します。 "プロジェクトをアップグレードする" の代わりに、次のように言います。

• ".NET 10 にアップグレードする必要があります。"
• "Newtonsoft.Json から System.Text.Json にアップグレードする必要があります。"
• "プロジェクトを SDK 形式に変換します。"

今後の不一致を防ぐために、シナリオ設定を scenario-instructions.md に追加します。

ビルドとコンパイルの問題

これらの問題は、ビルドエラー、NuGet 復元の問題、およびコード生成エラーに関連しています。

エージェントの変更後にビルドが失敗する

原因： アップグレードでは、 破壊的な API の変更、パッケージの不足、または互換性のないコード パターンが発生する可能性があります。

Solution:

1. エージェントにエラーについて伝えます。 エージェントはエラーを自動的に分析します。
2. エージェントが問題を解決できない場合は、最後のコミット (git revert HEAD) を元に戻し、エージェントに別の方法を試すように依頼します。
3. 複雑な障害が発生した場合は、 execution-log.md チェックして、エージェントが何を変更し、どのような順序で変更されたかを把握します。

NuGet の復元が失敗する

原因： ターゲット フレームワークとパッケージの非互換性、またはプライベート NuGet フィードでの認証エラー。

Solution:

• プライベート フィードの場合: アップグレードを開始する前に、フィードに対して認証を行います。
• 互換性のないパッケージの場合: 問題のあるパッケージをエージェントに伝えます。 エージェントは、互換性のあるバージョンを検索したり、代替パッケージを提案したりすることができます。
• フィード接続の問題の場合:dotnet restoreを手動で実行できることを確認します。 最初にフィードの問題を修正してから、エージェントを再試行します。

エージェントがコンパイルされないコードを生成する

原因： AI によって生成されるコードには、特にエッジ ケースや一般的でない API パターンでエラーが含まれる場合があります。

Solution:

1. エージェントはコンパイル エラーを自動的に検出します。 エージェントが苦労している場合は、ガイダンスを提供するか、コードを手動で修正し、エージェントに続行するように指示します。
2. 複数回試行した後にエージェントが特定の修正に苦しむ場合は、コードを手動で編集し、エージェントに「MyClass.csでコンパイル エラーを修正し、このタスクを完了にマークします」と伝えます。
3. エージェントは手動修正から学習し、同じ問題が他の場所に表示されたときに同様のパターンを適用します。

Git の問題

エージェントでブランチを作成できない

原因： 作業ツリーでのコミットされていない変更、ブランチの名前付けの競合、または Git がワークスペースで初期化されていません。

Solution:

1. シナリオを開始する前に、保留中の変更をコミットまたは隠します。
2. ワークスペース ルートで git status を実行して、Git が初期化されていることを確認します。
3. エージェントの目的の名前を持つブランチが既に存在する場合は、既存のブランチを削除するか、別のブランチ名を使用するようにエージェントに依頼します。

すべてのエージェントの変更を元に戻す

原因： アップグレードが計画どおりに行かず、最初からやり直す必要があります。

Solution:

1. git checkout main (またはベース ブランチ) を使用して、元のブランチに戻ります。
2. エージェントの作業ブランチには、メイン ブランチから分離されたすべての変更が含まれています。
3. エージェントのブランチを完全に削除するには、 git branch -D <agent-branch-name>実行します。
4. いくつかの変更を保持するには、 git cherry-pick <commit-hash>を使用して特定のコミットを選択します。

パフォーマンスの問題

これらの問題は、アップグレードの速度と評価期間に関連しています。

エージェントの速度が遅い、または時間がかかる

原因： 多くのプロジェクト、複雑な依存関係グラフ、または多数の破壊的変更を含む大規模なソリューションは、当然ながら時間がかかります。

Solution:

大規模なソリューション (50 以上のプロジェクト) の場合は、バッチでのアップグレードを検討してください。 関連するプロジェクトをグループ化し、それらを一緒にアップグレードします。

評価に時間がかかる

原因： 評価では、すべてのプロジェクトの依存関係、NuGet パッケージ、ターゲット フレームワーク、適用可能な破壊的変更が分析されます。 大規模なソリューションの場合、当然ながら評価にかかる時間は長くなります。

Solution:

1. 大規模なソリューションでは、長い評価時間が通常です。 アクションは必要ありません。
2. Output パネル (Visual Studioのドロップダウンから AppModernizationExtension を選択) で進行状況を監視します。
3. 評価はシナリオごとに 1 回だけ実行されます。 後続のフェーズでは、キャッシュされた結果が使用されます。

カスタマイズの問題

これらの問題は、カスタム スキルとシナリオ命令ファイルに関連しています。

カスタムスキルが認識されない

原因： スキル ファイルの場所が間違っているか、メタデータが見つからないか無効であるか、形式が正しくありません。

Solution:

1. スキル ファイルがサポートされているいずれかの場所にあることを確認します。
   • .github/skills/ (リポジトリ レベル、チーム全体)
   • .github/upgrades/skills/ (シナリオ レベル)
   • %UserProfile%/.copilot/skills/ (ユーザー レベル、個人用)
2. スキルメタデータに少なくとも name フィールドと description フィールドが含まれていることを確認します。
3. discovery フィールド (設定されている場合) が、lazy、preload、またはscenarioのいずれかであることを確認します。
4. スキルの description が、適用する予定のタスクの種類と一致することを確認します。 エージェントは、説明の照合を使用してスキルを選択します。

scenario-instructions.md への変更は有効になりません

原因： エージェントがファイルの中間部分を再読み取りしないか、編集内容が間違ったセクションにある可能性があります。

Solution:

1. エージェントに "手順を再読み込み" するか、新しいチャット セッションを開始して再読み取りを強制するように依頼します。
2. 編集内容がファイルの正しいセクションにあることを確認します。
   • ユーザー設定: 一般的な設定と制約の場合。
   • 主な決定事項: アップグレード中に行われた重要な決定を記録します。
   • カスタム指示: 特定の動作をオーバーライドするためのもの。
3. ファイルが保存され、予想されるパス ( .github/upgrades/{scenarioId}/scenario-instructions.md) にあることを確認します。

ヘルプを取得する

何かが期待どおりに動作しない場合:

1. エージェントに問い合わせ:「最後のタスクで何が問題になったのか」と尋ねます。エージェントは、多くの場合、何が起こったかを説明し、次の手順を提案できます。
2. 実行ログを確認します。execution-log.mdで.github/upgrades/{scenarioId}/を開きます。 ログには、エージェントが実行した内容 (発生したエラーを含む) の時系列レコードが表示されます。
3. 問題を解決する:バグが見つかった場合、またはエージェントが常に何かに失敗する場合は、@modernize-dotnet GitHub リポジトリで問題を報告します。

関連するコンテンツ

• GitHub Copilot の最新化とは何ですか？
• ベスト プラクティス
• コアコンセプト
• GitHub Copilotモダン化に関する FAQ