OpenSpec

プロジェクトのセットアップ ​

プロジェクトに OpenSpec を追加する: init を実行し、何が書かれたかを確認して調整します。

OpenSpec の配置場所を選択 ​

  • リポジトリ内（デフォルト）: スペックと変更は、それらが記述するコードの隣に配置され、一緒にバージョン管理されます。このページの残りはこのパスに従います。
  • ストア内: 使用するリポジトリ間で共有される別の計画リポジトリで、マルチリポジトリ構成やリポジトリから計画を完全に分離したい場合に使用します。ストア（ベータ） では、それが有益な場合と設定方法について説明します。

プロジェクトを初期化 ​

CLI をインストールしたら（インストール）、プロジェクトのルートで init を実行します。ターミナルで：

bash
cd <your-project>
openspec init

Init は、どの AI ツールを使用しているかを尋ね、選択したツールのワークフローファイルを作成し、取得したものを報告します：

OpenSpec Setup Complete

Created: Claude Code
6 skills and 6 commands in .claude/
Config: openspec/config.yaml (schema: spec-driven)

新しいコマンドを有効にするには、IDE を再起動します。

init の再実行は安全です：

  • 既に設定したツールは Created の代わりに Refreshed と表示されます。
  • 新しいツールを選択して init を再度実行すると、そのツールが追加されます。
  • --tools フラグはピッカーをスキップします（CLI リファレンス）。

既存の project.md を移行 ​

Init はレガシーな openspec/project.md を config.yaml にコピーしません。ファイルは保持され、AI 支援の移行リクエストが表示されます。

AI チャットで：

Review openspec/project.md and migrate its useful content to openspec/config.yaml.
Keep context concise: include only project-wide facts needed during artifact creation, apply, and archive.
Move artifact-specific guidance into rules for the matching artifacts.
Move guidance for apply or archive into the matching operations entry.
Leave out generic, outdated, or verbose material. Do not delete project.md.

config.yaml を確認し、準備ができたら project.md を削除します。

init がインストールするもの ​

init を実行すると、プロジェクトに 2 つのものが作成されます：

  • リポジトリルートの openspec/ フォルダ
  • AI ツールのフォルダ（.agents/、.claude/ など）に追加されるワークフローファイル（スキルとコマンド）

これらすべてを他のソースと同様にコミットします。init はリポジトリの他の部分を変更しません（古い OpenSpec バージョンの残骸が見つかった場合は、クリーンアップ前に確認します）。

openspec/ フォルダ ​

すべての OpenSpec アーティファクトは、プロジェクトルートのここに配置されます。次のようになります：

openspec/
├── config.yaml     project settings and context for the AI
├── specs/          your specs (empty for now)
└── changes/        in-motion changes (empty for now)
    └── archive/    completed changes move here

プロジェクト設定 では config.yaml について説明します。

ワークフローファイル（スキルとコマンド） ​

これらは OpenSpec ワークフローであり、作業時に使用するアクションです。ここでは、ほとんどのツールが使用する共有 .agents/ フォルダにインストールされたスキルとして表示されています：

.agents/skills/
├── openspec-explore/              think through an idea first
├── openspec-propose/              propose a change
├── openspec-apply-change/         implement a change's tasks
├── openspec-update-change/        revise a change's plan
├── openspec-sync-specs/           sync a change's spec updates into specs/
├── openspec-archive-change/       move a finished change to the archive
├── openspec-verify-change/        check the implementation matches the plan (not included by default)
└── openspec-bulk-archive-change/  archive several changes at once (not included by default)

これはデフォルトセットに 2 つのオプションワークフローを追加したものです。プロファイル には 12 すべてがリストされています。

デフォルトでは、各ワークフローは 2 つの形式でインストールされます：

  • スキル (openspec-apply-change): 作業を依頼すると、エージェントが独自に取得する指示です。
  • コマンド (Claude Code の /opsx:apply): 同じワークフローの、より短い名前の型付きエントリポイントです。

これらは機能的に同一です。ワークフローのスキルとコマンドは同じ指示を持ちます。

なぜ 2 つあるのか：コマンドが最初にあり、各ツールが独自の方法で記述します。スキルはツール間で共有される新しい標準ですが、すべてのツールがスキルを直接呼び出せるわけではないため、コマンドはそれらのツールのエントリポイントとして残ります。

一部のツールはスキル形式のみでインストールされます。ツールがスキルを直接実行する場合、init はコマンドをスキップし、そのように表示します (Commands skipped for: codex (uses skills))。

私たちはスキルを好み、最終的にコマンドを廃止することを期待しています。

インストール内容を変更 ​

対話型ピッカーは配信形式とワークフローセットを変更します（プロファイル）。ターミナルで：

bash
openspec config profile

スキルのみに切り替える例です：

Current profile settings
  Delivery: both

? What do you want to configure? Delivery only
? Delivery mode (how workflows are installed): Skills only

Config changes:
  delivery: both -> skills
? Apply changes to this project now? (Y/n) y

はいと答えると、現在のプロジェクトに即座に適用されます。他のプロジェクトは次回の openspec update で取得します。この設定はマシンごとにグローバルです。

Claude Code がワークフローを表示しない ​

Claude Code は、配信設定に基づいて、これらのプロジェクトパスの 1 つまたは両方から OpenSpec ワークフローを読み込みます：

  • スキル: .claude/skills/openspec-*/SKILL.md
  • コマンド: .claude/commands/opsx/<id>.md

ファイルが欠落している場合は、プロジェクトを更新します。ターミナルで：

bash
openspec update

コマンドファイルは存在するが /opsx: に OpenSpec コマンドが表示されない場合は、Claude Code を更新して再起動します。コマンドがまだ読み込まれない場合は、スキルも有効にします。ターミナルで：

bash
openspec config set delivery both
openspec update

Claude Code を再起動し、チャットで /openspec-propose を実行します。一部のワークフローだけが欠落している場合は、プロファイルを変更 してください。

セットアップは完了です。クイックスタート では、ここから最初の変更を行います。