コンセプト

このガイドでは、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/              │   │
│   │                     │      │                               │   │
│   │  信頼できる情報源    │◄─────│  提案された修正               │   │
│   │  システムの現在の    │ merge│  各変更 = 1つのフォルダ       │   │
│   │  動作方法           │      │  アーティファクトと差分を含む │   │
│   │                     │      │                               │   │
│   └─────────────────────┘      └───────────────────────────────┘   │
│                                                                    │
└────────────────────────────────────────────────────────────────────┘

仕様 (Specs) は信頼できる情報源です — システムの現在の動作を記述します。

変更 (Changes) は提案された修正です — マージする準備が整うまで、個別のフォルダに置かれます。

この分離が重要です。競合なく複数の変更を並行して作業できます。メインの仕様に影響を与える前に変更をレビューできます。変更をアーカイブすると、その差分は信頼できる情報源にきれいにマージされます。

調整ワークスペース

ワークスペースのサポートは現在開発中であり、まだ使用する準備ができていません。ワークスペースの動作に基づいて外部の自動化、統合、または長期間のワークフローを構築しないでください。コマンド、状態ファイル、およびJSON出力はいつでも変更される可能性があります。

以下のコマンドは、リンクされたリポジトリまたはフォルダ全体の計画のための初期セットアップフローを提供します。

リポジトリローカルなOpenSpecプロジェクトは、1つのリポジトリが計画、実装、およびアーカイブフローを所有する場合の適切なデフォルトです。一部の作業は複数のリポジトリまたはフォルダにまたがります。その場合、OpenSpec調整ワークスペースが永続的な計画の拠点となります。

ワークスペースのメンタルモデルは次のとおりです：

text

workspace = 関連するクロスリポジトリの変更が存在する場所
link      = ワークスペースが計画できるリポジトリまたはフォルダの安定した名前
change    = 1つの機能、修正、プロジェクト、またはその他の計画された作業

ワークスペースはリポジトリローカルプロジェクトとは異なる構造を持ちます：

text

workspace-folder/
├── changes/                       # ワークスペースレベルの計画
└── .openspec-workspace/
    ├── workspace.yaml             # 共有ワークスペースの識別情報とリンク名
    └── local.yaml                 # このマシンのローカルパス

リポジトリローカルなOpenSpec状態は既存の構造を維持します：

text

repo-root/
└── openspec/
    ├── specs/
    └── changes/

この区別は重要です。ワークスペースフォルダは、リンクされたリポジトリまたはフォルダ全体の計画のための調整面です。各リポジトリの openspec/ ディレクトリは、リポジトリが所有する仕様、リポジトリローカルな変更、および実装計画の拠点であり続けます。ユーザーはワークスペースフォルダ内でリポジトリローカルな openspec init を実行する必要はありません。

安定したリンク名は、ワークスペース計画がリポジトリおよびフォルダを参照する方法です。共有ワークスペース状態は api、web、checkout などの名前を保持し、各マシンは .openspec-workspace/local.yaml 内でそれらの名前を自身のローカルパスにマッピングします。

yaml

# .openspec-workspace/workspace.yaml
version: 1
name: platform
links:
  api: {}
  web: {}

yaml

# .openspec-workspace/local.yaml
version: 1
paths:
  api: /repos/api
  web: /repos/web

OpenSpecで作成されたワークスペースは、デフォルトで .openspec-workspace/local.yaml をポータブルな共同作業状態から除外します。.openspec-workspace/workspace.yaml はワークスペース名と安定したリンク名を格納し、特定のユーザーの絶対チェックアウトパスを格納しないため、ポータブルであり続けます。

リンクされたパスは、完全なリポジトリ、大きなモノリポ内のフォルダ、またはその他の既存のフォルダにすることができます。ワークスペース計画に参加する前に、リポジトリローカルな openspec/ 状態は必要ありません。後の実装、検証、またはアーカイブのワークフローでは、より多くのリポジトリの準備が必要になる場合がありますが、計画の可視性はリンクから始まります。

text

