5体のAIコーディングエージェントがフィーチャーエピックに取り組んでいる。Agent 1がAPI層を構築中。Agent 2はそのAPIがないとフロントエンドを接続できない。Agent 3は両方に依存する統合テストを書いている。Agent 4と5はマイグレーションとドキュメントを担当し、それぞれ異なるピースでブロックされている。

これは約20分機能する。そしてAgent 1が予期しないスキーマ問題にぶつかり、Agent 2が停止する。Agent 3はAgent 2にブロックされ、Agent 2はAgent 1にブロックされている。Agent 4と5は作業を続けるが、チェーンが解決するまでマージできない。1時間何も出荷されていない理由を不思議に思い、すべてのイシューに対してbd blockedを実行し始めるまで気づかない。

依存関係の情報は存在する。イシュートラッカーの中にある。しかしCLIで管理していると、フラットテキスト出力から頭の中でグラフを再構成することになる。その再構成は、最も重要な瞬間、つまりグラフが複雑で壊れているときに失敗する。

beadsが依存関係を追跡する方法

beadsは、AIエージェントのコーディネーションのために構築されたGitバックドのイシュートラッカーだ。すべてをリポジトリの.beads/ディレクトリ内のローカルDoltデータベースに保存する。クラウドサービスなし、アカウントなし、同期コンフリクトなし。

エージェントは1つのコマンドで依存関係を宣言する:

bd dep add ISSUE-42 ISSUE-37

これはISSUE-42がISSUE-37に依存することを記録する。ISSUE-37がクローズされるまでISSUE-42は進められない。逆のクエリも同様にシンプルだ:

bd blocked

ワークスペース内で未解決の依存関係によりブロックされているすべてのイシューを返す。特定のイシューについては:

bd dep list ISSUE-42

ISSUE-42が何に依存しているか、何がISSUE-42に依存しているかを表示する。

データモデルはクリーンだ。問題は依存関係の記録ではない。問題はそれを見ることだ。5体のエージェントにまたがる30のアクティブなイシューがある場合、bd blockedを実行するとリストが得られる。リストでは、ISSUE-12が3体のエージェントにまたがる7つの下流タスクをブロックするボトルネックであることは示されない。リストでは、Agent 3がISSUE-18とISSUE-22の間に循環依存チェーンを作成したことは示されない。グラフの空間的なビューが必要で、逐次的なものではない。

Beadboxが見せるもの

Beadboxはbeads CLIをビジュアルインターフェースでラップするネイティブデスクトップアプリだ。エージェントが書き込むのと同じ.beads/データベースから読み取り、エージェントの作業に合わせてリアルタイムで更新される。

エピックツリービューでは、未解決の依存関係を持つすべてのイシューにブロックバッジがインラインで表示される。エピックの完全なツリー構造が見え、ブロックされたイシューは一目でマークされている。実行するコマンドもパースする出力もない。

依存関係チェーンが空間的に見える。ISSUE-42がISSUE-37に依存し、ISSUE-37がISSUE-15に依存し、ISSUE-15がスタックしているAgent 1にアサインされている場合、ツリーをスキャンしてそのチェーンをたどれる。個別のCLIクエリから再構成することなく、ボトルネックの形が見える。

リアルタイムの部分が重要だ。Agent 1がようやくISSUE-15をクローズすると、Beadbox UIに1秒以内に反映される。ISSUE-37のブロックバッジが消える。ISSUE-37だけがISSUE-42をブロックしていた場合、そのバッジも消える。作業が完了するにつれて依存関係チェーンが崩壊していくのを、リフレッシュや再クエリなしで見守ることができる。

内部的には、これはシンプルなパイプラインで動作する: WebSocketサーバーがfs.watch()で.beads/ディレクトリを監視する。エージェントがデータベースに書き込む(イシューのクローズ、依存関係の追加、ステータスの更新)と、ファイルシステムイベントが接続されたすべてのクライアントへのブロードキャストをトリガーする。React UIが新しいデータで再レンダリングされる。エージェントのアクションからビジュアル更新までサブ秒のレイテンシ。

