English · 日本語
コントリビューターワークフローチュートリアル¶
Bajutsu に 貢献する ための、手を動かしながら進めるチュートリアルです。読み終えるころには、一つの アイデアを大まかな一文から
/ideationに通してマージ済みの提案にし終えています。CI がその恒久的なBE-NNNNを割り当てる様子も確認し、/implement-beでマージ済みのプルリクエストまで出荷し終えている はずです。getting-started チュートリアルは Bajutsu を 動かす ためのもので、 このページは Bajutsu を 作る ための対応物です。リファレンスの各ページは個々の規則の内容を説明します。 このページは、順を追って実際に手を動かしてもらいます。
関連:roadmap-workflow · ai-development · CONTRIBUTING.md · roadmaps/README
このページで扱わないこと。 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」ワークフローをローカルで再現します。PR で指摘されるのを
待たずに済ませます。新規サブエージェントが、.github/claude-review-prompt.md
の契約をステージ済みの差分に適用します。このサブエージェントは起草の会話を見ていません。CI のレビュアーが
起草の経緯を知らない状態からレビューするのと同じ条件です。見つかった指摘はすべて直しますが、例外が
2 つあります。
- 誤検知や説明済みのトレードオフは、理由を書き添えて見送ります。
- 設計そのものに関わる指摘は、直そうとせずユーザーにエスカレーションします。
レビューは最大 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はその逆で、自分で PR を開きます (手順 B5)。出力が常にゲート green のコードだからです。
手順 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: Approved で存在するようになり、番号が確定します。この番号がパート B の
入力になります。
実例:曖昧なアイデアが、範囲の定まった提案になる¶
「十分に範囲が定まっている」を学ぶ最速の方法は、弱いアイデアとその作り直した形を並べて見ることです。
この比較は、手順 A1 の一文に対して /ideation の問いが何をするかを示します。
❌ 変更前。詳細を欠いた一文:
「flaky な手順にリトライを足す」
レビュアーはこの一文を扱えず、一文はプライムディレクティブにも触れます。理由は 3 つの欠落にあります。
- 上限がない。 「リトライ」を何回でしょうか。無条件のリトライループは、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、タイトル、平易な言葉での要約、現在の状態です。それから、項目がすでに審査のゲートを通過した
マージ(2人承認、または single-approver proposal の免除下では1人承認)の時点で受理されていると述べます。
そのため、実装は項目に 着手する ことを意味し、この PR が項目を Implemented に切り替えます。
手順 B2:トラッキング issue を確保する¶
すべての open な項目には、roadmap-tracking ラベルの付いた GitHub のトラッキング issue があります。スキルは
誰がアサインされているかを確認します。すでに他の人が持っていれば、その作業と衝突せず 停止して あなたに
伝えます。空いていれば(またはすでにあなたのものであれば)自分をアサインして続けます。これが、並行する
セッションが所有権を伝え合う仕組みです。
手順 B3:下調べし、計画し、コードを書く前に確認する¶
スキルは Detailed design と Alternatives considered を読みます。後者は、すでに却下された道筋を、しばしば
ディレクティブ上の理由とともに記録しているので、再提案しません。提案がリンクするすべてのファイルを開き、
前提となる項目がそれ自身まだ提案のままでないかを確認します。
ロードマップ項目全体は大きく、元に戻しにくい作業です。そこでスキルは、具体的な計画を提示してあなたの 了承を待ちます。計画に含めるのは次の項目です。
- 触れるファイル
- 動くことを証明する機械可読な成果と、AI が座ってよい場所とよくない場所
- テスト
- 両言語で移すべきドキュメント
- プライムディレクティブとの緊張
1 行のコードも書く前に、あなたが確認します。
手順 B4:実装し、レビューし、項目を切り替え、ゲートを走らせる¶
実装はコードベースの流儀に合わせます。厳格な mypy、設定された ruff、sleep ではなく条件待ち、新しい
つまみは targets.<name> の設定に置きます。挙動を変えるときは、回帰ネットとしてテストを付けます。
続いてスキルは、判定せず助言する 2 つの起草の補助で差分を洗練します。組み込みの 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 が 直列の経路 です。提案し、マージし、割り当て、実装します。直列の経路が既定
なのは、理由が 2 つあるからです。コードを書く 前に 設計をレビューに通させます。また、出荷される項目にだけ
番号を費やすので、BE-NNNN の並びが連続します。
小さく範囲が定まっていて、レビューが設計を作り直すとは思えない項目 を考えます。この種の項目では、
直列の経路の遅延は純粋なオーバーヘッドです。遅延とは「提案を開いた」から「ID が割り当てられた」までの
空き時間です。この場面のためにあるのが
propose-and-build スキルです。
/propose-and-build
このスキルは、同じ 2 つのスキルを組み合わせます。起草と実装を 1 つのブランチ で進め、両方を 1 つの BE 作成 PR として出します。この PR は、ロードマップ項目とコードとテストをまとめて運びます。コントリビューター であるあなたから見ると、流れは次のとおりです。
- 同じブランチで、提案の起草と実装の構築を進めます。項目は
BE-XXXXのプレースホルダを保ったまま PR のなかでStatus: Implementedに到達します。Statusと PR 番号は、まだ採番されていない id に依存しないためです。 - PR を 1 つ開きます。プレーンな scoped タイトルの BE 作成 PR で、
[BE-NNNN]の接頭辞は付けません。 - 人がマージすると、CI が実際の
BE-NNNNを割り当てます。手順 A5 とまったく同じです。CI は項目ディレクトリを rename し、項目自身のファイルのなかでBE-XXXXをBE-NNNNに書き換えます。項目はマージ後の手直しなしに、 採番されて Implemented の状態で着地します。
守るべき規則が 1 つあります。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 つのプライムディレクティブ。