multi-repo:
  api      -> /repos/api
  web      -> /repos/web

large monorepo:
  billing  -> /repos/platform/services/billing
  checkout -> /repos/platform/apps/checkout

管理されたワークスペースは、標準のOpenSpecデータディレクトリの下に存在します：

text

getGlobalDataDir()/workspaces

これは、XDG_DATA_HOME が設定されている場合は $XDG_DATA_HOME/openspec/workspaces、Unixスタイルのフォールバックでは ~/.local/share/openspec/workspaces、ネイティブWindowsのフォールバックでは %LOCALAPPDATA%\openspec\workspaces を意味します。ネイティブWindowsシェル、PowerShell、およびWSL2はそれぞれ、OpenSpecを実行しているランタイムのパス文字列を保持します。この基盤は、D:\repo、/mnt/d/repo、およびUNC WSLパス間で変換されません。

OpenSpecは、マシンローカルなレジストリも維持します：

text

getGlobalDataDir()/workspaces/registry.yaml

レジストリはワークスペース名をワークスペースの場所にマッピングし、後のグローバルコマンドがどこからでも既知のワークスペースを一覧表示または選択できるようにします。これは単なるインデックスです。各ワークスペースフォルダは、自身の .openspec-workspace/workspace.yaml および .openspec-workspace/local.yaml に対して権威があり続けるため、古いレジストリレコードは、ワークスペース自体を再定義せずに報告および修復できます。

ワークスペースの可視性は変更のコミットメントではありません。OpenSpecが関連するリポジトリまたはフォルダを認識すべき場合にワークスペースをセットアップし、後で機能、修正、プロジェクト、またはその他の作業を計画する準備ができたときに変更を作成します。

便利なコマンド：

bash

# ガイド付きセットアップ
openspec workspace setup

# 自動化に適したセットアップ
openspec workspace setup --no-interactive --name platform --link /repos/api --link web=/repos/web
openspec workspace setup --no-interactive --name platform --link /repos/api --opener codex

# ローカルレジストリから既知のワークスペースを表示
openspec workspace list
openspec workspace ls

# 選択されたワークスペースのリンクを追加または修復
openspec workspace link /repos/api
openspec workspace link api-service /repos/api
openspec workspace relink api-service /new/path/to/api

# このマシンが解決できるものを確認
openspec workspace doctor
openspec workspace doctor --workspace platform

# リンクされた作業セットを開く
openspec workspace open
openspec workspace open platform --agent github-copilot
openspec workspace open --editor

workspace setup は常に標準のワークスペース場所にワークスペースを作成し、ローカルレジストリに記録し、ワークスペースの場所を表示し、少なくとも1つのリンクされたリポジトリまたはフォルダを必要とします。インタラクティブセットアップでは、優先オープナーを尋ねます。非インタラクティブセットアップでは、--opener codex、--opener claude、--opener github-copilot、または --opener editor が提供された場合にのみ、1つを保存します。

OpenSpecは、ルートワークスペースオープンファイルも維持します：AGENTS.md 内のOpenSpec管理ガイダンスブロック、VS CodeおよびGitHub Copilot-in-VS-Codeのオープン用のマシンローカルな <workspace-name>.code-workspace ファイル、およびその管理された .code-workspace ファイルの特定の無視エントリ。ユーザーが作成した *.code-workspace ファイルは、無視ルールが管理されたファイルのみを対象とするため、追跡可能なままです。

管理されたVS Codeワークスペースには、調整ルートとして . と、有効なリンクされたリポジトリまたはフォルダが追加ルートとして含まれます。VS Codeはこれらのエントリをマルチルートワークスペースとして表示します。

workspace open は、そのセッションのために --agent <tool> または --editor が渡されない限り、保存された優先オープナーでリンクされた作業セットを開きます。両方のオープナーオーバーライドを渡すことはエラーです。ルートワークスペースオープンにより、リンクされたリポジトリおよびフォルダが探索と計画のために可視化されます。実装は、ユーザーが明示的に実装作業を要求した後に開始されます。

