Beads - AIエージェント用永続タスクメモリ
会話圧縮後も存続するグラフベースのIssueトラッカー。複雑な依存関係を持つ複数セッションの作業に永続的なメモリを提供します。
概要
bd（beads） は、マークダウンタスクリストを、Gitに保存された依存関係を認識するグラフに置き換えます。TodoWrite（セッション限定）とは異なり、bdは圧縮後も存続し、複雑な依存関係を追跡します。
主な違い:
- bd: 複数セッションの作業、依存関係、圧縮耐性、Git管理
- TodoWrite: 単一セッションのタスク、線形実行、会話限定
中核機能:
- 📊 依存関係グラフ: 何が何をブロックしているかを追跡（blocks、parent-child、discovered-from、related）
- 💾 圧縮耐性: 会話履歴が圧縮されてもタスクは存続
- 🐙 Git統合: Issueが
.beads/issues.jsonlでバージョン管理され、bd syncで同期 - 🔍 スマートディスカバリー: 準備完了の作業（
bd ready）、ブロックされている作業（bd blocked）を自動検出 - 📝 監査証跡: ステータス変更、メモ、決定の完全な履歴
- 🏷️ リッチメタデータ: 優先度（P0-P4）、タイプ（bug/feature/task/epic）、ラベル、担当者
bd vs TodoWriteの使用タイミング:
- ❓ "2週間後にこのコンテキストが必要になるか？" → はい = bd
- ❓ "会話履歴が圧縮される可能性があるか？" → はい = bd
- ❓ "これにブロッカー/依存関係があるか？" → はい = bd
- ❓ "これは曖昧/探索的な作業か？" → はい = bd
- ❓ "このセッションで完了するか？" → はい = TodoWrite
- ❓ "これは今の自分用のタスクリストに過ぎないか？" → はい = TodoWrite
判断ルール: bdなしで2週間後に再開するのが難しい場合は、bdを使用してください。
前提条件
必須:
- bd CLI: バージョン0.34.0以降がインストールされ、PATHが通っていること
- Gitリポジトリ: カレントディレクトリがGitリポジトリであること
- 初期化:
bd initが一度実行されていること（人間が行い、エージェントは行いません）
インストール確認:
bd --version # 0.34.0以降が返されること
初回セットアップ（人間が一度実行）:
cd /path/to/your/repo
bd init # データベースを含む.beads/ディレクトリを作成
任意:
- BEADS_DIR 環境変数：別のデータベースロケーションを指定
- デーモン: バックグラウンド同期用：
bd daemon --start
使用方法
セッション開始プロトコル
すべてのセッションで、ここから開始してください:
ステップ1: 準備完了の作業を確認
bd ready
ブロッカーがなく、優先度順（P0 → P4）にソートされたタスクを表示します。
表示内容:
- タスクID（例：
myproject-abc） - タイトル
- 優先度
- Issueタイプ（bug、feature、task、epic）
出力例:
claude-code-plugins-abc [P1] [task] open
ユーザー認証を実装
claude-code-plugins-xyz [P0] [epic] in_progress
データベース層をリファクタリング
ステップ2: 最優先タスクを選択
準備ができているタスクの中から最も優先度の高い（P0 > P1 > P2 > P3 > P4）ものを選びます。
ステップ3: 完全なコンテキストを取得
bd show <task-id>
表示:
- タスクの完全な説明
- 依存関係グラフ（これをブロックしているもの、これがブロックしているもの）
- 監査証跡（すべてのステータス変更、メモ）
- メタデータ（作成日、更新日、担当者、ラベル）
ステップ4: 作業を開始
bd update <task-id> --status in_progress
タスクをアクティブに作業中としてマークします。
ステップ5: 作業中にメモを追加
bd update <task-id> --notes "完了: X。進行中: Y。ブロック中: Z"
圧縮耐性のために重要: 会話コンテキストがゼロの将来のエージェントに説明するつもりでメモを書いてください。
メモ形式（ベストプラクティス）:
完了: 具体的な成果物（例：「JWTリフレッシュエンドポイント + レート制限を実装」）
進行中: 現在の状態 + 次の即時ステップ
ブロッカー: 進行を妨げているもの
主要な決定: 重要なコンテキストやユーザーの指示
タスク作成ワークフロー
タスクを作成するタイミング
bdタスクを作成するのは以下の場合:
- ユーザーがセッションをまたいだ追跡について言及した場合
- ユーザーが「Xを修正/構築/追加すべき」と言った場合
- 作業に依存関係やブロッカーがある場合
- 境界が曖昧な探索的/調査的作業の場合
基本的なタスク作成
bd create "タスクタイトル" -p 1 --type task
引数:
- タイトル: 簡単な説明（必須）
- 優先度: 0-4（0=クリティカル、1=高、2=中、3=低、4=バックログ、デフォルト: 2）
- タイプ: bug、feature、task、epic、chore（デフォルト: task）
例:
bd create "認証バグを修正" -p 0 --type bug
説明付きで作成
bd create "OAuthを実装" -p 1 --description "Google、GitHub、Microsoft向けにOAuth2サポートを追加。passport.jsライブラリを使用。"
子タスクを持つEpic
# 親Epicを作成
bd create "Epic: OAuth実装" -p 0 --type epic
# 返り値: myproject-abc
# 子タスクを作成
bd create "OAuthプロバイダーを調査" -p 1 --parent myproject-abc
bd create "認証エンドポイントを実装" -p 1 --parent myproject-abc
bd create "フロントエンドログインUIを追加" -p 2 --parent myproject-abc
更新と進捗ワークフロー
ステータス変更
bd update <task-id> --status <新しいステータス>
ステータス値:
open- 未開始in_progress- 作業中blocked- 停止中、何かを待機中closed- 完了
例:
bd update myproject-abc --status blocked
進捗メモの追加
bd update <task-id> --notes "ここに進捗状況を記入"
既存のメモフィールドに追記します（置き換えはしません）。
優先度変更
bd update <task-id> -p 0 # クリティカルにエスカレーション
ラベルの追加
bd label add <task-id> backend
bd label add <task-id> security
ラベルは、ステータスやタイプを超えた横断的な分類を提供します。
依存関係管理
依存関係の追加
bd dep add <子ID> <親ID>
意味: <親ID>が<子ID>をブロックします（親が先に完了する必要があります）。
依存関係のタイプ:
- blocks: 親がクローズされるまで子は準備完了にならない
- parent-child: 階層関係（epicとサブタスク）
- discovered-from: タスクAからタスクBが発見された
- related: タスクは関連しているがブロックはしない
例:
# デプロイはテスト合格によってブロックされる
bd dep add deploy-task test-task # test-taskがdeploy-taskをブロック
依存関係の表示
bd dep list <task-id>
表示:
- このタスクがブロックしているもの（依存タスク）
- このタスクをブロックしているもの（ブロッカー）
循環依存の防止
bdは自動的に循環依存を防止します。サイクルを作成しようとすると、コマンドは失敗します。
完了ワークフロー
タスクをクローズ
bd close <task-id> --reason "完了サマリー"
ベストプラクティス: 何を達成したかを説明する理由を常に含めてください。
例:
bd close myproject-abc --reason "完了: Google、GitHubプロバイダーでOAuthエンドポイントを実装。テスト合格。"
新たにブロック解除された作業を確認
タスククローズ後、実行:
bd ready
タスクをクローズすると、依存タスクのブロックが解除され、新たに準備完了になる場合があります。
子タスク完了時にEpicをクローズ
bd epic close-eligible
すべての子タスクがクローズされたEpicを自動的にクローズします。
Git同期ワークフロー
オールインワン同期
bd sync
実行内容:
- データベースを
.beads/issues.jsonlにエクスポート - 変更をGitにコミット
- リモートからプル（必要に応じてマージ）
- 更新されたJSONLをデータベースにインポート
- ローカルコミットをリモートにプッシュ
使用タイミング: セッション終了時、チームメイトへの引き継ぎ前、大きな進捗後。
エクスポートのみ
bd export -o backup.jsonl
Git操作なしでJSONLバックアップを作成します。
インポートのみ
bd import -i backup.jsonl
JSONLファイルをデータベースにインポートします。
バックグラウンドデーモン
bd daemon --start # バックグラウンドで自動同期
bd daemon --status # デーモンの健全性を確認
bd daemon --stop # 自動同期を停止
デーモンはデータベースの変更を監視し、JSONLに自動エクスポートします。
検索・検索コマンド
準備完了の作業を見つける
bd ready
ブロッカーがないタスクを表示します。
すべてのタスクを一覧表示
bd list --status open # オープンタスクのみ
bd list --priority 0 # P0（クリティカル）のみ
bd list --type bug # バグのみ
bd list --label backend # 「backend」とラベル付けされたもののみ
bd list --assignee alice # aliceに割り当てられたもののみ
タスク詳細の表示
bd show <task-id>
完全な詳細: 説明、依存関係、監査証跡、メタデータ。
テキスト検索
bd search "authentication" # タイトルと説明を検索
bd search login --status open # フィルターと組み合わせる
ブロックされている作業を見つける
bd blocked
オープンなブロッカーがあり作業が妨げられているすべてのタスクを表示します。
プロジェクト統計
bd stats
表示:
- ステータス別の総Issue数（open、in_progress、blocked、closed）
- 優先度別Issue数（P0-P4）
- タイプ別Issue数（bug、feature、task、epic、chore）
- 完了率
完全なコマンドリファレンス
| コマンド | 使用タイミング | 例 |
|---|---|---|
| 検索コマンド | ||
bd ready | ブロックされていないタスクを検索 | ユーザーが「何をすればいい？」と尋ねた場合 |
bd list | フィルター付きですべてのタスクを表示 | 「すべてのオープンバグを見せて」 |
bd show <id> | タスクの詳細を取得 | 「タスクbd-42を見せて」 |
bd search <query> | タスク間のテキスト検索 | 「authに関するタスクを探して」 |
bd blocked | スタックしている作業を検索 | 「何が私たちをブロックしている？」 |
bd stats | プロジェクトメトリクス | 「いくつのタスクがオープンですか？」 |
| 作成コマンド | ||
bd create | 新しい作業を追跡 | 「このバグのタスクを作成して」 |
bd template create | Issueテンプレートを使用 | 「バグテンプレートからタスクを作成」 |
bd init | beadsを初期化 | 「このリポジトリでbeadsをセットアップ」（人間のみ） |
| 更新コマンド | ||
bd update <id> | ステータス/優先度/メモを変更 | 「進行中とマーク」 |
bd dep add | 依存関係をリンク | 「これがあれをブロックする」 |
bd label add | ラベルでタグ付け | 「これをbackendとラベル付け」 |
bd comments add | コメントを追加 | 「タスクにコメントを追加」 |
bd reopen <id> | クローズしたタスクを再オープン | 「bd-42を再オープン、リグレッションを発見」 |
bd rename-prefix | Issueプレフィックスを変更 | 「プレフィックスをbd-からproj-に変更」 |
bd epic status | Epicの進捗を確認 | 「Epicの完了%を表示」 |
| 完了コマンド | ||
bd close <id> | タスクを完了とマーク | 「このタスクをクローズ、完了しました」 |
bd epic close-eligible | 完了したEpicを自動クローズ | 「すべての子が完了したEpicをクローズ」 |
| 同期コマンド | ||
bd sync | Git同期（オールインワン） | 「タスクをGitに同期」 |
bd export | JSONLにエクスポート | 「すべてのタスクをバックアップ」 |
bd import | JSONLからインポート | 「バックアップから復元」 |
bd daemon | バックグラウンド同期管理 | 「自動同期デーモンを開始」 |
| クリーンアップコマンド | ||
bd delete <id> | Issueを削除 | 「テストタスクを削除」（--forceが必要） |
bd compact | 古いクローズタスクをアーカイブ | 「データベースを圧縮」 |
| レポートコマンド | ||
bd stats | プロジェクトメトリクス | 「プロジェクトの健全性を表示」 |
bd audit record | インタラクションを記録 | 「このLLM呼び出しを記録」 |
bd workflow | ワークフローガイドを表示 | 「beadsの使い方は？」 |
| 高度なコマンド | ||
bd prime | AIコンテキストをリフレッシュ | 「bdワークフロールールを読み込み」 |
bd quickstart | インタラクティブチュートリアル | 「beadsの基本を教えて」 |
bd daemons | マルチリポジトリデーモン管理 | 「すべてのbeadsデーモンを管理」 |
bd version | バージョンチェック | 「bdバージョンを確認」 |
bd restore <id> | 圧縮されたIssueを復元 | 「Gitから完全な履歴を取得」 |
出力
このスキルは以下を生成します:
タスクID: 形式 <プレフィックス>-<ハッシュ>（例：claude-code-plugins-abc、myproject-xyz）
ステータスサマリー:
5 open, 2 in_progress, 1 blocked, 47 closed
依存関係グラフ（視覚ツリー）:
myproject-abc: 本番環境にデプロイ [P0] [blocked]
ブロック元:
↳ myproject-def: 統合テストを実行 [P1] [in_progress]
↳ myproject-ghi: 失敗するテストを修正 [P1] [open]
監査証跡（完全な履歴）:
2025-12-22 10:00 - aliceが作成 (P2, task)
2025-12-22 10:15 - 優先度変更: P2 → P0
2025-12-22 10:30 - ステータス変更: open → in_progress
2025-12-22 11:00 - メモ追加: 「JWT認証を実装...」
2025-12-22 14:00 - ステータス変更: in_progress → blocked
2025-12-22 14:01 - メモ追加: 「ブロック中: APIエンドポイントが503を返す」
エラーハンドリング
よくある失敗
1. bd: command not found
原因: bd CLIがインストールされていないか、PATHが通っていない 解決策: https://github.com/steveyegge/beads からインストール
# macOS/Linux
curl -fsSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash
# またはnpm経由
npm install -g @beads/bd
# またはHomebrew経由
brew install steveyegge/beads/bd
2. No .beads database found
原因: このリポジトリでbeadsが初期化されていない
解決策: bd initを実行（人間が一度実行し、エージェントは実行しません）
bd init # .beads/ ディレクトリを作成
3. Task not found: <id>
原因: 無効なタスクID、またはタスクが存在しない
解決策: bd listを使用してすべてのタスクを表示し、ID形式を確認
bd list # すべてのタスクを表示
bd search <部分タイトル> # タイトルでタスクを検索
4. Circular dependency detected
原因: 依存関係の循環を作成しようとした（AがBをブロック、BがAをブロック） 解決策: bdは自動的に循環依存を防止します。依存関係グラフを再構築してください。
bd dep list <id> # 現在の依存関係を表示
5. .beads/issues.jsonl でのGitマージコンフリクト
原因: 複数のユーザーが同じIssueを変更した 解決策: bd syncはJSONLのコンフリクトを自動的に処理します。手動介入が必要な場合:
# コンフリクトを表示
git status
# bdはコンフリクト解決ツールを提供
bd sync --merge # 自動解決を試行
6. Database is locked
原因: デーモンまたは別のプロセスが排他的ロックを保持している 解決策: デーモンを再起動するか、ロックが解除されるのを待つ
bd daemon --stop
bd daemon --start
7. 同期失敗
原因: ネットワーク問題、認証失敗、またはGit設定 解決策: Gitリモートアクセスと認証情報を確認
git fetch # 接続性をテスト
git status # リポジトリの状態を確認
例
完全なワークフロー例
この例は、ユーザーがプロジェクトに新しい機能を要求した場合の、完全なエンドツーエンドのbdワークフローを示しています。
ユーザー: "データベースにユーザー設定を保存する機能が必要です。これを追跡しておいてください。"
エージェント:
# 1. Epicを作成
bd create "ユーザー設定ストレージ" -p 1 --type epic
# 返り値: myproject-abc
# 2. 子タスクを追加
bd create "設定スキーマを設計" -p 1 --parent myproject-abc --description "ユーザー設定のデータベーススキーマを設計"
bd create "設定APIエンドポイントを実装" -p 1 --parent myproject-abc
bd create "設定UIコンポーネントを構築" -p 2 --parent myproject-abc
# 3. 依存関係をリンク
bd dep add myproject-def myproject-ghi # UIはAPIに依存
エージェント: "タスクを追跡しました。作業できる状態のものを確認しましょう:"
bd ready
出力:
myproject-abc: ユーザー設定ストレージ [P1] [epic] open
サブタスク:
myproject-def: 設定スキーマを設計 [P1] [task] in_progress
myproject-ghi: 設定APIエンドポイントを実装 [P1] [task] open
myproject-jkl: 設定UIコンポーネントを構築 [P2] [task] open
エージェント: 「スキーマの設計から始めましょう。」
bd show myproject-def
# 詳細を表示
bd update myproject-def --status in_progress
セッション再開例
新しいセッションが開始されました。エージェントは以前のコンテキストを失っていますが、bdは存続しています。
エージェント:
bd ready
出力:
myproject-ghi: 設定APIエンドポイントを実装 [P1] [task] open
myproject-jkl: 設定UIコンポーネントを構築 [P2] [task] open
エージェント: 「前回のセッションで設定スキーマを設計し、完了しました。次は実装段階です。」
bd show myproject-ghi
出力:
myproject-ghi: 設定APIエンドポイントを実装 [P1] [task] open
説明: RESTful APIエンドポイント (/api/v1/settings) をCRUD操作用に作成
依存関係:
ブロック元:
↳ myproject-def: 設定スキーマを設計 [closed] ✓
ブロック先:
↳ myproject-jkl: 設定UIコンポーネントを構築 [open]
メタデータ:
作成: 2025-12-22 by エージェント
タイプ: task
ラベル: backend, api
監査証跡:
2025-12-22 10:00 - 作成 (P1, task)
2025-12-22 10:05 - 依存関係追加: myproject-def → myproject-ghi
エージェント: 「スキーマは完了しました。APIエンドポイントの実装を始めましょう。」
トラブルシューティング
よくある問題
| 問題 | 原因 | 解決策 |
|---|---|---|
bd ready が空 | すべてのタスクにブロッカーがある、またはタスクがない | bd list --status open でオープンタスクを確認 |
| 同期が遅い | 大量のIssue、大きなGitリポジトリ | bd compact で古いクローズタスクをアーカイブ |
| 重複タスク | 複数のエージェントが同時に実行 | bd search <タイトル> で重複を確認後、bd delete <id> で削除 |
| 誤ったラベル | タイプミス | bd label list で既存のラベルを確認してから bd label add |
トラブルシューティングのヒント
- ヘルプを表示:
bd helpまたは特定のコマンドに対してbd <command> --help - データベースの状態を確認:
bd statsで Issueの状態概要を表示 - Gitログを確認:
git log .beads/issues.jsonlでデータベースの変更履歴を確認 - bd sync を再実行: 同期の問題に対して
bd syncは冪等で安全 - ログを確認:
.beads/ディレクトリにログが含まれている場合があります。デーモンの問題をデバッグするのに役立ちます。
ワークフロー図
flowchart TD
A[セッション開始] --> B{bd ready を実行}
B --> C[最優先タスクを選択]
C --> D[bd show <id> で全コンテキストを取得]
D --> E[bd update --status in_progress]
E --> F[作業中にメモを追加]
F --> G{タスク完了?}
G -->|いいえ| F
G -->|はい| H[bd close <id> --reason 完了サマリー]
H --> I[bd ready で新たなブロック解除を確認]
I --> J{Epic完了?}
J -->|はい| K[bd epic close-eligible]
J -->|いいえ| B
K --> B
セキュリティに関する考慮事項
.beads/ディレクトリは.gitignoreに追加しないでください。履歴の永続性のためにGitで追跡する必要があります。- データベースファイル（
.beads/issues.jsonl）には機密情報が含まれる可能性があります。リポジトリのアクセス許可が適切に設定されていることを確認してください。 bd syncの認証情報はGitリモートの設定を使用します。機密のトークンやパスワードはbeadsデータベースに保存しないでください。- 依存関係グラフを操作するときは、意図しない情報漏洩を防ぐため、データの正確性を検証してください。
リソース
- ドキュメント: beads documentation
- 問題報告: GitHub Issues
- コミュニティ: Discord
- ライセンス: MIT
このスキルはBeadsタスク管理システムの一部です。詳細については公式ドキュメントを参照してください。