チームで OpenSpec を使う

他のガイドで説明する内容は、個人でも20人のチームでも同じです。チームで変わるのは周辺の疑問です。仕様をどこに置くか、メンバーが計画をどうレビューするか、既存のプルリクエストの流れにどう組み込むか、といった点です。

簡単に言うと、change は単なるファイル群であり、OpenSpec は git に一切触れません。そのため、既存のワークフローを置き換えるのではなく、そのまま組み込めます。このページでは、うまく機能する慣例を説明します。

原則: OpenSpec は git に触れない

OpenSpec は openspec/ 以下の通常の Markdown ファイルを読み書きします。プロジェクト内でコミット、ブランチ作成、push、pull を行うことはありません。また、独自に store を clone または同期することもありません。つまり:

• 他のソースと同じように openspec/ をコミットする。 仕様、作業中の change、アーカイブはプロジェクトの履歴の一部です。（はい、フォルダー全体をコミットします。FAQを参照。）
• change はコードと同じようにバージョン管理するフォルダー。 openspec/changes/add-dark-mode/ はブランチ上にある単なるファイル群です。
• 以下の内容はすべて慣例であり、強制ではない。 OpenSpec はこのやり方を強要しません。既存の流れに無理なく組み込めます。

日常の作業サイクル

効果的なワークフローでは、change をブランチとプルリクエストに対応させます。

git switch -c add-dark-mode        通常どおりブランチを作成
   │
/opsx:propose add-dark-mode        計画を下書き（proposal + specs + tasks）
   │
計画をレビュー                       コードを書く前に確認 — 「変更のレビュー」を参照
   │
/opsx:apply                        実装。成果物とコードを一緒に変更
   │
git commit && open a PR            PR に仕様の差分とコードを含める
   │
チームメンバーがレビューし、マージ
   │
/opsx:archive                      差分を specs/ に統合し、change を archive/ に移動

計画とコードは同じブランチに並んでいるため、チームメンバーは両方をまとめてレビューできます。6か月後もアーカイブ済みの仕様が、コードがそのような形になった理由を説明します。

プルリクエストで仕様をレビューする

チームではここに大きな効果が表れます。PR に change の差分仕様が含まれていると、レビュアーはコードを1行も読む前に、生の差分だけでは得られない この変更が何を実現するのかという平易な説明 を確認できます。

レビュアーには次の順で確認することを勧めます。

1. proposal.md を読む — 適切な問題と範囲が選ばれているか。
2. specs/ 以下の差分を読む — 完了条件が正しく定義されているか。（これは変更のレビューで紹介する2分間の確認を、PR 内で行うものです。）
3. その後でコードの差分を読む — 要件どおりに実装されているか。

進め方 に異論があるレビュアーは、300行のコードをめぐって議論し直すのではなく、提案に対して低コストで意見できます。差分仕様を PR の説明の上部に置くか、change フォルダーを示して、そこからレビューを始めてもらいましょう。

アーカイブするタイミング

アーカイブすると change の差分がメインの openspec/specs/ に統合され、change フォルダーは openspec/changes/archive/YYYY-MM-DD-<name>/ に移動します。specs/ は共有される真実の情報源なので、チームではタイミングが重要です。実用的な慣例は2つあります。

• PR のマージ後にアーカイブする（推奨）。 ブランチ上で change を管理し、メインブランチへのマージ後にそこでアーカイブします（小さな追加コミットや定期的な整理として行うことが多いです）。実際にリリースされた作業だけが共有 specs/ に反映されます。
• PR 内でアーカイブする。 小規模チームでは、コードを追加する PR で同時に同期とアーカイブを行う方が簡単です。ただし specs/ とコードの差分が同じ PR に含まれるため、PR がやや煩雑になることがあります。

どちらかを選び、一貫して運用してください。いずれの場合も /opsx:archive はタスクの完了を確認し、先に同期するかどうかを提示するため、未完成の内容が誤ってマージされるのを防げます。

2人で変更を並行して進める

change は別々のフォルダーなので、互いに競合しません。

• 別々の人が別々の change を行う — 問題なし。 add-dark-mode と rate-limit-login は異なるブランチの別々のフォルダーです。両方をアーカイブするまでは互いに影響しません。
• 1つの change に担当者は1人。 同じ change フォルダーを2人で編集すると、同じファイルを2人で編集する場合と同様に競合します。担当者を1人にするか、2つの change に分割してください（変更の適切な規模を保つもう1つの理由です）。
• 競合が発生するのは specs/。 2つの change が 同じ 要件を変更した場合、2つ目のアーカイブ時に openspec/specs/…/spec.md で競合が起きます。通常のマージ競合と同様に、現実を反映する要件を残して解決します。これはまれですが、システムの動作に関する意見の不一致を git が知らせてくれるという意味で、有用です。

計画が1つのリポジトリに収まらなくなったら

これまでは、計画をコードリポジトリ内の openspec/ フォルダーに置くことを前提としてきました。これは適切な既定の方法です。計画が実際に複数のリポジトリやチームにまたがる場合（1つの機能が3つのサービスに関係する、あるいは1つのチームが所有する要件を他チームが利用する場合など）は、ベータ版の stores 機能を利用できます。計画専用のリポジトリを用意し、各コードリポジトリから参照できます。Stores ユーザーガイドを参照してください。

次に読むページ

• 変更のレビュー — PR 内で行うレビュー
• 良い仕様を書く — 1つのブランチに収まる change の規模にする方法
• Stores ユーザーガイド — リポジトリやチームをまたぐ計画