Beads を約 1 か月使って分かってきた Beads の扱い方〜優先度判断と notes 運用〜
はじめに
以前、AI コーディングエージェントのタスク状態を Beads で管理し、どこまで自動化できるかを検証しました。
前回の記事では、セッション開始時の状態は自動で復元できる一方、状態の更新には人の働きかけが必要だと書きました。
その後約 1 か月、複数のリポジトリで Beads を使い続けました。まずメリットとして、ブロッカーなど依存関係が登録されるので AI コーディングエージェントが優先度の高いタスクを選ぶのが上手くなったと感じています。 一方で、Beads の notes へ途中経過を追記し続けると、古い情報と現在の情報が混在する問題があることも見えてきました。現在は、notes を現在状態のスナップショットへ統合する運用にしています。
Beads とは
Beads は、AI コーディングエージェント向けに設計された課題管理ツールです。課題の状態、優先度、依存関係を管理し、ブロッカーのない課題を bd ready で取得できます。基本的な仕組みと導入方法は前回の記事で紹介しています。
運用環境
- bd 1.1.2
- Claude Code 2.1.236
対象読者
- Beads を導入した後の運用方法を知りたい方
- AI コーディングエージェントへ複数タスクの着手順を判断させたい方
- Beads の notes が長くなり、現在の状態を追いにくくなっている方
参考
背景
前回の検証では、引き継ぎドキュメント (例: HANDOFF.md) から Beads へ移したことで、セッション開始時に未完了の課題を復元できることを示しました。その後は、作業の状態だけでなく、調査後の方針決定と実装順も Beads で管理するようになりました。
たとえば、調査によって新しい制約が判明すると、予定していた実装へすぐに着手できないことがあります。 先に設計を決める、利用者の判断を得る、別の検証を終えるといったタスクが必要になるためです。
HANDOFF.md を使った引き継ぎでは、この順序を読み手が組み立て直します。一方 Beads であれば、タスク間の依存関係と優先度として登録できます。情報収集から実装までの流れにも Beads を使い、AI コーディングエージェントに次の着手候補を選んでもらっています。
現在の運用
bd ready は、未解消のブロッカーがない未着手の課題を抽出し、既定では優先度順に表示します。
bd blocked では、ブロッカーによって着手できない課題を確認できます。
bd ready
bd blocked
この 2 つを使うと、着手できるタスクと、先に解消すべきブロッカーを分けて取得できます。
次に何をするかをエージェントに尋ねたときに、エージェントは着手可能な候補を優先度順に挙げ、その前提となるブロッカーを説明できるようになりました。 会話や引き継ぎ文書から依存関係を毎回組み立て直していたときよりも、候補を比較するところから会話を始められます。
状態の更新は、次の順で依頼しています。
- エージェントに情報収集を依頼する
- 調査結果を Beads へ反映させる (ここは今のところ人が能動的に指示しています)
- 優先度と依存関係を人とすり合わせるよう依頼する
- 人が方針を判断する
- 人による判断を Beads へ記録させる (ここも今のところ人が能動的に指示しています)
- ※これは同じ議論を蒸し返さないために必要
- エージェントに実装へ着手させる
Beads やエージェントが勝手に全部方針を決めてくれるわけではありません。調査結果、利用者の判断、タスクの依存関係を同じ場所へ記録することで、エージェントが次の候補を選ぶための情報が揃います。
Beads を更新するタイミングは、現在も人が決めています。タスクを整理すべき区切りは、新しい事実が揃ったとき、選択肢が出そろったとき、実装前に方針を確定したいときなど、作業内容によって変わるためです。私の場合、こういった区切りでは明示的に
Beads 更新して
と依頼しています。約 1 か月使った範囲では、人が更新のタイミングと方針を判断し、エージェントが調査結果の構造化・依存関係の登録・着手候補の抽出を担う分け方があっていました。
問題点
運用を続けるうちに、1 つの課題へ bd note で途中経過を追記し続けるようになりました。
これがあまり良い運用ではありませんでした。
作業に使っていた 25 リポジトリの集計をとったところ、notes の文字数は合計 550,793 文字にも達していました。1 課題あたりで確認すると、中央値は 1,011 文字、最大は 49,216 文字でした。
また文字数だけでなく内容にも問題がありました。例えば、ある集計タスクでは、最初に記録した 894 回という値が誤りだと分かり、後から正しい 216 回を追記していました。notes には次の 2 つが残っていました。
Stop フックの発火回数: 894
【訂正】894 回は誤り。正しくは 216 回
訂正前の一行はそもそも残す必要がありません。notes を読んだエージェントは、両方を読んで訂正関係を解釈する必要があります。否定された仮説や変更前の方針もこのように追記で残っていて、同じことが起きていました。
対策
現在は、notes を履歴ではなく、いま有効な状態のスナップショットとして扱うルールに変更しました。
その課題に属する調査や検証で事実が確定した時点では、これまでどおり bd note で途中経過を残します。後続課題は別の課題として登録し、複数の課題で使う決定や知見は永続メモリへ分けます。
bd note <issue-id> "確認した事実と確認方法"
新しい事実によって既存の記述が古くなった場合は、訂正を末尾へ足すのではなく、bd update --notes で notes 全体を現在の状態へ統合します。
bd update <issue-id> --notes "現在有効な調査結果、決定、残作業"
書き換える対象は、誤りと判明した記述、否定された仮説、置き換わった方針です。後から参照する価値がある失敗や判断の過程は、書き換える前にレポートへ移します。
| 情報 | 保存先 |
|---|---|
| 現在有効な状態と残作業 | Beads の notes |
| 後から参照する価値がある失敗や判断の過程 | docs/reports のレポート |
| 今後も繰り返し必要になる決定や知見 | Beads の永続メモリ |
永続メモリを更新するときも、既存のキーを指定して上書きします。--key を付けずに別の記録として追加すると、古い内容が残るためです。
bd remember "現在有効な決定または知見" --key <key>
この運用では、事実が判明した時点の追記と、古い記述が生じた時点の統合を分けます。途中経過を失わず、次のセッションには現在有効な状態を渡せます。
まとめ
Beads を約 1 か月運用してみたところ、依存関係を基に AI コーディングエージェントが次の着手候補を挙げてくれるようになりました。一方、notes へ訂正を追記し続けると、過去と現在の情報が混在します。対策として、事実が判明した時点では追記し、古い記述が生じた時点で notes 全体を現在状態へ統合するようにしました。AI を用いた開発におけるタスク管理に悩んでいる人の参考になれば幸いです。
