PR の地図とマージ

ゼロから作ると、PR は 200〜300 本になります。BeesBuild は、PR を 1 本ずつの一覧ではなく、ブロックと塊で整理した地図にします。地図から、入れる順・並行して進める道・「ここまで入れると動く」ゴールを計算し、エンジニアに範囲で渡します。

PR が本番に届くまで

1. 仕事の札：会話・作業場・連絡箱・Geniam Time で話した仕事が、仕事の札になります。既定では、ハブの issue にもなります（issue の扱い）。
2. 下書きの PR：スレッドが枝を切り、最初の commit で下書きの PR を立てます。
3. AI の一次レビュー：AI が先に読み、指摘を出します。承認の数には入れません（レビュー）。
4. PR の地図：PR がブロック・塊・順・道・ゴールに置かれます。
5. 担当の範囲：引き継ぎの文と一緒に、人かチームに渡します。
6. 人のレビュー：人が読み、学びの印を付けます。
7. マージ：開発の段階のモードで分かれます。実験モードと試す人ありモードは、自動マージの決まりに合えば BeesBuild がマージします。運用モードは、エンジニアがマージの机で 1 本ずつ押します。
8. ステージングと動作確認：マージの後に自動でデプロイし、ゴールの試験が緑ならクリアです。
9. 本番：人が押します（公開と反映）。

地図の 4 段

大きく見る ↗

PR の巣。セルごとに、六角の升が状態の色で塗られる画面設計（開発中）・数字は見本

段	中身	例
ブロック	データの持ち主で分けたまとまり	月謝のブロック
塊	それだけで試験が通り、ステージングで確かめられる単位	月謝の請求の塊（9 本）
積み重ね	下の PR の枝を base にした束（stacked PRs）。GitHub が下から順にマージし、上の PR の base を付け替える	型 → 処理 → 画面の 3 本
PR	題の頭・枝の名前・commit の印で、ハイブ・ブロック・スレッドが分かる	[KN][B4-T2] 月謝の請求の画面

PR の題の頭にハイブとブロックを付ける決まりは、スレッドと名札にあります。

依存の線

線	確かさ	元
積み重ね	確定	stacked PRs の下と上
Depends-on	確定	PR の説明の Depends-on: #241。別のリポジトリの PR も書ける
約束の型	推定	型の持ち主の PR が先
層の順	推定	型 → 処理 → つなぎ → 画面

• 推定の線は点線で描き、人が確定にできます。
• 同じファイルに触るだけの PR は線にせず、「ぶつかりの恐れ」の印を付けます。
• 1 つの機能が 3 つのリポジトリにまたがる形も、リポジトリをまたぐ線で持てます。

順・道・クリティカルパス・ゴール

計算する物	決め方
順	依存の向きを守って並べる。同じ段なら、解くと先に進める数が多い物 → クリティカルパスの上 → 小さい物 → 古い物
道	並行して進められる流れ。依存の図を鎖に分け、1 本の道を 1 人が受け持てる形にする。土台の道には「1 本ずつ・先に」の印を付ける
クリティカルパス	見込みの時間がいちばん長い鎖。細い線で示す
ゴール（ここまでで動く）	設計図の機能・旗・動作確認の試験 1 本の組。要る PR を依存の線から自動で集める

• PR の番号は GitHub のまま使い、振り直しません。順は「道 B の 12 番目」のように、道の中の位置で見せます。
• ゴールは、要る PR が全部マージされ、ステージングにデプロイされ、その試験が緑になったら「クリア」です。
• ゴールの無いプロジェクトでは、AI が案を出し（推定の印）、人が決めます。
• ゴールには、営業やほかのチームにも分かる外向けの一言を付けます。AI が下書きし、ゴールの持ち主が入れます。共有のボードの札にもなり、空の時は「準備中」と出ます。

進み具合と描き方

• 進み具合は、PR の本数・行（本番のコードとテストを分ける）・ゴールの数・道とブロックごとの残り・終わる見込みで見ます。数は記録から数え、AI は数を作りません。終わる見込みは推定の印付きです（開発の速さ）。
• 遠く（ブロックの島と残りの輪）→ 中（塊と積み重ね）→ 近く（PR の六角の升と番号）の 3 段で描きます。
• 読むのは変わった PR だけです。条件つきの読み方（変わっていなければ 304 が返る）と GraphQL のまとめ読みで、GitHub の API の上限の内に収めます。読み直しは 15 分ごとです。

