2つ目のClaude Codeエージェントを立ち上げた。ここから問題が始まる。

1つ目のエージェントはリファクタリングの途中。2つ目は同じファイルの一部に触る機能を実装する必要がある。お互いの存在を知らない。あなたはルーター、ステートストア、コンフリクト解決者のすべてを兼任していて、使えるツールはターミナルウィンドウ間でコンテキストをコピペすることだけだ。

ほとんどの開発者がClaude Codeで壁にぶつかるのはここだ。エージェントのコーディング能力が低いからではない。何に取り組むべきかを伝えるシステムがないからだ。

コピペ問題

Claude Codeのワークフローは大抵同じように始まる。頭の中に（あるいはJiraやGitHub issueに）タスクがあって、その説明をエージェントのプロンプトに貼り付ける。「認証フローを作って」「ページネーションのバグを直して」「ダークモード対応を追加して」

エージェント1つなら、これでうまくいく。エージェントはフルコンテキストを持っていて、出力を監視でき、画面を見ているから完了もわかる。

2つ目のエージェントを追加した瞬間にひびが入る。

エージェントAがAPIレイヤーをリファクタリングしている。エージェントBが新しいエンドポイントを構築している。どちらもserver/routes.tsを触っている。互いの変更を知らない。一方がpushして他方の作業が壊れた時にコンフリクトを発見する。あるいはもっと悪いケースでは、両方ローカルでは成功するが、マージ結果がどちらのdiffにも現れない形で壊れる。

根本原因はエージェントが雑だからではない。共有ステートが存在しないからだ。「エージェントAがAPIリファクタリングを担当している」と記録された場所がない。「routesファイルが修正中だから順番を待て」というステータスがない。エージェントたちは全体像を一切把握せず、個別のプロンプトで動いている。

3つ目のエージェントを追加すると、コーディングよりコーディネーションに時間を使うようになる。

エージェントがタスクシステムに本当に必要なもの

ツールを探す前に問う価値がある。Claude Codeエージェントが良い仕事をするために実際に必要なものは何か。

驚くほど少ない。

一意の識別子。 コミットやコメントで参照できるもの。「バグを直した」はマルチエージェントのログでは役に立たない。「PROJ-47完了：フィルタービューでページネーションが誤ったカウントを返す」は追跡可能だ。

明確なスコープ。 タイトル、説明、受け入れ基準。小説ではなく、ペルソナ付きのユーザーストーリーでもなく、「完了」がどう見えるかの具体的な記述。「/usersエンドポイントはページネーションされた結果を返す。ページサイズのデフォルトは25。next_cursorフィールドは最終ページでnull。」

更新可能なステータス。 エージェントは自分がどこにいるかを示す必要がある：クレーム済み、作業中、完了。これがないと、ターミナルウィンドウを覗いて推測する作業に戻る。

依存関係の認識。「PROJ-46がマージされるまでこれを始めるな」は最も一般的なマルチエージェント障害を防ぐ：まだ存在しないコードの上に構築すること。

このリストに何がないか注目してほしい。スプリント計画。ベロシティ追跡。カンバンボード。ストーリーポイント。カラーコードされたラベル付きエピック。エージェントにプロジェクト管理の見せかけは不要だ。必要なのはタスク、ステータス、「完了」と言う方法だけだ。

CLAUDE.mdの契約

タスクシステムはエージェントに何をやるか伝える。CLAUDE.mdファイルはどうやってやるか伝える。

複数のClaude Codeエージェントを運用しているなら、各エージェントにアイデンティティと境界を定義するCLAUDE.mdがあるべきだ。これはオプションの設定ではない。協調するエージェントと互いの足を踏むエージェントの違いそのものだ。

エンジニアリングエージェント向けの簡略化した例：

## Identity

Engineer for the project. You implement features, fix bugs,
and write tests. You own implementation quality.

## What You Own

- All files under `components/` and `lib/`
- Unit tests in `__tests__/`
- You may read but not modify files under `server/`

## What You Don't Own

