チームでのOpenSpec
他のガイドの内容は、個人で作業していても20人のチームで作業していても同じように機能します。チームで変わるのは周辺の質問です：仕様書はどこに保存するか、チームメイトはどのように計画をレビューするか、そしてこれらすべてが既存のプルリクエストフローにどう適合するか？
簡単な答え：変更は単なるファイルであり、OpenSpecはgitに触れることはありません。つまり、既存のワークフローを置き換えるのではなく、それに適合します。このページでは、うまく機能する慣例を説明します。
1つのルール：OpenSpecはgitに触れない
OpenSpecはopenspec/ディレクトリ配下のプレーンマークダウンを読み書きするだけです。プロジェクト内でコミット、ブランチ作成、プッシュ、プルを一切行いません。また、独自にストアをクローンしたり同期したりすることもありません。つまり：
openspec/は他のソースコードと同様にコミットしてください。 仕様書、アクティブな変更、アーカイブはプロジェクトの履歴の一部です。（フォルダ全体をコミットしてください。FAQを参照。）- 変更はコードと同様にバージョン管理するフォルダです。
openspec/changes/add-dark-mode/はブランチ上の単なるファイルです。 - 以下は強制ではなく慣例です。 OpenSpecはこの方法を強制しませんが、きれいに適合します。
日常のワークフロー
うまく機能するワークフローは、変更をブランチとプルリクエストにマッピングします：
git switch -c add-dark-mode ブランチを作成（通常通り）
│
/opsx:propose add-dark-mode 計画をドラフト（提案書 + 仕様書 + タスク）
│
REVIEW THE PLAN コードを書く前に読む — 「変更のレビュー」を参照
│
/opsx:apply 実装；成果物とコード変更を同時に作成
│
git commit && open a PR プルリクエストに仕様差分とコードの両方を含める
│
teammate reviews, merges チームメイトがレビューし、マージ
│
/opsx:archive 差分を仕様書に統合し、変更フォルダをアーカイブに移動計画とコードは同じブランチ内に並んで存在するため、チームメイトは両方を一緒にレビューできます。6ヶ月後にはアーカイブされた仕様書が、コードがそのような形になっている理由を説明してくれます。
プルリクエストでの仕様書レビュー
ここがチームのメリットを実感できる部分です。プルリクエストに変更の差分仕様書が含まれていると、レビュアーは生のdiffでは得られないものを得られます：コードを1行も読む前に、この変更が何を目的としているかを示す平易な言語による説明です。
レビュアーにとって良いレビューの順序：
proposal.mdを読む — これは正しい問題とスコープか？specs/配下の差分を読む — 「完了」の定義は正しいか？（これは変更のレビューの2分間の確認が、プルリクエスト内で行われている状態です。）- 次にコードのdiffを読む — それらの要件を正確に満たしているか？
アプローチに同意できないレビュアーは、300行のコードにわたって再議論するのではなく、提案書に対して安易に意見を述べることができます。差分仕様書をプルリクエスト説明の上部に配置するか、レビュアーを変更フォルダに誘導して、そこから始めるようにしてください。
アーカイブするタイミング
アーカイブは変更の差分をメインのopenspec/specs/に統合し、変更フォルダをopenspec/changes/archive/YYYY-MM-DD-<name>/に移動します。specs/は共有の信頼できる情報源であるため、チームではタイミングが重要です。2つの実用的な慣例：
- プルリクエストマージ後にアーカイブ（推奨）。 ブランチはアクティブな変更を保持します。メインブランチにマージされたら、そこでアーカイブしてください（通常は小さなフォローアップコミットまたは定期クリーンアップ）。これにより、共有の
specs/が実際にリリースされた作業でのみ前進することを保証します。 - プルリクエスト内でアーカイブ。 小規模チームには簡単：コードを追加する同じプルリクエストが同期とアーカイブも行います。トレードオフは、
specs/の差分とコードの差分が同時に landed するため、プルリクエストが煩雑になる可能性があることです。
どちらかを選んで一貫性を保ってください。どちらの場合でも、/opsx:archiveはタスクが完了していることを確認し、最初に同期するかどうかを尋ねるため、誤って未完成のものがマージされることはありません。
2人での並行変更
変更は別々のフォルダであるため、競合しません：
- 異なる変更、異なる人 — 問題なし。
add-dark-modeとrate-limit-loginは異なるブランチ上の異なるフォルダです。両方がアーカイブされるまで互いに触れることはありません。 - 1つの変更、1人の担当者。 同じ変更フォルダを2人が編集すると、同じファイルを2人が編集する場合とまったく同じように競合します。変更は単一の作成者に留めるか、2つの変更に分割してください（適切なサイズに調整するもう1つの理由です）。
- 競合が発生する唯一の場所は
specs/です。 2つの変更が同じ要件を変更した場合、2つ目の変更をアーカイブするとopenspec/specs/…/spec.mdで競合が発生します — 他のマージ競合と同様に解決し、現実を反映する要件を保持してください。これは稀であり、機能です：gitが2つの変更がシステムの動作方法について意見が一致しなかったことを通知しているのです。
計画が1つのリポジトリを超えて拡大する場合
上記のすべては、計画がコードリポジトリ自身のopenspec/フォルダに存在することを前提としています。これはデフォルトとして正しいです。計画が複数のリポジトリやチームにまたがる場合 — 1つの機能が3つのサービスに触れる場合や、あるチームが所有する要件を他のチームが消費する場合 — ベータ版のストア機能がそのためにあります：計画が独自のリポジトリを持ち、任意のコードリポジトリがそれを参照できます。ストアユーザーガイドから始めてください。
次のステップ
- 変更のレビュー — プルリクエスト内で行われるレビュープロセス
- 良い仕様書の書き方 — 1つのブランチに収まるように変更のサイズを適切に調整する方法を含む
- ストアユーザーガイド — リポジトリやチームをまたぐ計画