OPSXへの移行

このガイドでは、従来のOpenSpecワークフローからOPSXへの移行を支援します。移行はスムーズに行えるよう設計されており、既存の作業はそのまま保持され、新しいシステムにより柔軟性がもたらされます。

何が変わるのか？

OPSXは、従来のフェーズロック型ワークフローに代わり、流動的でアクションベースのアプローチを採用しています。主な変更点は以下の通りです。

項目	従来	OPSX
コマンド	/openspec:proposal, /openspec:apply, /openspec:archive	デフォルト: /opsx:propose, /opsx:explore, /opsx:apply, /opsx:update, /opsx:sync, /opsx:archive (拡張されたワークフローコマンドはオプション)
ワークフロー	すべてのアーティファクトを一括で作成	増分的に作成するか、一括で作成するか—選択可能
戻り方	不自然なフェーズゲート	自然—いつでも任意のアーティファクトを更新可能
カスタマイズ	固定構造	スキーマ駆動、完全にハック可能
設定	マーカー付きの CLAUDE.md と project.md	openspec/config.yaml 内のクリーンな設定

哲学の変更: 作業は直線的ではありません。OPSXはそのふりをやめます。

---

開始する前に

既存の作業は安全です

マイグレーションプロセスは、データの保持を念頭に設計されています：

• openspec/changes/ 内のアクティブな変更 — 完全に保持されます。OPSX コマンドを使用して継続できます。
• アーカイブされた変更 — 変更されません。履歴はそのまま維持されます。
• openspec/specs/ 内のメイン仕様 — 変更されません。これらは信頼できる情報源（ソース・オブ・トゥルース）です。
• CLAUDE.md、AGENTS.md などのコンテンツ — 保持されます。OpenSpec マーカーブロックのみが削除され、あなたが記述した内容はすべて残ります。

削除されるもの

置き換えられる OpenSpec 管理下のファイルのみが対象となります：

対象	理由
レガシー スラッシュコマンド ディレクトリ/ファイル	新しいスキルシステムに置き換えられます
openspec/AGENTS.md	廃止されたワークフロートリガー
CLAUDE.md、AGENTS.md などの OpenSpec マーカー	不要になりました

ツール別のレガシーコマンドの場所（例；ツールによって異なる場合があります）：

• Claude Code: .claude/commands/openspec/
• Cursor: .cursor/commands/openspec-*.md
• Devin Desktop (旧 Windsurf): .windsurf/workflows/openspec-*.md
• Cline: .clinerules/workflows/openspec-*.md
• Roo: .roo/commands/openspec-*.md
• GitHub Copilot: .github/prompts/openspec-*.prompt.md（IDE拡張機能のみ；Copilot CLIではサポートされていません）
• Codex: OpenSpec は現在、標準的な .agents/skills/openspec-* パスを使用します。旧 .codex/skills パス配下にあった OpenSpec 管理の SKILL.md ファイルは、置き換えファイルが存在してから調整されます。カスタムファイルや差分のあるコピーはその場に留まります。マークされていない .agents ツリー内に既に OpenSpec スキルが含まれている場合、OpenSpec はレガディディレクトリから推測するのではなく、既存の Codex ($openspec-*) または汎用 (/openspec-*) のレンダリングを保持します。所有権を切り替えるには、openspec init で codex を明示的に選択してください。レガシプロンプトのクリーンアップは、$CODEX_HOME/prompts または ~/.codex/prompts 内の OpenSpec 許可リストにあるファイル名のみを対象とします。
• その他（Augment、Continue、Amazon Q など）

マイグレーションは、設定されているツールを検出し、それらのレガシーファイルをクリーンアップします。

削除リストが長く見えるかもしれませんが、これらはすべて OpenSpec が元々作成したファイルです。あなたの独自コンテンツは一切削除されません。

注意が必要な箇所

手動でのマイグレーションが必要なファイルが1つあります。

openspec/project.md — このファイルは、あなたが記述したプロジェクトコンテキストを含んでいる可能性があるため、自動的に削除されません。以下の手順が必要です：

