意図的にエージェントを減速させる

速いエージェントが良いソフトウェアを作るわけではない — 規律あるエージェントが作るのだ。RakuAIを一貫性のあるものに保っているスロットルは、本気でエージェント駆動のチームを運用するなら誰もが必要とすると私たちが考える規律そのものだ。

この土曜日の計画は、ここ数週末とは違うものだった。ここ数週はスループット重視の週末だった。80コミット、70コミット、その前は282。トレンドは上昇していた。私はエージェントキューを全開にして乗りこなし、積み上がっていくコードの行数を眺めていた。

この週末、私は意図的にそれを37コミットまで絞った。このグラフのトレンドは今や下降しており、それは意図的な下降であり、その理由について書いておきたい。なぜなら、AIエージェントで何かを構築している人のほとんどが予想するトレンドとは違うと思うからだ。

このワークフローについて本当に言えること

エージェントは疲れない。実装レイヤーからのスループットは、トークンコストと、キューにいくつのイシューが開いているかによって制限される。もし私が朝6時に100件のイシューをファイルすれば、キューは一日中空になっては満たされ、私は100件のPRを受け取ることになる。それが、全開で走らせたときにこのワークフローがすることだ。

全開で走らせたときにこのワークフローがしないことは、一貫性のあるコードベースを生み出すことだ。各PRは孤立した状態ではきれいに着地する。1日で着地する40件のPRの交差点で、ずれが生じ始める。命名規則が分岐していく。サブシステムの境界があいまいになっていく。あるイシューに取り組んだエージェントは、ランタイムレイヤーについて何かを前提としていたが、並行する別のイシューに取り組んだエージェントはそれを前提としていなかった。土曜の夜までには、その2つの前提が3つ目のPRの中で衝突し、それを調停しなければならなくなる。そしてその調停は雑になる。

このワークフローにおけるボトルネックはエージェントではない。エージェントが生み出したものを読み、アーキテクチャの一貫性を保つ人間のほうだ。

何を変えたか

2つある。どちらもこの週末のコミットパターンに表れている。

キューの深さを削った。 常時15件開いているエージェントキューのイシューの代わりに、それを6件まで落とした。エージェントはもう全開では走っていない。次のバッチが着地する前に、私が実際にその出力を読めるペースで走っている。

レビューを前倒しした。 エージェントのPRを、まとめて取り組めるバッチが溜まるまで放置する代わりに、開かれたときにそれぞれをレビューするやり方に切り替えた。これは遅く聞こえるし、実際遅い。だがこれは、ずれが伝播する前にそれを捕捉する。土曜の朝早くに修正された誤った前提は、土曜の夜に6件のPRにわたってほどく必要がなくなる。

この2つの変更を組み合わせた効果が、80コミットの週末ではなく37コミットの週末だ。組み合わせた効果はまた、先週の土曜よりも良い状態にあるコードベースでもある。それが要点だ。

それでも着地したもの

複数リポジトリの規律が、この週末でより固まった。ランタイム、SDK、ドキュメントのリポジトリはすべて足並みを揃えて動いた。ランタイムはREADMEにドキュメントディレクトリの概要を得た。SDKはそれに対応する相互参照を得た。ドキュメントは育った。3つのリポジトリのどれも、他を出し抜くことはなかった。

これが重要なのは、エージェント駆動のワークフローにおいて、ドキュメントは単なるドキュメントではないからだ。ドキュメントは、エージェントが次のイシューを拾うときに読む入力だ。もしドキュメントがランタイムの対応状況について嘘をついていれば、エージェントは忠実に、その嘘のバージョンのランタイムに対するコードを書き、そのコードは現実に対してコンパイルできなくなる。対処法は、3つのリポジトリすべてを常に正直に保つことだ。自分が自然と作業したくなるリポジトリがそのうちの一つであってもだ。

この週末のもう一つの、静かに重要だったことはAPI表面の整理だった。9月の急ぎの時期に追加されたいくつかのAPIは、公開インターフェースには属さないことが判明した。それらは内部用に降格された。エージェントはSDK全体にわたるその降格を1つのPRで処理した。それは、1人の人間がやれば丸一日かかる種類のリファクタだ。このワークフローでやれば、1つのイシューと1つのPR、そして注意深いレビューで済む。

このワークフローにおける「ベストプラクティス」とは何を意味するか

短いリストだ。ペースを削るという経験によって、この週末に研ぎ澄まされた。

ドキュメントは開発の出力ではなく入力だ。 ドキュメントが悪ければ、作業も悪くなる。コードを保守するようにそれを保守すること。コードをレビューするようにそれをレビューすること。ドキュメントが省略された機能はマージを拒否すること。

サブシステム間の境界は神聖だ。 エージェントは、コードベースがすでに持っていなかった境界を発明しない。境界がほしいなら、自分でそれを描き、ラベルを付け、それに違反するPRを拒否しなければならない。

リポジトリをまたぐ同期はファーストクラスのタスクだ。 ランタイムとSDKが足並みを揃えて動かなければならないとき、PRの説明はそれを述べなければならず、片方のマージはもう片方のマージにゲートされなければならない。2つのリポジトリの状態が乖離することは、避けやすい失敗モードの一つであり、そこから回復するのはより苦しい部類だ。

意図的に減速すること。 エージェントはそうしない。あなたがそうしなければならない。エージェントが100件のPRを出荷する週末が、コードベースが100件のPR分の価値だけ改善する週末と同じであるとは限らない。エージェントが37件のよくレビューされたPRを出荷する週末は、そうかもしれない。

パートナーにとって役に立つかもしれないこと

もしあなたが自律コーディングエージェントで何かを構築していて、「エージェントは速く働くが、コードベースは散らかっている」というこのワークフローのバージョンに陥っているなら、答えはより良いエージェントではない。答えは、より小さなキュー、より早いレビューのパス、そしてエージェントが入力として読むドキュメントだ。

もしあなたが、こうした自律PRワークフロー向けにコーディングエージェントをチューニングしているAIラボなら、実務上私が最も有用だと感じている指標は、1日あたりに出荷されたコード行数ではない。週の早い時期に着地したPRが、コードベースがその下で動いてしまったために、同じ週末の後半に書き直されなければならない頻度だ。その数字が低いほど、エージェントは実際の仕事がうまいということだ。

37コミット。先週の土曜日よりも良いコードベース。土曜の午後、私は散歩に行くつもりだ。