beads

このスキルでは、AI エージェント向けに設計された、分散型の Git ベースの課題トラッカー beads（bd）を効果的に使う方法を説明します。beads を使ってタスクを追跡し、依存関係を管理し、セッションをまたいで作業を調整します。

はじめに

まず、beads が利用可能で、初期化済みかどうかを確認します。

# Check if bd is installed
bd version

# Check if current project has beads initialized
bd status

bd がインストールされていない場合は、ユーザーに希望するインストール方法を尋ねます。

• npm： npm install -g @beads/bd
• Homebrew： brew install beads（macOS）
• Go： go install github.com/steveyegge/beads/cmd/bd@latest

これらはグローバルなシステムパッケージであるため、ユーザーの確認なしにインストールしないでください。

プロジェクトで初期化されていない場合は、次を実行します。

bd init

共有プロジェクトで個人的に使う場合（リポジトリにはコミットしません）：

bd init --stealth

フォークしたリポジトリのコントリビューター向け（別の計画用リポジトリにルーティングします）：

bd init --contributor

基本的なコマンド

コマンド	目的
bd ready	オープンなブロッカーがないタスクを一覧表示します（次に取り組むタスク）
bd create "Title" -p 1	タスクを作成します（優先度は0～3で、数値が小さいほど優先度が高くなります）
bd show <id>	タスクの詳細と依存関係を表示します
bd list	すべてのオープンな課題を一覧表示します
bd close <id>	タスクを完了としてマークします
bd update <id> --status in_progress	タスクのステータスを更新します
bd dep add <child> <parent>	依存関係を作成します（child は parent にブロックされます）
bd sync	Git への即時同期を強制します

結果を解析するときは、機械可読な出力を得るため、必ず --json フラグを使ってください。

タスク階層

Beads は作業を整理するための階層型 ID をサポートしています。

• bd-a3f8 — エピック（大規模な機能）
• bd-a3f8.1 — エピック配下のタスク
• bd-a3f8.1.1 — サブタスク

階層型タスクを作成します。

bd create "Epic: User Authentication" -t epic -p 1
bd create "Implement login flow" -p 1 --parent bd-a3f8

セッションのワークフロー

セッションの開始

# See what's ready to work on
bd ready --json

# Pick a task and mark it in progress
bd update <id> --status in_progress

# View full details
bd show <id> --json

作業中

# Create new tasks as you discover them
bd create "Fix edge case in validation" -p 2

# Add dependencies
bd dep add <new-task> <blocking-task>

# Update task with notes
bd update <id> --notes "Found issue with timezone handling"

セッションの終了（「着陸させる」）

作業を終えるときは、次の手順をすべて完了してください。

# 1. File issues for remaining work
bd create "TODO: Add integration tests" -p 2

# 2. Close completed tasks
bd close <id> --reason "Completed"

# 3. Sync and push (MANDATORY)
git pull --rebase
bd sync
git push

# 4. Verify push succeeded
git status  # Must show "up to date with origin"

# 5. Identify next task for follow-up
bd ready --json

重要： セッションを終了する前に、必ずプッシュしてください。プッシュされていない作業は、複数のエージェントを使うワークフローで調整上の問題を引き起こします。

重要なルール

bd update はフラグを使って実行してください

bd update <id> --description "new description"
bd update <id> --title "new title"  
bd update <id> --design "design notes"
bd update <id> --notes "additional notes"
bd update <id> --acceptance "acceptance criteria"
bd update <id> --status in_progress

bd edit は使わないでください

edit コマンドを実行すると、AI エージェントが使用できない対話型エディター（$EDITOR）が開きます。代わりに、必ずフラグを使って bd update を実行してください。

セッション終了前に同期してください

bd sync  # Forces immediate export, commit, and push

bd sync を実行しないと、変更は30秒のデバウンス期間中に保留され、コミットされない可能性があります。

コミットメッセージに課題 ID を含めてください

git commit -m "Fix auth validation bug (bd-abc)"

これにより、bd doctor が孤立した課題を検出できるようになります。

依存関係の種類

# Hard blocker - child cannot start until parent is done
bd dep add <child> <parent> --type blocks

# Soft link - related but not blocking  
bd dep add <issue1> <issue2> --type related

# Parent-child - hierarchical relationship
bd dep add <child> <parent> --type parent-child

マージコンフリクトへの対処

.beads/issues.jsonl でコンフリクトが発生した場合：

# Accept remote version
git checkout --theirs .beads/issues.jsonl

# Re-import to database
bd import -i .beads/issues.jsonl

# Continue with your work

Git フック（推奨）

自動同期のためにフックをインストールします。

bd hooks install

これにより、コミット、マージ、プッシュ、チェックアウト時に自動同期され、古い JSONL に関する問題を防げます。

MCP サーバーの代替手段

より緊密に統合するには、beads が提供する MCP サーバー（beads-mcp）を使うと、ツールをエージェントに直接提供できます。次のコマンドでインストールします。

pip install beads-mcp

CLI（bd）と MCP サーバーは、同じ基盤データベースを使用します。

クイックリファレンス

# What should I work on?
bd ready

# Create a task
bd create "Fix bug in login" -p 1

# Start working
bd update bd-xyz --status in_progress

# Done working
bd close bd-xyz --reason "Completed"
bd sync
git push