ガイド

チームでの Rasen

他のガイドで説明している内容は、1人で使う場合でも20人のチームで使う場合でも同じように機能します。チームで変わってくるのは、その周辺にある問いです。スペックはどこに置くのか、チームメンバーはどうやってプランをレビューするのか、そしてこれは既存のプルリクエストフローにどう馴染むのか、といった点です。

答えを先に言うと、変更（change）はただのファイルであり、rasen は git に一切触れません。だからこそ、既存のワークフローを置き換えるのではなく、そこに馴染みます。このページでは、うまく機能する運用ルールをまとめます。

1つのルール：rasen は git に触れない

Rasen は rasen/ 以下のプレーンな Markdown を読み書きするだけです。プロジェクト内でコミット、ブランチ作成、push、pull を行うことは一切なく、store を自分から clone したり同期したりすることもありません。つまり：

rasen/ はソースコードと同じようにコミットします。 スペック、進行中の変更、アーカイブはすべてプロジェクトの履歴の一部です（そう、フォルダごとコミットしてください — 詳しくは FAQ を参照）。
1つの変更は、コードと同じようにバージョン管理するフォルダです。 rasen/changes/add-dark-mode/ は、ブランチ上のただのファイル群にすぎません。
以下はすべて運用ルールであり、強制ではありません。 Rasen がこのやり方を押し付けてくることはありません。ただ、自然に馴染むというだけです。

日々のループ

うまく機能するワークフローは、1つの変更を1つのブランチと1つのプルリクエストに対応させます。

git switch -c add-dark-mode        start a branch, as usual
   │
/rasen:propose add-dark-mode        draft the plan (proposal + specs + tasks)
   │
REVIEW THE PLAN                    you read it before any code — see Reviewing a Change
   │
/rasen:apply                        build it; artifacts + code change together
   │
git commit && open a PR            the PR contains the spec delta AND the code
   │
teammate reviews, merges
   │
/rasen:archive                      fold the delta into specs/, move the change to archive/

プランとコードは同じブランチ上に並んで存在するので、チームメンバーは両方を一緒にレビューできますし、半年後にアーカイブされたスペックを見れば、なぜコードがそういう形になっているのかがまだ説明されています。

プルリクエストでスペックをレビューする

ここが、チームがその見返りを実感する場所です。PR に変更のデルタ仕様（delta spec）が含まれていると、レビュアーは生の diff からは決して得られないもの——この変更が何をすべきかを平易な言葉で述べた文章——を、コードを1行読む前に手に入れられます。

レビュアーにとって良いレビュー順序はこうです。

proposal.md を読む — これは正しい課題であり、正しいスコープか？
specs/ 下の差分を読む — 「完了」の定義は正しいか？（これは Reviewing a Change にある2分間のチェックが、そのまま PR の中で行われている形です。）
その後でコードの diff を読む — それらの要件を正確に満たしているか？

アプローチそのものに異論があるレビュアーは、300行のコードを巡って蒸し返すのではなく、提案（proposal）に対して安価に意見を言えます。デルタ仕様を PR の説明の冒頭近くに置くか、レビュアーを変更フォルダに案内して、まずそこから読んでもらうようにしましょう。

いつアーカイブするか

アーカイブは、変更の差分をメインの rasen/specs/ に取り込み、変更フォルダを rasen/changes/archive/YYYY-MM-DD-<name>/ に移動する操作です。specs/ はチームで共有される唯一の事実源であるため、チームではそのタイミングが重要になります。使いやすい運用ルールは2つあります。

PR がマージされた後にアーカイブする（推奨）。 ブランチは進行中の変更を保持し、それがメインブランチにマージされたらそこでアーカイブします（小さなフォローアップコミットや定期的なクリーンアップとして行うことが多いです）。こうすることで、共有される specs/ は実際に出荷された作業だけで前進し続けます。
PR の中でアーカイブする。 小規模チームにはこちらの方がシンプルです。コードを追加するのと同じ PR で、同期とアーカイブも行います。トレードオフとして、specs/ の差分とコードの差分が一緒に現れるため、PR がやや読みにくくなることがあります。

どちらか一方を選び、一貫して使いましょう。いずれの方法でも、/rasen:archive はタスクが完了しているかを確認し、先に同期するかどうかを尋ねてくれるので、誤って中途半端な状態のままマージされることはありません。

2人で並行して変更する

変更はそれぞれ独立したフォルダなので、互いに衝突しません。

異なる変更を異なる人が担当する場合は問題ありません。 add-dark-mode と rate-limit-login は、異なるブランチ上の異なるフォルダであり、どちらもアーカイブされるまでは互いに触れ合うことがありません。
1つの変更には1人の所有者を置きます。 2人が同じ変更フォルダを編集すると、2人が同じファイルを編集するのとまったく同じように衝突します。変更は1人の作者に限定するか、2つの変更に分割してください（これも変更を適切なサイズに保つべき理由の1つです）。
衝突が起きる唯一の場所は specs/ です。 2つの変更が同じ要件を変更している場合、後からアーカイブする方が rasen/specs/…/spec.md で衝突します。これは通常のマージコンフリクトと同じように解決し、実態を反映している方の要件を残してください。これは稀なケースであり、むしろ良い機能です。つまり、2つの変更がシステムの振る舞いについて食い違っていたことを、git が教えてくれているのです。

プランニングが1つのリポジトリを超えるとき

ここまでの内容はすべて、プランがコードリポジトリ自身の rasen/ フォルダにあることを前提としており、それが正しいデフォルトです。プランニングが本当に複数のリポジトリやチームにまたがる場合——1つの機能が3つのサービスにまたがる、あるいは1つのチームが所有する要件を他のチームが利用する場合——そのために、ベータ版のstore機能があります。プランニング自体が独自のリポジトリを持ち、どのコードリポジトリからもそこを参照できるようになります。まずは Stores User Guide から始めてください。

次に読むべきもの

Reviewing a Change — レビューの手順が、そのまま PR の中に収まります。
Writing Good Specs — 変更を1つのブランチに収まるサイズにする方法も含みます。
Stores User Guide — リポジトリとチームをまたぐプランニング。