大規模なレガシープロジェクトを担当するエンジニアは、毎日2時間かけてコードの山を掘り返しています。grepで文字列を追いかける手法には、もはや限界が来ています。AIエージェントを導入したくても、ワークフローにどのように組み込めばよいのか悩むのが現実です。この記事では、エージェントを単なるチャットボットではなく、実務の生産性を向上させるツールとして定着させるための具体的な技術的手順を扱います。
ノイズから取り除いてください
エージェントにコードベース全体を丸投げすると、コンテキストが汚染されます。不要なデータを学習させると的外れな回答が返ってくるだけでなく、トークンコストも浪費します。インデックス作成の範囲を絞るだけで、応答速度は体感できるほど速くなります。
以下の3つを即座に適用してください。
- プロジェクトルートに .cursorignore ファイルを作成してください。 /dist、/build、/target、node_modules のような巨大なビルドアーティファクトは必ず除外します。
- Protobuf のスタブや自動生成された *.gen.ts ファイルも除外してください。これにより、エージェントが下位互換性を無視したコードを生成するのを防げます。
- マークルツリーベースの同期ツールを使用してください。インデックス全体を毎回作り直すのではなく、変更されたファイルのハッシュ値のみを更新することで、インデックス作成速度を3倍以上に高めます。
構文木で依存関係を追跡してください
テキストベースの検索では、複雑な継承関係を見つけ出すことはできません。ast-grep のようなツールを使用して、コードの構文木（AST）を分析する必要があります。これをプロンプトに組み込むことで、単なる検索よりもはるかに精度の高いクエリが可能になります。
- 分析対象の構文パターンを定義してください。例えば、エラー処理が欠落している非同期関数のパターンを ast-grep の文法で記述します。
- エージェントに @codebase ツールとこのパターンを合わせて渡してください。その際、外部ライブラリは無視し、内部モジュール間の継承関係のみを探すよう範囲を絞る指示を追加します。
- 結果を Mermaid ダイアグラムで出力させてください。複雑な呼び出しフローを可視化することで、課題解決にかかる時間を約40%短縮できます。
修正案をテストで検証してください
AIが提案する修正案には、半分ほどエラーが含まれています。これらをそのままマージすれば技術的負債が積み上がるだけです。テスト影響分析（TIA）を CI パイプラインに組み込み、検証ループを自動化してください。
- Jest の --findRelatedTests のように、変更されたコードに関連するテストのみを選択して実行するスクリプトを作成します。
- エージェントに指示を出します。テストが失敗した場合は、エラーログを分析してコードを自動で修正するようなループを設定します。
- CodeQL のようなツールを CI ステップに導入してください。人間が見落としがちなセキュリティの脆弱性まで自動的に検出します。
このループを構築すれば、構文の妥当性検証の精度を飛躍的に向上させることができます。既存のツールチェーンをすべて捨てる必要はありません。ripgrep は依然として単純な検索においてエージェントより10倍以上高速です。ツールの特性に合わせて役割を分担させることが、シニアエンジニアの真の役割です。
