OpenSpec

はじめに ​

本ガイドでは、インストールと初期化が完了した後の OpenSpec の動作について説明します。インストール手順については、メイン README または インストールガイド を参照してください。ドキュメント全体が初めての方は、ドキュメントのホーム から全体像を把握できます。

これらのコマンドはどこに入力するの？ 2つの場所があり、この混同が最もよくある初期のつまずきです。

  • openspec ... コマンド（例：openspec init）は ターミナル で実行します。
  • /opsx:... コマンド（例：/opsx:propose）は AI アシスタントのチャット で実行します。コードを書かせて依頼するのと同じ入力欄です。

別途「対話モード」を開始する必要はありません。チャットにスラッシュコマンドを入力するだけで、アシスタントが引き継ぎます。詳細は コマンドの仕組み を参照してください。

最初の5分間 ​

各ステップの実行場所をラベル付きで示した全体のフローです：

text
TERMINAL   $ npm install -g @fission-ai/openspec@latest
TERMINAL   $ cd your-project && openspec init
AI CHAT      /opsx:explore                    (任意：まず考えを整理)
AI CHAT      /opsx:propose add-dark-mode      (AI が計画を起草、あなたがレビュー)
AI CHAT      /opsx:apply                      (AI が実装)
AI CHAT      /opsx:archive                    (仕様を更新、変更をアーカイブ)

ターミナルで2ステップのセットアップを行い、以降はチャットで作業します。本ガイドの残りでは、各ステップの動作と表示される内容について詳しく説明します。

ターミナル作業を自分でやりたくない場合？ セットアッププロンプト をアシスタントに貼り付けると、両方の行を処理し、作成された内容について報告してくれます。

何を作るかまだ決めていない場合？ /opsx:explore から始めましょう。 これはリスクのない思考パートナーで、コードベースを読み込み、選択肢を比較検討し、曖昧なアイデアを具体的な計画に磨き上げます。成果物やコードが存在する前にすべて完了します。全体像が明確になったら、/opsx:propose に引き継ぎます。AI が自信満々で間違ったものを作り上げてしまうのを防ぐために、最も有効な習慣です。Explore ガイド を参照してください。

動作原理 ​

OpenSpec は、コードを書き始める前に、あなたと AI コーディングアシスタントが何を作るかについて合意するのを助けます。

デフォルトのクイックパス（core プロファイル）：

text
/opsx:explore ──► /opsx:propose ──► /opsx:apply ──► /opsx:sync ──► /opsx:archive
   (任意)

何をするか検討中なら /opsx:explore から始め、すでにわかっている場合は /opsx:propose に直接飛びます。Explore はデフォルトプロファイルに含まれているため、いつでも利用可能です。

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

text
/opsx:new ──► /opsx:ff or /opsx:continue ──► /opsx:apply ──► /opsx:verify ──► /opsx:archive

デフォルトのグローバルプロファイルは core で、propose、explore、apply、update、sync、archive が含まれます。openspec config profile で拡張ワークフローコマンドを有効にし、その後 openspec update を実行できます。

OpenSpec が作成するもの ​

openspec init を実行した後、プロジェクトには以下の構造が作成されます：

openspec/
├── specs/              # ソースオブトゥルース（システムの動作）
│   └── <domain>/
│       └── spec.md
├── changes/            # 提案中の更新（変更ごとにフォルダ）
│   └── <change-name>/
│       ├── proposal.md
│       ├── design.md
│       ├── tasks.md
│       └── specs/      # Delta specs（変更内容）
│           └── <domain>/
│               └── spec.md
└── config.yaml         # プロジェクト設定（任意）

2つの主要ディレクトリ：

  • specs/ - ソースオブトゥルース。これらの仕様は、システムが現在どのように動作するかを記述しています。ドメインごとに整理されています（例：specs/auth/、specs/payments/）。

  • changes/ - 提案中の修正。各変更には関連する成果物がすべて含まれた専用フォルダが割り当てられます。変更が完了すると、その仕様はメインの specs/ ディレクトリにマージされます。

成果物について ​

各変更フォルダには、作業を導く成果物が含まれます：

成果物目的
proposal.md「なぜ」と「何」- 意図、スコープ、アプローチを記録
specs/ADDED/MODIFIED/REMOVED の要件を示す Delta specs
design.md「どうやるか」- 技術的なアプローチとアーキテクチャの決定
tasks.mdチェックボックス付きの実装チェックリスト

成果物は段階的に構築されます：

