beads-viewer

Beads Viewer

概要

Beads Viewer（BV）は、Beads プロジェクト（.beads/beads.jsonl）向けのグラフを考慮したトリアージエンジンです。9 種類のグラフ指標を計算し、実行計画を生成して、決定論的な推奨事項を提示します。

使用する場合： Beads タスクのトリアージ、依存関係グラフの分析、ボトルネックの特定、循環依存の検出、並列実行トラックの計画、スプリントのバーンダウンデータの生成、プロジェクトの過去の状態との比較。

使用しない場合： beads.jsonl を直接解析する場合（BV はグラフ指標を事前計算します）、単純な Bead の CRUD 操作を行う場合（代わりに bd CLI を使用してください）、.beads/beads.jsonl がないプロジェクトの場合。

機能	生の beads.jsonl	BV ロボットモード
クエリ	「すべてのイシューを一覧表示」	「リリースを妨げている上位 5 件のボトルネックを一覧表示」
コンテキストコスト	高（イシュー数に比例）	低（固定の要約構造体）
グラフロジック	エージェントが計算する必要あり	事前計算済み（PageRank、媒介中心性、循環）
安全性	エージェントが循環を見落とす可能性あり	循環を明示的にフラグ付け

クイックリファレンス

コマンド	用途	主なポイント
bv --robot-triage	推奨事項を含む完全なトリアージ	まずこれを使用します。quick_wins と blockers が含まれます
bv --robot-next	claim コマンド付きの最優先候補 1 件	コンテキストコストが最小
bv --robot-plan	並列実行トラック	--robot-insights より高速
bv --robot-insights	グラフ指標全件（9 種類すべて）	status フィールドを確認してください。コストが高くなります
bv --robot-priority	優先度の不整合を検出	優先度設定が不適切な項目にフラグを付けます
bv --robot-alerts	古いイシュー、ブロックの連鎖	予防的な健全性チェック
bv --robot-suggest	ハイジーン：重複、依存関係の欠落	循環を解消する提案が含まれます
bv --robot-graph	依存関係グラフのエクスポート	JSON、DOT、または Mermaid 形式
bv --recipe <name> --robot-<cmd>	任意のロボットコマンドの前に事前フィルターを適用	レシピ：actionable、high-impact、bottlenecks
bv --robot-triage --label <name>	対象をラベルのサブグラフに限定	分析対象を絞り、ノイズを減らします

重要： エージェントのセッションから、引数なしで bv を実行しないでください。セッションをブロックする対話型 TUI が起動します。必ず --robot-* フラグを使用してください。

9 つのグラフ指標

指標	測定内容	主な洞察
PageRank	依存関係の重要度を再帰的に評価	基盤となるブロッカー
Betweenness	最短経路上のトラフィック	ボトルネックと橋渡し役
HITS	ハブ／オーソリティの二面性	エピックとユーティリティ
Critical Path	最長の依存関係チェーン	余裕時間がゼロの要石
Eigenvector	隣接ノードを介した影響力	戦略的な依存関係
Degree	直接接続数	直接のブロッカー／被ブロック
Density	エッジとノードの比率	プロジェクトの結合度の健全性
Cycles	循環依存	構造上のエラー（必ず修正！）
Topo Sort	有効な実行順序	作業キューの基盤

指標は 2 つのフェーズで計算されます。フェーズ 1（degree、topo sort、density）は即時に完了し、フェーズ 2（PageRank、betweenness、HITS、eigenvector、cycles）には 500ms のタイムアウトがあります。出力の status フィールドを必ず確認してください。

組み込みレシピ

レシピ	目的
default	優先度順に並べた、すべての未完了イシュー
actionable	すぐに作業可能（ブロッカーなし）
high-impact	PageRank スコア上位
blocked	依存関係待ち
stale	30 日以上更新されていない未完了項目
triage	算出されたトリアージスコア順
quick-wins	ブロッカーのない簡単な P2／P3 項目
bottlenecks	Betweenness の高いノード

ロボット出力の構造

すべてのロボット JSON 出力には、次の標準フィールドが含まれます。

フィールド	目的
data_hash	一貫性を検証するための beads.jsonl のフィンガープリント
status	指標ごとの状態：computed、approx、timeout、skipped
as_of / as_of_commit	時点をさかのぼるクエリで --as-of を使用した場合に表示されます

コマンドごとの主な出力セクション：

• --robot-triage：quick_ref、recommendations、quick_wins、blockers_to_clear、project_health、commands
• --robot-insights：bottlenecks、keystones、influencers、hubs、authorities、cycles、clusterDensity
• --robot-plan：plan.tracks（並行作業ストリーム）、plan.summary.highest_impact

よくある間違い

間違い	正しいパターン
エージェントのセッションから bv をそのまま実行する	必ず --robot-* フラグを使用してください。bv をそのまま実行すると対話型 TUI が起動し、エージェントがブロックされます
ロボット出力の status フィールドを無視する	メトリクスごとのステータスを必ず確認してください。大規模なグラフでは、500ms のタイムアウトにより approx または skipped になるメトリクスがあります
次のタスクだけが必要なのに --robot-insights を使用する	候補を 1 つだけ選ぶ場合は --robot-next、手早く推奨事項を得る場合は --robot-triage を使用してください。insights はコストがかかります
実装を始める前に循環依存を確認しない	bv --robot-insights を実行して、まず .cycles を確認してください。循環依存は解決が必要な構造上のエラーです
stderr を JSON データとして解析する	JSON が含まれるのは stdout のみです。診断情報と警告は stderr に出力されます
bead の変更後に古いメトリクスを使用する	data_hash フィールドを確認してください。結果は beads.jsonl のフィンガープリントによってキャッシュされます
現在の作業に合わない推奨事項を使用する	--recipe actionable を使用して、ブロックされておらず、すぐに作業できる項目だけに絞り込んでください

委任

• プロジェクトの依存関係の健全性とボトルネックを分析する：Task エージェントを使用して BV のロボットコマンドを実行し、グラフのメトリクスを要約します
• トリアージ出力からスプリント作業を計画する：Plan エージェントを使用してトリアージの推奨事項を解釈し、実行トラックを作成します
• 関連する bead のコンテキストを検索する：Explore エージェントを使用して bead の説明を調査し、実装パターンを見つけます

参考資料

• ロボットコマンド、出力構造、jq のパターン
• グラフのメトリクス、2 段階分析、メトリクスのレシピ
• エージェントのワークフロー、TUI ビュー、統合、タイムトラベル