workspace link および workspace relink は既存のフォルダのみを記録します。リンクされたリポジトリまたはフォルダを作成、コピー、移動、初期化、または編集しません。リンクまたはリリンクが成功した後、OpenSpecは管理ガイダンス、VS Codeワークスペースファイル、および無視ルールを更新します。

1つのワークスペースが必要なワークスペースコマンドは、--workspace <name> を使用してどこからでも実行できます。ワークスペースフォルダまたはサブディレクトリ内で実行すると、OpenSpecはその現在のワークスペースを使用します。複数の既知のワークスペースが利用可能で、--workspace <name> を渡さない場合、人間のコマンドはピッカーを表示します。--json および --no-interactive は、プロンプトの代わりに構造化されたステータスエラーで失敗します。

直接ワークスペースコマンドは、スクリプト用のJSON出力をサポートします。JSON応答は、主要なデータを workspace、workspaces、または link オブジェクトに保持し、警告またはエラーを status 配列で報告します。正常なオブジェクトは status: [] を使用します。

仕様

仕様は、構造化された要件とシナリオを使用してシステムの動作を記述します。

構造

openspec/specs/
├── auth/
│   └── spec.md           # 認証動作
├── payments/
│   └── spec.md           # 支払い処理
├── notifications/
│   └── spec.md           # 通知システム
└── ui/
    └── spec.md           # UIの動作とテーマ

仕様をドメイン別に整理します — システムにとって理にかなった論理的なグループです。一般的なパターン：

機能領域別: auth/、payments/、search/
コンポーネント別: api/、frontend/、workers/
境界付きコンテキスト別: ordering/、fulfillment/、inventory/

仕様のフォーマット

仕様には要件が含まれ、各要件にはシナリオがあります：

markdown

# Auth Specification

目的

アプリケーションの認証とセッション管理。

要件

要件: ユーザー認証

システムは、ログイン成功時にJWTトークンを発行するものとします。

シナリオ: 有効な認証情報

有効な認証情報を持つユーザーが
ログインフォームを送信すると
JWTトークンが返される
かつ、ユーザーはダッシュボードにリダイレクトされる

シナリオ: 無効な認証情報

無効な認証情報が
ログインフォームに送信されると
エラーメッセージが表示される
かつ、トークンは発行されない

要件: セッション有効期限

システムは、30分間の非アクティブ後にセッションを期限切れにしなければなりません。

シナリオ: アイドルタイムアウト

認証済みのセッションが
30分間アクティビティなしで経過すると
セッションは無効化される
かつ、ユーザーは再認証が必要になる


**主要な要素:**

| 要素 | 目的 |
|---------|---------|
| `## 目的` | この仕様の領域の高レベルな説明 |
| `### 要件:` | システムが持つべき特定の動作 |
| `#### シナリオ:` | 要件の具体的な実行例 |
| SHALL/MUST/SHOULD | 要件の強度を示すRFC 2119キーワード |

### なぜこのように仕様を構造化するのか

**要件は「何を」か** — 実装を指定せずに、システムが何をすべきかを述べます。

**シナリオは「いつ」か** — 検証可能な具体的な例を提供します。良いシナリオは：
- テスト可能（自動テストを記述できる）
- ハッピーパスとエッジケースの両方をカバー
- Given/When/Thenまたは同様の構造化された形式を使用

**RFC 2119キーワード**（SHALL、MUST、SHOULD、MAY）は意図を伝えます：
- **MUST/SHALL** — 絶対的な要件
- **SHOULD** — 推奨、ただし例外あり
- **MAY** — 任意

### 仕様とは何か（そして何でないか）

仕様は**動作契約**であり、実装計画ではありません。

良い仕様の内容：
- ユーザーやダウンストリームシステムが依存する観察可能な動作
- 入力、出力、エラー条件
- 外部制約（セキュリティ、プライバシー、信頼性、互換性）
- テストまたは明示的に検証可能なシナリオ

