OpenSpec

ストア（ベータ） ​

リポジトリをまたぐ計画の変更：1つのストア、複数のリポジトリ。

OpenSpecは通常、1つのリポジトリ内に存在します：計画するコードの隣にある openspec/ フォルダ。ストアはそのフォルダを独自のリポジトリに移動し、複数のコードリポジトリで共有できるようにします。

各マシンでの一度きりのセットアップ後、status、new change、archive などのコマンドは、どのディレクトリからでもストアで機能します。

         team-plans  (a store: OpenSpec in its own repo)
         ├── .openspec-store/store.yaml   the store's name
         └── openspec/
             ├── specs/
             └── changes/
                   ▲
                   │ set up once on each machine,
                   │ shared by pushing and cloning like any repo
     ┌─────────────┼─────────────┐
     │             │             │
 web-app       api-server     mobile-app
(code repo)   (code repo)    (code repo)

ストアはgitで共有し、コードを共有するのと同じ方法で管理します：コミット、プッシュ、プル、そして自分でレビューします。仕様と変更もコードと同じようにブランチとプルリクエストを得ます。

ストアが必要なケース ​

ストアを使用する2つの一般的な理由：

  • フロントエンドとバックエンドが別々のリポジトリにある場合：1つの機能が両方に影響し、計画は2つの断片ではなく1つの場所を必要とします。

          shop-plans  (store)
      └── openspec/changes/add-discounts/    one plan for the feature
                ▲
      ┌─────────┴─────────┐
      │                   │
  storefront             api
(frontend repo)     (backend repo)

  • 1つの製品、複数のクライアントリポジトリ：Android、iOS、Webがそれぞれのリポジトリからリリースされますが、1つの期待される動作を共有します。仕様は実装ではなく動作を記述するため、1つの仕様が3つすべてに役立ちます。

            product-specs  (store)
        └── openspec/specs/checkout/spec.md    the expected behavior
                  ▲
    ┌─────────────┼─────────────┐
    │             │             │
android-app    ios-app       web-app
(code repo)   (code repo)   (code repo)

複数のストアを持つこともできますが、数は少なく抑えることをお勧めします。

ストアをセットアップする ​

1人がストアを作成し、他の全員がそれに参加します。

  1. ストアを作成する（1人、チームごとに1回）。openspec store setup を実行し、プロンプトに回答します：

    bash
    # run from anywhere; it asks what to create and where
openspec store setup

    3つの質問が表示されます：

    • Store name: team-plans
    • Where should this store live?: ~/openspec/<name> があらかじめ入力されています。Enter キーを押して受け入れるか、別のパスを入力します
    • Create this store?: 作成内容が表示されます。Yes と回答します

    その後、作成された内容が報告されます：

    yaml
    Store ready: team-plans
Location: ~/openspec/team-plans
OpenSpec root: ready
Registry: registered

Next: run normal OpenSpec commands against this store, for example:
  openspec new change <change-id> --store team-plans
Share this store by committing and pushing it like any Git repo.

  2. Git ホストにプッシュする。 まずホスト上に空の team-plans リポジトリを作成します。セットアップでは git リモートが追加されないため、ストアをそのリポジトリに接続してからプッシュします：

    bash
    # connect the store to the empty repo on your git host
cd ~/openspec/team-plans
git remote add origin git@github.com:acme/team-plans.git

# publish it
git push -u origin main

  3. ストアに参加する（チームメイト全員、マシンごとに1回）：

    bash
    # get the store onto your machine
git clone git@github.com:acme/team-plans.git ~/openspec/team-plans

# tell OpenSpec where it lives
openspec store register ~/openspec/team-plans
    yaml
    Store registered: team-plans
Location: /Users/you/openspec/team-plans
OpenSpec root: ready
Registry: registered

    登録すると、マシンがこのストアの場所を認識します。ストアの名前は .openspec-store/store.yaml 内にすでにコミットされています。セットアップ時に作成者のコピーが登録されているため、この手順が必要なのはクローンしたコピーのみです。

  4. 動作確認、任意のディレクトリから：

    bash
    # any OpenSpec command reaches the store by name
openspec status --store team-plans
    yaml
    Using OpenSpec root: team-plans (/Users/you/openspec/team-plans)
No active changes. Create one with: openspec new change <name> --store team-plans

セットアップの種類 ​

OpenSpec には3つのセットアップがあります。このページの残りではこれらの名前を使用します：

  • repo-local: リポジトリ内に OpenSpec があり、ストアはありません。デフォルトです。
  • store-only: リポジトリに独自の spec や change はありません。すべてがストアに存在します。
  • store-optional: プロジェクトに独自の openspec/ フォルダがあり、必要に応じてストアにもアクセスします。

デフォルト: リポジトリ内の OpenSpec（repo-local） ​

openspec init はコードの隣に openspec/ フォルダを作成し、そのリポジトリの spec と change はそこに存在します。ストアは関与しません。これは Set up your project で説明されているセットアップであり、ほとんどのプロジェクトにはこれで十分です。

