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

これは白紙ではなく 相談相手 です。何かを提案する前に、 roadmaps/README-ja.md（すでにスコープ外のもの、未整理のアイデア）、実装状況の表（すでに出荷済みのものを「提案」しないため）、そしてあなたの主題の近くにある 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 を開く¶

コミットする前に、CI の「Claude review」ワークフローをローカルで再現します。この起草の会話を見ていない新規サブエージェントに、CI のレビュアーが起草の経緯を知らない状態からレビューするのと同じ条件で、 .github/claude-review-prompt.md の契約をステージ済みの差分に適用させ、見つかった指摘をすべて直します。誤検知や説明済みのトレードオフは理由を書き添えて見送り、設計そのものに関わる指摘は直そうとせずユーザーにエスカレーションします。3 回繰り返しても収束しない場合も、ユーザーに判断を仰ぎます。手順の詳細は ideation の手順 5 を参照してください。

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 が `main` 上で実際の `BE-NNNN` を割り当てる¶

レビューが済んだら、BE-XXXX のまま PR をマージします。割り当てが起きるのは PR が開いたときではなく、マージした後です。roadmap-id ワークフローは main への push をトリガーとして走り、main 自身のツリーに対して scripts/allocate_roadmap_ids.py を実行します。マージした順番で次の空き ID を確保し、BE-XXXX を BE-NNNN に すべての箇所 で（ディレクトリ、両ファイル、相互リンク）書き換えて、結果を main に直接コミットし、マージ済みの PR に割り当てた ID を知らせるコメントを付けます（BE-0089）。これで項目は恒久的なパスに 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 スキルと、.github/claude-review-prompt.md の契約に照らしたレビュー（判定せず助言する起草の補助）で差分を洗練します。更新した差分に契約を再度当てる作業は、指摘がなくなるまで繰り返します。手順 A4 と同じく 3 回を上限とし、それでも実際の指摘が残る場合は、PR を開かずユーザーに判断を仰ぎます。そこで初めて両言語ファイルで項目を Status: Implemented に切り替え、Implementing PR の行を足します。ダッシュボードがそのメタデータから新しい状態を直接読み取るので、ほかに再生成するものはありません。それからゲートです。

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 つのスキルを組み合わせますが、起草と実装を 1 つのブランチ で進め、ロードマップ項目とコードとテストをまとめて運ぶ 1 つの BE 作成 PR として出します。コントリビューターであるあなたから見ると、こう見えます。

同じブランチで、提案の起草と実装の構築を進めます。項目は BE-XXXX のプレースホルダを保ったまま PR のなかで Status: Implemented に到達します。Status と PR 番号は、まだ採番されていない id に依存しないためです。
PR を 1 つ開きます。プレーンな scoped タイトルの BE 作成 PR で、[BE-NNNN] の接頭辞は付けません。
人がマージすると、CI が実際の BE-NNNN を割り当てます。手順 A5 とまったく同じで、項目ディレクトリを rename し、項目自身のファイルのなかで BE-XXXX を BE-NNNN に書き換えます。項目はマージ後の手直しなしに、採番されて Implemented の状態で着地します。

守るべき唯一の規則は、BE-XXXX のプレースホルダを項目自身のファイル以外のどこにも書かないことです。採番はそのディレクトリだけを書き換えるので、コードやコメントに書いた id は main に古いまま残ります。先ほどの実例で言えば、もし「一過性に blocked された手順への上限付きリトライ」が十分に小さく固まっていて、レビューが作り直さないと確信できる設計だったなら、マージを待たずに 1 つの PR で提案と実装をまとめて出せたでしょう。代償は現実にあります。 1 つの PR は設計のチェックポイントをコードレビューと一体にするので、レビューが 実際に 提案を変えたら、同じ PR のなかでコードをやり直します。ですから経験則は単純です。

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

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

次に読むもの¶

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

roadmap-workflow：2 つのスキルのループの考え方の概観と、なぜ起草と出荷を分けるのか。
ai-development：運用規則の全文。ゲート、一トピック一ブランチ、pre-push フック、worktree、厳格な BE ID のライフサイクル、モデルの階層、PR のタイトルと本文のテンプレート。
CONTRIBUTING.md：人間のコントリビューターの入口と、環境の準備。
roadmaps/README：ロードマップ項目の追加方法、すでにスコープ外のもの、 BE 番号を待つ未整理のアイデア。
CLAUDE.md：working agreement と、あらゆる変更が守る 3 つのプライムディレクティブ。