エージェント指向エンジニアリング

SwarmForge: Uncle Bob のエージェント群が正しく捉えていること

SwarmForge は複数の AI コーディングエージェントを tmux のウィンドウで動かします。各エージェントは専用の git worktree を持ち、担うのはただ 1 つのエンジニアリングロールです。ツール自体は意図的に地味で、面白いのはそこに刻まれた組織図です。

AI エンジニアリングチームに相談する AI 開発サービスを見る

SwarmForge の実体

SwarmForge は、多くのチームがすでに持っている 3 つのプリミティブ、すなわち tmux のウィンドウ、git worktree、プロンプトファイルを、シェルと Babashka で束ねた harness です。各ウィンドウは 1 つのロールのエージェントを .worktrees/ 配下の専用 worktree に対して動かすため、2 つのエージェントが同じ作業ツリーを取り合うことはありません。振る舞いは swarmforge/roles/<role>.prompt のプレーンテキストで決まり、その土台に共有の constitution.prompt とその記事群があります。エージェントは互いの端末に打ち込むのではなく、.swarmforge/handoffs/ 経由で検証済みのハンドオフをキューに入れます。積荷はコミットの 10 文字の短縮 hash か、最大 80 文字のメモのどちらかです。バックエンドはロール単位で選べるので、1 つのセッションで Claude、Codex、Copilot、Grok を混在させられます。

main ブランチはドキュメント用です。実際に動く群れは two-pack、four-pack、six-pack の各ブランチにあり、望む形のブランチを取得して ./swarm を実行します。前提は zsh、git、tmux、Babashka、そして設定済みのエージェント CLI です。

3 つの群れの形

各ブランチは「そのタスクにどれだけのプロセスが必要か」への異なる答えです。流れはキューではなくリングで、仕事は一巡して戻ってきます。

two-pack

coder → cleaner → coder

テストファーストで書く coder と、片付け・CRAP と DRY のレビュー・構造の修正を担う cleaner。実用最小のループです。まず書き、それを愛着のない誰かに渡す。

four-pack

specifier → coder → refactorer → architect → specifier

Gherkin の受け入れ仕様が先頭に入ります。refactorer が振る舞いを保ったまま整理してカバレッジを補い、architect が構造と依存の向きをレビューしてから、リングは再び仕様へ戻ります。

six-pack

specifier → coder → cleaner → architect → hardener → QA

コードを変異させて盲点を探すハードニングのパスと、実行可能な検証を回す QA ロールが加わります。品質を 1 エージェントの善意ではなく、分離された関心事として扱う形です。

1 エージェント、1 規律

ロールこそが主張です。どれもが普段は、同じ人・同じ 1 時間・同じ締め切りに押し込められている仕事です。

specifier

Gherkin の受け入れ仕様と QA 手順を書きます。曖昧な一文のまま群れに入るものは何もない。多くのエージェントワークフローが立ち直れない失敗モードは、まさにそこです。

coder

テストファーストで実装します。TDD をこのウィンドウの既定の振る舞いにしているのは、誰も読まない規約ページではなくロールのプロンプトです。

cleaner

局所的な整理、カバレッジ、CRAP と DRY のレビュー。命名と重複が、誰も対応しないレビューコメントではなく専用のパスを与えられます。

architect

モジュール構造、境界、依存の向き。目の前のチケットではなく全体の形を気にしてよい唯一のロールです。

ハードニングのロール

ミューテーションによるハードニング。コードを揺らして、テストスイートがどこで盲目かを突き止めます。コードが既にきれいになった後に意図的に置かれた、否定側のチェックです。

QA

実行可能な検証スクリプトと通知。検証とは走って報告するものであり、変更が問題なさそうに見えたという感覚ではありません。

協調の仕組み

3 つのファイルと 3 つのスクリプトが protocol の全部を担います。それが要点です。トポロジーはデータであり、規律はテキストです。

トポロジーは設定ファイル 1 枚

conf

各行が tmux のウィンドウを宣言します。どのロールか、どのエージェントバックエンドか、どの worktree か、そして仕事をタスク単位で受けるのかバッチで受けるのか。

# swarmforge/swarmforge.conf
# window <role> <agent> <worktree> [task|batch] [extra-cli-args...]
window coordinator codex master
window coder       codex coder
window architect   codex architect

ハンドオフは会話ではなく検証

エージェントは送信側のハンドオフをキューに入れ、次のロールは空いたときに仕事を受け取り、現在の項目を閉じるのは明示的な行為です。積荷はコミットかごく短いメモなので、意味はコードが運ばなければなりません。

# queue work for the next role: a commit, or a note of <= 80 chars
./swarm_handoff.sh coder 4f2a9c1b0d "boundary rule now specified"

# on the receiving side
./ready_for_next.sh      # accept the next item or batch
./done_with_current.sh   # close it out and free the window