web-app  (code repo)
└── openspec/
    ├── specs/
    └── changes/

リポジトリの外、ストア内の OpenSpec（store-only） ​

リポジトリに独自の spec や change はありません。計画したすべてはストアに存在し、リポジトリの設定の1行が両者を接続します。

1つのチームがすべてのリポジトリを構築し、1か所で計画する場合に一般的です。上記の例 はすべてこの形式です。

team-plans  (store)
└── openspec/
    ├── specs/       the repo's specs live here
    └── changes/     its changes too
          ▲
          │ store: team-plans   (the connecting line)
web-app  (code repo)
└── openspec/
    └── config.yaml    nothing else

リポジトリ内とストア内の OpenSpec（store-optional） ​

リポジトリは独自の作業のために repo-local のままであり、ストアが共有の spec と change を保持します。リポジトリ内では、OpenSpec はプロジェクトの openspec/ フォルダを使用し、--store を渡したときにのみストアにアクセスします。

ストアが存在する前にリポジトリで OpenSpec を使用していた場合、またはほとんど独立したリポジトリが時折共有作業に触れる場合に一般的です。

team-plans  (store)
└── openspec/          the shared specs and changes
          ▲
          │ only when you pass --store team-plans
web-app  (code repo)
└── openspec/          this repo's own
    ├── config.yaml
    ├── specs/
    └── changes/

リポジトリは repo-local で始まり、後から spec と change をストアに移動できます。リポジトリの spec と change をストアに移動する で方法を説明します。

ストア使用時の成果物の作成場所 ​

ストアを使用する場合、OpenSpec は成果物の作成場所も決定する必要があります。セットアップによって異なります：

  • store-only（プロジェクトがストアにのみ書き込む）: すべての成果物がストアに作成されます。以下の store: 行がそれを記録します。
  • store-optional（プロジェクトに独自の openspec/ フォルダがあり、ストアも使用する）: リクエストでストア名を指定するか、その change に --store を渡さない限り、成果物はプロジェクトに作成されます。エージェントはその後、フラグをワークフローの残りに引き継ぎます。

OpenSpec は成果物を2つの場所のいずれかに書き込みます：プロジェクトの openspec/ フォルダ、またはストアです。以下の順序で選択し、最初に適用されるオプションが優先されます：

  1. コマンドの --store <id>。 常に優先され、任意のディレクトリから有効です。
  2. プロジェクトの openspec/ フォルダ。 プロジェクトに独自の specs/ または changes/ フォルダがある場合、OpenSpec はそれらを使用します。
  3. プロジェクトの store: 行。 store-only プロジェクトがストアを記録する方法です。
  4. マシンの defaultStore。 上記のいずれも適用されない場合のフォールバックです。

これらのいずれも適用されず、登録済みのストアがある場合、コマンドは失敗し、それらを一覧表示します。1つのストアの id が origin リモートのリポジトリ名と一致する場合、エラーはそのストアとそれを選択する store: 行を指定します。OpenSpec は名前でストアを自動的に選択することはありません。これは、異なる組織のリポジトリが同じ名前を共有する可能性があるためです。

OpenSpec がストアを選択すると、コマンド出力の前に Using OpenSpec root: ... を表示します。

store: 行（store-only プロジェクト） ​

プロジェクトの openspec/config.yaml に1行追加します：

yaml
# web-app/openspec/config.yaml
store: team-plans

プロジェクト内で実行するすべてのコマンドが、フラグを入力することなくストアを使用するようになります：

bash
# inside web-app, connected
openspec status
yaml
Using OpenSpec root: team-plans (/Users/you/openspec/team-plans)
No active changes. Create one with: openspec new change <name> --store team-plans
  • 行がない場合: store-only プロジェクトで通常のコマンドを実行すると、OpenSpec は登録済みストアを一覧表示するエラーで停止します。
  • コミットする: プロジェクトをクローンしたチームメイトもその行を取得します。マシンにストアが登録されている必要があります（ストアをセットアップする のステップ3）。登録されていない場合、OpenSpec はエラーを表示し、登録するよう指示します。
  • 実際のフォルダがある場合: プロジェクトに specs/ または changes/ フォルダもある場合、OpenSpec はそれらを使用し、行は警告とともに無視されます。

store-only リポジトリで統合をインストールする ​

コードリポジトリのルートから init を実行し、計画をリポジトリ内に戻すことなく AI ツール統合ファイルをインストールします：

bash
# inside web-app, at the repository root
openspec init --tools claude
  • 統合ファイル: コードリポジトリに書き込まれます。
  • openspec/config.yaml: store: 行を含め、バイト単位で保持されます。
  • openspec/specs/ と openspec/changes/: コードリポジトリには作成されません。

OpenSpec はコードリポジトリのサブディレクトリからこのコマンドの実行を拒否します。リポジトリルートから実行してください。

OpenSpec はここでも --language を拒否します。言語は外部ストアの設定に属するためです。ストアルートで init を実行するか、その設定を直接編集してください。

