beads-docs

beads ドキュメントの執筆

これは、Mintlify サイトとして公開されている beads のユーザードキュメント、docs/ の標準スタイルです。専門用語を使う前に動機付けを行い、どこでも同じことを同じ表現で伝え、長文の羅列ではなく図やスニペットで概念を示し、コードとの食い違いを決して生じさせないドキュメントを目指します。作成、編集、レビューするすべてのページに適用してください。

docs/ の対象読者は、beads のユーザーです。つまり、bd をインストールし、作業を追跡して同期する人間またはエージェントです。コントリビューター向けの資料は engdocs/ と AGENTS.md にあり、別のルールに従います（実装を文字どおりに説明してもかまいません）。このガイドで「ドキュメント」と言う場合は、docs/ を指します。

1. 標準モデル

Beads は、ワークフローレイヤーを備えた、依存関係を認識するイシューグラフです。一貫性を保って説明し、繰り返し説明するのではなく、標準概念ページの docs/core-concepts/index.md にリンクしてください。

概念	役割	重要な考え方
bead（イシュー）	作業単位	ハッシュ ID（bd-a1b2）、種類、ステータス、優先度を持つ追跡対象の項目。「bead」と「issue」は同じものを指します
依存関係	順序付け	blocks エッジがあると、ブロッカーがクローズするまでエージェントに bead が表示されません。parent-child、related、discovered-from はブロックせずに整理します
準備完了の作業	bd ready が算出するもの	未クローズのブロッカーがないオープン状態の bead。ただし、in_progress、blocked、deferred、hooked は除きます。つまり、着手可能な範囲です
formula	ワークフローのソース	ステップの DAG を定義する TOML/JSON ファイル。bd cook で proto にコンパイルします
proto	ワークフローのテンプレート	{{variables}} を含むテンプレート epic（ラベル template）。進行中の作業ではありません
molecule	インスタンス化されたワークフロー	proto から生成された実際の bead（bd mol pour）。永続します
wisp	一時的な molecule	同じ方法でインスタンス化されますが、ライフサイクルは一時的です（bd mol wisp）。bd purge で削除されます
gate	非同期の待機	人間、タイマー、GitHub の実行／PR、または別 rig の bead によってクローズされるまで、ワークフローのステップをブロックします
sync	マシン間の移動	git リモートの refs/dolt/data 上で Dolt の push/pull を行います。.beads/issues.jsonl は受動的なエクスポートであり、データベースではありません
フェデレーション	リポジトリ間の同期	リポジトリ／組織間で bead をピアツーピアで共有します

覚えておくべきパイプラインは、formula → (cook) → proto → (pour) → molecule または → (wisp) → wisp です。gate は molecule のステップを一時停止し、bd ready は着手可能なステップを表示し、sync はグラフ全体をマシン間で移動します。

ページで繰り返し誤記されているストレージに関する事実：組み込みモード（デフォルトの bd init）では、データは .beads/embeddeddolt/ に保存されます。サーバーモード（bd init --server）では .beads/dolt/ を使用します。.beads/dolt/ を一般的なデータ保存先として記載してはいけません。

プロジェクト間の用語（beads ↔ Gas City）。 姉妹プロジェクトの Gas City でも molecule、formula、wisp、gate という言葉を使いますが、2 つのドキュメント群では意味が異なります。Gas City のドキュメントでは、molecule/wisp は v1 の実装詳細として扱われ（ユーザー向けの概念としては使われません）、Gas City の formula はオーケストレーターがエージェント間で実行するオーケストレーション手法です。beads では、molecule/wisp/proto はユーザー向けの概念であり、formula は proto に調理する TOML ソースです。Gas City の定義を beads のページに（またはその逆に）持ち込んではいけません。2 つのプロジェクトをつなぐ必要があるページでは、どちらのプロジェクトでの意味を指すのかを明示してください。

2. 必須用語

左列の用語を使い、右列の用語は使わないでください（注記がある場合を除く）。文章とリテラルの使い分けに関する詳しい規則については、 references/terminology.mdを参照してください。

