OpenSpec

スキーマ ​

OpenSpec が生成する内容を変更します。アーティファクト、その順序、テンプレートです。

スキーマは、変更提案が何を生成するか（どのアーティファクトを、どの順序で、どのテンプレートから生成するか）を定義します。たとえば、デフォルトで同梱されるスキーマである spec-driven は、おおよそ次の順序で 4 つのアーティファクトを生成し、それぞれが前の成果物を基に構築されます。

proposal → specs → design → tasks

これらの成果物を別のドキュメントにしたい場合、つまり数を減らしたい、名前を変えたい、構造を変えたい場合は、スキーマをフォークします。

スキーマの保存場所 ​

OpenSpec はスキーマを 3 つの場所で順番に探し、最初に見つかったものを使用します。

  1. プロジェクト内: openspec/schemas/。リポジトリにコミットしておけば、チーム全員が利用できます。
  2. マシン上: macOS と Linux では ~/.local/share/openspec/schemas（$XDG_DATA_HOME を設定している場合はその配下）、Windows では %LOCALAPPDATA%\openspec\schemas。ここにあるスキーマは、作業するすべてのプロジェクトで利用できます。
  3. パッケージ内: spec-driven などの組み込みスキーマは、openspec 自体に同梱されています。

同じ名前のスキーマが複数の場所に存在する場合、より具体的な場所のものが優先されます。openspec schema which を使うと、どのコピーが使用されているかを確認できます。

$ openspec schema which spec-driven
Schema: spec-driven
Source: project
Path: /your-project/openspec/schemas/spec-driven

Shadows:
  package: .../openspec/schemas/spec-driven

スキーマの構成 ​

スキーマは、プレーンなファイルを格納したフォルダで定義されます。アーティファクトを宣言する 1 つの schema.yaml と、各アーティファクト用のテンプレートです。組み込みの spec-driven は次のとおりです。

spec-driven/
├── schema.yaml
└── templates/
    ├── proposal.md
    ├── spec.md
    ├── design.md
    └── tasks.md
  • schema.yaml: 各アーティファクトについて、生成するファイル、開始点となるテンプレート、最初に必要な依存関係、作成時にエージェントが受け取る指示を宣言します。各フィールドの仕様は schema.yaml に記載されています。
  • templates/: アーティファクトごとに 1 つの Markdown スケルトンがあり、エージェントがそれを埋めます。

schema.yaml における tasks アーティファクトのエントリを抜粋すると、次のようになります。

yaml
artifacts:
  - id: tasks
    generates: tasks.md
    description: Implementation checklist with trackable tasks
    template: tasks.md
    instruction: |
      ...what the agent is told when creating tasks.md...
    requires:
      - specs
      - design

組み込みスキーマは openspec パッケージ内に同梱されているため、その場で編集することはありません。フォークすることで独自のコピーを取得できます。

独自のカスタムスキーマを作成する ​

独自のスキーマを取得する方法は 2 つあります。

  1. 既存のスキーマをフォークしてコピーを編集します。既存のスキーマが目的に近い場合は、ここから始めてください。そのスキーマ内のすべてがすでに動作しているからです。
  2. どれも合わない場合はゼロから開始し、openspec schema init で空のスキーマをスキャフォールドします。

既存のスキーマをフォークする ​

  1. プロジェクトルートで、開始点にしたいスキーマをフォークします。

    console
    $ openspec schema fork spec-driven

Note: Schema commands are experimental and may change.
✔ Forked 'spec-driven' to 'spec-driven-custom'

Source: .../openspec/schemas/spec-driven (package)
Destination: /your-project/openspec/schemas/spec-driven-custom

    2 番目の引数を渡して名前を指定します（openspec schema fork spec-driven team-flow）。名前はケバブケースです。

  2. コピーを編集します。schema.yaml とテンプレートです。変更内容についてはフォークの編集で説明します。

  3. 検証します。

    bash
    openspec schema validate spec-driven-custom

    これは、変更の途中で問題に直面する前に、壊れたスキーマ（テンプレートの欠落、不正な YAML、依存関係の循環）を検出できる唯一のコマンドです。

  4. openspec/config.yaml でプロジェクトが使用するスキーマを指定します。フォークは config.yaml を変更しないため、この手順は自分で行う必要があります。

    yaml
    schema: spec-driven-custom

  5. 新しい変更提案は、今後このスキーマに従います。以前に作成された変更は、開始時に使用したスキーマを保持します。

