はじめに：バックグラウンドコーディングエージェントの始まり

AIコーディングエージェントは、もはやデモレベルのおもちゃではありません。Spotifyは内部コードネーム「Honk」というバックグラウンドコーディングエージェントを構築し、数百のリポジトリにまたがる大規模マイグレーションを自動化しています。このエージェントはコードを修正し、ビルドとテストを実行し、自動的にPR（プルリクエスト）を生成します。

しかし、ここで重要な疑問が生じます：このエージェントに「何をすべきか」を正確に伝えるにはどうすればよいのでしょうか？

本記事では、Spotifyが「Context Engineering」と呼ぶ、コーディングエージェントのための効果的なプロンプト設計手法を集中的に解説します。良いマイグレーションプロンプトの条件、エージェントがアクセスすべきツール、そして本番環境でマージ可能なPRを安定して生成するために確立した原則について見ていきます。

根拠資料

Developer writing a prompt for an AI coding agent on a laptop screen

初期の試み：オープンソースエージェントの限界

当初、SpotifyはGooseやAiderといったオープンソースエージェントを実験しました。単純なプロンプト1つで、コードベースを探索し、修正箇所を見つけ出し、コードを編集する様子は本当に驚くべきものでした。

しかし、このアプローチはスケーラビリティにおいて大きな問題を露呈しました。数千のリポジトリに同じ変更を適用しようとする際、一貫してマージ可能なPRを生成することが非常に困難でした。優れたプロンプトを作成すること自体も難しいですが、エージェントが正しくタスクを実行したかを検証することはさらに複雑な問題でした。

自前のエージェントループ構築：予測可能性への第一歩

より予測可能なエージェントを求めて、SpotifyはLLM APIの上に独自の「エージェンティックループ（agentic loop）」を構築しました。各タスクは3つの部分で構成されていました：

  1. ユーザーがプロンプトとすべての対象ファイルリストを提供
  2. エージェントがプロンプトに基づいてファイルを編集し、各ターンでビルドシステムからのフィードバックを統合
  3. テスト合格または制限超過時にタスク完了（セッションあたり10ターン、最大3回再試行）

この方式は小さな変更（例：デプロイマニフェストの編集、設定フラグの交換、1行のコード変更）にはうまく機能しました。しかし、それを超える複雑なタスクではすぐに限界にぶつかりました。

最大の問題はコンテキストウィンドウ管理でした。ユーザーがgit grepコマンドで正確なファイルを選択する必要があり、検索パターンが広すぎるとLLMのコンテキストウィンドウが溢れ、狭すぎるとエージェントが問題解決に十分な情報を得られませんでした。

また、複数ファイルの変更に弱かったのです。例えば、あるファイルのpublicメソッドを修正し、続けてすべての呼び出し箇所を変更する「カスケード変更」が必要な場合、エージェントは頻繁にターンを使い果たしたり、コンテキストウィンドウがいっぱいになって元のタスクを忘れてしまったりしました。

Claude Code導入：ゲームチェンジャー

自前構築エージェントの限界を克服するため、SpotifyはClaude Codeに切り替えました。Claude Codeはより自然なタスク指向プロンプトを許可し、内蔵のTodoリスト管理とサブエージェント生成機能により、コンテキストウィンドウの問題を緩和してくれました。

現在、Claude CodeはSpotifyで最もパフォーマンスの高いエージェントであり、約50件のマイグレーションと大半のバックグラウンドエージェントPRに使用されています。

プロンプトの技術：実戦の教訓

Spotifyチームが強調する核心はこれです：プロンプト作成は思ったよりずっと難しい。 ほとんどの開発者はこれに関する経験が不足しています。単純に見える指示がどのようにとんでもない結果を引き起こすのか、プロンプトの微妙な違いを理解していなければ気づきにくいのです。

主要アンチパターン

  1. 過度に一般的なプロンプト - エージェントが意図と結果をテレパシーで察することを期待します。
  2. 過度に具体的なプロンプト - すべてのケースを一つ一つ列挙しますが、予期せぬ状況が発生するとすぐに崩壊します。

Spotifyの6つの核心的な教訓

  1. エージェントに合わせてプロンプトを調整せよ

    • 自前構築エージェント：厳格なステップバイステップ指示が効果的
    • Claude Code：最終状態を説明し、到達方法は自律性に任せる方が良い

  2. 前提条件を明示せよ

    • エージェントは指示に従うことに熱心すぎます。マイグレーションシナリオでプロンプトを複数のリポジトリに再利用する際に特に問題になります。「この作業が不可能な場合は何もしない」といった条件を明確に記述しましょう。

  3. 例を使用せよ

    • 具体的なコード例がいくつかあるだけで、結果に大きな影響を与えます。

  4. 最終状態を定義せよ、理想的にはテストの形で

    • 「このコードを改善して」は悪いプロンプトです。エージェントが反復的に解決策を見つけられるよう、検証可能な目標が必要です。

  5. 一度に一つの変更だけを行え

    • 複数の関連変更を一つの複雑なプロンプトにまとめるのは便利に見えますが、コンテキストウィンドウを消費したり、部分的な結果しか出さない可能性が高くなります。

  6. エージェントにプロンプトに関するフィードバックを求めよ

    • セッション後、エージェント自身がプロンプトで何が欠けていたかを驚くほど正確に把握します。このフィードバックを活用してプロンプトを改善しましょう。