1. コンテンツを確認する
2. 有用なコンテキストを openspec/config.yaml に移動する（以下のガイダンス参照）
3. 準備ができたらファイルを削除する

この変更を行った理由：

古い project.md は受動的なものであり、エージェントがそれを読むかどうか、読んだ内容を覚えているかは一定ではありませんでした。信頼性は不安定であることが判明しました。

新しい config.yaml のコンテキストは、すべての OpenSpec プランニングリクエストに積極的に注入されます。これにより、AI が成果物を生成する際に、プロジェクトの規約、技術スタック、ルールが常に存在することになります。信頼性が向上します。

トレードオフ：

コンテキストがすべてのリクエストに注入されるため、簡潔さを心がける必要があります。本当に重要なことに焦点を当ててください：

• 技術スタックと主要な規約
• AI が知る必要がある非自明な制約
• 以前頻繁に無視されていたルール

完璧を目指しすぎないでください。ここでのベストプラクティスはまだ学習段階にあり、実験を通じてコンテキスト注入の仕組みを改善していく予定です。

---

マイグレーションの実行

openspec init と openspec update の両方がレガシーファイルを検出し、同じクリーンアッププロセスをガイドします。状況に応じてどちらかを使用してください：

• 新規インストールでは、デフォルトで core プロファイル（propose, explore, apply, update, sync, archive）が適用されます。
• 移行済みインストールでは、必要に応じて custom プロファイルを作成することで、以前インストールされたワークフローを保持します。

openspec init の使用

新しいツールを追加したり、セットアップ済みのツールを再構成したい場合に実行します：

openspec init

init コマンドはレガシーファイルを検出し、クリーンアップをガイドします：

Upgrading to the new OpenSpec

OpenSpec now uses agent skills, the emerging standard across coding
agents. This simplifies your setup while keeping everything working
as before.

Files to remove
No user content to preserve:
  • .claude/commands/openspec/
  • openspec/AGENTS.md

Files to update
OpenSpec markers will be removed, your content preserved:
  • CLAUDE.md
  • AGENTS.md

Needs your attention
  • openspec/project.md
    We won't delete this file. It may contain useful project context.

    The new openspec/config.yaml has a "context:" section for planning
    context. This is included in every OpenSpec request and works more
    reliably than the old project.md approach.

    Review project.md, move any useful content to config.yaml's context
    section, then delete the file when ready.

? Upgrade and clean up legacy files? (Y/n)

「はい」と言った場合の処理内容：

1. レガシー スラッシュコマンドディレクトリが削除されます
2. CLAUDE.md、AGENTS.md などの OpenSpec マーカーが除去されます（あなたのコンテンツは保持されます）
3. openspec/AGENTS.md が削除されます
4. 新しいスキルが .claude/skills/ にインストールされます
5. デフォルトスキーマ付きの openspec/config.yaml が作成されます

openspec update の使用

既存のツールをマイグレートして最新バージョンに更新したいだけの場合はこちらを実行します：

openspec update

update コマンドもレガシーアーティファクトを検出してクリーンアップし、現在のプロファイルおよび配信設定に合わせて生成されたスキル/コマンドを更新します。

非対話型 / CI 環境向け

スクリプトによるマイグレーションの場合：

openspec init --force --tools claude

--force フラグはプロンプトをスキップし、クリーンアップを自動承認します。

これには、グローバル Codex プロンプトディレクトリ内の OpenSpec 管理下の Codex プロンプトファイルのクリーンアップも含まれます。クリーンアップは OpenSpec の許可リストにあるレガシー Codex プロンプトファイル名のみを対象とし、置き換え用の .agents/skills/openspec-* スキルが存在してからそれらを削除し、その他のファイルは保持します。

---

project.md から config.yaml への移行

古い openspec/project.md はプロジェクトコンテキスト用の自由形式の Markdown ファイルでした。新しい openspec/config.yaml は構造化されており、重要なのはすべてのプランニングリクエストに注入されるため、AI が作業する際にあなたの規約が常に存在することです。

