beads-task-tracker

Beads タスクトラッカー

概要

Beads は、AI コーディングエージェント向けに特化して設計された、Git でバージョン管理され、依存関係を認識する課題トラッカーです。セッション間でエージェントのコンテキストが失われる「健忘症問題」を、エージェントが作業の状況を把握し、着手可能な作業を見つけ、長期にわたるプロジェクトの依存関係を追跡するために利用できる、永続的で検索可能なタスクデータベースを提供することで解決します。

Beads は次の場合に使用してください：

• 相互に関連する複数のタスクがあるプロジェクトで作業する場合
• タスクが複数のエージェントセッション（10 分超）にまたがる場合
• ブロックされている作業と着手可能な作業を追跡する必要がある場合
• 実装中に記録すべき新しい作業が見つかった場合
• 複数のエージェントまたはマシンが同じコードベースで作業している場合
• 計画が古くなり、整理されなくなる「Markdown 計画の沼」を避けたい場合

インストールの確認

Beads を使用する前に、bd コマンドがインストールされていることを確認してください。

bd version

インストールされていない場合は、次の方法でインストールしてください。

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

インストール後の PATH 設定：

インストール後、bd が PATH で見つからない場合は、Go の bin ディレクトリをシェルのプロファイルに追加してください。

zsh（macOS のほとんどのシステム）の場合は、~/.zshrc に追加します。

export PATH="$PATH:$HOME/go/bin"

bash の場合は、~/.bashrc または ~/.bash_profile に追加します。

export PATH="$PATH:$HOME/go/bin"

次に、シェルを再読み込みします。

source ~/.zshrc  # or source ~/.bashrc

または、PATH を設定するまで、フルパス /Users/[username]/go/bin/bd を使用できます。

ワークフローの概要

1. プロジェクトの初期化

プロジェクトのディレクトリで Beads を初期化します（プロジェクトごとに一度だけ必要です）。

bd init

これにより、次の内容を含む .beads/ ディレクトリが作成されます。

• issues.jsonl - Git でバージョン管理される信頼できる情報源
• *.db - ローカルの SQLite キャッシュ（gitignore 対象）

2. 作業の作成

新しい作業を始めるとき、または実装中にタスクを見つけたときに課題を作成します。

基本的な作成：

bd create "Task title" -d "Description" -p 1 -t task --json

課題の種類：

• task - 標準的な作業項目（デフォルト）
• feature - 新機能
• bug - 修正が必要な不具合
• epic - 大規模な作業（複数のタスクの親）
• chore - 保守作業

優先度レベル（0～4）：

• 0 - 緊急／ブロッキング
• 1 - 優先度高
• 2 - 優先度中（デフォルト）
• 3 - 優先度低
• 4 - できれば対応

Markdown ファイルからの作成：

bd create -f plan.md --json

形式：## Issue Title で新しい課題を作成します。任意のセクションとして ### Priority、### Type、### Description、### Dependencies を指定できます。

整理用のラベルを追加：

bd create "Add auth" -l "backend,security,p1" --json

3. 依存関係の管理

関連する作業をリンクして、順序を設定し、ブロッカーを追跡します。

依存関係の追加：

# Format: bd dep add <dependent> <blocker>
bd dep add bd-5 bd-3  # bd-5 depends on bd-3 completing first

依存関係の種類：

• blocks（デフォルト）- 強いブロッカー。ブロッカーがクローズするまで、依存先は開始できません
• parent-child - 階層関係（子は親に依存します）

  bd dep add bd-task bd-epic --type parent-child
  

• discovered-from - 別の課題の作業中に見つかった課題

  bd dep add bd-new bd-current --type discovered-from
  

• related - 弱い関連付け。課題同士は関連していますが、ブロックしません

依存関係を可視化：

bd dep tree bd-42 --json

循環依存を検出：

bd dep cycles --json

循環依存があると、着手可能な作業の検出が妨げられるため、解消する必要があります。

4. 着手可能な作業を見つける