具体的なシナリオ: ボトルネックの発見

5体のエージェントが24のイシューを持つフィーチャーエピックに取り組んでいる。Beadboxを開いてエピックツリーを見る。12のイシューが進行中。6つにブロックバッジが表示されている。

それだけですでに持っていなかった情報だ。bd listは12の進行中イシューを表示するが、どの進行中イシューが実際に停滞しているかを理解するには、bd blockedを別途実行してクロスリファレンスする必要がある。

ブロックバッジをスキャンすると気づくことがある: 6つのブロックされたイシューのうち4つが、Agent 4にアサインされたデータベーススキーママイグレーションのISSUE-19に依存している。Agent 4はまだ作業中だが、ISSUE-19が単一障害点のボトルネックになっている。4体のエージェントが事実上アイドル状態で、1つのタスクを待っている。

ビジュアルビューがなければ、これに気づくのはあと1時間後かもしれない。ビジュアルビューがあれば、即座に介入できる。ISSUE-19をより速いエージェントに再アサインするかもしれない。一部の依存先を先にブロック解除できるよう、より小さなピースに分割するかもしれない。4つの依存関係のうち2つが過剰宣言だったと気づき、bd dep removeで削除できるかもしれない。

ポイントは情報が以前利用不可能だったということではない。常にデータベースにあった。ポイントは、ビジュアル表現がフラットテキストでは埋もれるパターンを表面化するということだ。

よくある依存関係アンチパターン

1つのリポジトリで複数のAIエージェントを実行すると、いくつかの繰り返し発生する依存関係の問題が生まれる。すべてCLIクエリよりビジュアルでキャッチしやすい。

過剰宣言。 エージェントは保守的になりがちだ。疑わしいときは依存関係を宣言する。結果として必要以上に密な依存関係グラフになり、実際には必要ない作業にブロックされるイシューが出る。Beadboxでは、イシューにブロックバッジがあるのにブロッキングイシューがコードベースのまったく無関係な部分にあるとき、これに気づく。素早くbd dep removeでクリーンアップする。

循環チェーン。 Agent AがAgent Bの作業への依存を宣言。Agent Bが独立して作業し、Agent Aの作業への依存を宣言。両方が互いにブロックされ、どちらも進められない。beads CLIは作成時に明らかな循環依存をキャッチするが、3つ以上のイシューを経由する間接的なサイクルは検出が難しい。エピックツリーでは、他の作業が完了しても決して解消しないブロックバッジの塊として気づく。

単一障害点ボトルネック。 1つのイシューに5、6、7の下流依存先が蓄積する。並列で作業するエージェントが全員同じ基盤ピースを必要とするとき、これは自然に起きる。上のシナリオがこのパターンを示している。リストビューでは7つのブロックされたイシューが見える。ツリービューでは7つの矢印が同じノードを指しているのが見える。ボトルネックは明白だ。

はじめよう

BeadboxはmacOS、Linux、Windowsで動作する。Homebrewでインストール:

brew tap beadbox/cask && brew install --cask beadbox

.beads/ディレクトリを持つ任意のリポジトリに向ける。すでにエージェントフリートでbeadsを実行しているなら、Beadboxが既存のデータベースをピックアップして即座にレンダリングを開始する。インポート手順なし、設定なし、アカウント作成なし。

エージェントは引き続きCLIを使う。bd dep add、bd update、bd closeをいつも通り実行する。Beadboxがデータベースを監視し、すべての変更をリアルタイムで反映する。エージェントのワークフローを変更せずにビジュアル層が得られる。

Beadboxはベータ期間中無料。

単一のコードベースで複数のAIエージェントをコーディネートしているなら、依存関係グラフがワークフローを最初に壊すものだ。CLIを通じて盲目的に管理するか、見えるようにするか。見えるほうが速い。