実際のプロンプト例：AutoValue → Java Records マイグレーション

# 目標: AutoValueで生成されたクラスをJava Recordに変換
# 前提条件: 対象ファイルがJava 16+を使用するプロジェクトに属していること

以下のルールに従って変換を実行せよ:
1. @AutoValueアノテーションが付いたクラスを探せ。
2. 各クラスをrecordに変換せよ。(例: public final class Foo → public record Foo)
3. abstractアクセサをrecordコンポーネントに置き換えよ。
4. toBuilder(), builder()メソッドがあれば削除せよ。
5. 変換後、コンパイルが通るか'verify'ツールで確認せよ。
6. コンパイルエラーが発生したら元に戻し、理由をログに残せ。

# 例
# Before:
# @AutoValue
# public abstract class User {
#   public abstract String name();
#   public abstract int age();
# }
# After:
# public record User(String name, int age) { }

適切なツール選択：制限こそが自由

Spotifyはバックグラウンドコーディングエージェントのツールとフックを非常に限定的に保っています。これはエージェントがプロンプトに集中し、正しいコード変更を生成できるようにするためです。ツールが多ければ多いほど、予測不可能性が高まります。

現在、エージェントがアクセスできるツールは3つだけです：

ツール用途備考
verifyフォーマッタ、リンター、テスト実行自社ビルドシステム呼び出しをMCPでエンコード、ログ要約
git制限的で標準化されたGitアクセスpush禁止、committer固定、標準コミットメッセージ形式
Bash厳格な許可リストのコマンドripgrepなど少数のコマンドのみ許可

注意点: 現在、コード検索やドキュメントツールはエージェントに公開されていません。代わりに、ユーザーがプロンプトに関連コンテキストを事前に圧縮して渡すように設計されています。これは予測可能性を高める代わりに、ユーザーにより多くの準備作業を要求します。

日本開発コミュニティでの適用文脈

日本の大規模エンタープライズプロジェクトやSIer環境においても、このアプローチは非常に有用です。数百のモジュールで構成されるレガシーシステムにおいて、APIバージョンアップグレード、ライブラリマイグレーション、コーディング規約変更などを自動化する際、Spotifyの「制限されたツール＋洗練されたプロンプト」戦略は効果を発揮します。

ただし、日本環境では以下の点を考慮する必要があります：

  • 自社ビルドシステムがMCPと互換性を持つ必要がある
  • リポジトリごとにビルド設定が大きく異なる場合、verifyツールの一般化が困難な可能性
  • セキュリティポリシー上、エージェントのGitアクセス権限を細かく制御する必要がある

本技術の限界と注意点

  • プロンプト品質への依存: 依然として「試行錯誤」に大きく依存しています。プロンプトやモデルのパフォーマンスを評価する体系的な方法はまだありません。
  • 検証の難しさ: PRがマージされたからといって、元の問題が解決されたか確信できません。フィードバックループが不可欠です。
  • スケーラビリティと予測可能性のトレードオフ: より多くのツールとコンテキストを提供すれば複雑なタスクが可能になりますが、予測可能性は低下します。

次のステップ学習方向

  • フィードバックループ構築: PRマージ後、実際に問題が解決されたかを自動確認するシステムを設計してみましょう。
  • プロンプトのバージョン管理: プロンプトをコードのようにバージョン管理し、テストを書き、パフォーマンスを評価する方法を研究しましょう。
  • MCPサーバー開発: 自社ビルドシステムやデプロイパイプラインと連携するMCPサーバーを自作してみるのも良い実践です。

合わせて読みたい記事：

Spotify engineering team using Claude Code for automated code migration System Abstract Visual

結論：まだ道半ば

Spotifyはバックグラウンドコーディングエージェントの最先端機能を引き続き探求しています。Claude Codeは大きな可能性を示し、エージェントへの指示方法と効果的なツール構築を学ぶ中で大きな進歩を遂げました。タスクを適切な単位に分解し、良いプロンプトを作成し、ツールをインフラとより良く統合することが、クリーンなPRを生成する鍵です。

しかし実際には、まだ大部分を直感に頼っています。プロンプトは試行錯誤を通じて進化しており、どのプロンプトやモデルが最良のパフォーマンスを発揮するかを評価する体系的な方法はまだありません。そして、マージされたPRが実際に元の問題を解決したか、どうやって確認できるのでしょうか？この問いへの答えは次回の記事で扱われる予定です。

今すぐあなたのプロジェクトに適用できる一言アドバイス：小さく始め、徹底的にテストし、エージェントのフィードバックに耳を傾けよ。

Cloud infrastructure diagram showing multi-repository PR automation pipeline

本コンテンツは、信頼性の高い情報源をもとにAIツールを活用して作成され、編集者によるレビューを経て公開されています。専門家によるアドバイスの代替となるものではありません。