日々の開発業務においてIDE上のAIコーディングアシスタントを活用する際、多くのソフトウェアエンジニアやフルスタック開発者が共通の課題に直面します。複数のソースコードファイルにまたがる変更を手作業でコピー＆ペーストするのは退屈でミスが発生しやすく、一方でAIエージェントに完全な書き込み権限とシェル実行権限を無条件に委譲すると、重要ファイルの誤削除やターミナルコマンドの暴走といった致命的なセキュリティ事故を招くリスクがあります。
Visual Studio CodeおよびJetBrains IDE（IntelliJ IDEA、PyCharm、WebStormなど）に対応するCodeGPTは、**Agent Mode（エージェントモード）と内部ツール群（Internal Tools）**の組み合わせにより、この自動化の効率と安全性の両立を実現しています。開発者は「全て手作業」と「制御不能な完全自動」の二者択一を迫られることなく、タスクプランナーでリファクタリング要件を段階的に分解し、ファイル読み書きやターミナルコマンド実行に対するきめ細かな権限設定（手動承認または自動実行）を行うことができます。
本ガイドでは、CodeGPTのAgent Modeの仕組み、安全な権限設定手順、および複数ファイル操作を安全に完遂するためのベストプラクティスを解説します。
1. プロファイルモードの理解と適切な選択
CodeGPTは、チャットパネル下部にあるモードセレクターから切り替え可能な3つの定義済みプロファイルモード（Profile Modes）を提供しています。現在の作業内容に応じて適切なモードを選ぶことが、不要なファイル変更を防ぐ最初の防壁となります。
| プロファイルモード | 利用可能なツール | 機能概要 | 最適なユースケース |
|---|---|---|---|
| Chat Mode（チャットモード 💬） | ツール無効 | 純粋な対話型Q&A。プロンプトと貼り付けたコードスニペットのみを参照。 | 文法やアルゴリズムの質問、プロジェクトファイルに触れない単一コードブロックの検証。 |
| Search Mode（検索モード 🔍） | 読み取り専用ツール（Code Search、Read File、View Folder Structure） | コードベース全体のセマンティック検索、構造把握、依存関係の解析。書き込みやコマンド実行は不可。 | 初見のリポジトリ構造の把握、影響範囲の調査、リファクタリング前の設計確認。 |
| Agent Mode（エージェントモード 🤖） | 全ツール有効（読み取り、作成、変更、削除、ターミナル実行、ToDo更新） | 自律的なマルチターン問題解決。ファイルの作成・編集・削除およびターミナルでのコマンド実行が可能。 | 複数ファイルにまたがるリファクタリング、新機能の実装、テストの自動生成と検証。 |
複雑な実装作業を開始する際は、チャット画面下部のドロップダウンメニューからChat ModeまたはSearch Modeから Agent Mode に切り替えます。
2. 前提条件：Function Calling対応モデルの選択
Agent Modeで内部ツールを機能させるには、使用するAIモデルが**ネイティブなFunction Calling（ツール呼び出し）**をサポートしている必要があります。
- 対応プロバイダーおよびモデル例: Anthropic（Claude 3.5 / 3.7 Sonnet）、OpenAI（GPT-4o、oシリーズ）、Google（Gemini 1.5 / 2.0 / 2.5シリーズ）、DeepSeek、Mistral、およびOpenRouterやBedrock経由の対応モデル。
- 非対応モデルを選択した場合: Function Callingに対応していないモデルを選択すると、CodeGPTは内部ツール機能を自動的に無効化し、通常のテキスト出力のみにダウングレードされます。
3. 内部ツールの権限設定：手動承認と自動承認の使い分け
Agent Modeにおいて、CodeGPTは以下の8つの組み込み内部ツールを使用します。
Code Search: セマンティック解析により、類似するコードパターンや関数定義を検索。Read File: 指定されたパスのファイル内容を取得。View Folder Structure: プロジェクトのディレクトリ階層とファイル構成を表示。Create File/Folder: 新しいファイルやフォルダをプロジェクト内に作成。Edit File: 既存のファイルに対して高精度なパッチ修正を適用。Delete File: プロジェクトからファイルを削除（高リスク操作）。Run Terminal Command: ビルド、テスト実行、パッケージ導入などのターミナルコマンドを実行。Update ToDo List: 複数ステップのタスクリスト、課題、進捗状況を動的に管理。
ツール権限の設定手順
- CodeGPTパネル内の Settings（歯車アイコン ⚙️）を開きます。
- Tools セクションに移動します。
- 利用したいツールごとに実行モードを設定します。
Enabled（手動承認モード）: エージェントが該当ツールを呼び出す前に一時停止し、Diff差分やターミナルコマンド文字列をプレビュー表示します。開発者が明示的に Approve（承認）または Reject（拒否）をクリックするまで実行されません。Auto-Approve（自動承認モード）: エージェントがタスクの文脈に応じて自動的にツールを実行します。都度承認を求めるポップアップが出ないため作業速度が向上します。
安全のための安全装置：20回の自動実行リミット
エージェントがエラー修正の無限ループに陥り、意図しないファイル書き換えやターミナルコマンドの乱発が発生するのを防ぐため、CodeGPTにはハードセーフティリミットが組み込まれています。潜在的に危険な操作（Create File/Folder、Edit File、Delete File、Run Terminal Command）に対する連続自動承認（Auto-Approve）の上限は最大20回に制限されており、20回に達した時点で自動処理が停止し、開発者の手動確認が要求されます。
4. 開発チームに推奨される階層型セキュリティポリシー
日常の開発で全ツールをAuto-Approveに設定するのは極めて危険です。リスクレベルに応じた階層的な権限設定を推奨します。
flowchart TD
A[CodeGPT Agent Modeプロンプト入力] --> B{呼び出し対象ツールの判定}
B -->|読み取り・計画: Code Search, Read File, ToDo| C[Auto-Approve: 即時自動実行]
B -->|ファイル変更: Create File, Edit File| D{リファクタリング範囲の確認}
D -->|独立ブランチ / ボイラープレート| E[Auto-Approve または Diff目視確認]
B -->|高リスク: Delete File| F[Enabled: 厳格な手動承認を強制]
B -->|高リスク: Run Terminal Command| G[Enabled: 厳格な手動承認を強制]
F --> H[開発者による影響範囲レビュー]
G --> I[開発者によるシェル引数レビュー]
H --> J[Approveクリックで実行適用]
I --> J
レベル1：読み取り＆タスク計画ツール（Auto-Approve推奨）
Code Search: Auto-ApproveRead File: Auto-ApproveView Folder Structure: Auto-ApproveUpdate ToDo List: Auto-Approve 理由: これらの操作は作業コンテキストの収集や内部状態の整理のみを行い、ローカルディスクや外部システムに不可逆な変更を加えません。
レベル2：ファイル作成および編集ツール（状況に応じた設定）
Create File/Folder: クリーンなフィーチャーブランチ内ではAuto-Approve可。Edit File: 初期段階やコアロジックではEnabled（手動承認でDiffを確認）。エージェントの挙動が意図通りであることを確認できた段階で、定型修正向けに自動承認へ緩和。 理由: 既存コードの上書きによる重要ロジックの喪失やコメント削除を防ぐため、IDEのDiffビューによる事前確認が有効です。
レベル3：ファイル削除およびターミナル実行（手動承認必須）
Delete File: Enabled（手動承認のみ）Run Terminal Command: Enabled（手動承認のみ） 理由: ターミナルコマンドはOSやネットワークに直接アクセスするため、依存関係の破壊、意図しないデータベースマイグレーションの実行、ファイル消失（rmなど）を引き起こす可能性があります。実行前に引数とコマンド内容を必ず目視確認してください。
5. IDE環境ごとの留意点：VS CodeとJetBrainsの比較
CodeGPTはマルチプラットフォームで同様の機能を提供しますが、環境による挙動の違いに注意が必要です。
Visual Studio Code
- UI統合度: チャットフッターにプロファイル切り替えバーが常時表示され、切り替えが容易です。
- Diffプレビュー:
Edit Fileの変更提案時に、VS Codeネイティブの左右分割Diffビューで差分を直接確認できます。 - 設定共有: プロジェクトルートの
.vscode/settings.jsonに設定を保存することで、チーム内で同一のセキュリティポリシーを共有可能です。
JetBrains IDE（IntelliJ IDEA、PyCharm、WebStormなど）
- 内部通信ポート: JetBrainsプラグインはIDEとの通信にローカルポート 54112 または 54113 を使用します。ファイアウォールや他のプロセスによるポート占有がないことを確認してください。
- 承認ダイアログ: ツール実行の確認プロンプトはJetBrainsの通知ウィンドウまたはツールウィンドウ内に表示され、コマンドはIDE内蔵ターミナルで実行されます。
6. 実践：複数ファイルリファクタリングを安全に進める5ステップ
APIの認証方式を刷新し、複数のコントローラーとテストコードを更新するような実務シナリオでは、以下の5ステップに沿って進めます。
ステップ1: Git作業ツリーのクリーン化
作業開始前に git status を実行し、未コミットの変更がないことを確認します。専用のブランチ（例: git checkout -b refactor/jwt-auth）を作成しておけば、エージェントが予期せぬ変更を行っても git reset --hard で即座にロールバックできます。
ステップ2: Search Modeで事前調査を実施
書き込み権限を与える前に、まずは Search Mode に切り替えます。
「UserServiceと各Controller間の依存関係を調査し、認証ミドルウェアを非同期方式に変更した場合に影響を受けるファイル一覧を提示してください。」
読み取り専用ツールで全体構造と影響範囲を洗い出すことで、無駄なトークン消費と不用意なファイル書き換えを防ぎます。
ステップ3: Agent Modeに切り替え、計画作成を指示
プロファイルを Agent Mode に切り替え、プロンプト内で Update ToDo List の活用を明示します。
「Agent Modeに切り替えてください。すべてのControllerに新しいJWT認証ミドルウェアを適用します。コード変更に着手する前に、まず詳細なToDoリストを作成してください。手順は、1) ユーティリティ関数の作成、2) ミドルウェアの実装、3) 各Controllerの更新、4) テストの修正とします。承認なしに既存ファイルを削除しないでください。」
これにより、チャット画面上に視覚的なチェックリストが展開され、全体の進行状況を把握できます。
ステップ4: Diff差分とコマンド内容を精査
エージェントがタスクを順次実行する際：
Edit Fileに対してはDiffプレビューを開き、余計なロジックが削られていないか確認します。Run Terminal Commandに対しては、単体テスト（npm testやpytest）などの読み取り・検証系コマンドであることを確認してから承認します。
ステップ5: 全体検証とコミット
ToDoリストの全項目が完了したら、ターミナルで手動によりフルビルドとリグレッションテストを実行します。git diff で差分全体を最終確認し、コミットを完了します。
まとめ
CodeGPTのAgent Modeは、単なるコード補全を超えて複数ファイルにまたがる実装と環境操作を自動化する強力なパートナーです。ファイル削除とターミナル実行の手動承認を堅持し、Search ModeからAgent Modeへの段階的なアプローチと20回自動実行リミットを活用することで、開発速度を最大化しながらコードベースの安全を確実に守ることができます。