大規模なコードベースでの作業
大規模なコードベースを操作・作業するための戦略
大規模なコードベースで作業するには、コンテキストの制約を管理し、生産性を維持するための特定の戦略が必要です。このガイドでは、Verdent for VS Code を使って大規模なプロジェクトを効率的にナビゲート、理解、変更するための実践的なワークフローを紹介します。
コードベースの探索に Explorer エージェントを使う
大規模なコードベースに不慣れで、特定の機能がどこに実装されているかを見つける必要がある場合を考えてみましょう。
幅広い探索的な質問をする
Where is user authentication handled in this codebase?Verdent は、コードベース検索に特化したトークン効率の高い専門エージェントである Explorer エージェントに自動的に委任します。
Explorer が効率的に検索する
Explorer エージェントは次を行います。
- ファイル名とパスの検索
- キーワードでコードコンテンツを grep
- アーキテクチャパターンの分析
- ファイルパスとコードスニペットを含む結果の返却
検索を絞り込む
Show me all files that import the authentication moduleExplorer はフォローアップの検索を実行して結果を絞り込めます。
複雑な検索を並列化する
包括的な探索のために、Verdent は複数の Explorer エージェントを並列で実行できます。
- Explorer 1: 認証ロジックを見つける
- Explorer 2: 認可ロジックを見つける
- Explorer 3: セッション管理を見つける
並列検索により結果がより速く得られます。
ヒント:
- Explorer エージェントはメインコンテキストを埋めずに大規模なコードベースで効率的に動作します
- 複数の Explorer エージェントが異なる側面を同時に検索できます
- パターンマッチングやアーキテクチャの探索には Explorer を使用してください
- 結果にはコンテキストとなるファイルパスと関連するコードスニペットが含まれます
タスクを管理しやすい単位に分割する
大規模なコードベースで作業していて、多数のファイルにまたがる機能を追加する必要がある場合を考えてみましょう。
自然なタスクの境界を特定する
すべてを一度に依頼するのではなく、次のようにします。
Phase 1: Add the data models for the notification systemまずは自己完結した 1 つのコンポーネントに集中します。
フェーズを完全に終わらせる
フェーズ 2 に進む前に、テストを含めてフェーズ 1 を完全にやり切ります。これによりクリーンなチェックポイントが作られます。
進捗をコミットする
git add .
git commit -m "feat: add notification data models"コミットすることで、安全にロールバックできるポイントが作られます。
次のフェーズに向けてコンテキストをクリアする
複雑なタスクでは、次のフェーズに進む前にコンテキストをクリアします。これにより、Verdent がピーク時のパフォーマンスを維持するのに十分なコンテキスト容量を確保できます。
Phase 2: Build the notification API endpoints using the data modelsフェーズ 2 だけに集中した、新しいコンテキストの新規セッションを開始します。
ヒント:
- 自然な区切りはコンテキストの枯渇を防ぎます
- 各フェーズは独立してテスト可能であるべきです
- フェーズ間でコミットすることで安全に実験できます
- 新しいセッションはコンテキストをクリーンで集中した状態に保ちます
大規模な変更に Plan Mode を活用する
大規模なコードベース内の数十のファイルに散らばった機能をリファクタリングする必要がある場合を考えてみましょう。
Plan Mode で開始する
Switch to Plan Mode: Refactor the payment processing logic to use a new payment provider across all filesPlan Mode では、ファイルの変更にコンテキストを消費せずに読み取り専用の分析が行えます。
Explorer を使って影響を受けるすべてのファイルを見つける
Use the Explorer agent to find all files that reference payment processing更新が必要なすべての箇所を確実に発見できます。
包括的なプランをレビューする
Verdent は次を示すプランを提示します。
- 変更が必要なすべてのファイル（25 件のファイルを特定）
- メインコンテキストに含める最小限のファイルセット
- 操作の順序
- 変更間の依存関係
このアプローチを採用する前にレビューします。
実行を承認する
プランに満足したら、実行を承認します。Verdent が体系的に変更を進めます。
ヒント:
- Plan Mode は実行前に最小限のファイルセットを特定するのに役立ちます
- Explorer は大規模なリファクタリングでファイルの見落としを防ぎます
- プランはコンテキストを消費する前にスコープを明確に示します
- ドキュメント化やチームのレビューのためにプランをファイルに保存します
多数のファイルにまたがる協調的な変更を行う
大規模なコードベース全体で 50 以上のファイルで使われている関数の名前を変更する必要がある場合を考えてみましょう。
Explorer を使ってすべての使用箇所を見つける
Use the Explorer agent to find all files that use the calculateTotal function更新が必要なすべてのファイルを特定します。
Plan Mode でスコープをレビューする
In Plan Mode: Rename calculateTotal to computeFinalTotal across all files変更を行う前に、スコープ全体を確認します。
ファイルの見落としがないか確認する
Verdent は更新が必要な 52 件すべてのファイルを表示します。リストをレビューして漏れがないことを確認します。
協調的な変更を実行する
プランを承認します。Verdent がすべてのファイルを体系的に更新し、あらゆる箇所で一貫した名前変更を保証します。
テストを実行して検証する
Run the full test suite to verify all references were updated correctlyテストにより見落とされた参照を検出できます。
ヒント:
- Explorer は大規模な変更でファイルの見落としを防ぎます
- Plan Mode は実行前にスコープ全体を示します
- 体系的な更新はすべてのファイルにわたって一貫性を維持します
- 大規模なリファクタリング後は包括的にテストします
多数のファイルにまたがる協調的な変更は、フェーズに分けて行う方が安全です。1 つのレイヤーを更新し、検証してから、依存するレイヤーへ進みます。
よくある質問
コンテキストの上限に近づいているかどうかをどう判断すればよいですか？
応答時間が遅くなる、セッションが数時間続いている、多数の大きなファイルが読み込まれている、といった兆候があります。セッションの長さとファイル数を監視してください。パフォーマンスの低下に気づいたら、現在のタスクを完了し、進捗をコミットして、クリーンなコンテキストで新しいセッションを開始します。
Verdent に一度に数十のファイルを変更させても安全ですか？
適切に使えば安全です。常にまず Plan Mode でスコープ全体をレビューし、包括的なテストカバレッジを確保し、フェーズ間で頻繁にコミットしてください。これにより変更を段階的に検証でき、必要に応じて簡単にロールバックできます。
Explorer エージェントを使うべき場合と、ファイルを直接読み込むべき場合はどう使い分けますか？
メインコンテキストを消費せずに探索や検索を行うタスクには Explorer エージェントを使います。@メンションでファイルを直接読み込むのは、それらを変更する必要がある場合だけにしてください。Explorer は「〜であるすべてのファイルを見つける」といった質問に最適で、@メンションは「この特定のファイルを更新する」タスク向けです。
大規模なコードベースの作業にはどのモデルプリセットが最適ですか？
複雑な複数ファイルの操作やリファクタリングには Performance プリセットを使います。単純な検索や探索のタスクには Efficiency プリセットを使います。Performance は協調的な変更により多くの推論能力を提供し、Efficiency は探索においてより高速でコスト効率に優れています。