標準はプロンプトの木に住む

text

共有の記事がエンジニアリング規則、ハンドオフ規則、ワークフローを持ち、ローカルの記事でプロジェクトがそれを上書きします。ロールのプロンプトはその上に載ります。コーディング標準は、仕事についての文書ではなく仕事への入力になります。

swarmforge/
  swarmforge.conf
  constitution.prompt
  constitution/articles/
    engineering.prompt
    handoffs.prompt
    workflow.prompt
    project.prompt
    local-engineering.prompt
    local-workflow.prompt
  roles/
    <role>.prompt

動かさなくても借用すべきもの

各パスに名前と 1 つの仕事を与える

- 仕様、実装、整理、構造、検証を、別々の指示を持つ別々のパスに分ける
- 1 つのエージェント、あるいは 1 人の技術者に、5 つの関心事を同時に抱えさせるのをやめる
- どのパスなのかをプルリクエストに書き、どの問いが既に答えられているかレビュアーに分かるようにする

ブランチだけでなく作業空間を分離する

- ロールごとの git worktree は、2 つのエージェントが同じファイルを同時に編集するという障害の系統をまるごと消す
- 分離は並行作業を可読にする。各ロールが独立に検査できるツリーを持つ
- 同じ手は、群れなしでローカルに複数エージェントを動かす 1 人にも効く

ハンドオフを狭く、検証付きにする

- コミット参照と 1 行の短文は、意図をコードとメッセージに押し込む
- ハンドオフ境界での検証は、次のロールが 1 回の実行を無駄にする前に不正な依頼を捕まえる
- 狭いハンドオフは監査できる。誰が何をいつ渡したかを再構成できる

標準は仕事が起こる場所に置く

- プロンプトの記事として書かれたエンジニアリング規則は、wiki ページと違って毎タスク読まれる
- 共有の規則とプロジェクト固有の上書きを分け、あるチームの例外が全体の規則にならないようにする
- 規則をコードと一緒にバージョン管理し、その変更をコードと同じようにレビューする

正直な留保はどこか

リングにはリングの費用がかかる

6 つのロールが互いの成果をレビューすれば、1 変更あたり複数回のエージェント実行になります。小さなタスクでは two-pack のループが合理的で、six-pack は欠陥が高くつく仕事のためのものです。

80 文字は細い管

ごく小さなハンドオフの積荷は規律です。コミット自身が説明しなければならない。同時にそれは、群れの共通理解が仕様とコードだけに宿るという意味でもあります。コードが自ら説明していないなら、群れがそれを直してはくれません。

ロールはプロンプトであって保証ではない

TDD を使えと書いたプロンプトは強い後押しですが、強制の仕組みではありません。本当に効くのは実行可能なもの、つまりテスト実行、ミューテーション実行、QA スクリプトです。それらは群れの中だけでなく CI に置いてください。

承認する人は依然として必要

群れの出力は変更の提案であり、リリースの決定ではありません。責任は tmux のウィンドウに分散せず、もっともらしいコードの量が増えるほどレビュアーの仕事は楽ではなく難しくなります。

ワークフローこそが貢献

tmux も Babashka も tarball インストールも取り除けば、SwarmForge はソフトウェア工学についての 1 つの主張になります。コードを住みやすく保つ規律は分離でき、それぞれが自分の指示を持つ自分の番を与えられるべきだ、という主張です。これはエージェント以前から真であり、だからこそ移植できます。

プラットフォームではなくリファレンス実装として読んでください。ロール分割、worktree による分離、検証付きハンドオフを取り入れれば、その仕事をするのが 6 エージェントでも 2 人の技術者でも、その両方が 1 つずつでも、価値のほとんどは得られます。

よくある質問

SwarmForge を動かすには何が必要ですか?

zsh、git、tmux、Babashka に加えて、Claude、Codex、Copilot、Grok などの設定済みエージェント CLI です。クラウドサービスも立ち上げるべきオーケストレーション層もありません。群れは目で追える tmux のウィンドウと、ディスク上のロールごとの worktree です。

チームはどのブランチから始めるべきですか?

two-pack です。ハンドオフの規律が自分たちの仕事に合うかを感じ取るにはロール 2 つで足り、それが分かる前に 6 ロールのフルリングの費用を正当化するのは難しいでしょう。

エージェント群があれば QA は不要になりますか?

なりません。QA を実行可能なスクリプトを持つ名前付きのロールへ移すのは、暗黙のまま放置するより改善ですが、検証自体は製品がユーザーに何を負っているかを理解した人が書く必要があります。

本番運用に耐えるオーケストレーションですか?

運用されたプラットフォームではなく、ワークフローのリファレンスとして扱ってください。持続する価値はエンジニアリング関心事の分割と狭いハンドオフ protocol にあり、どちらもシェルスクリプトとは独立に採用できます。