移行前（project.md）

# Project Context

This is a TypeScript monorepo using React and Node.js.
We use Jest for testing and follow strict ESLint rules.
Our API is RESTful and documented in docs/api.md.

## Conventions

- All public APIs must maintain backwards compatibility
- New features should include tests
- Use Given/When/Then format for specifications

移行後（config.yaml）

schema: spec-driven

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

rules:
  proposal:
    - Include rollback plan for risky changes
  specs:
    - Use Given/When/Then format for scenarios
    - Reference existing patterns before inventing new ones
  design:
    - Include sequence diagrams for complex flows

主な違い

project.md	config.yaml
自由形式の Markdown	構造化された YAML
1つの大きなテキスト塊	分離されたコンテキストと成果物ごとのルール
使用タイミングが不明瞭	コンテキストはすべての成果物に表示；ルールは一致する成果物のみに表示
スキーマ選択なし	明示的な schema: フィールドがデフォルトのワークフローを設定

保持すべきものと除外すべきもの

移行時は選別を行ってください。「AI はすべてのプランニングリクエストにおいてこれを必要とするか？」と自問してください。

context: への適切な候補

• 技術スタック（言語、フレームワーク、データベース）
• 主要なアーキテクチャパターン（モノレポ、マイクロサービスなど）
• 非自明な制約（「ライブラリ X は〜の理由で使用できない」など）
• 頻繁に無視されがちな重要な規約

代わりに rules: へ移動させるもの

• 成果物固有のフォーマット（「仕様に Given/When/Then を使用する」など）
• 審査基準（「提案にはロールバック計画を含める必要がある」など）
• これらは一致する成果物に対してのみ表示され、他のリクエストを軽量に保ちます

完全に除外するもの

• AI がすでに知っている一般的なベストプラクティス
• 要約可能な冗長な説明
• 現在の作業に影響しない歴史的コンテキスト

移行の手順

1. config.yaml の作成（init によってすでに作成されていない場合）：

   schema: spec-driven

2. コンテキストの追加（簡潔に—これはすべてのリクエストに含まれるため）：

   context: |
     Your project background goes here.
     Focus on what the AI genuinely needs to know.

3. 成果物ごとのルールの追加（オプション）：

   rules:
     proposal:
       - Your proposal-specific guidance
     specs:
       - Your spec-writing rules

4. 有用なコンテンツをすべて移動したら、project.md を削除します。

考え込みすぎないでください。 本質的なところから始めて反復してください。AI が重要な見落としをしていることに気づいたら追加してください。コンテキストが肥大化していると感じたら削ってください。これは生きたドキュメントです。

ヘルプが必要ですか？このプロンプトを使用してください

project.md の要約方法に迷った場合、AI アシスタントに問い合わせてください：

I'm migrating from OpenSpec's old project.md to the new config.yaml format.

Here's my current project.md:
[paste your project.md content]

Please help me create a config.yaml with:
1. A concise `context:` section (this gets injected into every planning request, so keep it tight—focus on tech stack, key constraints, and conventions that often get ignored)
2. `rules:` for specific artifacts if any content is artifact-specific (e.g., "use Given/When/Then" belongs in specs rules, not global context)

Leave out anything generic that AI models already know. Be ruthless about brevity.

AI が、何が必須で何が削れるかを特定するのを手伝ってくれます。

---

新しいコマンド

コマンドの利用可否はプロファイルに依存します：

デフォルト（core プロファイル）：

コマンド	目的
/opsx:propose	変更を作成し、プランニング成果物を1ステップで生成
/opsx:explore	構造化せずにアイデアを検討
/opsx:apply	tasks.md のタスクを実装
/opsx:update	変更のプランニング成果物を改訂し、整合性を維持
/opsx:sync	デルタ仕様をメイン仕様に取り込む
/opsx:archive	変更を終了しアーカイブ

拡張ワークフロー（カスタム選択）：

