Shared Knowledge MCP Server

--- description: AIコードエージェントの問題解決とトラブルシューティングガイド ruleId: troubleshooting-01jpcvxfxra1qd2v1btrrz4s2z tags: - ai - troubleshooting - debugging aliases: - ai-troubleshooting globs: - '**/*.ts' - '**/*.tsx' - '**/*.js' - '**/*.jsx' - '**/*.go' - '**/*.rs' - '**/*.scala' --- # AIエージェントのトラブルシューティング ## 概要 このドキュメントでは、AIコードエージェントを使用する際に発生する可能性のある問題と、その解決方法を提供します。 一般的な問題のトラブルシューティング手順と、問題を防ぐためのベストプラクティスを説明します。 ## 一般的な問題と解決方法 ### 1. コミュニケーションの問題 #### 指示が正しく理解されない **症状** - AIが要件と異なる実装を提案する。 - 文脈を誤って解釈している。 - 重要な制約を見落としている。 **解決方法** 1. 指示を明確かつ具体的に再構成する。 2. 要件を箇条書きで列挙する。 3. 制約条件を明示的に示す。 4. 期待する結果を具体的に説明する。 #### 文脈の喪失 **症状** - 以前の会話の内容が反映されていない。 - 同じ説明を繰り返す必要がある。 - 一貫性のない応答をする。 **解決方法** 1. 重要な文脈情報を再提供する。 2. 会話の目的を定期的に確認する。 3. 進行中のタスクの状態を明確にする。 4. 必要に応じて新しいセッションを開始する。 ### 2. コード生成の問題 #### 不適切なコード生成 **症状** - コーディング規約に従っていない。 - 非効率な実装が含まれる。 - セキュリティ上の問題がある。 **解決方法** 1. コーディング規約を明示的に共有する。 2. 具体的な改善点を指摘する。 3. 望ましい実装例を提示する。 4. セキュリティ要件を強調する。 #### 依存関係の問題 **症状** - 互換性のないバージョンが指定される。 - 必要な依存関係が不足している。 - 循環参照が発生する。 **解決方法** 1. プロジェクトの依存関係を明確に示す。 2. バージョン制約を説明する。 3. アーキテクチャの制約を共有する。 4. 既存の依存関係の管理方法を説明する。 ### 3. パフォーマンスの問題 #### 非効率な実装 **症状** - 実行時間が長い。 - メモリ使用量が多い。 - リソースの無駄遣いがある。 **解決方法** 1. パフォーマンス要件を明確にする。 2. ボトルネックを特定する。 3. 最適化の方針を示す。 4. ベンチマーク結果を共有する。 #### スケーラビリティの問題 **症状** - 大規模データでの処理が遅い。 - 並行処理が適切でない。 - リソース使用が線形でない。 **解決方法** 1. スケーラビリティ要件を定義する。 2. 処理方法の見直しを依頼する。 3. 並行処理の導入を検討する。 4. キャッシュ戦略を改善する。 ### 4. テストの問題 #### 不十分なテストカバレッジ **症状** - エッジケースが考慮されていない。 - 重要な機能のテストが不足。 - テストの品質が低い。 **解決方法** 1. テスト要件を明確にする。 2. カバーすべきケースを列挙する。 3. テストパターンを提示する。 4. テスト品質の基準を共有する。 #### テストの失敗 **症状** - テストが不安定。 - 環境依存の問題がある。 - アサーションが不適切。 **解決方法** 1. テスト環境を統一する。 2. テストデータを整備する。 3. アサーションを見直す。 4. テストの独立性を確保する。 ## 予防的対策 ### 1. 事前準備 - プロジェクトの構造とガイドラインを共有する。 - 開発環境の設定を明確にする。 - コーディング規約を提供する。 - テスト戦略を定義する。 ### 2. 品質管理 - コードレビューのプロセスを確立する。 - 自動テストを整備する。 - 静的解析ツールを導入する。 - パフォーマンスモニタリングを実施する。 ### 3. ドキュメント整備 - APIドキュメントを維持する。 - 設計判断を記録する。 - トラブルシューティングガイドを更新する。 - ベストプラクティスを文書化する。 ## デバッグ手順 ### 1. 問題の特定 ```markdown 【デバッグ手順】。 1. 症状の観察。 - エラーメッセージの確認。 - ログの分析。 - 動作の観察。 - パフォーマンス計測。 2. 問題の切り分け。 - 発生条件の特定。 - 影響範囲の確認。 - 依存関係の調査。 - 環境要因の確認。 ``` ### 2. 解決策の実装 ```markdown 【解決手順】。 1. 対策の検討。 - 複数の解決案を検討。 - 影響範囲を評価。 - リスクを分析。 - 実装方針を決定。 2. 修正の実施。 - コードの修正。 - テストの追加。 - ドキュメントの更新。 - レビューの実施。 ``` ## ベストプラクティス ### 1. コミュニケーション - 明確で具体的な指示を心がける。 - 文脈情報を適切に提供する。 - フィードバックを積極的に行う。 - 進捗を定期的に確認する。 ### 2. コード品質 - コーディング規約を遵守する。 - テストを充実させる。 - パフォーマンスを考慮する。 - セキュリティを重視する。 ### 3. ドキュメント - 設計判断を記録する。 - APIドキュメントを整備する。 - トラブルシューティング手順を更新する。 - ベストプラクティスを共有する。 ## 関連情報 - [API設計・ドキュメント作成ガイドライン](../development/api/guidelines-01jpcvxfxqe37ka9pn3xb4m9ys.md) - [AIエージェントとの対話プロトコル](interaction-01jpcvxfxs0zr4jqmx1jn4f9re.md) - [AIエージェントの機能と制限](capabilities-01jpcvxfxs0zr4jqmx1jn4f9rh.md) - [AIエージェント活用のベストプラクティス](best-practices-01jpcvxfxs0zr4jqmx1jn4f9rj.md)