クリアの見え方

PR の状態の帯は、PR → AI の一次 → 人のレビュー → マージ → ステージング → 動作確認 → 本番 の 7 つの区切りです。本番は、提供先の数だけ分けて見せます。色は画面の決まりのとおり、水色が AI の作業中、紫がレビュー中、琥珀が人の番、緑が済み、赤が失敗、灰が信号なしです（信号の色）。

• 地図の上では、PR の六角の升が状態に合わせて塗られます。ゴールの旗は、要る PR が全部マージされてステージングで動いた時に緑になります。
• 知らせ方は、短い光の帯と数の繰り上がりだけです。紙吹雪や絵は使いません。
• 出す所は、PR の地図・コントロールセンターとダッシュボードの「クリアの帯」・現状報告です。クリアマップには「PR の層」の入口があります。
• 持ち主がふだん見るのは「今週のゴール」と「反映の表」だけで足ります。PR 1 本ずつは、押した時だけ開きます。

GitHub の Projects に写す

地図は、GitHub の Projects（表・板・ロードマップの見方を持つ GitHub の画面）にも写します。BeesBuild を入れていないエンジニアも、同じ地図で進められます。

決まり	中身
Project の数	ハイブごとに、組織の Project を 1 つ。PR を自動で足す
欄	ブロック・塊・段・道・道の中の位置・ゴール・担当・反映・見込み
書く人	順・道・ゴール・反映は BeesBuild が書く。担当とメモは人が書ける
読み返し	人が直した欄を 15 分ごとに読み返す。BeesBuild は変わった欄だけを書く

• 全部の情報（PR・issue・レビュー・反映・人が直した欄）は、BeesBuild に集めます。中のエージェント（統括・BeesAgent・クラウドの蜂）は、Hive Bus の読むだけの道具で地図を読み、次の手を決めます。書く道具は持たせません（Hive Bus の道具）。
• PR の説明のいちばん上に、BeesBuild が 1 行を書きます。

▶ 押すと開く資料 ／ 道 B の 12 番目 ／ 次は #245 ／ ゴールまで残り 3

順を GitHub の上でも守る

BeesBuild の GitHub App が、PR ごとに check beesbuild/order を書きます。前の PR がマージ済みなら緑です。運用モードでは、この check をルールセットで必須にします。GitHub の画面でマージしても、順が崩れません。

担当の範囲と引き継ぎ

範囲は、道の一続き（例：道 B の #241〜#258）・塊・ゴールに要る PR の全部・PR 1 本のどれかで切ります。

1. 範囲を選ぶ：地図かロードマップで選びます。AI に「道 B をレビューの役のメンバーに」と話してもかまいません。
2. 負荷を見る：担当ごとの本数・行・見込みの時間・GitHub の Busy の状態を見ます。
3. 引き継ぎの文を作る：AI が作ります。
4. 割り当てる：確認のカードで割り当てます。
5. 受ける：担当が「受けた」を押します。
6. 済みにする：範囲の最後の PR がマージされ、ゴールがステージングで動いたら「済み」になり、次の範囲の担当に「ここまで入りました」が届きます。

引き継ぎの文

欄	中身
範囲とゴール	どこからどこまでか。何が動けば終わりか
順	道の中の位置と、次の PR
地図と資料	地図への道と、束の資料
試し方	試す手順と、試すデータ
手元で動かす命令	clone・install・試すデータの投入・起動・試験の命令。置き換えの要らない完成形で書き、.env.example（秘密を入れない雛形）を付ける
見込みの時間	終わるまでの見込み（推定）
終わりの条件	何が済んだら「済み」か
困った時	Undam（旧 Xroid Work）のスレッド

• 言葉はハブの言葉の設定に従います（既定は日本語だけ）。宛先は役で書き、名前は送る時に人が入れます。
• 置き場は GitHub（範囲の最初の PR のコメントと Projects）と Undam です。Slack は下書きまでで、送るのは担当の人です。
• GitHub の担当とレビューの依頼は、順が来た PR だけに付けます。通知の量を抑えるためです。レビューを頼まれる人には、リポジトリの Write の権限が要ります。
• 範囲は書く鍵ではありません。ほかの人が手伝ってもかまいません。
• 担当がレビュー中の PR に AI のスレッドが push する時は、担当に知らせます。運用モードでは「最新の push の承認」を必須にします。