config.yaml を変更せずにすべてのプロジェクトでデフォルトを置き換えるには、同じ名前でフォークします: openspec schema fork spec-driven spec-driven。すると、スキーマの保存場所で説明されているとおり、プロジェクトのコピーが組み込みスキーマより優先されます。

ゼロから開始する ​

openspec schema init は既存のスキーマをコピーするのではなく、新しいスキーマをスキャフォールドします。

console
$ openspec schema init lite --description "Lite flow" --artifacts proposal,tasks

✔ Created schema 'lite'
Schema created at: /your-project/openspec/schemas/lite
Artifacts: proposal, tasks

スキャフォールドされる内容は最小限です。アーティファクトは組み込みの 4 つの ID からのみ選択でき、生成されるテンプレートには指示が含まれないため、独自の指示を書くまでエージェントが受け取るガイダンスは少なくなります。以降はフォークの手順がそのまま当てはまります。検証してから、config.yaml で指定してください。

フォークの編集 ​

フォークには、編集すべき 2 種類のファイルがあります。

  • templates/ は各ドキュメントのスケルトンを変更します。tasks テンプレートにセクションを追加すると、新しい tasks.md はすべてそのセクションで始まります。1 行目の # タイトルは残してください。アーティファクトはそれを継承するため、生成されるすべてのファイルはタイトル付きのドキュメントとして始まります。
  • schema.yaml はワークフロー自体を変更します。どのアーティファクトが存在するか、各アーティファクトが最初に何を必要とするか、作成時にエージェントが受け取る指示を定義します。

たとえば、より簡潔なフローのために design ドキュメントを削除するには、次のようにします。

  1. schema.yaml から design エントリを削除します。

  2. tasks の requires リストから design を削除します。

  3. 検証します。

    console
    $ openspec schema validate spec-driven-custom

✓ Schema 'spec-driven-custom' is valid

手順 2 を省略すると、検証で検出されます。

console
✗ Schema 'spec-driven-custom' has errors:
  error: Invalid dependency reference in artifact 'tasks': 'design' does not exist

手動で編集するたびに検証してください。そうしないと、壊れたスキーマは変更の途中、ワークフローが存在しないファイルを要求したときに表面化します。config.yaml と同様、スキーマの編集は次回の実行時にエージェントへ反映されます。

フォークはスナップショット ​

openspec update はインストール済みのスキルとコマンドを更新しますが、openspec/schemas/ には一切触れません。フォークは、あなたが残した状態のまま正確に動作し続けます。これは、組み込みスキーマが進化しても改善を受け取らなくなることも意味します。後からそれらの改善を取り込むには、組み込みスキーマを新しい名前で再度フォークし、差分を移植してください。

スキーマの共有 ​

スキーマを共有するとは、そのフォルダをコピーすることです。

  • チーム内: openspec/schemas/ をコミットすれば、リポジトリの全員が利用できます。
  • プロジェクト間: スキーマの保存場所で示したユーザーレベルのディレクトリにフォルダを置きます。
  • コミュニティから: コミュニティカタログには共有スキーマが一覧されています。1 つを openspec/schemas/<name> にコピーすれば、自分のスキーマと同様に動作します。

現在、パブリックおよびプライベートのスキーマレジストリを開発中です。これにより、スキーマを手動でコピーする代わりに名前でインストールできるようになります。

OpenSpec と Superpowers を組み合わせて使用する ​

コミュニティでメンテナンスされている superpowers-bridge スキーマは、OpenSpec のアーティファクトを Superpowers の実行スキルに接続します。プロジェクトにコピーする前に、ブリッジのインストールと互換性に関する注意事項に従ってください。

ブリッジは OpenSpec の外部でリリースされています。OpenSpec は Superpowers 統合のテストやバージョン管理を行いません。