この記事について
最近Claude Code界隈で見かける「Beads(bd)」というタスク管理ツールを、実際にインストールして手を動かしながら検証しました(bd v1.2.1で確認)。「AIエージェント用のIssueトラッカー」という触れ込みですが、実際に触ってみると単なるTODOツールではなく、既存のプロジェクト管理習慣そのものを置き換えにくる設計だったので、その辺りを中心にまとめます。
Beadsとは何か
Beadsは、Steve Yegge氏が公開したGo製のCLIツールで、「コーディングエージェント(Claude CodeやCodexなど)にとってのメモリ」を謳っています。
普通のTODOアプリと違うのは以下の点です。
- タスク同士の依存関係グラフを持つ(このタスクはあのタスクが終わるまで着手できない、を表現できる)
- バックエンドがDoltというバージョン管理付きSQLデータベースで、gitのリモートに乗せて複数マシン・複数エージェント間で同期できる
- IDが
beads-demo-a3f2ddのようなハッシュベースなので、複数人(複数エージェント)が同時に作業してもID衝突が起きない - 「今着手できるタスク(＝ブロックされていないタスク)」を1コマンドで取得できる(
bd ready)
要するに、Markdownの - [ ] やること リストや、エージェントごとにバラバラなメモリファイルを、依存関係付きのデータベースに置き換えるツールです。
インストール
brew install beads
Doltが依存として一緒に入ります。macOS/Linux/Windows/FreeBSDに対応しています。
bd initが想像以上に色々やってくれる(そして踏み込んでくる)
適当なリポジトリでbd initを実行してみると、こうなりました。
$ bd init
Repository ID: dfb7758a
✓ Created AGENTS.md with agent instructions
Installing Claude hooks for this project...
✓ Registered SessionStart hook
✓ Created new CLAUDE.md with beads integration
✓ Claude Code integration installed
Installing Beads agent skill...
✓ Beads agent skill installed
Skill: .agents/skills/beads/SKILL.md
Installing Codex native hooks for this project...
✓ Codex instructions installed
✓ Cursor integration installed (rules + skill + hooks)
✓ Committed beads files to git
✓ bd initialized successfully!
Backend: dolt
Mode: embedded
git log --statで見ると、1回のbd initだけでこれだけのファイルが自動でコミットまでされます。
.agents/skills/beads/SKILL.md
.beads/config.yaml, README.md, hooks/*(pre-commit, post-merge, pre-push...)
.claude/settings.json
.codex/config.toml, hooks.json
.cursor/hooks.json, rules/beads.mdc
.gitignore
AGENTS.md
CLAUDE.md
Claude CodeだけでなくCodex CLIやCursor向けの設定・フック・スキルファイルまで一括で生成し、しかもgit commitまで自動で済ませてくれます。「便利」と「勝手にリポジトリにコミットされるのはちょっと驚く」が同居するポイントで、既存のCLAUDE.mdがあるプロジェクトに導入する際は中身の差分を確認してから使うのがよさそうです。
生成されたCLAUDE.mdには、はっきりとこう書かれていました。
### Rules
- Use `bd` for ALL task tracking — do NOT use TodoWrite, TaskCreate, or markdown TODO lists
- Use `bd remember` for persistent knowledge — do NOT use MEMORY.md files
TodoWriteや素朴なMEMORY.mdでの管理を明示的に「使うな」と指示してくる設計です。既存のメモリ/TODO運用と competes する前提で作られていることが分かります。
基本ワークフローを動かしてみる
依存関係を持つ2つのタスクを作って、実際の挙動を確認しました。
$ bd create "ログインAPIの設計" -p 1 -t task
✓ Created issue: beads-demo-cu4 — ログインAPIの設計
$ bd create "認証機能を追加する" -p 1 -t feature
✓ Created issue: beads-demo-cw5 — 認証機能を追加する
# 「認証機能」は「ログインAPI設計」が終わるまで着手できない、という依存を追加
$ bd dep add beads-demo-cw5 beads-demo-cu4
✓ Added dependency: beads-demo-cw5 depends on beads-demo-cu4 (blocks)
この状態でbd ready(着手可能なタスク一覧)を見ると、ブロックされている方は出てきません。
$ bd ready
○ beads-demo-cu4 P1 ログインAPIの設計
Ready: 1 issues with no active blockers
依存元のタスクをclaimして完了させると、ブロックされていたタスクが自動的にbd readyに出てくるようになりました。
$ bd update beads-demo-cu4 --claim
✓ Updated issue: beads-demo-cu4 — ログインAPIの設計
$ bd close beads-demo-cu4 --reason "設計完了"
✓ Closed beads-demo-cu4 — ログインAPIの設計: 設計完了
$ bd ready
○ beads-demo-cw5 P1 認証機能を追加する
ready → claim → close → 次のreadyに反映という一連の流れが、まさにエージェントが「次に何をやればいいか」を毎回問い合わせながら仕事を進める設計になっているのが分かります。
セッションが変わっても記憶が引き継がれる仕組み
bd rememberでプロジェクトの知見を保存し、bd primeでそれを含めたコンテキストを出力できます。
$ bd remember "このプロジェクトはNext.jsを使っている"
Remembered [next-js]: このプロジェクトはNext.jsを使っている
$ bd prime
## Persistent Memories (1)
### next-js
このプロジェクトはNext.jsを使っている
# 🚨 SESSION CLOSE PROTOCOL 🚨
**CRITICAL**: Before saying "done" or "complete", you MUST run this checklist:
[ ] 1. bd close <id1> <id2> ... (close completed issues)
[ ] 2. run quality gates (tests, linters, builds when relevant)
[ ] 3. git status (check what changed)
.claude/settings.jsonにはSessionStartフックとしてbd prime --hook-jsonが登録されており、Claude Codeのセッション開始時に自動でこの内容が読み込まれるようになっています。エージェントが「前回何をやっていたか忘れる」問題に対して、セッションをまたいだ記憶をツール側で強制的に持たせる、という思想がよく分かる部分でした。
つまづいた点: PATHが衝突すると静かに壊れる
検証中、環境によってはbdという名前の別コマンド(自分の場合はasdfの古いshim)が先にPATHに乗っていて、Homebrew版のbdが影に隠れてしまうケースがありました。
$ brew install beads
==> Caveats
The following beads executables are shadowed by other commands earlier in your PATH:
bd (shadowed by ...)
この状態でgit commitすると、.beads/のpre-commitフックが「違う方のbd」を呼んでしまい、エラーメッセージだけ出て本来のissues.jsonlエクスポートが走らない、という現象に遭遇しました。導入直後はwhich bdで意図したバイナリを指しているか確認しておくのが安全です。
まとめ
| 特徴 | 内容 |
|---|---|
| データ構造 | 依存関係グラフ(Dolt DB)。bd readyでブロックなしタスクだけ抽出 |
| ID設計 | ハッシュベースIDでマルチエージェント環境でも衝突しない |
| セットアップ |
bd init一発でClaude/Codex/Cursor向け設定・フック・スキルを自動生成しコミット |
| 記憶 |
bd remember/bd primeでセッションをまたいだ記憶を強制 |
| 注意点 | 自動コミットの量が多い、PATH衝突時にフックが静かに失敗する |
「Makefile対Taskfile」のような比較記事とは違い、Beadsは「TODO管理の習慣そのものをエージェント向けに置き換える」ツールという印象を持ちました。個人のメモ書き感覚で入れると、CLAUDE.mdやAGENTS.mdが勝手に書き換わって驚くと思うので、既存のプロジェクトに導入する際はbd init前後の差分を必ず確認することをおすすめします。