マージの机

大きく見る ↗

マージの机。塊の順に、次の 1 本を押す画面設計（開発中）・数字は見本

運用モードでは、エンジニアがマージの机で 1 本ずつ押します。

見る物	中身
次の 1 本	順が来た PR
点検	CI・T9 の点検・開発ルール・AI の一次レビュー（数えない）・人のレビュー・ぶつかり・下の PR の状態
マージ	本人の GitHub のログインでマージする。積み重ねは下から順に入れる
マージの後	main の試験・ステージングへのデプロイ・動作確認の進み

• 「次へ」を押すと、次の 1 本が出ます。前の塊が終わるまで、次の塊は押せません。
• AI のテスト（単体・裏で動く Playwright の E2E・画面の比べ・守りの点検）を先に通し、人のテストは塊ごとの短い手順と専用のデータで行います。
• ステージングから本番へは人が押し、前の版へ 1 回で戻せます（公開と反映）。
• 試しのデータは、終わったら片付けます。

自動マージ

実験モードと試す人ありモードでは、人が確認のカードで一度承認した「自動マージの決まり」に合う PR だけを、BeesBuild のコアが GitHub App の名前（beesbuild[bot]）でマージします。AI のスレッドがマージすることはありません。

決まりの項目	中身
行き先	どのリポジトリの、どの枝へ入れるか
条件	下の「自動マージの条件」のすべて
除くパス	人が押す物
量の上限	1 時間に 20 本・1 日に 150 本（案）
止める条件	止める表に載った PR、main が壊れた時
承認の記録	承認した役と日時

自動マージの条件

次のすべてを満たした PR だけが入ります。

• CI が緑（Linux と Windows）
• T9 の点検と、開発ルールの「必ず」が通る
• 監査の重さ「高」が 0
• AI の一次レビューの重さ「高」の指摘が 0（AI の承認は数えませんが、高の指摘は止める条件にします）
• 止める表に無い
• 積み重ねの下がマージ済み
• ほかの PR とぶつからない
• 下書きでない
• 順の check（beesbuild/order）が緑

除く物（人が押す）

除く物	理由
共有のファイル	全部のブロックに効く
.github/workflows/	CI とデプロイの動きを変える
依存の宣言とロックのファイル	外のコードが入る
鍵・認証・更新・配る包みの口	守りと、利用者の手元に届く物に効く
消す方向の DB の移行	戻せない
ルールセットと CODEOWNERS	main の守りそのもの
スキルと開発ルールの元	AI の動き方を変える

試す人ありモードでは、さらに対象を絞ります。自動でマージするのは、持ち場だけ・旗がオフ・危なくない PR だけです。試す人に開けた旗の機能、その画面と API の形、データの移行に触る PR は人が押します。「危なくない PR」の細かい線は、試しの週に決めます。確認中

マージの仕方

• GitHub の async merge API（マージを頼み、結果を後で取りに行く口）で、積み重ねを下から順にマージします。頼んだ ID と結果は、マージの記録に残します。
• 決まりを飛ばす指定（bypass）は使いません。必須の CI とルールセットを必ず通ります。
• GitHub の merge queue は、非公開のリポジトリでは GitHub Enterprise Cloud が要ります。使える時だけ上乗せで使い、使えない時は BeesBuild の列で代わりにします。

BeesBuild の列は、6 つの仕組みでできています。

仕組み	中身
点検	持ち場のフォルダー・共有のファイル・型は足すだけ・旗・言葉のキー
了承の表	入れてよい PR。PR の番号と head の sha に結ぶ
止める表	入れない PR。PR の番号と head の sha に結ぶ
順の表	入れる順。PR の番号と head の sha に結ぶ
毎日一巡	開いている PR を全部重ねて試す
列	1 本ずつ入れ、main が壊れたら止める

sha に結ぶので、了承の後に push された PR は、了承が外れます。

壊れた時

モード	すること
実験モード	列を止め、壊した PR を戻す PR を自動でマージし、作ったスレッドへ返す
試す人ありモード	同じ。試す人に開けた機能が壊れたら、旗を閉じるカードも出す
運用モード	戻す PR を作り、エンジニアがマージする

AI がマージしない理由

