English · 日本語

コントリビューターワークフローチュートリアル¶

Bajutsu に 貢献する ための、手を動かしながら進めるチュートリアルです。読み終えるころには、一つのアイデアを大まかな一文から /ideation に通してマージ済みの提案にし、CI がその恒久的な BE-NNNN を割り当てる様子を確認し、/implement-be でマージ済みのプルリクエストまで出荷し終えているはずです。 getting-started チュートリアルが Bajutsu を 動かす ための同じ役割を果たすのに対し、このページは Bajutsu を作るための対応物です。リファレンスの各ページが個々の規則の内容を説明するのに対して、このページは順を追って、実際に手を動かしてもらいます。

このページで扱わないこと。 BE ID のライフサイクル、モデルの階層、PR テンプレートは、ここでは説明し直しません。それらは ai-development と roadmap-workflow が担い、このチュートリアルは複製せずにリンクします。最初の貢献を実際に やってみる ためにこのページを読み、規則の全文が必要になったらそれらのページを参照してください。

始める前に¶

getting-started と同じく、動作するチェックアウトとゲートが green の状態が必要です。

uv sync --group dev   # .venv（Python 3.13）+ 依存 + 開発ツール
make setup            # 上記に加え、追跡されている git フックを配線する（新しいクローンで一度だけ実行）
make check            # 決定的なゲート。green でなければならない（ステップの全一覧は CLAUDE.md）

make check は契約です。CI と完全に一致し、Simulator を必要とせず、どこでも走ります。以下の両半分の終わりで、もう一度これを走らせます。このチュートリアルのどの手順も API キーを必要としません。スキルはエディタのセッションのなかで動き、決定的なゲートはモデルに一切到達しないからです。

道のり全体は 2 つの半分に分かれ、それぞれに専用のスキルがあります。

半分	スキル	出発点	到達点
起草	`/ideation`	大まかなアイデア	CI が割り当てた `BE-NNNN` を持つマージ済みの提案
出荷	`/implement-be BE-NNNN`	マージ済みの提案	マージ済みの実装 PR。項目は `Implemented` に切り替わる

この 2 つは意図的に対をなしていて、片方がロードマップを満たし、もう片方がそれを消化します。「なぜ 1 つではなく 2 つのスキルなのか」という考え方は roadmap-workflow にあります。ここでは、その両方を順にたどります。

パート A — `/ideation` で提案を起草する¶

手順 A1 — アイデアを持ち込む。粗くてよい¶

完成した設計は要りません。一文で十分です。このチュートリアルでは、遅い simulator でときどき失敗する手順に繰り返しぶつかっていて、こう考えたとしましょう。

「Bajutsu は、flake する手順を実行全体の失敗にせず、リトライすべきだ」

これはわざと詳細を欠いています。/ideation の仕事の一つは、これを 研ぎ澄ます ことです。前後の比較は下の実例を見てください。

手順 A2 — `/ideation` を走らせ、下調べをさせる¶

セッションのなかでスキルを呼び出します。

/ideation

これは白紙ではなく 相談相手 です。何かを提案する前に、ロードマップの索引、実装状況の表（すでに出荷済みのものを「提案」しないため）、そしてあなたの主題の近くにある BE 項目を読みます。それから、あなたと 一緒に 発想します。範囲の定まった形を提示し、範囲を研ぎ澄ます問いを投げかけます。誰のためか、どの tier に触れるか、そして何より 機械可読な成果 は何か、つまり決定的な run や単体テストが検証できるものは何か、という問いです。プライムディレクティブの内側で作れないアイデアは、捨てられず、収まるように作り直されます。

生き残った各アイデアを、次の 3 つの落とし所のいずれかに分類し、どれを選んだかを告げます。

既存の項目と重なる → 重複させず、その項目を拡充します。
新規で範囲が定まっている → 新しい項目を起草します。
まだ形になっていない → 後で昇格させるため、Unsorted ideas の下に箇条書きを残します。

手順 A3 — 仮の ID で項目を起草する¶

アイデアが「新規で範囲が定まっている」に落ち着くと、スキルはファイルの雛形を作ります。

make new-roadmap-item SLUG=retry-flaky-step TITLE="Bounded retry for transiently-blocked steps"

これで roadmaps/BE-XXXX-retry-flaky-step/ が、正式な Swift-Evolution 形式の両言語ファイルとともに作られます。スキルは TBD の各節（Introduction、Motivation、MECE な Detailed design、Alternatives considered）を埋め、日本語側を自然な日本語に書き直します。

BE-XXXX というリテラルは意図したものです。番号を手で選ぶことは決してありません。 ID は恒久的かつ単調で、多数のブランチが同時に進行しているため、手で番号を選ぶと 2 つの PR が同じ番号を奪い合います。CI がマージ時に割り当てます（手順 A5）。

手順 A4 — 検証し、提案 PR を開く¶

docs だけの変更でも、ゲートは green のままです。

make check

続いてブランチを push し、PR を開きます。提案 PR は純粋にドキュメントなので、working agreement に従い、Draft ではなく Ready for review で、steering-committee チームを reviewer にして開きます。

