Beads - AI時代のGitベースタスク管理ツール

はじめに

AI駆動の開発が当たり前になった昨今、イシューやタスクの管理方法もよりAIフレンドリーな手法が議論されるようになってきました。

GitHub Issues や Jira は人間が使うだけなら十分便利ですが、Claude Code のような AI エージェントと協調するとなるとMCPを噛ませたり何かしらの工夫が必要ですよね。
かく言う私は結構こういう連携をめんどくさがってそのままが多いです。。
Web UI を開いて、マウスでクリックして、内容を噛み砕いてAIにやらせる、そんな感じです。

今回紹介する Beads (bd) は、そんな課題を解決する Git-native なイシュートラッカーです。

Beads とは

Beads は CLI ベースのイシュートラッカーで、人間がコマンドからイシューを操作することもできるし、もちろんAIがそれをすることもできます。

https://github.com/steveyegge/beads

元 Google・Amazon エンジニアの Steve Yegge 氏によって開発された、AI エージェント向けの分散型イシュートラッカーです。

Beadsが解決してくれること

CLI ベース
ターミナルで完結するため、Claude CodeのようなCLI上で動くAIエージェントとの協調が容易。

Git 統合
イシューデータがリポジトリ内に存在するため、コードと一緒にバージョン管理できる。

AI フレンドリー
JSON 形式のデータで機械可読性が高く、Claude Code などの AI エージェントと連携しやすい。

データ管理の仕組み

Beads の特徴的な点は、2つのストレージシステムを併用していることです。

.beads/
├── beads.db           # SQLite (ローカル、.gitignore で除外)
├── issues.jsonl       # JSONL (Git で管理 ✅)
└── config.yaml        # 設定ファイル

なぜ SQLite と JSONL の両方？

それぞれのストレージには明確な役割があります。

beads.db (SQLite)
高速なローカルクエリを実現します。複雑な検索、フィルタリング、依存関係の解決が高速に行えます。このファイルは .gitignore で除外され、Git では管理されません。

issues.jsonl (JSONL)
Git で管理され、チーム間でイシューを共有するために使用されます。人間が読める形式で、diff が見やすい。

JSONL 形式の利点

{"id":"issue-8cr","title":"Add month navigation",...}
{"id":"issue-mrf","title":"Add user authentication",...}

JSONL 形式は 1行 = 1イシューという構造になっています。そのため、新規イシューを追加してもマージコンフリクトが起きにくく、git diff で変更が見やすいという利点があります。

データの流れ

実際の運用では以下のような流れでデータが同期されます。

1. イシュー作成
   bd create "Add feature"
   ↓
   両方に保存: beads.db + issues.jsonl

2. ローカル作業
   bd list   → beads.db から高速読み取り
   bd update → beads.db + issues.jsonl を更新

3. Git 同期
   git add .beads/issues.jsonl
   git commit -m "Update issues"
   git push

4. 他の開発者が git pull
   ↓
   Beads が自動的に JSONL → DB にインポート

イシュー作成・更新時に自動的に両方のストレージを更新します。git pull 後も JSONL が新しければ自動的に DB を更新するため、手動での同期作業はほとんど必要ありません。

基本的な使い方

インストール

インストールは 1 コマンドで完了します。

curl -fsSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash

# PATH に追加（~/.zshrc or ~/.bashrc）
export PATH="$PATH:/Users/yourusername/.local/bin"

初期化

プロジェクトで Beads を使い始めるには、リポジトリのルートで初期化を実行します。

cd your-project
bd init

Agent.mdに 「issue管理はbeadsを使え」 と書いておく

開発の中に「気づいたけどやるのは今じゃないな」っていう気づきよくありますよね。忘れないようにissueを立てたり、TODOコメント残したりして後でやろってやつです。私はたまにissueを立てること自体を忘れます。

これを書くだけで気付いたその場で「これissueにしといて」でissueを作成してくれます。

依存関係の管理

タスク間に依存関係を持たせることができます。

# 親タスクを作成
bd create -t epic "Implement authentication"

# 依存関係を持つ子タスクを作成
bd create -t feature "Add login form" --depends-on issue-xxx

# ブロッカーがない作業可能なタスクだけを表示
bd ready

bd ready コマンドを使うことで、依存関係が解決済みで今すぐ着手できるタスクだけを表示できます。これにより、AIも人間も、次に何をすべきかを迷わずに判断できます。

AI エージェントとの協調作業

パターン 1: 人間がイシューを作成 → AI が実装

最もシンプルな使い方は、人間がイシューを作成し、AI に実装を任せるパターンです。

# 人間: イシューを作成
bd create -t feature "Implement ~"

# 人間: AI に指示
「~ のタスクを実装して」

パターン 2: AI が作業中に新しいイシューを発見

AI が作業中に関連タスクを発見し、新しいイシューを提案することもあります。

# AI の提案
「この機能を実装するには、先に XXX が必要です。
 新しいイシューを作成しますか？」

# 人間の承認
「お願いします！」

# AI がイシューを作成し、依存関係を設定
bd create -t feature "Implement XXX prerequisite"
bd update issue-yyy --depends-on issue-xxx

GitHub との連携

Beads は Git と統合されているため、GitHub との連携もスムーズです。

# 1. ローカルでイシューを作成
bd create -t feature "New feature"
# → beads.db と issues.jsonl の両方に保存

# 2. イシューの状態を更新
bd update issue-xxx --status in_progress

# 3. コード実装
# ... コーディング ...

# 4. Git にコミット
git add .beads/issues.jsonl
git add .
git commit -m "feat: implement new feature (issue-xxx)"
git push

# 5. 他の開発者が pull
git pull
# → Beads が自動的に issues.jsonl を読み込んで beads.db を更新

イシューデータも通常のコード変更と同じように Git で管理され、ローカルとの同期も自動で行われる。

終わりに

AI時代のイシュー管理としてBeadsを紹介しました。

CLIで完結するシンプルさとGitとの統合により、AI駆動開発でのタスク管理に最適化されています。
セットアップも簡単なので、「タスク管理ツールとAIの連携、ちょっと面倒だな」と感じたことがある方は試してみる価値があると思います。

参考

https://github.com/steveyegge/beads