仕様で避けるべきこと：
- 内部のクラス/関数名
- ライブラリやフレームワークの選択
- ステップバイステップの実装詳細
- 詳細な実行計画（これらは`design.md`または`tasks.md`に属します）

簡単なテスト：
- 実装を変更しても外部から見える動作が変わらない場合、それは仕様に属さない可能性が高い。

### 軽量さを保つ：段階的な厳密さ

OpenSpecは官僚主義を避けます。変更を検証可能にする最小限のレベルを使用します。

**Lite仕様（デフォルト）：**
- 短い動作中心の要件
- 明確なスコープと非目標
- 具体的な受け入れチェックをいくつか

**完全な仕様（より高いリスクの場合）：**
- チーム横断またはリポジトリ横断の変更
- API/契約の変更、移行、セキュリティ/プライバシーの懸念
- 曖昧さが高価な再作業につながりやすい変更

ほとんどの変更はLiteモードに留まるべきです。

### 人間 + エージェントのコラボレーション

多くのチームでは、人間が探索し、エージェントが成果物を起草します。意図されたループは：

1. 人間が意図、コンテキスト、制約を提供する。
2. エージェントがこれを動作中心の要件とシナリオに変換する。
3. エージェントは実装の詳細を`design.md`と`tasks.md`に保持し、`spec.md`には保持しない。
4. 検証は、実装前に構造と明確さを確認する。

これにより、仕様は人間にとって読みやすく、エージェントにとって一貫性のあるものになります。

## 変更

変更とは、システムへの提案された修正であり、その内容を理解し実装するために必要なすべてがフォルダとしてパッケージ化されたものです。

### 変更の構造

openspec/changes/add-dark-mode/ ├── proposal.md # 理由と内容 ├── design.md # 方法（技術的アプローチ） ├── tasks.md # 実装チェックリスト ├── .openspec.yaml # 変更メタデータ（オプション） └── specs/ # デルタ仕様 └── ui/ └── spec.md # ui/spec.mdの変更内容


各変更は自己完結しています。以下を含みます：
- **成果物** — 意図、設計、タスクを文書化したもの
- **デルタ仕様** — 追加、修正、または削除される内容の仕様
- **メタデータ** — この特定の変更のオプション設定

### 変更がフォルダである理由

変更をフォルダとしてパッケージ化することには、いくつかの利点があります：

1. **すべてが一箇所に。** 提案、設計、タスク、仕様が一箇所に集約されます。異なる場所を探し回る必要がありません。

2. **並行作業。** 複数の変更が競合せずに同時に存在できます。`add-dark-mode`の作業中に`fix-auth-bug`も進行中にしておくことができます。

3. **クリーンな履歴。** アーカイブされると、変更は完全なコンテキストを保持したまま`changes/archive/`に移動します。何が変更されたかだけでなく、なぜ変更されたかを振り返って理解できます。

4. **レビューしやすい。** 変更フォルダはレビューしやすいです — 開いて、提案を読み、設計を確認し、仕様の差分を確認できます。

## 成果物

成果物とは、作業を導く変更内の文書です。

### 成果物の流れ

proposal ──────► specs ──────► design ──────► tasks ──────► implement │ │ │ │ why what how steps

scope changes approach to take


成果物は相互に構築されます。各成果物は次の成果物のためのコンテキストを提供します。

### 成果物の種類

#### 提案 (`proposal.md`)

提案は、高レベルで**意図**、**範囲**、および**アプローチ**を捉えます。