- Deployment configuration (that's ops)
- Issue triage and prioritization (that's the coordinator)
- QA validation (QA tests your work independently)

## Completion Protocol

Before marking any task done:
1. Run the full test suite: `pnpm test`
2. Verify your change works manually
3. Comment what you did with the commit hash
4. Push before reporting completion

境界セクションが荷重を支える部分だ。明示的なファイルオーナーシップがなければ、エージェントは迷走する。エンジニアリングエージェントが「親切に」デプロイ設定をリファクタリングする。QAエージェントがテスト対象のコードをテストの代わりに変更して「修正」する。明示的な境界がこれらの障害モードを防ぐ。

完了プロトコルも同じくらい重要だ。最も一般的なエージェントの障害を防ぐ：単にコンパイルが通っただけで完了を主張すること。「フルテストスイートを実行」と「手動で検証」は具体的なゲートだ。このプロトコルに従うエージェントは人間が信頼できる成果物を生む。これなしのエージェントは一行一行確認が必要な成果物を生む。

これを複数エージェントにスケールすると、各メンバーが自分のレーン、引き継ぎプロトコル、「完了」の意味を知るフリートが得られる。

CLI-firstのタスク管理

ワークフローに関する気づきで、自分が思った以上に時間がかかったものがある。Claude CodeエージェントはGUIインターフェースよりCLIツールのほうが劇的にうまく機能する。

考えてみれば当然だ。Claude Codeエージェントはターミナルに住んでいる。コマンドを実行し、出力を読み、結果に基づいてアクションを取れる。Web UIをナビゲートし、ボタンをクリックし、レンダリングされたページを解釈するよう求めるのは、エージェントの自然なインターフェースに逆らうことだ。

CLIベースのタスクシステムなら、エージェントは一連の流れでこれを実行できる：

# Read the task
task show PROJ-47

# Claim it
task update PROJ-47 --status in_progress --assignee agent-1

# Do the work...

# Report completion
task comment PROJ-47 "DONE: Fixed pagination. Commit: abc1234"
task update PROJ-47 --status done

コンテキストスイッチなし。ブラウザウィンドウなし。カンバンボードのスクリーンショットなし。エージェントはタスクを読み、作業し、ステータスを更新する。すべて操作環境を離れずに。

出力はマシンリーダブルでもある。エージェント全体で何が起きているか確認する必要がある時、クエリできる：

task list --status in_progress    # What's being worked on?
task list --assignee agent-2      # What is agent-2 doing?
task list --blocked               # What's stuck?

これが機能するツーリングの形だ。エージェントの言語を話すCLI。

Beads：エージェントのためのローカルファーストissueトラッキング

上で説明したワークフローは仮説ではない。beadsを使って毎日実行しているものだ。beadsはまさにこの種のエージェント駆動開発のために作られた、オープンソースのローカルファーストissueトラッカーだ。

beadsはissue（「beads」と呼ばれる）をコードベースと並行してローカルのDoltデータベースに格納する。各beadにはID、タイトル、説明、ステータス、優先度、依存関係、コメントスレッドがある。CLIはbdと呼ばれ、エージェントがタスクを読み、ステータスを更新し、構造化されたコメントを残すために使うインターフェースだ。

実際のワークフロー。タスクを作成する：

bd create --title "Fix pagination on filtered views" \
  --description "The /users endpoint returns wrong count when filters are applied. Page size defaults to 25. next_cursor should be null on the last page." \
  --priority p2

エージェントがクレームする：

bd update bb-r3k2 --claim --actor eng1
bd update bb-r3k2 --status in_progress

コードを書く前に、エージェントはプランをコメントする：

bd comments add bb-r3k2 --author eng1 "PLAN:
1. Fix count query in /users to apply filters before COUNT()
2. Add cursor boundary check for last page
3. Add test cases for filtered pagination

Files:
- server/routes/users.ts - fix count query
- server/routes/users.test.ts - add filtered pagination tests"

これはチェックポイントだ。プランが間違っていれば、45分後に悪い実装を発見する代わりに30秒で気づける。

エージェントは作業を行い、テストを実行し、完了をコメントする：

bd comments add bb-r3k2 --author eng1 "DONE: Fixed filtered pagination count.

- COUNT() now applies the same WHERE clause as the data query
- next_cursor returns null when offset + page_size >= total_count
- Added 4 test cases covering filtered + unfiltered pagination

Commit: a1b2c3d"

bd update bb-r3k2 --status ready_for_qa

タスクには完全な監査証跡がある：何がリクエストされたか、エージェントが何を計画したか、実際に何をしたか、レビュー用のコミットハッシュ。QAを実行する2番目のエージェントがこれを拾って独立に検証できる。

これが機能するのは、beadsがエージェントと同じ言語を話すからだ。すべてがCLIコマンド。すべてが構造化された出力を生成する。ツールとエージェントの間にインピーダンスミスマッチがない。

全体像を見る

CLIワークフローは3〜4エージェントまでスケールし、そこで新たな天井に達する。ツールの天井ではなく、認知的な天井だ。

5エージェントになると、bd listを実行してプロジェクトの状態を頭の中で組み立てるのは、スプレッドシートを読みながら依存関係グラフを頭の中に保持しようとするようなものだ。どのタスクがブロックされている？どのエージェントが20分間ステータスを更新していない？機能エピックは60%完了か80%完了か？情報はすべてCLI出力にあるが、組み立てるのに必要な労力はエージェントが増えるたびに蓄積される。

ここにBeadboxが収まる。beadsの上に位置するリアルタイムダッシュボードで、エージェントフリート全体の状態を表示する。視覚的にレンダリングされた依存関係ツリー。エピックの進捗バー。5つのbd showコマンドを実行せずにスキャンできるエージェントコメントスレッド。

BeadboxはCLIを置き換えない。エージェントは引き続きすべてにbdを使う。Beadboxは全体像が必要な時に開くレイヤーだ：どのワークストリームが動いているか、どれが止まっているか、ボトルネックはどこか。beadsデータベースの変更を監視し、リアルタイムで更新されるので、古いデータを見ることはない。

ベータ期間中は無料で、完全にローカルマシン上で動作する。アカウント不要、クラウド不要、データはローカルに残る。

はじめ方

構造化されたタスク管理から価値を得るのに13エージェントは必要ない。2つのClaude Codeエージェントと1つのルールから始めよう：すべてのタスクにbeadを作り、すべてのエージェントはコーディング前にプランをコメントし、すべての完了に検証ステップを含める。

このパターンは複利で効く。エージェントに共有タスクシステムが備わったら、独立に作業を検証するQAエージェントを追加できる。優先度キューからタスクをディスパッチするコーディネーターを追加できる。コーディネーションのオーバーヘッドが線形に増加することなく5、10、15エージェントにスケールできる。以前は手動のコンテキストスイッチだったものをプロトコルが処理するからだ。

ツール：

beads ローカルファーストのタスク管理。オープンソース。
Claude Code エージェントランタイムとして。
Beadbox フリートが大きくなった時の視覚的なオーバーサイト。

このようなワークフローを構築しているなら、GitHubでBeadboxにスターを。

Claude Code Agentのタスク管理方法