Beads でタスク進行管理はどこまで自動化できるか確かめた
はじめに
AI コーディングエージェントを使っていると、引き継ぎドキュメントを書くことになります。HANDOFF.md、handover.md、session-handoff.md と名前は違っても、やることは同じです。次のセッションが文脈ゼロから再開できるよう、現状と残作業を書き残すものです。
私もそうしていましたが、この方式に疑問がありました。長大な引き継ぎドキュメントを後から人間が読むのは面倒です。どうせ AI に読ませるのであれば、可読性は高くなくてよいはずです。
そもそもタスクの進行管理とは、言ってしまえば状態管理です。状態管理は AI 以前から人間がぶつかってきた問題であり、だからこそカンバン方式をはじめ、さまざまな方式が発明されてきました。車輪の再発明は避けたい。すでに誰かが考えているはずだと思い、自分で作る前に調べることにしました。
そこで見つけたのが Beads です。本記事では、既存のプロジェクトの引き継ぎドキュメントを Beads へ移し、状態管理をどこまで自動化できるかを確かめます。先に結論を述べると、セッション開始時の状態の復元は自動化できましたが、状態の更新は自動では行われず、人が補う必要が残りました。
Beads とは
Beads は、AI コーディングエージェント向けに設計された課題管理ツールです。コマンドは bd です。課題どうしの依存関係を第一級の概念として扱い、着手できる課題とブロッカーで止まっている課題を区別できます。状態はローカルのデータベースに保存され、セッション開始時にエージェントの文脈へ自動的に注入されます。
検証環境
- macOS 26.5.2
- bd 1.1.2 (Homebrew)
- Claude Code 2.1.220
対象読者
- AI コーディングエージェントの引き継ぎドキュメントの運用に手応えを感じていない方
- コンパクションで文脈が落ちることに困っている方
- AI エージェント向けの状態管理ツールの導入を検討している方
参考
背景: 引き継ぎドキュメントの限界
導入の動機は、コンパクション (context compaction) で文脈が落ちることでした。コンパクションは、会話が長くなって文脈が上限に近づいたときに、Claude Code が会話履歴を要約へ置き換える処理です。
コンパクションが走るたびに、エージェントは過去のナレッジを読み直します。そのたびにトークンを大量に消費します。エージェントは会話をたどって状態を復元しようとしますが、会話は行ったり来たりするため、状態の正本にするには無理があります。
分量が多いのでサブエージェントに要約させることもありますが、重要な部分が抜け落ちたり、当たりを付けて検索した結果、肝心なところを持ってこなかったりします。
引き継ぎドキュメントそのものにも、欠陥があります。依存関係とブロッカーを文章で表現すると、読み手が毎回それを頭の中で組み立て直すことになります。何が終わっていて、いま何に着手できるのかが一目で分かりません。
また、世代交代のたびに項目が落ちます。私が関わっていた、とあるプロジェクトの引き継ぎドキュメントは 3 世代に分かれていました。旧版に書かれていた設計ドキュメントの誤記修正が最新版へ転記されておらず、誤記は未修正のまま約 2 週間残っていました。
Beads に移せば、この項目は完了になるまで課題として出続けるはずです。
検証結果: 状態の復元と更新
移行そのものはうまくいきました。移行を終えた時点で、既存の 8 つのプロジェクトに課題 34 件と永続メモリ 41 件を登録できました。
セッション開始時とコンパクション後には、次のような一覧が自動的にエージェントの文脈へ入ります。
○ status-manager-u4l ● P1 my-claude-code-rules v3.0.0 の変更をレビューしてコミットする
○ status-manager-2uv ● P2 [epic] 既存 handoff.md 10 件を Beads へ移行する
--------------------------------------------------------------------------------
Ready: 2 issues with no active blockers
会話履歴に頼らず状態が戻ります。ここは期待どおりでした。取得できるのは指定した課題だけで、データベース全体を読み込む必要はありません。
しかし、更新は自動では行われませんでした。仕方なく、「タスクの進行状況を更新して」などと伝え、私が都度補いました。
更新が自動でないことは、コンパクションと組み合わさると影響が大きくなります。
自動コンパクションは文脈が上限に近づくと走るため、作業の途中でも発生します。タイミングを見張るのは現実的ではありません。コンパクションでは会話履歴が要約に置き換わるため、要約される過程で一部が欠落します。コンパクションの直前に実行されるフックは存在しますが、記録を促す指示を注入できません。
検証結果: 記録先
一度決着した議論を蒸し返す挙動もありました。意思決定のログ管理が正常に行われていればありえない挙動です。
原因を調べると、記録自体は残っていました。ただし、それは課題を完了にしたときに書く完了理由の中でした。
完了理由は次のセッションに注入されません。 注入されるのは、永続メモリと、未完了の課題だけです。書いたのに読まれない場所へ置いていたわけです。
| 記録先 | 次のセッションに注入されるか |
|---|---|
| 永続メモリ | される |
| 未完了の課題 | される |
| 完了理由 | されない |
| 完了済み課題への追記 | されない |
対策
以上を踏まえ、3 点の対策を入れました。
-
記録のタイミングの変更
- 作業の終わりにまとめて書くのをやめ、事実が確定した時点で書くようにしました
- 方針を決めた・検証が通った・ブロッカーが判明したという区切りごとに記録します
-
記録しないまま話を終わらせない
- エージェントが応答を終えようとする直前に、フックで記録の状況を確認します
- 着手中の課題が 15 分以上更新されていなければ、応答をいったん止めて記録を促します
-
記録先の指定
- 利用者から受け取った判断は、必ず自動で注入される領域へ書くよう定めました
対策後に使用感が改善されたかどうかについては、また別記事にて続報を書かせていただければと思います。
まとめ
引き継ぎドキュメントから Beads へ状態管理を移し、既存プロジェクトで運用しました。セッション開始時の状態の復元は自動化できた一方、状態の更新は自動で行われなかったため対策を実施しました。その後の使用感についてはまた記事にできればと思います。
