カスタマイズ

OpenSpec は、3 段階のカスタマイズレベルを提供します。

レベル	機能	適したユーザー
プロジェクト設定	デフォルトの設定、コンテキスト/ルールの注入	ほとんどのチーム
カスタムスキーマ	ワークフローアーティファクトの独自定義	独自のプロセスを持つチーム
グローバルオーバーライド	すべてのプロジェクト間でスキーマを共有	パワーユーザー

---

プロジェクト設定

openspec/config.yaml ファイルは、チームのために OpenSpec をカスタマイズする最も簡単な方法です。これにより、以下のことを行うことができます。

• デフォルトスキーマの設定 - 各コマンドで --schema オプションを省略可能にします
• プロジェクトコンテキストの注入 - AI が技術スタックや規約などを認識します
• アーティファクトごとのルール追加 - 特定のアーティファクトに対するカスタムルール
• 操作ごとのガイダンス追加 - apply および archive 作業に関する推奨事項
• 統合オプションの記憶 - 例：GitHub Copilot クラウドコーディングエージェント のオプトイン状態

クイックセットアップ

openspec init

これにより、対話形式で設定ファイルの作成が完了します。または、手動で作成することもできます。

# openspec/config.yaml
schema: spec-driven

context: |
  Tech stack: TypeScript, React, Node.js, PostgreSQL
  API style: RESTful, documented in docs/api.md
  Testing: Jest + React Testing Library
  We value backwards compatibility for all public APIs

rules:
  proposal:
    - Include rollback plan
    - Identify affected teams
  specs:
    - Use Given/When/Then format
    - Reference existing patterns before inventing new ones

operations:
  apply:
    guidance:
      - Run focused tests before the full suite
  archive:
    guidance:
      - Keep the completion summary concise

# Set by `openspec init` when you choose (or decline) the GitHub Copilot
# cloud coding agent; controls whether `init`/`update` generate its files.
githubCopilot:
  cloudAgent: false

動作原理

デフォルトスキーマ:

# 設定なしの場合
openspec new change my-feature --schema spec-driven

# 設定ありの場合 - スキーマは自動的に適用される
openspec new change my-feature

コンテキストとルールの注入:

任意のアーティファクトを生成する際、コンテキストとルールは AI プロンプトに注入されます。

<context>
Tech stack: TypeScript, React, Node.js, PostgreSQL
...
</context>

<rules>
- Include rollback plan
- Identify affected teams
</rules>