```markdown
# 提案: ダークモードの追加

## 意図
ユーザーは、夜間の使用時の目の疲れを軽減し、システム設定に合わせるために、ダークモードオプションを要望しています。

## 範囲
範囲内:
- 設定でのテーマ切り替え
- システム設定の検出
- localStorageでの設定の永続化

範囲外:
- カスタムカラーテーマ（将来の作業）
- ページごとのテーマオーバーライド

## アプローチ
ステート管理にReactコンテキストを使用し、CSSカスタムプロパティでテーマ設定を行います。初回読み込み時にシステム設定を検出し、手動での上書きを可能にします。

提案を更新すべきタイミング：

範囲が変更された場合（狭まるか広がるか）
意図が明確になった場合（問題のより良い理解）
アプローチが根本的に変更された場合

仕様 (`specs/` 内のデルタ仕様)

デルタ仕様は、現在の仕様に対する変更内容を記述します。以下のデルタ仕様を参照してください。

設計 (`design.md`)

設計は、技術的アプローチとアーキテクチャの決定を捉えます。

markdown

# 設計: ダークモードの追加

## 技術的アプローチ
プロップスドリリングを避けるため、Reactコンテキストでテーマ状態を管理します。CSSカスタムプロパティにより、クラスの切り替えなしにランタイムでの切り替えが可能になります。

## アーキテクチャの決定

### 決定: Reduxではなくコンテキスト
テーマ状態にReactコンテキストを使用する理由：
- シンプルな二値状態（ライト/ダーク）
- 複雑な状態遷移がない
- Reduxの依存関係を追加しない

### 決定: CSSカスタムプロパティ
CSS-in-JSではなくCSS変数を使用する理由：
- 既存のスタイルシートと互換性がある
- ランタイムオーバーヘッドがない
- ブラウザネイティブのソリューション

## データフロー
```
ThemeProvider (context)
       │
       ▼
ThemeToggle ◄──► localStorage
       │
       ▼
CSS Variables (applied to :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

# Authのデルタ

## 追加要件

### 要件: 二要素認証
システムはTOTPベースの二要素認証をサポートしなければなりません。

#### シナリオ: 2FA登録
- 前提: 2FAが有効でないユーザー
- 操作: ユーザーが設定で2FAを有効にする
- 結果: 認証アプリのセットアップ用QRコードが表示される
- かつ: ユーザーは有効化前にコードで検証する必要がある

#### シナリオ: 2FAログイン
- 前提: 2FAが有効なユーザー
- 操作: ユーザーが有効な資格情報を送信する
- 結果: OTPチャレンジが提示される
- かつ: 有効なOTPの後のみログインが完了する

## 修正要件

### 要件: セッション有効期限
システムは15分間の非アクティブ後にセッションを期限切れにしなければなりません。
（以前：30分）

#### シナリオ: アイドルタイムアウト
- 前提: 認証済みセッション
- 操作: アクティビティなしで15分が経過する
- 結果: セッションが無効化される

## 削除要件

### 要件: ログイン状態を保持
（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（デフォルト）

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]   # リサーチに基づいたproposal

  - id: tasks
    generates: tasks.md
    requires: [proposal]   # specs/designをスキップし、直接tasksへ

カスタムスキーマの作成と使用の詳細については、カスタマイズを参照してください。

アーカイブ

アーカイブは、変更のデルタ仕様をメイン仕様にマージし、変更を履歴として保存することで、変更を完了させます。

アーカイブ時に何が起こるか

アーカイブ前：

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

アーカイブプロセス

デルタをマージします。 各デルタ仕様セクション（ADDED/MODIFIED/REMOVED）が対応するメイン仕様に適用されます。
アーカイブに移動します。 変更フォルダは、時系列順に並べるための日付プレフィックスを付けてchanges/archive/に移動します。
コンテキストを保存します。 すべての成果物はアーカイブ内にそのまま残ります。変更が行われた理由をいつでも振り返ることができます。

アーカイブが重要な理由

クリーンな状態。 アクティブな変更（changes/）には進行中の作業のみが表示されます。完了した作業は邪魔にならない場所に移動します。

監査証跡。 アーカイブは、すべての変更の完全なコンテキストを保存します。何が変更されたかだけでなく、その理由を説明するproposal、方法を説明するdesign、そして行われた作業を示すtasksが含まれます。

仕様の進化。 変更がアーカイブされるにつれて、仕様は有機的に成長します。各アーカイブはそのデルタをマージし、時間とともに包括的な仕様を構築していきます。

全体の連携