コマンド	目的
/opsx:new	新しい変更スケルトンを開始
/opsx:continue	次の成果物を作成（一度に1つ）
/opsx:ff	ファストフォワード—プランニング成果物を一括で作成
/opsx:verify	実装が仕様と一致していることを検証
/opsx:bulk-archive	複数の変更を一括でアーカイブ
/opsx:onboard	ガイド付きのエンドツーエンドオンボーディングワークフロー

openspec config profile で拡張コマンドを有効にし、その後 openspec update を実行してください。

レガシーからのコマンドマッピング

レガシー	OPSX 相当
/openspec:proposal	/opsx:propose（デフォルト）または /opsx:new 後に /opsx:ff（拡張）
/openspec:apply	/opsx:apply
/openspec:archive	/opsx:archive

新しい機能

これらの機能は拡張ワークフローのコマンドセットの一部です。

粒度の細かい成果物作成：

/opsx:continue

依存関係に基づいて一度に1つの成果物を作成します。各ステップを確認したい場合に使用します。

探索モード：

/opsx:explore

変更を確定する前にパートナーとアイデアを検討します。

新しいアーキテクチャの理解

フェーズロックから流動的なワークフローへ

従来のワークフローは直線的な進行を強制していました：

┌──────────────┐      ┌──────────────┐      ┌──────────────┐
│   計画フェーズ   │ ───► │  実装フェーズ  │ ───► │  アーカイブ  │
│              │      │              │      │  フェーズ    │
└──────────────┘      └──────────────┘      └──────────────┘

実装中に設計が間違っていることに気づいたら？
残念ながら、フェーズゲートがあるため簡単には戻れません。

OPSXはフェーズではなくアクションを使用します：

         ┌───────────────────────────────────────────────┐
         │           アクション（フェーズではない）        │
         │                                               │
         │     new ◄──► continue ◄──► apply ◄──► archive │
         │      │          │           │             │   │
         │      └──────────┴───────────┴─────────────┘   │
         │                    任意の順序                   │
         └───────────────────────────────────────────────┘

依存関係グラフ

アーティファクトは有向グラフを形成します。依存関係はゲートではなくイネーブラー（進行を可能にする要素）です：

                        proposal
                       (ルートノード)
                            │
              ┌─────────────┴─────────────┐
              │                           │
              ▼                           ▼
           specs                       design
        (依存：                     (依存：
         proposal)                  proposal)
              │                           │
              └─────────────┬─────────────┘
                            │
                            ▼
                         tasks
                     (依存：
                     specs, design)

/opsx:continue を実行すると、準備が整っているものをチェックし、次のアーティファクトを提案します。また、順不同で複数の準備完了アーティファクトを作成することも可能です。

スキル vs コマンド

従来のシステムはツール固有のコマンドファイルを使用していました：

.claude/commands/openspec/
├── proposal.md
├── apply.md
└── archive.md

OPSXは新しい スキル 標準を採用しています：

.claude/skills/
├── openspec-explore/SKILL.md
├── openspec-new-change/SKILL.md
├── openspec-continue-change/SKILL.md
├── openspec-apply-change/SKILL.md
└── ...

スキルは複数のAIコーディングツールで認識され、より豊富なメタデータを提供します。

CodexはOPSXではスキルのみを使用します。OpenSpecはCodexのカスタムプロンプトファイルを生成しなくなりました。代わりに生成された .agents/skills/openspec-* ディレクトリを使用してください。

---

既存の変更の続行

進行中の変更はOPSXコマンドでシームレスに動作します。

従来のワークフローからアクティブな変更がある場合

/opsx:apply add-my-feature

OPSXは既存のアーティファクトを読み取り、中断したところから続行します。

既存の変更にさらにアーティファクトを追加したい場合

/opsx:continue add-my-feature

既存の状況に基づいて作成可能なものを表示します。

ステータスを確認する必要がある場合

openspec status --change add-my-feature

---

新しい設定システム

config.yamlの構造

# 必須: 新しい変更のためのデフォルトスキーマ
schema: spec-driven

