バックグラウンドコーディングエージェントのためのコンテキストエンジニアリング：Spotifyの実践から学ぶ信頼性の高いPR生成

コードの編集、ビルドの実行、プルリクエスト（PR）の自動オープンが可能なバックグラウンドコーディングエージェントを手に入れた後、重大な課題が浮上します：エージェントに何をすべきかをどのように効果的に伝えるか？ 単にエージェントを実行する段階を超え、実世界のコードベースにわたって信頼性が高くマージ可能なPRを生成するには、緻密なコンテキストエンジニアリングが不可欠です。本記事では、Spotifyが数百のリポジトリにわたって数千のPRを自動化した経験から得た貴重な知見、効果的なプロンプト作成とエージェントツール設計に関する洞察を紹介します。詳細な根拠資料はこちらでご確認いただけます。

プロンプトの落とし穴と得られた教訓

初期のオープンソースエージェントや自社製のエージェントループを実験する中で、Spotifyチームは2つの主要なアンチパターンを特定しました。

1. 過度に抽象的なプロンプト：エージェントがテレパシーのように意図と望ましい結果を推測することを期待します。「このコードを改善せよ」といった指示は検証可能な目標を提供せず、エージェントを混乱させます。
2. 過度に具体的なプロンプト：あらゆるケースをカバーしようとしますが、予期しない事態に遭遇すると崩壊します。厳格すぎるステップバイステップの指示はエージェントの柔軟性を奪い、複雑な多段階変更においてコンテキストウィンドウをすぐに枯渇させます。

Claude Codeへの移行により得られた核心的な原則は以下の通りです：

• エージェントに合わせてプロンプトを調整する：Claude Codeは、望ましい最終状態を説明し、到達方法を自ら見つける余地を残すプロンプトでより良く動作します。
• 前提条件を明記する：「リポジトリの言語レベルがJava 11未満の場合はアクションを起こさない」など、不可能なタスクを事前にブロックする指示を含めます。
• 例を使用する：具体的なコード例が結果に大きく影響します。
• 検証可能な目標を定義する：理想的には、テストの形で望ましい最終状態を定義します。エージェントは解決策を反復的に改善するための基準が必要です。
• 一度に一つの変更を行う：いくつかの関連する変更を一つにまとめると便利に見えますが、コンテキストウィンドウの枯渇や部分的な結果のリスクが大幅に高まります。
• エージェントにプロンプトのフィードバックを求める：セッション後、エージェント自身がプロンプトに何が不足していたかを驚くほど適切に指摘できます。これを将来のプロンプト改良に活用します。

予測可能性のためのツール制限の美学

複雑なタスクのためにエージェントに多数のツール（MCPツールなど）を接続し、動的にコンテキストを取得させることは可能です。しかし、これはテスト可能性と予測可能性を低下させます。ツールが多ければ多いほど、予測不可能性の次元が増えます。

Spotifyは、バックグラウンドコーディングエージェントのツールとフックを非常に限定して保持し、プロンプトから正しいコード変更を生成することに集中するように設計しています。

現在提供しているコアツールセット:

• verifyツール：フォーマッタ、リンター、テストを実行します。数千の異なるビルド設定を持つリポジトリで動作する必要があるため、社内ビルドシステムの呼び出しを抽象化し、ログをエージェントが理解しやすい形式に要約して提供します。
• Gitツール：限定された標準化されたGitアクセスを提供します。pushやoriginの変更のような危険なコマンドは公開せず、コミッターの設定や標準的なコミットメッセージフォーマットの使用などのアクションは標準化します。
• Bashツール：ripgrepなどのいくつかのコマンドへのアクセスを許可する厳格な許可リスト付きのBashツールです。

注目すべき点は、コード検索やドキュメントツールは現在エージェントに公開されていないことです。代わりに、ユーザーは関連するコンテキストを事前にプロンプトに凝縮するか、別のワークフローエージェントを使用して様々なソースからコーディングエージェント用のプロンプトを生成するように求められます。

このアプローチの限界と注意点

現在のエージェントとプロンプトエンジニアリングの状態は、依然として直感と試行錯誤に大きく依存しています。どのプロンプトやモデルが最も性能が良いかを評価する構造的な方法が不足しており、マージされたPRが元の問題を実際に解決したかを検証するフィードバックループはまだ初期段階です。エージェント生成コードの長期的な保守性への影響も未解決の問題です。

次の学習ステップ

この技術の真の成熟は、測定可能なフィードバックループの構築にかかっています。PRマージ率を超えて、生成されたコードの品質、レビュー時間の短縮効果、そして最終的にシステムの安定性に与える影響を定量的に評価する方法を探求する必要があります。さらに、プロンプトをコードのようにバージョン管理しテストする文化をチーム内に定着させることが、持続可能な自動化の核心です。