┌──────────────────────────────────────────────────────────────────────────────┐
│                              OPENSPEC フロー                                 │
│                                                                              │
│   ┌────────────────┐                                                         │
│   │  1. 開始       │  /opsx:propose（コア）または /opsx:new（拡張）           │
│   │     変更       │                                                         │
│   └───────┬────────┘                                                         │
│           │                                                                  │
│           ▼                                                                  │
│   ┌────────────────┐                                                         │
│   │  2. 作成       │  /opsx:ff または /opsx:continue（拡張ワークフロー）       │
│   │     成果物     │  proposal → specs → design → tasks を作成               │
│   │                │  （スキーマの依存関係に基づく）                           │
│   └───────┬────────┘                                                         │
│           │                                                                  │
│           ▼                                                                  │
│   ┌────────────────┐                                                         │
│   │  3. 実装       │  /opsx:apply                                            │
│   │     タスク     │  タスクを進め、完了チェックを入れる                      │
│   │                │◄──── 学んだことに基づき成果物を更新                      │
│   └───────┬────────┘                                                         │
│           │                                                                  │
│           ▼                                                                  │
│   ┌────────────────┐                                                         │
│   │  4. 検証       │  /opsx:verify（オプション）                              │
│   │     作業       │  実装が仕様と一致するか確認                              │
│   └───────┬────────┘                                                         │
│           │                                                                  │
│           ▼                                                                  │
│   ┌────────────────┐     ┌──────────────────────────────────────────────┐    │
│   │  5. アーカイブ │────►│  デルタ仕様がメイン仕様にマージされる         │    │
│   │     変更       │     │  変更フォルダがarchive/に移動する             │    │
│   └────────────────┘     │  仕様が更新された信頼の唯一の情報源となる     │    │
│                          └──────────────────────────────────────────────┘    │
│                                                                              │
└──────────────────────────────────────────────────────────────────────────────┘

好循環：

仕様が現在の動作を記述する
変更が修正を提案する（デルタとして）
実装が変更を現実のものにする
アーカイブがデルタを仕様にマージする
仕様が新しい動作を記述する
次の変更が更新された仕様に基づいて行われる

用語集

用語	定義
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/`ディレクトリ

次のステップ

はじめに - 実践的な最初のステップ
ワークフロー - 一般的なパターンと各パターンの使用タイミング
コマンド - 完全なコマンドリファレンス
カスタマイズ - カスタムスキーマの作成とプロジェクトの設定

コンセプト ​

哲学 ​

これらの原則が重要な理由 ​

全体像 ​

調整ワークスペース ​

仕様 ​

構造 ​

仕様のフォーマット ​

目的 ​

要件 ​

要件: ユーザー認証 ​

シナリオ: 有効な認証情報 ​

シナリオ: 無効な認証情報 ​

要件: セッション有効期限 ​

シナリオ: アイドルタイムアウト ​

仕様 (specs/ 内のデルタ仕様) ​

設計 (design.md) ​

タスク (tasks.md) ​

デルタ仕様 ​

フォーマット ​

デルタセクション ​

なぜデルタ仕様なのか ​

スキーマ ​

スキーマの仕組み ​

組み込みスキーマ ​

カスタムスキーマ ​

アーカイブ ​

アーカイブ時に何が起こるか ​

アーカイブプロセス ​

アーカイブが重要な理由 ​

全体の連携 ​

用語集 ​

次のステップ ​

コンセプト

哲学

これらの原則が重要な理由

全体像

調整ワークスペース

仕様

構造

仕様のフォーマット

目的

要件

要件: ユーザー認証

シナリオ: 有効な認証情報

シナリオ: 無効な認証情報

要件: セッション有効期限

シナリオ: アイドルタイムアウト

仕様 (`specs/` 内のデルタ仕様)

設計 (`design.md`)

タスク (`tasks.md`)

デルタ仕様

フォーマット

デルタセクション

なぜデルタ仕様なのか

スキーマ

スキーマの仕組み

組み込みスキーマ

カスタムスキーマ

アーカイブ

アーカイブ時に何が起こるか

アーカイブプロセス

アーカイブが重要な理由

全体の連携

用語集

次のステップ