gh pr create --reviewer bajutsu-e2e/steering-committee \
  --title "docs(roadmap): propose bounded retry for transiently-blocked steps" \
  --body "…"

タイトルに [BE-NNNN] の接頭辞が 付かない ことに注意してください。ID はまだ存在しないからです。ロードマップ項目を 導入する PR は、scoped なタイトルのままにします。

/ideation はこの PR を自動では開きません。 提案は人間のチェックポイントなので、起草スキルはブランチの push で止まります。PR を開くのはあなた（人間）です。これは /implement-be の逆です。あちらの出力は常にゲートが green なコードなので、/implement-be は自分で PR を開きます（手順 B5）。

手順 A5 — CI が実際の `BE-NNNN` を割り当て、マージする¶

PR が開くと、roadmap-id ワークフローが scripts/allocate_roadmap_ids.py を走らせます。次の空き ID をアトミックに確保し、BE-XXXX を BE-NNNN に すべての箇所 で（ディレクトリ、両ファイル、相互リンク）書き換え、結果をあなたのブランチに push し戻します。そのコミットを pull してください。レビューが済んで提案がマージされると、項目は恒久的なパスに Status: Proposal で存在し、番号は確定します。この番号がパート B の入力になります。

実例：曖昧なアイデアが、範囲の定まった提案になる¶

「十分に範囲が定まっている」を学ぶ最速の方法は、弱いアイデアとその作り直した形を並べて見ることです。これが、手順 A1 の一文に対して /ideation の問いがすることです。

❌ 変更前。詳細を欠いた一文：

「flaky な手順にリトライを足す」

なぜレビュアーがこれを扱えず、なぜプライムディレクティブに触れるのか。

上限がない。 「リトライ」を何回でしょうか。無条件のリトライループは、flakiness を表に出さずに隠します。これは determinism first に反します。3 回目でようやく通る手順は、塗りつぶすべきノイズではなく、本物の信号だからです。
契機がない。 どの条件でリトライするのでしょうか。あらゆる失敗か、それとも一過性で自然に解消する blocker のときだけか。両者はまったく別の機能です。
機械可読な成果がない。 動くことを証明するために、決定的なテストが何を assert するのか。書かれていません。

✅ 変更後。/ideation が導く形：

一過性に blocked された手順への上限付きリトライ。 手順が 既知で自然に解消する blocker が存在したために 失敗したとき（たとえば on_blocked が閉じるシステムアラートなど）、blocker が解消したあとに手順を ちょうど 1 回だけ リトライします。「通るまで試し続ける」ループには決してしません。Tier： 決定的な実行ループ。機械可読な成果： fake ドライバを使う単体テストで、解消可能な blocker とともに手順を一度失敗させ、次に成功させると、実行がちょうど 2 回の試行で通ることを assert します。ほかのあらゆる理由で失敗した手順は即座に失敗することを、2 つめのテストで assert します。プライムディレクティブの点検： リトライは条件で制御され上限があるので決定的なままです。flakiness を隠さず、名前の付いた 一過性の状態から回復します。 run の経路に LLM はありません。

作り直した版は、その範囲、触れる tier、それを証明する正確な assertion、そしてディレクティブと抱えていた緊張とその解消の仕方を明示します。これが /implement-be に手渡せる仕様です。（実のところ、これは実行ループの実在する「on_blocked が blocker を解消したあとに 1 回リトライする」挙動の上限の付け方に、おおよそ対応します。）

実在するマージ済みの項目で「良い」がどう見えるか。クリックして辿ってください。

BE-0214 — Web-only beginner tutorial は docs 型 の項目です。Detailed design を読むと、ドキュメントの変更でも MECE なチェックリストに分解されていることがわかります。Implementing PR のリンクを辿れば実際の diff に届きます。
BE-0017 — MCP server は コード型 の項目です。 Detailed design が追加する surface を列挙し、その PR（[BE-0017] feat(mcp): add MCP server）が、タイトルの規約と項目から PR への逆リンクを実地で示します。

マージ済みの項目の提案、その Progress の記録、リンク先の PR を読むことが、自分の提案を開く前にそれを較正する、もっとも確実な方法です。

パート B — `/implement-be` で出荷する¶

提案はマージされ、実際の ID を持つようになりました。仮に BE-0300 としましょう。提案の Detailed design が仕様であり、判定するのは決定的なゲートで、LLM ではありません。

手順 B1 — スキルを起動する¶

/implement-be BE-0300

完全な ID、単なる番号（300）、slug の一部を受け付けます。まず項目を あなたに説明し返します。ID、タイトル、平易な言葉での要約、現在の状態です。それから、Proposal を実装することはそれを受理することだと述べます。この PR が項目を Implemented に切り替えます。

手順 B2 — トラッキング issue を確保する¶

すべての open な項目には、roadmap-tracking ラベルの付いた GitHub のトラッキング issue があります。スキルは誰がアサインされているかを確認します。すでに他の人が持っていれば、その作業と衝突せず 停止して あなたに伝えます。空いていれば（またはすでにあなたのものであれば）自分をアサインして続けます。これが、並行するセッションが所有権を伝え合う仕組みです。

