コンセプト
このガイドでは、OpenSpecの背後にあるコアな考え方と、それらがどのように組み合わさるかについて説明します。実際の使い方については、入門ガイドとワークフローを参照してください。
哲学
OpenSpecは4つの原則を中心に構築されています：
fluid not rigid — no phase gates, work on what makes sense
iterative not waterfall — learn as you build, refine as you go
easy not complex — lightweight setup, minimal ceremony
brownfield-first — works with existing codebases, not just greenfieldなぜこれらの原則が重要なのか
柔軟であり、固定的ではない。 従来の仕様システムは、段階に縛られます：まず計画し、次に実装し、そして完了です。OpenSpecはより柔軟で、作業にとって合理的な順序で成果物を作成できます。
反復的であり、ウォーターフォールではない。 要件は変わります。理解は深まります。当初は良いように思えたアプローチも、コードベースを実際に見た後には合わなくなるかもしれません。OpenSpecはこの現実を受け入れています。
簡単であり、複雑ではない。 一部の仕様フレームワークは、広範なセットアップ、厳格な形式、または重厚なプロセスを必要とします。OpenSpecは邪魔をしません。数秒で初期化し、すぐに作業を開始し、必要な場合にのみカスタマイズします。
既存コードベース優先。 ほとんどのソフトウェア作業は、ゼロから構築するものではありません。既存のシステムを変更するものです。OpenSpecのデルタベースアプローチにより、新しいシステムを説明するだけでなく、既存の動作への変更を容易に指定できます。
全体像
OpenSpec は、作業を2つの主要な領域に整理します：
┌────────────────────────────────────────────────────────────────────┐
│ openspec/ │
│ │
│ ┌─────────────────────┐ ┌───────────────────────────────┐ │
│ │ specs/ │ │ changes/ │ │
│ │ │ │ │ │
│ │ 真実の源 │◄─────│ 提案された変更 │ │
│ │ システムの現在の │ merge│ 各変更 = 1つのフォルダ │ │
│ │ 動作 │ │ アーティファクト + デルタを │ │
│ │ │ │ 含む │ │
│ └─────────────────────┘ └───────────────────────────────┘ │
│ │
└────────────────────────────────────────────────────────────────────┘Specs（仕様） は真実の源です — システムの現在の動作を記述します。
Changes（変更） は提案された修正です — マージする準備ができるまで、個別のフォルダに格納されます。
この分離が重要です。競合なしに複数の変更を並行して作業できます。メインの仕様に影響を与える前に変更をレビューできます。また、変更をアーカイブすると、そのデルタは真実の源にきれいにマージされます。
Specs（仕様）
Specs（仕様）は、構造化された要件とシナリオを使用して、システムの動作を記述します。
構造
openspec/specs/
├── auth/
│ └── spec.md # 認証動作
├── payments/
│ └── spec.md # 支払い処理
├── notifications/
│ └── spec.md # 通知システム
└── ui/
└── spec.md # UIの動作とテーマドメインごとに仕様を整理します — システムにとって意味のある論理的なグループです。一般的なパターン：
- 機能領域別:
auth/,payments/,search/ - コンポーネント別:
api/,frontend/,workers/ - bounded context別:
ordering/,fulfillment/,inventory/
仕様のフォーマット
仕様は要件を含み、各要件にはシナリオがあります：
markdown
# Auth Specification
## Purpose
アプリケーションの認証とセッション管理。
## Requirements
### Requirement: User Authentication
システムは、ログイン成功時にJWTトークンを発行するものとする（SHALL）。
#### Scenario: Valid credentials
- GIVEN 有効な資格情報を持つユーザー
- WHEN ユーザーがログインフォームを送信する
- THEN JWTトークンが返される
- AND ユーザーはダッシュボードにリダイレクトされる
#### Scenario: Invalid credentials
- GIVEN 無効な資格情報
- WHEN ユーザーがログインフォームを送信する
- THEN エラーメッセージが表示される
- AND トークンは発行されない
### Requirement: Session Expiration
システムは、30分間の非アクティブ後にセッションを期限切れにするものとする（MUST）。
#### Scenario: Idle timeout
- GIVEN 認証済みセッション
- WHEN アクティビティなしで30分が経過する
- THEN セッションは無効化される
- AND ユーザーは再認証が必要となる主要な要素：
| 要素 | 目的 |
|---|---|
## Purpose | この仕様のドメインの高レベルな説明 |
### Requirement: | システムが持つべき特定の動作 |
#### Scenario: | 要件の具体的な実行例 |
| SHALL/MUST/SHOULD | 要件の強度を示すRFC 2119キーワード |
なぜこのように仕様を構造化するのか
要件は「何を」 — 実装を指定せずに、システムがすべきことを述べます。
シナリオは「いつ」 — 検証可能な具体的な例を提供します。良いシナリオは：
- テスト可能である（自動テストを書ける）
- ハッピーパスとエッジケースの両方をカバーする
- Given/When/Then または同様の構造化フォーマットを使用する
RFC 2119キーワード（SHALL, MUST, SHOULD, MAY）は意図を伝えます：
- MUST/SHALL — 絶対的な要件
- SHOULD — 推奨されるが、例外が存在する
- MAY — オプション
仕様とは何か（そうでないもの）
仕様は動作契約であり、実装計画ではありません。
良い仕様の内容：
- ユーザーや下流システムが依存する観測可能な動作
- 入力、出力、エラー条件
- 外部の制約（セキュリティ、プライバシー、信頼性、互換性）
- テストまたは明示的に検証可能なシナリオ
仕様で避けるべきもの：
- 内部のクラス/関数名
- ライブラリやフレームワークの選択
- ステップごとの実装詳細
- 詳細な実行計画（これらは
design.mdやtasks.mdに属する）
簡単なテスト：
- 実装が外部から見える動作を変更せずに変更できる場合、それはおそらく仕様に属さない。
軽量に保つ：段階的な厳密さ
OpenSpecは官僚主義を避けることを目指します。変更を検証可能にするのに必要な最も軽いレベルを使用します。
ライト仕様（デフォルト）：
- 短い動作優先の要件
- 明確な範囲と非目標
- 少数の具体的な受入チェック
フル仕様（より高いリスクの場合）：
- チーム横断またはリポジトリ横断の変更
- API/契約の変更、移行、セキュリティ/プライバシーの懸念
- 曖昧さが高コストな再作業を引き起こす可能性のある変更
ほとんどの変更はライトモードにとどめるべきです。
人間 + エージェントのコラボレーション
多くのチームでは、人間が探索し、エージェントがアーティファクトを草案します。意図的なループは以下の通りです：
- 人間が意図、コンテキスト、制約を提供する。
- エージェントこれを動作優先の要件とシナリオに変換する。
- エージェントは実装の詳細を
design.mdやtasks.mdに保持し、spec.mdには書かない。 - 検証は実装前に構造と明確さを確認する。
これにより、仕様は人間にとって読みやすく、エージェントにとって一貫性のあるものになります。
Changes（変更）
変更は、システムへの提案された修正であり、理解と実装に必要なすべてを含むフォルダとしてパッケージ化されます。
変更の構造
openspec/changes/add-dark-mode/
├── proposal.md # なぜ、何を
├── design.md # どのように（技術的アプローチ）
├── tasks.md # 実装チェックリスト
├── .openspec.yaml # 変更メタデータ（オプション）
└── specs/ # デルタ仕様
└── ui/
└── spec.md # ui/spec.md の変更内容各変更は自己完結しています。以下を含みます：
- アーティファクト — 意図、設計、タスクを捉える文書
- デルタ仕様 — 追加、変更、削除される内容の仕様
- メタデータ — この特定の変更のためのオプションの設定
なぜ変更はフォルダなのか
変更をフォルダとしてパッケージ化することにはいくつかの利点があります：
すべてが一か所に。 提案、設計、タスク、仕様がすべて一つの場所にあります。異なる場所を探し回る必要はありません。
並行作業。 複数の変更が競合せずに同時に存在できます。
fix-auth-bugが進行中でもadd-dark-modeに取り組めます。クリーンな履歴。 アーカイブされると、変更は完全なコンテキストを保持したまま
changes/archive/に移動します。何が変更されたかだけでなく、なぜ変更されたかを振り返って理解できます。レビューしやすい。 変更フォルダはレビューしやすいです — 開いて、提案を読み、設計を確認し、仕様のデルタを確認します。
Artifacts（アーティファクト）
アーティファクトは、作業を導く変更内の文書です。
アーティファクトのフロー
proposal ──────► specs ──────► design ──────► tasks ──────► implement
│ │ │ │
なぜ 何を どのように 取るべき
+ 範囲 変更内容 アプローチ ステップアーティファクトは互いに構築されます。各アーティファクトは次のものにコンテキストを提供します。
アーティファクトの種類
Proposal（proposal.md）
提案は、意図、範図、アプローチを高レベルで捉えます。
markdown
# Proposal: Add Dark Mode
## Intent
ユーザーは、夜間使用時の目の疲れを軽減し、システムの設定に合わせるためのダークモードオプションを要望しています。
## Scope
対象範囲内：
- 設定のテーマ切り替え
- システム設定の検出
- localStorageに設定を保存
対象範囲外：
- カスタムカラーテーマ（将来の作業）
- ページごとのテーマ上書き
## Approach
テーマ付けにはCSSカスタムプロパティを使用し、状態管理にはReactコンテキストを使用します。初回読み込み時にシステム設定を検出し、手動での上書きを許可します。提案を更新するタイミング：
- 範囲の変更（狭めること、拡大すること）
- 意図が明確になる（問題のより良い理解）
- アプローチが根本的に変化する
Specs（specs/ 内のデルタ仕様）
デルタ仕様は、現在の仕様に対して何が変更されるかを記述します。以下の Delta Specs を参照してください。
Design（design.md）
設計は技術的アプローチとアーキテクチャの決定を捉えます。
markdown
# Design: Add Dark Mode
## Technical Approach
テーマの状態は、プロップドリリングを避けるためReactコンテキストで管理します。
CSSカスタムプロパティにより、クラスの切り替えなしにランタイムで切り替えが可能になります。
## アーキテクチャの決定
### 決定：ReduxではなくContextの選択
テーマの状態管理にReact Contextを使用する理由：
- 単純なバイナリ状態（ライト/ダーク）
- 複雑な状態遷移が不要
- Reduxの依存関係を追加しない
### 決定：CSSカスタムプロパティ
CSS-in-JSではなくCSS変数を使用する理由：
- 既存のスタイルシートと連携可能
- ランタイムオーバーヘッドなし
- ブラウザネイティブのソリューション
## データフロー
```
ThemeProvider (コンテキスト)
│
▼
ThemeToggle ◄──► localStorage
│
▼
CSS Variables (適用先: :root)
```
## ファイル変更
- `src/contexts/ThemeContext.tsx`（新規）
- `src/components/ThemeToggle.tsx`（新規）
- `src/styles/globals.css`（変更済み）デザインを更新すべきタイミング：
- 実装の過程で、そのアプローチが機能しないことが判明した場合
- より良い解決策が見つかった場合
- 依存関係や制約が変更された場合
タスク（tasks.md）
タスクは実装チェックリストです。チェックボックス付きの具体的なステップです。
markdown
# タスク
## 1. テーマインフラストラクチャ
- [ ] 1.1 ライト/ダーク状態を持つThemeContextを作成
- [ ] 1.2 色のためのCSSカスタムプロパティを追加
- [ ] 1.3 localStorage永続化を実装
- [ ] 1.4 システム設定の検出を追加
## 2. UIコンポーネント
- [ ] 2.1 ThemeToggleコンポーネントを作成
- [ ] 2.2 設定ページにトグルを追加
- [ ] 2.3 ヘッダーにクイックトグルを追加
## 3. スタイリング
- [ ] 3.1 ダークテーマのカラーパレットを定義
- [ ] 3.2 コンポーネントをCSS変数を使用するよう更新
- [ ] 3.3 アクセシビリティのためのコントラスト比をテストタスクのベストプラクティス：
- 関連するタスクを見出しの下にグループ化する
- 階層的な番号付け（1.1、1.2など）を使用する
- タスクは1回のセッションで完了できる程度の小ささを保つ
- 完了したタスクにチェックを入れる
デルタ仕様
デルタ仕様は、OpenSpecがグリーンフィールド開発ではなく、ブラウンフィールド開発に適応するための重要な概念です。仕様全体を再記述するのではなく、何が変更されるかを記述します。
フォーマット
markdown
# 認証のデルタ
## 追加された要件
### 要件: 二要素認証
システムはTOTPベースの二要素認証を**must**サポートする。
#### シナリオ: 2FA登録
- GIVEN 2FAが有効になっていないユーザー
- WHEN ユーザーが設定で2FAを有効にする
- THEN 認証アプリのセットアップ用にQRコードが表示される
- AND ユーザーは有効化前にコードで検証する必要がある
#### シナリオ: 2FAログイン
- GIVEN 2FAが有効なユーザー
- WHEN ユーザーが有効な資格情報を送信する
- THEN OTPチャレンジが提示される
- AND 有効なOTPの後にのみログインが完了する
## 変更された要件
### 要件: セッションの有効期限
システムは15分間の非アクティブ後にセッションを期限切れに**must**する。
（以前：30分）
#### シナリオ: アイドルタイムアウト
- GIVEN 認証済みセッション
- WHEN アクティビティなしで15分が経過する
- THEN セッションが無効になる
## 削除された要件
### 要件: ログイン状態を保持
（2FAに代わり廃止。ユーザーは各セッションで再認証する必要がある。）デルタセクション
| セクション | 意味 | アーカイブ時の処理 |
|---|---|---|
## 追加された要件 | 新しい動作 | メイン仕様に追加 |
## 変更された要件 | 変更された動作 | 既存の要件を置換 |
## 削除された要件 | 廃止された動作 | メイン仕様から削除 |
なぜフル仕様ではなくデルタなのか
明確さ。 デルタは正確に何が変更されるかを示します。フル仕様を読むと、現在のバージョンとの差分を頭の中で比較する必要があります。
競合の回避。 2つの変更が同じ仕様ファイルに影響を与えることができます。異なる要件を変更する限り、競合しません。
レビュー効率。 レビュアーは変更のみを確認し、変更されていないコンテキストは確認しません。重要なことに集中できます。
ブラウンフィールドへの適合。 ほとんどの作業は既存の動作を変更します。デルタは変更を第一級のものとし、後付けにしません。
スキーマ
スキーマは、ワークフローの成果物の種類とその依存関係を定義します。
スキーマの仕組み
yaml
# openspec/schemas/spec-driven/schema.yaml
name: spec-driven
artifacts:
- id: proposal
generates: proposal.md
requires: [] # 依存関係なし、最初に作成可能
- id: specs
generates: specs/**/*.md
requires: [proposal] # 作成前にproposalが必要
- id: design
generates: design.md
requires: [proposal] # specsと並行して作成可能
- id: tasks
generates: tasks.md
requires: [specs, design] # specsとdesignの両方が先に必要成果物は依存関係グラフを形成します：
proposal
（ルートノード）
│
┌─────────────┴─────────────┐
│ │
▼ ▼
specs design
（requires: （requires:
proposal) proposal)
│ │
└─────────────┬─────────────┘
│
▼
tasks
（requires:
specs, design）依存関係は有効化であり、ゲートではありません。 何を作成可能かを示すものであり、次に何を作成しなければならないかを示すものではありません。必要なければdesignをスキップできます。specsはdesignの前後に作成できます。どちらもproposalにのみ依存します。
組み込みスキーマ
spec-driven（デフォルト）
仕様駆動開発のための標準ワークフロー：
proposal → specs → design → tasks → implement最適：実装前に仕様に合意したい、ほとんどの機能開発。
カスタムスキーマ
チームのワークフローに合わせたカスタムスキーマを作成：
bash
# 新規作成
openspec schema init research-first
# 既存のスキーマをフォーク
openspec schema fork spec-driven research-firstカスタムスキーマの例：
yaml
# openspec/schemas/research-first/schema.yaml
name: research-first
artifacts:
- id: research
generates: research.md
requires: [] # まず調査を行う
- id: proposal
generates: proposal.md
requires: [research] # 調査に基づいた提案
- id: tasks
generates: tasks.md
requires: [proposal] # specs/designをスキップし、直接タスクへカスタムスキーマの作成と使用の詳細については、カスタマイズを参照してください。
アーカイブ
アーカイブは、変更のデルタ仕様をメイン仕様にマージし、変更を履歴として保存することで、変更を完了させます。
アーカイブ時に何が起こるか
アーカイブ前：
openspec/
├── specs/
│ └── auth/
│ └── spec.md ◄────────────────┐
└── changes/ │
└── add-2fa/ │
├── proposal.md │
├── design.md │ マージ
├── tasks.md │
└── specs/ │
└── auth/ │
└── spec.md ─────────┘
アーカイブ後：
openspec/
├── specs/
│ └── auth/
│ └── spec.md # 2FA要件を含むようになった
└── changes/
└── archive/
└── 2025-01-24-add-2fa/ # 履歴として保存
├── proposal.md
├── design.md
├── tasks.md
└── specs/
└── auth/
└── spec.mdアーカイブプロセス
デルタをマージする。 各デルタ仕様セクション（追加/変更/削除）が対応するメイン仕様に適用される。
アーカイブに移動する。 変更フォルダは日付プレフィックス付きで
changes/archive/に移動し、時系列順に並べられる。コンテキストを保存する。 すべての成果物はアーカイブに完全に残る。変更がなぜ行われたかを理解するために、いつでも振り返ることができる。
アーカイブが重要な理由
クリーンな状態。 アクティブな変更（changes/）は進行中の作業のみを表示する。完了した作業は邪魔にならない。
監査証跡。 アーカイブはすべての変更の完全なコンテキストを保存する。何が変更されたかだけでなく、なぜ変更されたかを説明する提案、どのように変更されたかを説明する設計、行われた作業を示すタスクを含む。
仕様の進化。 変更がアーカイブされるにつれて、仕様は有機的に成長する。各アーカイブはデルタをマージし、時間とともに包括的な仕様を構築する。
すべてがどのように組み合わさるか
┌──────────────────────────────────────────────────────────────────────────────┐
│ OPENSPECフロー │
│ │
│ ┌────────────────┐ │
│ │ 1. 変更を │ /opsx:propose（コア）または /opsx:new（拡張） │
│ │ 開始する │ │
│ └───────┬────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────┐ │
│ │ 2. 成果物を │ /opsx:ff または /opsx:continue（拡張ワークフロー） │
│ │ 作成する │ proposal → specs → design → tasks を作成 │
│ │ │ （スキーマの依存関係に基づく） │
│ └───────┬────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────┐ │
│ │ 3. タスクを │ /opsx:apply │
│ │ 実装する │ タスクを進め、チェックを入れる │
│ │ │◄──── 学んだことに基づいて成果物を更新 │
│ └───────┬────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────┐ │
│ │ 4. 作業を │ /opsx:verify（オプション） │
│ │ 検証する │ 実装が仕様と一致するか確認する │
│ └───────┬────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────┐ ┌──────────────────────────────────────────────┐ │
│ │ 5. 変更を │────►│ デルタ仕様がメイン仕様にマージされる │ │
│ │ アーカイブ │ │ 変更フォルダがarchive/に移動される │ │
│ │ する │ │ 仕様は更新された信頼できる情報源となる │ │
│ └────────────────┘ └──────────────────────────────────────────────┘ │
│ │
└──────────────────────────────────────────────────────────────────────────────┘良性サイクル：
- 仕様は現在の動作を記述する
- 変更は修正を提案する（デルタとして）
- 実装は変更を現実にする
- アーカイブはデルタを仕様にマージする
- 仕様は新しい動作を記述する
- 次の変更は更新された仕様に基づいて構築する
用語集
| 用語 | 定義 |
|---|---|
| Artifact | 変更内のドキュメント（提案、設計、タスク、またはデルタ仕様） |
| Archive | 変更を完了し、そのデルタをメイン仕様にマージするプロセス |
| Change | システムへの提案された変更。アーティファクトを含むフォルダとしてパッケージ化される |
| Delta spec | 現在の仕様に対して変更（追加/変更/削除）を記述する仕様 |
| Domain | 仕様の論理的なグループ（例：auth/、payments/） |
| Requirement | システムが持つべき特定の動作 |
| Scenario | 要件の具体的な例。通常、Given/When/Then形式で記述される |
| Schema | アーティファクトの種類とその依存関係の定義 |
| Spec | システムの動作を記述する仕様。要件とシナリオを含む |
| Source of truth | 現在合意された動作を含むopenspec/specs/ディレクトリ |
次のステップ
- Getting Started - 実践的な最初のステップ
- Workflows - 一般的なパターンと各パターンの使用タイミング
- Commands - コマンドの完全なリファレンス
- Customization - カスタムスキーマの作成とプロジェクトの設定