使用する用語	使用しない用語	注記
bead ／ issue	単位の名前としての「task」、「ticket」、「TODO item」	どちらの用語も正しく、相互に置き換え可能です。概念を説明する場合は bead を優先し、CLI 出力やフラグに合わせる場合（bd create、「issue types」など）は issue を使います。「task」は issue の 種類 の一つであり、一般的な単位の名前ではありません。
ready work	形式的な用語としての「unblocked queue」、「available tasks」、「the ready set」	bd ready が返す内容として、オープンなブロッカーがないオープンな bead と説明します。
proto	概念を指す名詞としての「template」	template は、proto が持つリテラルなラベル名としてのみ使います。
molecule	文章中での「mol」	mol はコマンドのリテラル（bd mol pour）です。概念は molecule です。
formula	formula を molecule／proto と混同すること	formula は ファイル です。調理すると proto が作られ、注ぎ込むと実際の作業になります。
gate	「barrier」、「checkpoint」、「lock」	gate は、human、timer、gh:run、gh:pr、bead の種類がある非同期の待機条件です。
sync ＝ Dolt push／pull	同期ワークフローとしての export／import	refs/dolt/data を介した bd dolt push／bd dolt pull を指します。.beads/issues.jsonl は、ビューアーやデータ交換用の受動的なエクスポートです。
embedded mode ／ server mode	ストレージを指す「local mode」、「daemon mode」	embedded がデフォルトで、データは .beads/embeddeddolt/ にあります。server mode は dolt sql-server に接続し、データは .beads/dolt/ にあります。
federation	独立した機能名としての「multi-repo sync」	Federation は、リポジトリをまたいだピアツーピアの共有機能です。
hash ID	「random ID」、「UUID」	bd-a1b2 のような ID は、衝突を防ぐためにサイズが適応的に調整される、コンテンツ由来のハッシュです。

3. コンテンツの方針

• 仕組みの説明より先に、解決する課題を示します。 ページの冒頭では、まず解決する課題を示し、次に解決策、最後に仕組みを説明します。用語から説明を始めてはいけません。
• ドキュメントはプロジェクトの歴史ではありません。 ユーザー向けページでは、internal/* パッケージのパスや「これは vX で削除されました」という説明、「（v0.20.1+）」のようなバージョン条件は使いません。beads は 1.x の製品です。1.0 より前の経緯は engdocs/ または CHANGELOG に記載します。
• 価値を先に示します。 Beads の価値は、コーディングエージェント向けの永続的で依存関係を考慮したメモリです。作業グラフがセッション終了後も残るため、コンテキストを失ってもエージェントは作業を継続できます。GitHub Issues、Jira、Markdown の TODO リストとの比較は、新規ユーザーに使い始めてもらううえで最も効果的な説明です。比較がある場合は、ページの早い段階に置いてください。
• 具体例を一つ示すほうが、抽象的な説明を三文並べるより効果的です。 機能を説明する際は、bd の実行例とその出力を示してください。

4. 情報アーキテクチャ

ナビゲーションは docs/docs.json にあり、「Getting Started」、「Core Concepts」、「Architecture」、「Workflows」、「Recovery」、「Multi-Agent」、「Integrations」、「Community」、「Reference」で構成されます。生成された CLI Reference は、「Reference」内の折りたたみ可能なサブグループに配置します。

• 各セクションには索引／概要ページを設けます。 1、2 文でセクションを紹介したあと、すべての子ページを、正確な要約を添えた 1 行のリンクで一覧表示します。
• 1 ページにつき目的は一つです。説明と仕様の両方を教えようとするページは、どちらもうまく果たせません。ページを分けて、相互にリンクしてください。
• 概念に関する内容は core-concepts/index にまとめます。他のページでモデルを再説明せず、ここにリンクしてください。
• リポジトリの構成案内は README に置き、docs/ には置きません。

5. 文章の方針 — 言葉を削り、要点を際立たせる

冗長さの多くは、情報を適切でない媒体に保存していることから生まれます。より低コストな媒体に移し、役割を果たしていないものは削除します。すべてのページは単独で完結させてください。初めてそのページを読む人には、前のページを参照させるのではなく、1行で前提を説明する必要があります。

変換する（文章から情報を移す）：

• 関係性や手順 → 図（mermaid はネイティブでレンダリングされます。より詳細な図は Excalidraw のパイプラインを使います。§7 を参照してください）。
• 複数の選択肢・項目・比較 → 表。
• 「X を実行すると Y が行われます」という説明 → 注釈付き CLI スニペット（コマンドとその出力を示し、重要な行にコメントを付けます）。
• 例外ケースや詳細な仕組み → <Accordion> またはリファレンスページ。ページには一般的なケースの説明を残してください。

削除する（不要な負荷だったもの）：前置きの文（「このセクションでは…」）、曖昧な表現の連続（「一般に／通常は／ほとんどの場合」）、同じ内容の繰り返し、スニペットですでに示されているものの説明、根拠の代わりに使われている形容詞。

意図的に簡潔化する場合は、references/simplification.md に従ってください。各ページで行う手順と、適切な削減を保つための2つのガードレールが記載されています。欠落チェック（ほかにない場所にある事実を削除しない）と事実確認（削減した文章がコードと食い違わないようにする）です。

6. 強調と書式

• 太字は用語の初出時に限って使います。斜体は性質や対比を示します。段落あたりの強調は1〜2か所を目安にしてください。すでに導入した用語を再度強調したり、同じ語句に太字と斜体の両方を使ったりしないでください。
• 本文に # H1 は使いません。H1 は frontmatter の title です。##／### を使ってください。
• リンクはルート相対で、拡張子を付けません（/getting-started/quickstart）。サイト外へのリンク（engdocs/、リポジトリのファイル）には完全な GitHub URL を使います。
• Mintlify は .md を MDX として解析します。HTML コメントは使わず（代わりに {/* … */} を使う）、<id> のような山括弧で囲まれたプレースホルダーはバッククォートまたはコードフェンスの中に記述してください。
• Mintlify コンポーネント（<Note>、<Tip>、<Warning>、<Accordion>）は控えめに使ってください。繰り返すと効果が薄れます。

