オーケストレーション用のオープンソース仕様: Symphony

2026年4月27日 エンジニアリング

Alex Kotliarskyi、Victor Zhu、Zach Brockによる

概要

6ヶ月前、内部生産性ツールに取り組んでいた際、私たちのチームは物議を醸す決断を下しました。人間が書いたコードなしでリポジトリを構築するというものです。プロジェクトリポジトリのすべての行はCodexによって生成される必要がありました。それを実現するために、エンジニアリングワークフローを一から再設計しました。エージェント対応のリポジトリを構築し、自動テストとガードレールに大きく投資し、Codexを本格的なチームメンバーとして扱いました。その経験は以前のブログ投稿で記録しました。

それは機能しましたが、その後、次のボトルネックに直面しました。コンテキストスイッチングです。この新しい問題を解決するために、Symphonyというシステムを構築しました。

Symphonyはエージェントオーケストレーターで、Linearのようなプロジェクト管理ボードをコーディングエージェント用のコントロールプレーンに変えます。すべてのオープンタスクはエージェントを取得し、エージェントは継続的に実行され、人間が結果をレビューします。このポストでは、Symphonyの作成方法を説明します。これにより、一部のチームでランディングされたプルリクエストが500%増加しました。また、独自のイシュートラッカーを常時稼働するエージェントオーケストレーターに変える方法についても説明します。

インタラクティブコーディングエージェントの限界

コーディングエージェント（WebアプリまたはCLIでアクセスされるかどうかにかかわらず）は、使いやすくなっていますが、依然としてインタラクティブツールです。OpenAIでのエージェント作業の規模が増加するにつれて、新しい種類の負担が生じました。各エンジニアは数個のCodexセッションを開き、タスクを割り当て、出力をレビューし、エージェントを操舵し、繰り返します。実際には、ほとんどの人はコンテキストスイッチングが苦痛になる前に、3～5個のセッションを快適に管理できます。それを超えると、生産性が低下します。どのセッションが何をしているのか忘れてしまい、ターミナル間をジャンプしてエージェントを軌道に戻し、途中で停止した長時間実行タスクをデバッグします。エージェントは高速でしたが、システムボトルネックがありました。人間の注意です。本質的に、私たちは非常に有能なジュニアエンジニアのチームを構築し、その後、人間のエンジニアに彼らをマイクロマネジメントするよう割り当てました。それはスケールしません。

視点の転換

私たちは間違ったことを最適化していることに気づきました。コーディングセッションとマージされたPRを中心にシステムを方向付けていましたが、PRとセッションは本当に手段に過ぎません。ソフトウェアワークフローは主に成果物の周りに組織されています。イシュー、タスク、チケット、マイルストーンです。そこで、エージェントを直接監督するのをやめて、代わりにタスクトラッカーから作業を引き出させたらどうなるかと自問しました。そのアイデアがSymphonyになりました。エージェント作業を監督するための仕様として機能する書かれた仕様です。

イシュートラッカーをエージェントオーケストレーターに変える

Symphonyは単純な概念から始まりました。すべてのオープンタスクはエージェントによって取得され、完了される必要があります。複数のタブでCodexセッションを管理する代わりに、イシュートラッカーをコントロールプレーンにしました。このセットアップでは、各オープンLinearイシューは専用のエージェントワークスペースにマップされます。Symphonyはタスクボードを継続的に監視し、すべてのアクティブなタスクが完了するまでループで実行されているエージェントを確保します。エージェントがクラッシュまたは停止した場合、Symphonyはそれを再起動します。新しい作業が表示された場合、Symphonyはそれを取得し、作業の整理を開始します。

チケットステータスに基づいてワークフローを構築し、タスクマネージャーLinearを状態マシンとして使用しました。実際には、Symphonyは作業をセッションとプルリクエストから分離します。一部のイシューはリポジトリ全体で複数のPRを生成します。その他は、コードベースに触れることのない純粋な調査または分析です。作業がこのように抽象化されると、チケットはより大きな作業単位を表すことができます。Symphonyを使用して複雑な機能とインフラストラクチャマイグレーションをオーケストレーションすることは定期的です。