手順 B3 — 下調べし、計画し、コードを書く前に確認する¶

Detailed design と Alternatives considered を読みます（後者は、すでに却下された道筋を、しばしばディレクティブ上の理由とともに記録しているので、再提案しません）。提案がリンクするすべてのファイルを開き、前提となる項目がそれ自身まだ提案のままでないかを確認します。それから、ロードマップ項目全体は大きく元に戻しにくいので、具体的な計画を提示してあなたの了承を待ちます。触れるファイル、動くことを証明する機械可読な成果（そして AI が座ってよい場所とよくない場所）、テスト、両言語で移すべきドキュメント、プライムディレクティブとの緊張です。1 行のコードも書く前に、あなたが確認します。

手順 B4 — 実装し、レビューし、項目を切り替え、ゲートを走らせる¶

実装はコードベースの流儀に合わせます。厳格な mypy、設定された ruff、sleep ではなく条件待ち、新しいつまみは targets.<name> の設定に、そして挙動の変更には回帰ネットとしてのテストです。組み込みの simplify と code-review スキル（判定せず助言する起草の補助）で diff を洗練し、両言語ファイルで項目を Status: Implemented に切り替え、Implementing PR の行を足し、make roadmap-index で索引を再生成します。それからゲートです。

make check   # green でなければならない。red を push しない

手順 B5 — 自分で PR を開く。あなたがマージする¶

/ideation と違い、/implement-be は 自分で PR を開きます。その出力は常に、それ自体で完結しゲートが green な変更なので、待つものがないからです。PR は既定で Draft で、ID をタイトルに付け（[BE-0300] feat(run): bounded retry for transiently-blocked steps）、テンプレートに沿った十分な本文を持ちます。（docs だけ の項目は例外で、提案 PR と同じく steering-committee を reviewer に Ready で開きます。）

そこからは、CI の修正やレビューコメントへの返信という機械的な残務を、一定のペースの follow-up ループが進めます。ただし Draft の PR を ready にする（gh pr ready）のもマージするのも、人間だけ です。そのサインオフは意図的にあなたのものです。マージされると項目は出荷され、その Implementing PR の行は、それを出荷した PR を指します。

`propose-and-build` に手を伸ばすとき¶

上のパート A とパート B が 直列の経路 です。提案し、マージし、割り当て、実装します。これが既定なのは、コードを書く前に設計をレビューに通させ、出荷される項目にだけ番号を費やすことで BE-NNNN の並びを連続させるからです。

小さく範囲が定まっていて、レビューが設計を作り直すとは思えない項目 では、直列の経路の遅延、つまり「提案を開いた」から「ID が割り当てられた」までの空き時間は、純粋なオーバーヘッドです。それに応えるのが propose-and-build です。

/propose-and-build

同じ 2 つのスキルを組み合わせますが、起草と実装を 並行して 走らせ、一時的な 2 段の PR スタックにします。提案 PR が先で、実装 PR がその上に積まれます。コントリビューターであるあなたから見ると、受け渡しはこう見えます。

2 つのブランチで、提案の起草と実装の構築を同時に進めます。
提案 PR がマージされ、CI が実際の BE-NNNN を割り当てます。手順 A5 とまったく同じです。
スキルが 実装ブランチを rebase し、その BE-XXXX 参照を割り当て済みの BE-NNNN に書き換え、main に retarget し、/implement-be の昇格とゲートの手順を走らせます。こうしてスタックは、ふつうの implement-be 型の PR に畳まれます。

先ほどの実例で言えば、もし「一過性に blocked された手順への上限付きリトライ」が十分に小さく固まっていて、レビューが作り直さないと確信できる設計だったなら、マージを待たずに実装を提案の上に積めたでしょう。代償は現実にあります。レビューが 実際に 提案を変えたら、実装ブランチをやり直します。ですから経験則は単純です。

既定は直列です。設計が固まっていると確信できるときだけ propose-and-build に手を伸ばします。 設計が本当に不確かなときは、直列の経路の「コードの前にレビュー」はオーバーヘッドではなく利点です。

このスキル自体の仕組みは BE-0216 に記されています。この節は、コントリビューターの席から見たいつです。

次に読むもの¶

これで貢献のループ全体、つまりアイデアから /ideation、マージ済みの提案、/implement-be、マージ済みの PR まで辿れ、/propose-and-build でそれを畳むときもわかりました。リファレンスの各ページが、それぞれを深く扱います。

roadmap-workflow：2 つのスキルのループの考え方の概観と、なぜ起草と出荷を分けるのか。
ai-development：運用規則の全文。ゲート、一トピック一ブランチ、pre-push フック、worktree、厳格な BE ID のライフサイクル、モデルの階層、PR のタイトルと本文のテンプレート。
CONTRIBUTING.md：人間のコントリビューターの入口と、環境の準備。
roadmaps/README：すべての BE 項目の索引と、埋めていく項目ごとの提案形式。
CLAUDE.md：working agreement と、あらゆる変更が守る 3 つのプライムディレクティブ。