はじめに

この記事では、 AIコーディングエージェント向けのタスク管理ツール「Beads (bd)」を紹介します。
Claude Codeなどのエージェントにタスクを記憶させ、セッションをまたいだ作業管理を可能にするツールです。

beadsとは

AIエージェントが使用することを前提に作られたタスク管理ツールです。
bdコマンドというCLIを使ってタスク管理ができます。

CLIでタスクを操作できることから、Claude Codeなどのバイブコーティングツールを使用する開発者から高評価を得ています。

GitHub Issueなどとの違い

プロジェクトのタスク管理というとGitHub Issueが古くから使われていますが、GitHub Issueとbeadsのメカニズムの違いや、beadsを使うメリットは以下の通りです。

  • 依存関係の設定ができる
    • このタスクを完了しないと次のタスクを実行できない、といった複雑な依存関係の設定が可能です。
  • DBとJSONLでタスク管理
    • DBファイルとjsonlファイルの2つを用いてタスクを管理します。
      • DBファイル上でタスクのステータス、優先度、説明などが記録されています。
        • 軽量な内部DBにクエリを実行することで、エージェントは必要な情報のみを参照でき、コンテキストの肥大化を防げます。
      • DBへの変更はjsonlファイルにも同期され、人間にも読みやすい形式で表示されるため、Gitなどのバージョン管理ソフトで差分を確認できます。
      • ローカルのDBファイルを用いるので、クラウドを使わずオフラインでも動作します。
  • コマンドラインから操作できるので、AIエージェントからも操作が可能です。
    • エージェントにセッションをまたいだ情報を記憶させるrememberコマンドなど、エージェント向けの機能があります。

初回セットアップ

# Windowsにbeadsをインストール
irm https://raw.githubusercontent.com/gastownhall/beads/main/install.ps1 | iex

## 環境変数 Pathに以下のPathを設定
>> ==> bd installed to C:\Users\pocke\AppData\Local\Programs\bd\bd.exe

# project
cd project_folder
bd init

  # 他の人のリポジトリに貢献するかいなかを設定
  # Contributing to someone else's repo? [y/N]: n

  # タスク更新時に.beads/issues.jsonlファイルに自動で同期をするかを設定
  # Enable auto-export? [Y/n]: Y

コマンド実行後、以下のファイルが更新されます。

  • .beadsフォルダに関連ファイルが作成されます。
  • .gitignoreに以下の内容が反映されます。
# Beads / Dolt files (added by bd init)
.dolt/
*.db
.beads-credential-key
  • Claude Codeを使っている場合は、プロジェクトのsettings.jsonに以下の設定が反映されます。
    • bd primeは出力をAI向けに最適化するコマンドです。
    "PreCompact": [
      {
        "hooks": [
          {
            "command": "bd prime",
            "type": "command"
          }
        ],
        "matcher": ""
      }
    ],

    "SessionStart": [
      {
        "hooks": [
          {
            "command": "bd prime",
            "type": "command"
          }
        ],
        "matcher": ""
      }
    ]
  }
}
  • CLAUDE.mdやAGENTS.mdにも、bdを使ってタスク管理をする旨の指示が追記されます。
  • bd quickstartコマンドを実行すると、bdコマンドの使い方が表示されます。

基本的なコマンド

# issue作成
  bd create "Fix login bug"
  bd create "Add auth" -p 0 -t feature
  bd create "Write tests" -d "Unit tests for auth" --assignee alice

# issueリスト表示
  bd list
  bd list --status open  # ステータスで絞り込み
  bd list --priority 0

# issue詳細表示
  bd show issue名

# issue間の依存関係管理
  bd dep add bd-1 bd-2 # bd-1 => bd-2の依存関係を設定(bd-2がbd-1をブロックする)
  bd dep tree bd-1 # 依存関係をツリー表示
  bd dep cycles # 循環関係となる依存関係の検出

# 依存関係の種類
  blocks           タスクBが完了しないとタスクAが実行できない
  related          緩やかな関連、進行をブロックしない
  parent-child     親issue/子issueの階層関係
  discovered-from  AIが関連タスクを発見した際に自動生成される

# ステータスがopenでブロックされていないissueを表示
  bd ready

# issueを更新
  bd update bd-1 --claim
  bd update bd-1 --priority 0
  bd update bd-1 --assignee bob

# issueをクローズ
  bd close bd-1
  bd close bd-2 bd-3 --reason "Fixed in PR #42"

Gitと連携せずローカルのみで使う場合

Gitと連携せず、ローカル環境のみでタスク管理をする場合はstealthオプションをつけると、リポジトリにファイルを残さず実行できます。

# 初期化
bd init --stealth

## ロールの設定
▶ Already configured as: contributor
Change role? [y/N]: N

## リモートリポジトリをローカルに取り込み
▶ Detecting git repository setup...
⚠ No upstream remote detected

  For fork workflows, add an 'upstream' remote:
  git remote add upstream <original-repo-url>

Continue with contributor setup? [y/N]: y

## issueの保存場所を設定
Where should contributor planning issues be stored?
Default: C:\Users\.beads-planning
Planning repo path [press Enter for default]: C:\Users\.beads-planning

## issue更新時のissues.jsonlへの自動書き込み設定
Enable auto-export? [Y/n]: Y
  ✓ Auto-export enabled → .beads/issues.jsonl

  Backend: dolt
  Mode: embedded
  Database: hoge_hoge
  Issue prefix: hoge-hoge
  Issues will be named: hoge-hoge-<hash> (e.g., hoge-hoge-a3f2dd)

おわりに

Beadsを使うことで、AIコーディングエージェントに複雑な依存関係を持つタスク管理を任せられるようになり、セッションをまたいだ作業の引き継ぎもスムーズになります。DBとjsonlの二重管理により、エージェントにはコンテキストを圧迫しない軽量な情報参照を、人間にはGitで差分管理できる可読性を、それぞれ両立している点が特徴的です。

Claude Codeなどのエージェントを使ったタスク管理の効率化に興味がある方は、ぜひ導入を検討してみてください。