未解決のブロッカーがない、実行可能な作業を検索します。

# All ready work
bd ready --json

# Filter by priority
bd ready --priority 1 --json

# Filter by labels
bd ready --label backend --json

# Limit results
bd ready --limit 5 --json

最近／最新のタスクを見つける

重要： セッションを開始するときは、必ず最初に最新／最も番号の大きいタスクを確認してください。これらは通常、最も新しい作業と現在の優先事項を示しています。

ID の降順で最近のタスクを表示：

# List all open tasks, sorted by ID number (highest/newest first)
bd list --status open --json | jq -r '.[] | .id' | sort -t'-' -k3 -n -r | head -20

# Show full details of highest-numbered tasks
bd list --status open --json | jq 'sort_by(.id | sub(".*-"; "") | tonumber) | reverse | .[0:10]'

# Find tasks in a specific number range (e.g., 120-150)
bd list --json | jq '[.[] | select(.id | test("Twilio-Aldea-1[2-5][0-9]"))] | sort_by(.id | sub(".*-"; "") | tonumber) | reverse | .[] | {id, title, status, priority}'

セッション開始時のワークフロー例：

# 1. First, check what the highest task numbers are
HIGHEST=$(bd list --json | jq -r '.[].id' | grep -oE '[0-9]+$' | sort -n | tail -1)
echo "Highest task number: $HIGHEST"

# 2. View tasks in the recent range (e.g., last 30 tasks)
RANGE_START=$((HIGHEST - 30))
bd list --json | jq --arg start "$RANGE_START" '[.[] | select(.id | test(".*-([0-9]+)$") and (.id | match(".*-([0-9]+)$").captures[0].string | tonumber) >= ($start | tonumber))] | sort_by(.id | sub(".*-"; "") | tonumber) | reverse'

# 3. Find ready work among recent tasks
bd ready --json | jq -r '.[] | .id' | sort -t'-' -k3 -n -r | head -10

最初に最近のタスクを確認する理由：

• 最も新しい作業が現在の焦点であることが多い
• 最近のタスクには、より新しいコンテキストが含まれていることが多い
• 新たに作成された優先度の高い作業を見落としにくくなる
• 最後にどの作業に取り組んだかを把握しやすくなる

セッション開始時は、必ず次の操作を行ってください：

1. 最も番号の大きいタスクを確認し、現在の作業範囲を把握する
2. 最近のタスク（番号の大きいものから 20～30 件）を一覧表示し、現在の注力分野を確認する
3. bd ready --json を実行してブロックされていない作業を見つけ、最近のタスクを優先する
4. 優先度が最も高い着手可能な課題を選ぶ（優先度が同じ場合は最近のタスクを優先）
5. 作業を始める前に、ステータスを in_progress に更新する

5. 作業と更新

作業の進行に合わせて、課題のステータスを更新します。

作業を開始する：

bd update bd-42 --status in_progress --json

有効なステータス：

• open - 未着手
• in_progress - 作業中
• closed - 完了

ほかのフィールドを更新する：

bd update bd-42 --priority 0 --json
bd update bd-42 --assignee alice --json

完了した作業をクローズする：

bd close bd-42 --reason "Implementation complete, tests passing" --json

6. 作業中に見つかった課題

実装中に新たな作業が見つかった場合：

# 1. Create the discovered issue
NEW_ID=$(bd create "Fix discovered bug in auth" -t bug -p 1 --json | jq -r '.id')

# 2. Link back to parent work
bd dep add $NEW_ID bd-current --type discovered-from --json

# 3. Decide: handle now or defer?
# If blocking current work: switch to new issue
# If not blocking: continue current work, new issue will show in bd ready

7. クエリと確認

フィルターを指定して課題を一覧表示する：

bd list --status open --json
bd list --priority 1 --json
bd list --label backend,urgent --json  # AND: must have ALL
bd list --label-any frontend,backend --json  # OR: at least one

課題の詳細をすべて表示する：

bd show bd-42 --json