# 任意: プロジェクトコンテキスト (最大50KB)
# すべてのアーティファクト指示に注入されます
context: |
  プロジェクトの背景、技術スタック、
  規約、制約など。

# 任意: アーティファクトごとのルール
# 一致するアーティファクトにのみ注入されます
rules:
  proposal:
    - ロールバック計画を含めること
  specs:
    - Given/When/Then 形式を使用すること
  design:
    - フォールバック戦略を文書化すること
  tasks:
    - 最大2時間で完了できる単位に分割すること

スキーマの解決

使用するスキーマを決定する際、OPSXは以下の順序でチェックします：

1. CLIフラグ: --schema <name> (最優先)
2. 変更メタデータ: 変更ディレクトリ内の .openspec.yaml
3. プロジェクト設定: openspec/config.yaml
4. デフォルト: spec-driven

利用可能なスキーマ

スキーマ	アーティファクト	適しているプロジェクト
spec-driven	proposal → specs → design → tasks	ほとんどのプロジェクト

すべての利用可能なスキーマを一覧表示するには：

openspec schemas

カスタムスキーマ

独自のワークフローを作成する：

openspec schema init my-workflow

既存のものをフォークする：

openspec schema fork spec-driven my-workflow

詳細は カスタマイズ を参照してください。

---

トラブルシューティング

"非対話モードでレガシーファイルが検出されました"

CIや非対話環境で実行しています。次を使用してください：

openspec init --force

移行後にコマンドが表示されない

IDEを再起動してください。スキルは起動時に検出されます。

"ルール内の不明なアーティファクトID"

rules: のキーがスキーマのアーティファクトIDと一致しているか確認してください：

• spec-driven: proposal, specs, design, tasks

有効なアーティファクトIDを表示するには：

openspec schemas --json

設定が適用されない

1. ファイルが openspec/config.yaml にあることを確認してください（ .yml ではありません）
2. YAMLの構文を検証してください
3. 設定の変更は即座に反映されます。再起動は不要です

project.mdが移行されない

システムは project.md を意図的に保持します。これはカスタムコンテンツが含まれている可能性があるためです。手動で内容を確認し、有用な部分を config.yaml に移行してから削除してください。

何がクリーンアップされるか確認したい

openspec init を実行し、クリーンアップの確認プロンプトで拒否してください。変更を加えずに完全な検出サマリーが表示されます。

---

クイックリファレンス

移行後のファイル構成

project/
├── openspec/
│   ├── specs/                    # 変更なし
│   ├── changes/                  # 変更なし
│   │   └── archive/              # 変更なし
│   └── config.yaml               # 新規: プロジェクト設定
├── .claude/
│   └── skills/                   # 新規: OPSXスキル
│       ├── openspec-propose/     # デフォルトコアプロファイル
│       ├── openspec-explore/
│       ├── openspec-apply-change/
│       ├── openspec-update-change/
│       ├── openspec-sync-specs/
│       ├── openspec-archive-change/
│       └── ...                   # 拡張プロファイルではnew/continue/ffなどが追加される
├── CLAUDE.md                     # OpenSpecマーカーは削除され、コンテンツは保持
└── AGENTS.md                     # OpenSpecマーカーは削除され、コンテンツは保持

削除されたもの

• .claude/commands/openspec/ — .claude/skills/ に置き換え
• openspec/AGENTS.md — 廃止
• openspec/project.md — config.yaml に移行して削除
• CLAUDE.md、AGENTS.md などの OpenSpec マーカーブロック

コマンド早見表

/opsx:propose      素早く開始（デフォルトコアプロファイル）
/opsx:apply        タスクを実装
/opsx:archive      完了してアーカイブ

# 拡張ワークフロー（有効な場合）:
/opsx:new          変更のスキャフォールドを作成
/opsx:continue     次のアーティファクトを作成
/opsx:ff           計画アーティファクトを作成

---

ヘルプ

• Discord: discord.gg/YctCnvvshC
• GitHub Issues: github.com/Fission-AI/OpenSpec/issues
• ドキュメント: docs/opsx.md で完全なOPSXリファレンスを参照