<template>
[Schema's built-in template]
</template>

• コンテキスト はすべてのアーティファクトに表示されます
• ルール は、一致するアーティファクトに対してのみ表示されます

操作ガイダンス:

operations.apply.guidance と operations.archive.guidance は、エージェントがそれらの操作を実行する方法に関する推奨指示の配列です。これらは rules とは別物です：操作ガイダンスはアーティファクトの内容を制約せず、アーティファクトルールが操作ガイダンスとして再ラベル付けされることはありません。

apply と archive は実行時にこれらの入力を取得します。

openspec instructions apply --change my-feature --json
openspec instructions archive --change my-feature --json

両方の出力では、現在のプロジェクト context と一致する operationGuidance が個別のオプションフィールドとして返されます。各呼び出しは、解決されたルートから新しいスナップショットを読み取ります。--store <id> が選択されている場合、変更、コンテキスト、ガイダンスはいずれも現在のリポジトリではなく、そのストアから取得されます。archive 指示コマンドは読み取り専用です：デルタ仕様を検査またはマージしたり、メイン仕様を書き込んだり、変更を移動したり、静的 archive ワークフローを実行したりしません。

プロジェクトコンテキストは必須のプロンプトレベル入力です。生成されたワークフローはこれを読み取り、関連するプロジェクトの事実、規約、制約を適用します。操作ガイダンスはオプションの追加アドバイスであり、ワークフローはすべてのエントリを考慮し、ビルトインワークフローと互換性があり適用可能なエントリに従います。

両方のフィールドは、CLI で制御される状態、解決されたパス、ビルトインステップ、明示的なユーザーの選択、およびアーティファクトルールとは分離されています。ワークフローはコンテキストの競合を報告しつつ、制御値を保持します。適用不可能な競合するガイダンスは従わず、その理由を説明します。どちらのフィールドも強制チェックではなく、ワークフローはユーザーが別途そのコンテンツを要求しない限り、実装ファイル、仕様、変更アーティファクト、またはサマリーにそれらのテキストをコピーしません。

Archive と spec-sync の入力安全性:

Archive、一括 archive、スタンドアロン sync は、openspec status --json から得られる artifactPaths.specs.existingOutputPaths を唯一のデルタ仕様ソースとして使用します。specs アーティファクトを持たないスキーマ、または具体的な出力リストが空の変更には、同期対象がありません。他のアーティファクトを使用してデルタ仕様を推測することはありません。

セマンティックマージがメイン仕様を書き込む前に、ワークフローは現在の openspec instructions specs --change <name> --json の出力を消費します。返された specs ルールは、そのマージによって生成されるメイン仕様のみを制約します。単一 archive はこのスナップショットをインライン sync に渡し、スタンドアロン sync はそれを直接フェッチし、一括 archive は最初の仕様書き込みの前に必要なすべてのスナップショットを取得します。非ゼロまたは無効な JSON の archive/specs 指示応答は、空の入力ではなくルックアップ失敗です：ワークフローは影響を受ける仕様書き込みまたは変更移動（一括 archive の場合は、バッチ書き込みまたは移動の前）の前に停止します。

この設定は、archive 実行フェーズ、ユーザープロンプト、ファイルシステム操作、セマンティックマージの所有権、直接の openspec archive コマンド、またはアーティファクト rules の構造と出力を変更しません。

スキーマ解決順序

OpenSpec がスキーマを必要とする場合、以下の順序で確認します。

1. CLI フラグ: --schema <name>
2. 変更メタデータ（変更フォルダ内の .openspec.yaml）
3. プロジェクト設定（openspec/config.yaml）
4. デフォルト（spec-driven）

カスタムスキーマ

プロジェクト設定だけでは不十分な場合、完全にカスタマイズされたワークフローで独自のスキーマを作成できます。カスタムスキーマはプロジェクトの openspec/schemas/ ディレクトリに配置され、コードとともにバージョン管理されます。

your-project/
├── openspec/
│   ├── config.yaml        # プロジェクト設定
│   ├── schemas/           # カスタムスキーマはここに配置
│   │   └── my-workflow/
│   │       ├── schema.yaml
│   │       └── templates/
│   └── changes/           # 変更内容
└── src/

既存スキーマのフォーク

カスタマイズする最速の方法は、組み込みスキーマをフォークすることです：

openspec schema fork spec-driven my-workflow

これにより、spec-driven スキーマ全体が openspec/schemas/my-workflow/ にコピーされ、自由に編集できます。

取得される内容：

openspec/schemas/my-workflow/
├── schema.yaml           # ワークフロー定義
└── templates/
    ├── proposal.md       # プロポーザル成果物のテンプレート
    ├── spec.md           # 仕様のテンプレート
    ├── design.md         # デザインのテンプレート
    └── tasks.md          # タスクのテンプレート

次に schema.yaml を編集してワークフローを変更するか、テンプレートを編集して AI が生成する内容を変更します。

一からスキーマを作成する

完全に新しいワークフローを作成する場合：

# インタラクティブ
openspec schema init research-first

# 非インタラクティブ
openspec schema init rapid \
  --description "Rapid iteration workflow" \
  --artifacts "proposal,tasks" \
  --default

スキーマの構造

スキーマはワークフロー内の成果物とその依存関係を定義します：

# openspec/schemas/my-workflow/schema.yaml
name: my-workflow
version: 1
description: My team's custom workflow

artifacts:
  - id: proposal
    generates: proposal.md
    description: Initial proposal document
    template: proposal.md
    instruction: |
      Create a proposal that explains WHY this change is needed.
      Focus on the problem, not the solution.
    requires: []

  - id: design
    generates: design.md
    description: Technical design
    template: design.md
    instruction: |
      Create a design document explaining HOW to implement.
    requires:
      - proposal    # Can't create design until proposal exists

  - id: tasks
    generates: tasks.md
    description: Implementation checklist
    template: tasks.md
    requires:
      - design

apply:
  requires: [tasks]
  tracks: tasks.md

主要フィールド：

フィールド	用途
id	一意の識別子。コマンドやルールで使用
generates	出力ファイル名（specs/**/*.md のようなグロブをサポート）
template	templates/ ディレクトリ内のテンプレートファイル
instruction	この成果物を作成するための AI 指示
requires	依存関係 - 先に存在が必要な成果物

成果物を記述したい順序で列挙します。requires が何が可能かを決定し、artifacts: リストの順序が複数の成果物が同時に準備できた場合に何が先に来るかを決定します。

テンプレート

テンプレートは AI を導く Markdown ファイルです。成果物を作成する際にプロンプトに注入されます。

<!-- templates/proposal.md -->
## Why

<!-- Explain the motivation for this change. What problem does this solve? -->

## What Changes

<!-- Describe what will change. Be specific about new capabilities or modifications. -->

## Impact

<!-- Affected code, APIs, dependencies, systems -->

テンプレートには以下を含めることができます：

• AI が記入すべきセクションヘッダー
• AI 向けのガイダンスを含む HTML コメント
• 期待される構造を示す例のフォーマット

スキーマの検証

カスタムスキーマを使用する前に、検証してください：

openspec schema validate my-workflow

これにより以下がチェックされます：

• schema.yaml の構文が正しいこと
• すべての参照テンプレートが存在すること
• 循環依存がないこと
• 成果物 ID が有効なこと

カスタムスキーマの使用

作成後、以下のようにスキーマを使用します：

# コマンドで指定
openspec new change feature --schema my-workflow

# または config.yaml でデフォルトを設定
schema: my-workflow

スキーマ解決のデバッグ

どのスキーマが使用されているか不明な場合は、以下で確認できます：

# 特定のスキーマがどこから解決されるか確認
openspec schema which my-workflow

# 利用可能なすべてのスキーマをリスト表示
openspec schema which --all

出力には、プロジェクト、ユーザーディレクトリ、またはパッケージのいずれから読み込まれているかが表示されます：

Schema: my-workflow
Source: project
Path: /path/to/project/openspec/schemas/my-workflow

---

注： OpenSpec はプロジェクト間で共有するために ~/.local/share/openspec/schemas/ にユーザーレベルのスキーマもサポートしていますが、コードとともにバージョン管理されるため、openspec/schemas/ 内のプロジェクトレベルのスキーマが推奨されます。

---

使用例

高速反復ワークフロー

素早い反復のための最小限のワークフロー：

# openspec/schemas/rapid/schema.yaml
name: rapid
version: 1
description: Fast iteration with minimal overhead

artifacts:
  - id: proposal
    generates: proposal.md
    description: Quick proposal
    template: proposal.md
    instruction: |
      Create a brief proposal for this change.
      Focus on what and why, skip detailed specs.
    requires: []

  - id: tasks
    generates: tasks.md
    description: Implementation checklist
    template: tasks.md
    requires: [proposal]

apply:
  requires: [tasks]
  tracks: tasks.md

レビュー成果物の追加

デフォルトをフォークしてレビューステップを追加します：

openspec schema fork spec-driven with-review

次に schema.yaml を編集して以下を追加します：

  - id: review
    generates: review.md
    description: Pre-implementation review checklist
    template: review.md
    instruction: |
      Create a review checklist based on the design.
      Include security, performance, and testing considerations.
    requires:
      - design

  - id: tasks
    # ... existing tasks config ...
    requires:
      - specs
      - design
      - review    # Now tasks require review too

---

コミュニティスキーマ

OpenSpec は、単一のリポジトリ経由で配布されるコミュニティ管理のスキーマもサポートしています。これらは他のツールやシステムと OpenSpec を統合する、主観的なワークフローを提供します。github/spec-kit のコミュニティ拡張カタログ が spec-kit に対して行っているのと同様の仕組みです。

コミュニティスキーマは OpenSpec コアにベンダーインされていません — それぞれのリポジトリに独自のリリースサイクルとともに存在します。使用するには、スキーマバンドルをプロジェクトの openspec/schemas/<schema-name>/ ディレクトリにコピーします（各リポジトリの README にインストール手順が記載されています）。

スキーマ	メンテナー	リポジトリ	説明
intent-driven	@harikrishnan83	intent-driven-dev/openspec-schemas	実装前に変更の意図、観測可能な動作、技術設計、永続的なアーキテクチャ判断をキャプチャします。変更ローカルの ADR レビューマニフェストを追加し、該当する長期判断を不変で差し替え可能な ADR として書き出します。
superpowers-bridge	@JiangWay	JiangWay/openspec-schemas	OpenSpec の成果物ガバナンスを obra/superpowers の実行スキル（ブレインストーミング、計画作成、サブエージェントによる TDD、コードレビュー、仕上げ）と統合します。Superpowers がネイティブにカバーしていないギャップを埋める、エビデンスファーストの retrospective 成果物を追加します。
nanopm	@nmrtn	nmrtn/nanopm	PM ファーストのワークフロー。実装の上流で nanopm の計画パイプライン（監査 → 戦略 → ロードマップ → PRD）を実行します。プロダクト計画を OpenSpec の仕様駆動エンジニアリングワークフローに橋渡しします。.nanopm/ が存在する場合は成果物から読み込み — プロポーザルは監査を、デザインは戦略を、タスクは PRD の分解をソースとします。
e2e-runbooks	@Lukk17	Lukk17/openspec-schemas	機能レベルのエンドツーエンドテストランブック。各機能に不変の仕様、不変のタスクテンプレート、実行ごとにタイムスタンプ付きの 1 つのランレコードが付与されます。アサーションは観測可能な動作のみ（HTTP ステータス、レスポンスボディ、永続化状態 — ログ部分文字列は不可）。各ランは開始/終了 UTC、所要時間、推定 LLM トークン消費量を記録します。
anvil	@jikkujoyce	jikkujoyce/openspec-schemas	TDD 規律と敵対的レビューステップを備えた仕様駆動ワークフロー。フロー：proposal → specs → design → review → test-plan → tasks → apply → verify。review は新しいコンテキストの読み取り専用レビュアー（利用可能な場合は別のモデル）によって作成され、test-plan、tasks、apply をゲートするようエージェントに指示する VERDICT: 行を出力します。OpenSpec は成果物の存在のみをチェックするため、ゲートは独自の CI またはフックで強制してください。test-plan はすべての仕様シナリオを名前付きテストにマッピングし、verify が監査する赤/緑台帳としても機能します。

コミュニティスキーマに貢献したい場合は、リポジトリへのリンクを添えて Issue を開くか、このテーブルに新しい行を追加する PR を提出してください。

---

関連項目

• CLI リファレンス：スキーマコマンド - 完全なコマンドドキュメント