コンセプト
このガイドでは、OpenSpec の中核となるアイデアと、それらがどのように連携するかを解説します。実践的な使用方法については、Getting Started と Workflows を参照してください。
哲学
OpenSpec は以下の4つの原則に基づいて構築されています。
fluid not rigid — フェーズゲートはなく、意味のある作業に集中する
iterative not waterfall — 構築しながら学び、進めながら洗練させる
easy not complex — 軽量なセットアップ、最小限の儀式
brownfield-first — グリーンフィールドだけでなく、既存のコードベースでも動作するなぜこれらの原則が重要なのか
Fluid not rigid（柔軟であり、硬直的ではない）。 従来の仕様システムは、まず計画を立て、次に実装し、最後に完了するというフェーズにユーザーを縛り付けます。OpenSpec はより柔軟性が高く、あなたの作業にとって意味のある順序でアーティファクトを作成できます。
Iterative not waterfall（反復的であり、ウォーターフォール式ではない）。 要件は変化します。理解は深まります。最初は良いアプローチに見えても、コードベースを見てみると通用しない場合があります。OpenSpec はこの現実を受け入れます。
Easy not complex（簡単であり、複雑ではない）。 一部の仕様フレームワークでは、広範なセットアップ、厳格なフォーマット、または重厚なプロセスが必要です。OpenSpec は邪魔をしません。数秒で初期化し、すぐに作業を開始し、必要に応じてのみカスタマイズできます。
Brownfield-first（ブラウンフィールドファースト）。 ソフトウェア作業の大部分は、ゼロから構築することではなく、既存のシステムを変更することです。OpenSpec のデルタベースのアプローチにより、新しいシステムを記述するだけでなく、既存の振る舞いへの変更を簡単に指定できます。
全体像
OpenSpec は、あなたの作業を2つの主要な領域に整理します。
┌────────────────────────────────────────────────────────────────────┐
│ openspec/ │
│ │
│ ┌─────────────────────┐ ┌───────────────────────────────┐ │
│ │ specs/ │ │ changes/ │ │
│ │ │ │ │ │
│ │ Source of truth │◄─────│ Proposed modifications │ │
│ │ How your system │ merge│ Each change = one folder │ │
│ │ currently works │ │ Contains artifacts + deltas │ │
│ │ │ │ │ │
│ └─────────────────────┘ └───────────────────────────────┘ │
│ │
└────────────────────────────────────────────────────────────────────┘Specs（仕様）は唯一の信頼できる情報源（Source of truth）であり、システムが現在どのように動作するかを記述します。
Changes（変更）は提案された修正であり、マージする準備ができるまで別々のフォルダ内に保持されます。
この分離が重要です。複数の変更を並行して競合なく作業できます。メインの仕様に影響を与える前に、変更内容をレビューできます。また、変更をアーカイブすると、そのデルタ（差分）が信頼できる情報源にきれいにマージされます。
Specs
Specs は、構造化された要件とシナリオを使用してシステムの挙動を記述します。
構造
openspec/specs/
├── auth/
│ └── spec.md # 認証の挙動
├── payments/
│ └── spec.md # 決済処理
├── notifications/
│ └── spec.md # 通知システム
└── ui/
└── spec.md # UI の挙動とテーマSpecs はドメインごとに整理します。これはシステムにとって意味のある論理的なグループ分けです。一般的なパターンは以下の通りです。
- 機能領域別:
auth/,payments/,search/ - コンポーネント別:
api/,frontend/,workers/ - 境界付けられたコンテキスト別:
ordering/,fulfillment/,inventory/
Spec フォーマット
Spec には要件が含まれ、各要件にはシナリオがあります。
# Auth Specification
## Purpose
Authentication and session management for the application.
## Requirements
### Requirement: User Authentication
The system SHALL issue a JWT token upon successful login.
#### Scenario: Valid credentials
- GIVEN a user with valid credentials
- WHEN the user submits login form
- THEN a JWT token is returned
- AND the user is redirected to dashboard
#### Scenario: Invalid credentials
- GIVEN invalid credentials
- WHEN the user submits login form
- THEN an error message is displayed
- AND no token is issued
### Requirement: Session Expiration
The system MUST expire sessions after 30 minutes of inactivity.
#### Scenario: Idle timeout
- GIVEN an authenticated session
- WHEN 30 minutes pass without activity
- THEN the session is invalidated
- AND the user must re-authenticate主要な要素:
| 要素 | 目的 |
|---|---|
## Purpose | この仕様のドメインの高レベルな説明 |
### Requirement: | システムが持つべき特定の挙動 |
#### Scenario: | 要件が実際に適用される具体的な例 |
| SHALL/MUST/SHOULD | RFC 2119 キーワード。要件の強さを示す |
なぜこのように Specs を構造化するのか
要件は「何（what）」 — システムが何をすべきかを、実装方法を指定せずに記述します。
シナリオは「いつ（when）」 — 検証可能な具体的な例を提供します。良いシナリオは以下の特徴を持ちます：
- テスト可能である（自動テストを書ける）
- ハッピーパスとエッジケースの両方をカバーする
- Given/When/Then または同様の構造化フォーマットを使用する
RFC 2119 キーワード（SHALL, MUST, SHOULD, MAY）は意図を伝えます：
- MUST/SHALL — 絶対的な必須要件
- SHOULD — 推奨されるが、例外が存在しうる
- MAY — オプション
Spec とは何か（そしてそうでないもの）
Spec は実装計画ではなく、挙動契約です。
適切な Spec の内容：
- ユーザーや下流のシステムが依存する観測可能な挙動
- 入力、出力、エラー条件
- 外部制約（セキュリティ、プライバシー、信頼性、互換性）
- テスト可能、または明示的に検証できるシナリオ
Spec で避けるべきこと：
- 内部クラス名や関数名
- ライブラリやフレームワークの選択
- 段階的な実装の詳細
- 詳細な実行計画（これらは
design.mdやtasks.mdに属します）
簡単なテスト：
- 外部から見える挙動を変えずに実装を変更できる場合、それはおそらく Spec に属しません。
軽量さを保つ：漸進的な厳密さ
OpenSpec は官僚主義を回避することを目指しています。変更を検証可能にするのに十分な最も軽いレベルを使用してください。
ライト仕様（デフォルト）：
- 短く、挙動優先の要件
- 明確なスコープと非目標（non-goals）
- いくつかの具体的な受入チェック
フル仕様（リスクが高い場合）：
- チーム間またはリポジトリ間の横断的な変更
- API/契約の変更、マイグレーション、セキュリティ/プライバシーに関する懸念
- 曖昧さが高額な手戻りを引き起こしやすい変更
大多数の変更はライトモードで維持すべきです。
人間とエージェントの協力
多くのチームでは、人間が探索を行い、エージェントが成果物（artifacts）の下書きを作成します。意図されたループは以下の通りです：
- 人間が意図、文脈、制約を提供する。
- エージェントがこれを挙動優先の要件とシナリオに変換する。
- エージェントは実装の詳細を
spec.mdではなくdesign.mdとtasks.mdに保持する。 - バリデーションにより、実装前に構造と明確さが確認される。
これにより、Spec は人間にとって読みやすく、エージェントにとって一貫性が保たれます。
Changes
変更とは、システムに対する提案された修正のことです。理解し、実装するために必要なすべてを含むフォルダとしてパッケージ化されます。
変更の構造
openspec/changes/add-dark-mode/
├── proposal.md # なぜ、何を
├── design.md # どうやって（技術的アプローチ）
├── tasks.md # 実装チェックリスト
├── .openspec.yaml # 変更メタデータ（オプション）: schema, created, skip_specs, retire_capabilities
└── specs/ # デルタ仕様
└── ui/
└── spec.md # ui/spec.md で何が変更されるか各変更は自己完結型です。以下を含みます：
- 成果物（Artifacts） — 意図、設計、タスクを記録したドキュメント
- デルタ仕様（Delta specs） — 追加、変更、削除されるものの仕様
- メタデータ — この特定の変更用のオプション設定
なぜ変更はフォルダなのか
変更をフォルダとしてパッケージ化するには、いくつかの利点があります：
すべてが一緒にある。 プロポーザル、設計、タスク、仕様が一箇所にあります。異なる場所を探し回る必要はありません。
並行作業。 複数の変更を同時に存在させることができ、競合しません。
add-dark-modeを作業している間に、fix-auth-bugも進行中であっても問題ありません。クリーンな履歴。 アーカイブされると、変更は完全な文脈を保持したまま
changes/archive/に移動します。何が変更されただけでなく、なぜ変更されたのかを理解するために過去を遡ることができます。レビューに適している。 変更フォルダはレビューが容易です。開いて、プロポーザルを読み、設計を確認し、仕様のデルタを確認します。
成果物（Artifacts）
成果物とは、作業をガイドする変更内のドキュメントのことです。
成果物のフロー
proposal ──────► specs ──────► design ──────► tasks ──────► implement
│ │ │ │
why what how steps
+ scope changes approach to take成果物は相互に積み重なります。各成果物が次のための文脈を提供します。
成果物の種類
プロポーザル (proposal.md)
プロポーザルは、高レベルな意図、スコープ、アプローチを記録します。
# Proposal: Add Dark Mode
## Intent
Users have requested a dark mode option to reduce eye strain
during nighttime usage and match system preferences.
## Scope
In scope:
- Theme toggle in settings
- System preference detection
- Persist preference in localStorage
Out of scope:
- Custom color themes (future work)
- Per-page theme overrides
## Approach
Use CSS custom properties for theming with a React context
for state management. Detect system preference on first load,
allow manual override.プロポーザルを更新すべきタイミング：
- スコープの変更（縮小または拡大）
- 意図の明確化（問題へのより良い理解）
- アプローチの根本的な変化
仕様（specs/ 内のデルタ仕様）
デルタ仕様は、現在の仕様に対して何が変更されるかを記述します。以下の デルタ仕様 を参照してください。
設計 (design.md)
設計は技術的アプローチとアーキテクチャ判断を記録します。
# Design: Add Dark Mode
## Technical Approach
Theme state managed via React Context to avoid prop drilling.
CSS custom properties enable runtime switching without class toggling.
## Architecture Decisions
### Decision: Context over Redux
Using React Context for theme state because:
- Simple binary state (light/dark)
- No complex state transitions
- Avoids adding Redux dependency
### Decision: CSS Custom Properties
Using CSS variables instead of CSS-in-JS because:
- Works with existing stylesheet
- No runtime overhead
- Browser-native solution
## Data Flow
```
ThemeProvider (context)
│
▼
ThemeToggle ◄──► localStorage
│
▼
CSS Variables (applied to :root)
```
## File Changes
- `src/contexts/ThemeContext.tsx` (new)
- `src/components/ThemeToggle.tsx` (new)
- `src/styles/globals.css` (modified)設計を更新すべきタイミング：
- 実装によってそのアプローチが機能しないことが判明した場合
- より良いソリューションが見つかった場合
- 依存関係や制約が変化した場合
タスク (tasks.md)
タスクは実装チェックリストです。チェックボックス付きの具体的なステップです。
# 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
- [ ] 1.4 Add system preference detection
## 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.3 Test contrast ratios for accessibilityタスクのベストプラクティス：
- 関連するタスクを見出しの下にグループ化する
- 階層番号を使用する（1.1, 1.2 など）
- タスクを1セッションで完了できる程度に小さく保つ
- 完了したらタスクをチェックオフする
デルタ仕様（Delta Specs）
デルタ仕様は、OpenSpec が既存システム（ブラウンフィールド）の開発で機能するための鍵となる概念です。仕様全体を再述するのではなく、何が変更されるかを記述します。
フォーマット
# Delta for Auth
## ADDED Requirements
### Requirement: Two-Factor Authentication
The system MUST support TOTP-based two-factor authentication.
#### Scenario: 2FA enrollment
- GIVEN a user without 2FA enabled
- WHEN the user enables 2FA in settings
- THEN a QR code is displayed for authenticator app setup
- AND the user must verify with a code before activation
#### Scenario: 2FA login
- GIVEN a user with 2FA enabled
- WHEN the user submits valid credentials
- THEN an OTP challenge is presented
- AND login completes only after valid OTP
## MODIFIED Requirements
### Requirement: Session Expiration
The system MUST expire sessions after 15 minutes of inactivity.
(Previously: 30 minutes)
#### Scenario: Idle timeout
- GIVEN an authenticated session
- WHEN 15 minutes pass without activity
- THEN the session is invalidated
## REMOVED Requirements
### Requirement: Remember Me
(Deprecated in favor of 2FA. Users should re-authenticate each session.)デルタセクション
| セクション | 意味 | アーカイブ時の処理 |
|---|---|---|
## ADDED Requirements | 新しい挙動 | メインの仕様に行われる |
## MODIFIED Requirements | 変更された挙動 | 既存の要件を置き換える |
## REMOVED Requirements | 廃止された挙動 | メインの仕様から削除されます。変更が retire_capabilities: true を宣言している場合、最後の要件を削除することで機能が退役し、その仕様ファイルも削除されます |
## Purpose | 新規機能の目的 | 作成中のメインの仕様の Purpose を初期化します。仕様が存在する場合は無視されます |
なぜデルタなのか（フル仕様ではない理由）
明確さ。 デルタは変更点を正確に示します。フル仕様を読む場合、現在のバージョンとの差分を頭の中で計算する必要があります。
競合の回避。 2つの変更が同じ仕様ファイルに触れていても、異なる要件を変更するのであれば競合しません。
レビュー効率。 レビュアーは変更点のみを見て、変更されていない文脈は見ません。重要なことに集中できます。
ブラウンフィールドへの適合。 大多数の作業は既存の挙動を変更するものです。デルタは変更を第一級のものとし、後回しにしないようにします。
Schemas
Schemas はワークフローにおける成果物タイプとその依存関係を定義します。
Schemas の仕組み
# openspec/schemas/spec-driven/schema.yaml
name: spec-driven
artifacts:
- id: proposal
generates: proposal.md
requires: [] # No dependencies, can create first
- id: specs
generates: specs/**/*.md
requires: [proposal] # Needs proposal before creating
- id: design
generates: design.md
requires: [proposal] # Can create in parallel with specs
- id: tasks
generates: tasks.md
requires: [specs, design] # Needs both specs and design first成果物は依存関係グラフを形成します:
proposal
(root node)
│
┌─────────────┴─────────────┐
│ │
▼ ▼
specs design
(requires: (requires:
proposal) proposal)
│ │
└─────────────┬─────────────┘
│
▼
tasks
(requires:
specs, design)依存関係は制約ではなく、可能性を示すものです。 作成できるものを示すものであり、次に作成すべきものを強制するものではありません。必要なければ design をスキップできます。specs は design より前でも後でも作成できます — どちらも proposal にのみ依存しています。
組み込み Schemas
spec-driven（デフォルト）
仕様駆動開発の標準ワークフロー:
proposal → specs → design → tasks → implement最適な用途: 実装前に仕様について合意を取りたいほとんどの機能開発。
カスタム Schemas
チームのワークフローに合わせてカスタム Schemas を作成できます:
# Create from scratch
openspec schema init research-first
# Or fork an existing one
openspec schema fork spec-driven research-firstカスタム Schema の例:
# openspec/schemas/research-first/schema.yaml
name: research-first
artifacts:
- id: research
generates: research.md
requires: [] # Do research first
- id: proposal
generates: proposal.md
requires: [research] # Proposal informed by research
- id: tasks
generates: tasks.md
requires: [proposal] # Skip specs/design, go straight to tasksカスタム Schemas の作成と使用の詳細については、Customization を参照してください。
Archive
アーカイブは、変更の差分仕様をメイン仕様へマージして変更を完了し、変更履歴として保存します。
アーカイブ時に何が起きるか
Before archive:
openspec/
├── specs/
│ └── auth/
│ └── spec.md ◄────────────────┐
└── changes/ │
└── add-2fa/ │
├── proposal.md │
├── design.md │ merge
├── tasks.md │
└── specs/ │
└── auth/ │
└── spec.md ─────────┘
After archive:
openspec/
├── specs/
│ └── auth/
│ └── spec.md # Now includes 2FA requirements
└── changes/
└── archive/
└── 2025-01-24-add-2fa/ # Preserved for history
├── proposal.md
├── design.md
├── tasks.md
└── specs/
└── auth/
└── spec.mdアーカイブプロセス
差分のマージ。 各差分仕様セクション（ADDED/MODIFIED/REMOVED）が対応するメイン仕様へ適用されます。
アーカイブへ移動。 変更フォルダが日付プレフィックス付きで
changes/archive/へ移動され、時系列順に整理されます。コンテキストの保存。 すべての成果物がアーカイブ内にそのまま保持されます。変更がなぜ行われたのかをいつでも確認できます。
アーカイブが重要な理由
クリーンな状態。 アクティブな変更（changes/）には進行中の作業のみが表示されます。完了した作業は片付けられます。
監査証跡。 アーカイブはすべての変更の完全なコンテキストを保存します — 変更内容だけでなく、なぜ変更したかの提案、どのように変更したかの設計、そして実施された作業を示すタスクまで。
仕様の進化。 変更がアーカイブされるたびに差分がマージされ、仕様は有機的に成長します。時間とともに包括的な仕様書が構築されていきます。
全体像
┌──────────────────────────────────────────────────────────────────────────────┐
│ OPENSPEC FLOW │
│ │
│ ┌────────────────┐ │
│ │ 1. START │ /opsx:propose (core) or /opsx:new (expanded) │
│ │ CHANGE │ │
│ └───────┬────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────┐ │
│ │ 2. CREATE │ /opsx:ff or /opsx:continue (expanded workflow) │
│ │ ARTIFACTS │ Creates proposal → specs → design → tasks │
│ │ │ (based on schema dependencies) │
│ └───────┬────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────┐ │
│ │ 3. IMPLEMENT │ /opsx:apply │
│ │ TASKS │ Work through tasks, checking them off │
│ │ │◄──── Update artifacts as you learn │
│ └───────┬────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────┐ │
│ │ 4. VERIFY │ /opsx:verify (optional) │
│ │ WORK │ Check implementation matches specs │
│ └───────┬────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────┐ ┌──────────────────────────────────────────────┐ │
│ │ 5. ARCHIVE │────►│ Delta specs merge into main specs │ │
│ │ CHANGE │ │ Change folder moves to archive/ │ │
│ └────────────────┘ │ Specs are now the updated source of truth │ │
│ └──────────────────────────────────────────────┘ │
│ │
└──────────────────────────────────────────────────────────────────────────────┘好循環:
- 仕様は現在の動作を記述する
- 変更は修正を提案する（差分として）
- 実装が変更を実体化する
- アーカイブが差分を仕様へマージする
- 仕様は新しい動作を記述する
- 次の変更は更新された仕様を土台に進む
用語集
| 用語 | 定義 |
|---|---|
| Artifact（成果物） | 変更内のドキュメント（proposal、design、tasks、または差分仕様） |
| Archive（アーカイブ） | 変更を完了し、その差分をメイン仕様へマージするプロセス |
| Change（変更） | システムに対する提案された修正。成果物を含むフォルダとしてパッケージ化される |
| Delta spec（差分仕様） | 現在の仕様に対する変更（ADDED/MODIFIED/REMOVED）を記述する仕様 |
| Domain（ドメイン） | 仕様の論理的なグループ化（例: auth/、payments/） |
| Requirement（要件） | システムが備えるべき具体的な動作 |
| Scenario（シナリオ） | 要件の具体的な例。通常は Given/When/Then 形式で記述される |
| Schema（スキーマ） | 成果物タイプとその依存関係の定義 |
| Spec（仕様） | システムの動作を記述する仕様書。要件とシナリオを含む |
| Source of truth（真実の情報源） | openspec/specs/ ディレクトリ。現在合意された動作を含む |
次のステップ
- Getting Started - 実践的な最初のステップ
- Workflows - 一般的なパターンと使い分け
- Commands - 完全なコマンドリファレンス
- Customization - カスタム Schemas の作成とプロジェクトの設定