例えば、エージェントにコードベース、Slack、またはNotionを分析し、実装計画を作成するよう求めるタスクをファイルすることができます。計画に満足したら、エージェントはタスクのツリーを生成し、作業をステージに分割し、タスク間の依存関係を定義します。エージェントは、ブロックされていないタスクでのみ作業を開始するため、実行はDAG（実行ステップのシーケンス）に対して自然かつ最適に並列で展開されます。

例えば、ReactアップグレードをViteへのマイグレーションでブロックされたとしてマークしました。予想通り、エージェントはViteへのマイグレーションが完了した後にのみReactのアップグレードを開始しました。

エージェントは自分たちで作業を作成することもできます。実装またはレビュー中に、現在のタスクの範囲外にある改善に気付くことがよくあります。パフォーマンスの問題、リファクタリングの機会、またはより良いアーキテクチャです。その場合、彼らは単に新しいイシューをファイルします。これは後で評価およびスケジュール設定できます。これらのフォローアップタスクの多くもエージェントによって取得されます。このプロセスを監督している間、エージェントは整理された状態を保ち、作業を前に進めます。

このような作業方法は、曖昧な作業を開始する認知コストを劇的に削減します。エージェントが何か間違ったことをした場合、それは依然として有用な情報であり、私たちへのコストはほぼゼロです。エージェントがプロトタイプを作成して探索するためのチケットを非常に安く提出でき、気に入らない探索を破棄できます。オーケストレーターはdevboxで実行され、決して眠らないため、どこからでもタスクを追加でき、エージェントがそれを取得することを知っています。例えば、チームの1人のエンジニアは、居心地の良いキャビンの悪いwifiからLinearアプリで電話から3つの重要な変更を加えました。

このような作業方法からの探索の増加

Symphonyで作業する効果を観察する際、最も明らかな変化は出力でした。OpenAIの一部のチームでは、最初の3週間でランディングされたPRの数が500%増加しました。OpenAI外では、Linearの創設者Karri Saarinenは、Symphonyをリリースしたときにワークスペースが作成されたスパイクを強調しました。

しかし、より深い変化は、チームが作業をどのように考えるかです。エンジニアがCodexセッションの監督に時間を費やさなくなると、コード変更の経済学は完全に変わります。各変更の認識コストは低下します。人間の努力を実装自体の駆動に投資していないためです。それは私たちの行動を変えました。Symphonyで投機的なタスクをスピンアップするのは簡単になりました。アイデアを試し、リファクタリングを探索し、仮説をテストし、有望に見える結果のみを保持します。

また、作業を開始できる人を広げます。プロダクトマネージャーとデザイナーは、Symphonyに機能リクエストを直接ファイルできるようになりました。リポジトリをチェックアウトしたり、Codexセッションを管理したりする必要はありません。機能を説明し、実際の製品内で機能する機能のビデオウォークスルーを含むレビューパケットを取得します。

Symphonyは、OpenAIにあるような大規模なモノレポでも輝いています。PRのラストマイルのランディングが遅く、脆弱です。システムはCIを監視し、必要に応じてリベースし、競合を解決し、不安定なチェックを再試行し、一般的に変更をパイプラインを通してシェパードします。チケットが「マージ中」に到達するまでに、変更が人間のベビーシッティングなしでメインブランチに入ることに高い信頼があります。

Symphonyを実装した後、エージェントにより多くの作業を委任し、より難しく、より探索的なタスクに焦点を当てます。

進捗は新しい、異なる問題をもたらします

このレベルで動作することにはトレードオフが伴います。エージェントを対話的に操舵することからチケットレベルで作業を割り当てることに移行したとき、飛行中に継続的に彼らを押し、必要に応じて進路を修正する能力を失いました。時々、エージェントは完全にマークを逃したものを生成しました。それは有用でした。これらの失敗はシステムのギャップを明らかにし、それをより堅牢にするのに役立ちました。結果を手動でパッチする代わりに、ガードレールとスキルを追加して、エージェントが次回成功できるようにしました。