マシンの defaultStore ​

作業するすべてのプロジェクトが同じストアを使用する場合、一度設定します。OpenSpec はフラグ、ローカルの openspec/ フォルダ、store: 行が見つからない場合に、これをフォールバックとして使用します：

bash
# use team-plans whenever nothing else names a store
openspec config set defaultStore team-plans

# undo it
openspec config unset defaultStore

ローカルに留まるコマンド。 init、update、templates、schemas、および openspec schema サブコマンドは現在のディレクトリにのみ作用し、--store を受け付けません。

リポジトリの spec と change をストアに移動する ​

リポジトリを repo-local から store-only に移行するには：

  1. リポジトリの openspec/specs/ と openspec/changes/ 内のすべてをストアの同じフォルダに移動します。
  2. 空になったフォルダを削除し、リポジトリの openspec/ フォルダに config.yaml のみが残るようにします。
  3. その config.yaml に store: 行を追加します。

リポジトリ内で openspec status を実行すると、Using OpenSpec root: team-plans で始まるようになります。

ストアで作業する ​

ワークフローは、あなたにとってもエージェントにとっても変わりません。Propose、apply、archive はこれまで通り実行されます。違いは成果物の作成場所のみであり、上記のセクション で説明しています。

store-only リポジトリ内から change を作成すると、ストアに配置されます：

bash
# inside web-app; the store: line routes this to team-plans
openspec new change add-login
yaml
Using OpenSpec root: team-plans (/Users/you/openspec/team-plans)
Created change 'add-login' at /Users/you/openspec/team-plans/openspec/changes/add-login/
Schema: spec-driven
Next: openspec status --change add-login --store team-plans
  • 行き先: コードの隣ではなく、ストアリポジトリ内です。
  • 共有する: change はストアリポジトリをコミットしてプッシュするまで、チェックアウトにのみ存在します。チームメイトはプルしたときに確認できます。ワークフローが書き込むすべての成果物についても同様です。
  • ドキュメントのパス: ドキュメントに openspec/ パスが表示されている場合、ストアセットアップではそのフォルダはストアのものです。

成果物が予期しない場所に作成された場合、openspec doctor は設定を変更せずにチェックし、各検出事項に対する修正を表示します：

bash
# check the current root and its stores
openspec doctor
yaml
Doctor

Root
  Location: /Users/you/openspec/team-plans
  OpenSpec root: ok
  Store: team-plans (metadata ok)

References
  (none declared)

openspec context は、チェックなしで同じ状況を確認したい場合に、現在のディレクトリが動作するルートとストアを一覧表示します。

エージェントが両方を読み取れるように、1つのエディタウィンドウでストアとリポジトリを開くには、Worksets (beta) を参照してください。

他のストアから仕様を読み取る ​

リポジトリは自身の openspec/ フォルダを保持したまま、エージェントに別のストアの仕様を読ませることができます。そのストアは、リポジトリの openspec/config.yaml 内の references: で宣言します：

yaml
# api-server/openspec/config.yaml
references:
  - team-plans

参照は読み取り専用です。作業は自身のリポジトリに残り、参照によってエージェントに伝えられる内容だけが変わります。

ワークフローがアーティファクトを作成すると、その指示には参照ストアの仕様のインデックスが追加されます。それぞれに1行の要約と取得のための正確なコマンドが付きます：

xml
<referenced_stores>
<!-- 読み取り専用の上流コンテキスト。必要なものを取得し、使用したものを引用します。 -->
Store team-plans (/Users/you/openspec/team-plans):
  - payments: 課金と返金に関するルール。
  Fetch: openspec show <spec-id> --type spec --store team-plans
</referenced_stores>

参照にはストアのクローンURLを含めることもでき、まだそのストアを持っていないマシン向けです：

yaml
references:
  - team-plans
  - { id: design-system, remote: "git@github.com:acme/design-system.git" }

URL が宣言されていれば、openspec doctor は見つからないストアを貼り付け可能な修正方法に変換します：

yaml
# 出力を折り返し表示
References
  - team-plans: ok (/Users/you/openspec/team-plans)
  - design-system: 参照ストア 'design-system' がこのマシンに登録されていません。
    修正方法: git clone -- git@github.com:acme/design-system.git '/Users/you/openspec/design-system' &&
         openspec store register '/Users/you/openspec/design-system' --id design-system

ベータ版の制限 ​

  • 形は変わる可能性があります: コマンド名、フラグ、ファイル形式はリリース間で変更されることがあります。アップグレード後はこのページを再確認してください。
  • 同期なし、設計上: OpenSpec はクローン、プル、プッシュを一切行いません。古いチェックアウトではプルするまで古い仕様が表示され、参照はディスク上の内容から読み取られます。
  • ストア名ごとに1つのチェックアウト: 既に登録されている名前で2つ目のフォルダを登録しようとすると失敗し、最初に openspec store unregister を実行するように促されます。