7. 図

Mermaid フェンスはネイティブでレンダリングされるため、グラフやフローにはこちらを優先してください。より詳細な図には Excalidraw のパイプラインを使います。.excalidraw のソースを docs/diagrams/excalidraw/ に作成し、make diagrams-excalidraw でレンダリングします（ソースとレンダリング済みの .svg の両方をコミットします）。説明的な代替テキストを付けて /diagrams/excalidraw-rendered/<name>.svg として埋め込み、ラベルは短くしてください（ボックスに詰め込んだ文章より、「名前／役割」の2行のほうが適しています）。必ず守るべきことは2つです。

• レンダリングした図はすべてラスタライズして確認してください。 テキストのはみ出しやレイアウトの問題は、テキストの差分では確認できません。
• 図や画像は差分ではレビューできません。 レンダリングしてメンテナーの承認を得てからコミットしてください。

8. 生成コンテンツはソースで編集します

生成されたファイルを直接編集してはいけません。生成対象は次のとおりです。

• docs/cli-reference/*.md と docs/docs.json 内の CLI Reference ページ配列 — bd は、コミット対象外のステージングツリーにベンダー中立なページを出力します（cmd/bd/*.go の Cobra コマンド文字列から bd help --docs-root で生成）。その後、tools/docsmint がコミット対象の Mintlify 形式に後処理します。bd 自体は Mintlify（またはその他のサイトジェネレーター）固有の内容を出力しません。それらは docsmint が担います。
• docs/CLI_REFERENCE.md — bd help --docs-root が直接出力する単一ファイルのリファレンスです。

いずれかの文言を変更するには、Go ソース（Short:、Long:、Example: 文字列）を編集し、./scripts/generate-cli-docs.sh を実行します（両方の段階を実行します）。Mintlify のページ形式自体（コメントマーカー、リンクスタイル、ナビゲーション）を変更するには、tools/docsmint とそのテストを編集します。ドリフト検出ゲート（generate-cli-docs.sh --check、PR CI での scripts/check-cli-docs-drift.sh、および docs-autofix ボット）は、手動編集を失敗として検出するか、自動修正します。

ドキュメントが説明するのは main ではなく、固定されたリリースです。 docs/cli-docs.pin には、ドキュメント全体が対象とするリリースタグが記載されています。パイプラインはそのタグから bd をビルドして検証するため、main 上の Go ソースの変更がコミット済みドキュメントに反映されるのは、ピンを更新した後（リリース時に更新し、その後再生成した後）です。手書きのページも同じ方針に従います。main にしかない機能ではなく、固定されたリリースの動作を記述してください。詳しくは engdocs/decisions/2026-07-17-docs-release-pin.md を参照してください。

9. 完了とする前に検証します

references/verification.md に記載されたゲートを実行してください。主な項目は、bazel test //test/docsync:docsync_test --config=ci（ナビゲーションとファイルの同期、リンク規約）、./scripts/generate-cli-docs.sh --check（生成ドキュメントが最新であること）、./scripts/check-doc-freshness.sh（最終レビュー日時のマーカー）、および localhost:3000 でのライブプレビュー（make docs-dev または ./mint.sh dev）です。

ページを移動または削除する場合：docs/docs.json の redirects 配列にリダイレクトを追加し、リポジトリ全体の受信リンクを書き換えます（README、engdocs/、examples/、npm-package/、プラグインのリソースを対象に、推測せず grep で検索してください）。さらに、bd が古いパスを出力しているかどうかを確認してください（出力している場合は、Go ソースを修正して再生成します。ポインタースタブにしてはいけません。古いルートへのリダイレクトについては決定 6 を参照してください）。

10. レビューとコミットの規律

• 作成者が作成し、メンテナーがレビューし、明示的な承認後にコミットします。 テキスト差分ではレビューできない図や画像では、特に重要です。
• コミットは対象読者ごとにまとめます。ユーザードキュメント（docs/）、コントリビュータードキュメント（engdocs/、AGENTS.md）、ジェネレーターや Go の変更は、それぞれ分けてください。
• AGENTS.md に従って、ドキュメント作業を bd の課題として管理してください。