ブロックされている課題を確認する：

bd blocked --json

プロジェクトの統計情報：

bd stats --json

JSON 出力の解析

プログラムからアクセスする場合は、常に --json フラグを使用してください。jq で解析します。

# Get first ready issue
ISSUE=$(bd ready --json | jq -r '.[0]')
ISSUE_ID=$(echo "$ISSUE" | jq -r '.id')
ISSUE_TITLE=$(echo "$ISSUE" | jq -r '.title')

# Check if any ready work exists
READY_COUNT=$(bd ready --json | jq 'length')
if [ "$READY_COUNT" -eq 0 ]; then
  echo "No ready work. Check blocked issues:"
  bd blocked --json
fi

# Get highest task number and list recent tasks
HIGHEST=$(bd list --json | jq -r 'max_by(.id | sub(".*-"; "") | tonumber) | .id | sub(".*-"; "")')
echo "Highest task: #$HIGHEST"
bd list --json | jq --arg num "$HIGHEST" '[.[] | select((.id | sub(".*-"; "") | tonumber) >= (($num | tonumber) - 20))] | sort_by(.id | sub(".*-"; "") | tonumber) | reverse | .[] | {id, title, status, priority}'

ベストプラクティス

推奨事項：

• プロジェクト開始時に Beads を初期化します（bd init）
• 形式ばらないメモではなく、見つかった作業を課題として登録します
• 依存関係を使ってタスク間の関係をモデル化します
• セッション開始時に bd ready を実行して、状況を把握します
• 課題をクローズする際は、理由を具体的に記載します
• ラベルを使って作業を分類します（例：backend、frontend、urgent）
• .beads/issues.jsonl を Git にコミットします（変更後に自動エクスポートされます）

禁止事項：

• 循環依存を作成しないでください（bd dep cycles で検出できます）
• ステータスの更新を怠らないでください（古いステータスが残ると、着手可能な作業の検出に支障が出ます）
• 見つかった作業を親課題に関連付け忘れないでください
• Beads が利用可能な場合、タスク管理に Markdown ファイルを使わないでください
• ブロックされている課題をいつまでも放置しないでください（依存関係を再評価します）

複数セッションでのワークフローパターン

セッション 1 - 新規に開始：

# 1. Check for ready work
bd ready --json

# 2. If no ready work, check what's blocked
bd blocked --json

# 3. Start working on highest-priority ready issue
bd update bd-5 --status in_progress --json

# 4. During work, discover new issue
bd create "Fix validation bug" -t bug -p 0 --json
bd dep add bd-new bd-5 --type discovered-from --json

# 5. Complete original work
bd close bd-5 --reason "Feature implemented" --json

セッション 2 - エージェントが再開（別のセッション、場合によっては別の日）：

# 1. Check ready work (newly created bd-new is now ready)
bd ready --json

# 2. See discovered issue from previous session
# 3. Continue work seamlessly without context loss
bd update bd-new --status in_progress --json

クイックリファレンス

コマンドの包括的なチートシートについては、references/quick-reference.md を参照してください。

ワークフローパターンと高度な使用方法については、references/workflow-patterns.md を参照してください。

組み込みヘルプ

Beads には、インタラクティブなクイックスタートガイドが含まれています。

bd quickstart

これを実行すると、包括的な例とワークフローを確認できます。

プロジェクトドキュメントとの統合

AGENTS.md または CLAUDE.md に追加します。

## Task Tracking with Beads

We track implementation work using Beads (`bd`), a dependency-aware issue tracker. Use `bd ready --json` to see unblocked work, `bd create` to add tasks, and `bd update <id> --status in_progress` to claim work. Run `bd quickstart` for full documentation.

リソース

このスキルには、Beads を効果的に使うためのリファレンスドキュメントが含まれています。

references/

• quick-reference.md - カテゴリー別に整理されたコマンドのチートシート
• workflow-patterns.md - エージェントのワークフローでよく使われるパターンとベストプラクティス