時間が経つにつれて、これはエンドツーエンドテストの実行、Chrome DevToolsを通じたアプリの駆動、QAスモークテストの管理など、ハーネスに新しい機能を追加することにつながりました。ドキュメントを大幅に改善し、良いものが何であるかを明確にしました。

すべてのタスクがSymphonyスタイルの作業に適しているわけではありません。一部の問題は、エンジニアが対話的なCodexセッションで直接作業することを必要とします。特に曖昧な問題や、強い判断と専門知識が必要な作業です。実際には、これらは通常、エンジニアが時間を費やすのに最も興味深く楽しいタスクです。違いは、Symphonyが日常的な実装作業の大部分を処理できることです。これにより、エンジニアは小さなタスク間で継続的にコンテキストスイッチングする代わりに、一度に1つの難しい問題に焦点を当てることができます。

また、エージェントを状態マシンの厳密なノードとして扱うことはうまく機能しないことを学びました。モデルはより賢くなり、私たちがそれらを適合させようとするボックスよりも大きな問題を解決できます。エージェント作業の初期バージョンは、Codexにタスクを実装するよう求めていただけです。そのアプローチは制限が多すぎることが判明しました。Codexは複数のPRを作成し、レビューフィードバックを読み、それに対処することが完全に可能です。そこで、ツール（gh CLI、CIログを読むスキルなど）を与え、古いPRを閉じたり、完了した作業と放棄された作業に関するレポートを引き出したりするなど、Codexにより多くのことを行うよう求めることができます。

これらのタイプのタスクは、初期の機能実装ボックスの外にはるかに落ちました。そこで、最終的に厳密な遷移の代わりに目的を与えるエージェントに移行しました。良いマネージャーがチームの直属部下に目標を割り当てるのと同じようにです。モデルの力は推論する能力から来ているので、ツールとコンテキストを与え、彼らに料理させてください。

Symphonyを使用してSymphonyを構築する

Symphonyリポジトリを開くと、最初に気付くことは、Symphonyは技術的には単なるSPEC.mdファイルであるということです。問題と意図した解決策の定義です。複雑な監督システムを構築する代わりに、問題と意図した解決策を定義し、エージェントに高レベルの操舵を与えました。

# Symphony Service Specification

Status: Draft v1 (language-agnostic)

Purpose: Define a service that orchestrates coding agents to get project work done.

## 1. Problem Statement

Symphony is a long-running automation service that continuously reads work from an issue tracker
(Linear in this specification version), creates an isolated workspace for each issue, and runs a
coding agent session for that issue inside the workspace.

The service solves four operational problems:

- It turns issue execution into a repeatable daemon workflow instead of manual scripts.
- It isolates agent execution in per-issue workspaces so agent commands run only inside per-issue
workspace directories.
- It keeps the workflow policy in-repo ( `WORKFLOW.md` ) so teams version the agent prompt and runtime
settings with their code.
- It provides enough observability to operate and debug multiple concurrent agent runs.

Implementations are expected to document their trust and safety posture explicitly. This
specification does not require a single approval, sandbox, or operator-confirmation policy; some
implementations may target trusted environments with a high-trust configuration, while others may
require stricter approvals or sandboxing.

Important boundary:

- Symphony is a scheduler/runner and tracker reader.
- Ticket writes (state transitions, comments, PR links) are typically performed by the coding agent
using tools available in the workflow/runtime environment.
- A successful run may end at a workflow-defined handoff state (for example `Human Review` ), not
necessarily `Done` .

## 2. Goals and Non-Goals

### 2.1 Goals

- Poll the issue tracker on a fixed cadence and dispatch work with bounded concurrency.
- Maintain a single authoritative orchestrator state for dispatch, retries, and reconciliation.
- Create deterministic per-issue workspaces and preserve them across runs.
- Stop active runs when issue state changes make them ineligible.
- Recover from transient failures with exponential backoff.
- Load runtime behavior from a repository-owned `WORKFLOW.md` contract.
- Expose operator-visible observability (at minimum structured logs).
- Support restart recovery without requiring persistence.