AI の承認は数えない決まりと、そろえるためです。マージは、人が一度承認した決まりと機械の判定だけで起こります。記録では bot の名前に分かれるので、誰の判断で入ったかを後からたどれます。

BeesBuild 自身の開発でも、マージするのは AI のスレッドではなく、人が一度入れた GitHub Actions のマージの workflow です。GitHub App の token を使います。Actions の GITHUB_TOKEN で行った push では次の workflow が起きず、ステージングへのデプロイが続かないためです。

issue の扱い

issue の扱いは、ハイブごとに 3 つから選びます。切り替えるのは持ち主です。

設定	人の入口	ブロックの間・AI どうしの依頼
今のまま（既定）	会話でも issue でもよい。会話と Geniam Time で話した仕事は、AI が札にしてハブの issue にする	ハブの issue（ラベルの組）。AI どうしの仕事もログとして issue に残す
人は書かず、AI どうしだけ issue	会話（仕事の札）。人は issue を書かない	ハブの issue（ラベルの組）
issue を作らない	会話（仕事の札）。記録の正は PR	Hive Bus の手紙。PC やアカウントをまたぐ時は、クラウドの連絡箱か Projects の下書きの項目

既定の流れは次のとおりです。

1. 話す：Geniam Time や作業場で、仕事を話します。
2. 札と issue：仕事の札になり、ハブの issue になります。
3. 渡す：統括が、ブロックとスレッドへ渡します。
4. 下書きの PR：スレッドが枝を切り、最初の commit で下書きの PR を立てます。
5. 閉じる：直す PR の Fixes #n で、マージの時に issue が閉じ、元の場所に返ります。

• ラベルの組：宛先 block-NN・出した所 from-block-NN・種類（contract・waiting・decision・platform・shared・docs）。
• 守りの指摘は issue にしません。守りの台帳に置き、issue に穴の作り方を書きません（記録と監査）。
• あふれ対策：AI が作った issue には印のラベル（案：by-ai）を付け、人の一覧から外して見られるようにします。終わった依頼はすぐ閉じます。
• たどれる印：PR の説明に Card: HB-W-0123・Fixes #n・Depends-on: #241・Goal: fees.invoice を書きます。「作らない」設定でも、PR から元の依頼をたどれます。
• Projects の下書きの項目は Project の中だけにあり、リポジトリの issue にならず、GitHub の通知も出ません。通知は Hive Bus と BeesBuild が受け持ちます。
• 外から届く不具合の issue は、入口として読みます。仕事の札にし、直す PR で閉じます。

GitHub のプランで使える物

組織が GitHub Team のプランで、非公開のリポジトリの時の対応です。

機能	使えるか	BeesBuild の使い方
stacked PRs・async merge API	使える	塊の中の依存と、下から順のマージ
merge queue	使えない（公開のリポジトリか Enterprise Cloud）	BeesBuild の列で代わりにする
environments・デプロイしてよい枝・環境の秘密	使える	ステージングと本番の記録。本番は main からだけ
環境の人の承認・待ち時間	使えない（非公開では Enterprise だけ）	確認のカードと手動で起こす実行（公開と反映）
CODEOWNERS・ルールセット・auto-merge・チームのレビューの自動の割り当て・Projects	使える	持ち主・main の守り・順の check・担当・地図
役を自分で作る・Pages を非公開にする	使えない（Enterprise Cloud）	4 つの役は既定の役に写す。資料を Pages で出さない（みんなで作る）

データの形

型	中身
HbPrMap	PR の地図の版（点・依存の線〈確定・推定〉・段・道・クリティカルパス・Projects への写しの状態）
HbPrGoal	ここまでで動く（名前・外向けの一言・旗・要る PR・動作確認の試験・ステージングの URL・状態）
HbPrRange	担当の範囲と引き継ぎの文・受けた印・見込み・状態
HbMergePlan	マージの順番
HbAutoMergePolicy	自動マージの決まり（行き先・条件・除くパス・量の上限・止める条件・承認の記録）
HbMergeRun	マージの記録（PR・頼んだ ID と結果）
HbWorkCard	仕事の札（出どころ・つながる PR と issue）
HbIssuePolicy	issue の扱いの設定（3 つ・ラベルの組・AI の印のラベル）

次に読む

公開と反映3 つのモード・ステージングと本番レビューレビューの机と学び仕上げの管制残り 20 本からの詰め