proposal ──► specs ──► design ──► tasks ──► implement
   ▲           ▲          ▲                    │
   └───────────┴──────────┴────────────────────┘
            学習に応じて更新

実装中に新たな発見があれば、いつでも以前の成果物に戻って改善できます。

Delta Specs の仕組み ​

Delta specs は OpenSpec の中核となる概念です。現在の仕様に対する変更点を示します。

フォーマット ​

Delta specs は、変更の種類を示すセクションを使用します：

markdown
# Delta for Auth

## ADDED Requirements

### Requirement: Two-Factor Authentication
The system MUST require a second factor during login.

#### Scenario: OTP required
- GIVEN a user with 2FA enabled
- WHEN the user submits valid credentials
- THEN an OTP challenge is presented

## MODIFIED Requirements

### Requirement: Session Timeout
The system SHALL expire sessions after 30 minutes of inactivity.
(Previously: 60 minutes)

#### Scenario: Idle timeout
- GIVEN an authenticated session
- WHEN 30 minutes pass without activity
- THEN the session is invalidated

## REMOVED Requirements

### Requirement: Remember Me
(Deprecated in favor of 2FA)

アーカイブ時の動作 ​

変更をアーカイブすると：

  1. ADDED された要件はメインの仕様末尾に追加されます
  2. MODIFIED された要件は既存のバージョンを置き換えます
  3. REMOVED された要件はメインの仕様から削除されます

変更フォルダは監査履歴として openspec/changes/archive/ に移動されます。

例：最初の変更 ​

アプリケーションにダークモードを追加する流れを説明します。

1. 変更を開始（デフォルト） ​

text
You: /opsx:propose add-dark-mode

AI:  Created openspec/changes/add-dark-mode/
     ✓ proposal.md — why we're doing this, what's changing
     ✓ specs/       — requirements and scenarios
     ✓ design.md    — technical approach
     ✓ tasks.md     — implementation checklist
     Ready for implementation!

拡張ワークフロープロファイルを有効にしている場合、2ステップでも実行できます：/opsx:new の後で /opsx:ff（または /opsx:continue で逐次実行）。

2. 作成されるもの ​

proposal.md - 意図を記録します：

markdown
# Proposal: Add Dark Mode

## Intent
Users have requested a dark mode option to reduce eye strain
during nighttime usage.

## Scope
- Add theme toggle in settings
- Support system preference detection
- Persist preference in localStorage

## Approach
Use CSS custom properties for theming with a React context
for state management.

specs/ui/spec.md - 新規要件を示す Delta：

markdown
# Delta for UI

## ADDED Requirements

### Requirement: Theme Selection
The system SHALL allow users to choose between light and dark themes.

#### Scenario: Manual toggle
- GIVEN a user on any page
- WHEN the user clicks the theme toggle
- THEN the theme switches immediately
- AND the preference persists across sessions

#### Scenario: System preference
- GIVEN a user with no saved preference
- WHEN the application loads
- THEN the system's preferred color scheme is used

tasks.md - 実装チェックリスト：

markdown
# Tasks

## 1. Theme Infrastructure
- [ ] 1.1 Create ThemeContext with light/dark state
- [ ] 1.2 Add CSS custom properties for colors
- [ ] 1.3 Implement localStorage persistence

## 2. UI Components
- [ ] 2.1 Create ThemeToggle component
- [ ] 2.2 Add toggle to settings page
- [ ] 2.3 Update Header to include quick toggle

## 3. Styling
- [ ] 3.1 Define dark theme color palette
- [ ] 3.2 Update components to use CSS variables

3. 実装 ​

You: /opsx:apply

AI:  Working through tasks...
     ✓ 1.1 Created ThemeContext with light/dark state
     ✓ 1.2 Added CSS custom properties to globals.css
     ✓ 1.3 Implemented localStorage persistence
     ✓ 2.1 Created ThemeToggle component
     ...
     All tasks complete!

実装中に設計の調整が必要だと気づいたら、成果物を更新して続行してください。

4. アーカイブ ​

You: /opsx:archive

AI:  Archiving add-dark-mode...
     ✓ Merged specs into openspec/specs/ui/spec.md
     ✓ Moved to openspec/changes/archive/2025-01-24-add-dark-mode/
     Done! Ready for the next feature.

Delta specs がメインの仕様に加わり、システムの動作が文書化されました。

検証とレビュー ​

CLI を使って変更を確認します：

bash
# List active changes
openspec list

# View change details
openspec show add-dark-mode

# Validate spec formatting
openspec validate add-dark-mode

# Interactive dashboard
openspec view

次のステップ ​