spec-driven

デフォルトワークフローの成果物：その順序、形式、および生成される変更フォルダ。

spec-driven は OpenSpec に組み込まれたデフォルトスキーマです。schema.yaml が、このスキーマが設定するフィールドを定義しています。

成果物

このワークフローでは、4つの成果物を作成します。

成果物	ファイル	目的
proposal	proposal.md	なぜその変更が必要なのか
specs	specs/<capability-path>/spec.md（機能ごとに1つ）	どのような動作が変化するのか
design	design.md	どのように構築するのか
tasks	tasks.md	実装チェックリスト

作成順序

             ┌─ specs ──┐
proposal ────┤          ├── tasks ── apply
             └─ design ─┘

proposal を最初に作成します。specs と design はどちらの順序で続いてもよく、tasks はその両方を必要とします。実装（apply）は tasks.md が揃った時点で開始されます。

次の 2 つの成果物はスキップできます:

• design: その条件のいずれにも該当しない場合、エージェントはこれを省略し、それでも tasks を作成します。
• specs: 変更の .openspec.yaml で skip_specs: true を設定します。

変更フォルダの例

すべての成果物を作成した、add-user-auth という名前の変更:

openspec/changes/add-user-auth/
├── .openspec.yaml      変更メタデータ。変更の作成時に書き込まれる
├── proposal.md
├── specs/
│   └── user-auth/
│       └── spec.md     ケイパビリティごとに 1 つのデルタ spec
├── design.md
└── tasks.md

proposal.md

この変更がなぜ必要なのかを明確にします。

構造

エージェントが出力フォーマットとして受け取るテンプレート（templates/proposal.md）:

# Proposal

## Why

<!-- Explain the motivation for this change. What problem does this solve? Why now? -->

## What Changes

<!-- Describe what will change. Be specific about new capabilities, modifications, or removals. -->

## Capabilities

### New Capabilities
<!-- Capabilities being introduced. Name each capability for a cohesive system
     behavior that can own related requirements as the system evolves. Do not name
     implementation tasks or proposal sections. Avoid broad catch-all names. Use
     kebab-case for path segments you introduce (e.g., user-auth or identity/user-auth)
     that follow the project's existing spec organization. Each creates
     specs/<capability-path>/spec.md. -->
- `<capability-path>`: <brief description of what this capability covers>

### Modified Capabilities
<!-- Existing capabilities whose REQUIREMENTS are changing (not just implementation).
     Only list here if spec-level behavior changes. Each needs a delta spec file.
     Use the exact existing path under openspec/specs/. Leave empty if no requirement
     changes. A change with no capabilities at all (pure refactor, tooling, docs)
     must set `skip_specs: true` in its .openspec.yaml - openspec validate rejects
     a zero-delta change without that marker. Do not invent a requirement just to
     satisfy validation. -->
- `<existing-capability-path>`: <what requirement is changing>

## Impact

<!-- Affected code, APIs, dependencies, systems -->

指示

この成果物を作成する際にエージェントへ送られる指示（schema.yaml より）:

この変更がなぜ必要なのか（WHY）を明確にする proposal ドキュメントを作成します。

セクション:
- **Why**: 問題または機会について 1〜2 文で記述します。この変更は何を解決するのか？ なぜ今なのか？
- **What Changes**: 変更点の箇条書き。新しいケイパビリティ、変更、削除について具体的に記述します。破壊的変更には **BREAKING** を付けます。
- **Capabilities**: どの spec が作成または変更されるかを特定します:
  - **New Capabilities**: 導入するケイパビリティを列挙します。それぞれが新しい `specs/<capability-path>/spec.md` になります。各ケイパビリティには、この変更における作業内容（例: `add-login-endpoint`）ではなく、持続的なシステムの振る舞い（例: `user-auth`）に基づく名前を付けます。システムの進化に伴って関連する要件を所有できる、まとまりのある境界を選び、広範な catch-all 的なケイパビリティは避けます。新しく導入するパスセグメントには kebab-case を使用し（例: `user-auth` または `identity/user-auth`）、プロジェクトの既存の spec 構成に従います。
  - **Modified Capabilities**: 要件（REQUIREMENTS）が変わる既存のケイパビリティを列挙します。spec レベルの振る舞いが変わる場合（実装詳細のみの変更ではない場合）に限ります。それぞれにデルタ spec ファイルが必要です。`openspec/specs/` 配下の既存のパスを正確に使用します。要件の変更がなければ空のままにします。
- **Impact**: 影響を受けるコード、API、依存関係、システム。

重要: Capabilities セクションは極めて重要です。これは proposal フェーズと
specs フェーズの間の契約を形成します。記入する前に既存の spec を調査してください:
`openspec list --specs` を実行してプロジェクトのケイパビリティ一覧を取得し、関連しそうな
ものについては `openspec show "<spec-id>" --type spec --json --no-scenarios` を実行します -
これにより、spec ファイル全体をコンテキストに読み込むことなく、ケイパビリティの目的と
要件テキストが返されます。`--store "<id>"` は、登録済みのスタンドアロンストアの場合にのみ
両方のコマンドに付け、`--type spec` は維持してください。そうしないと、同名の change と
spec が ambiguous-item エラーになります。`--specs` を付けない `openspec list` は
進行中の change を一覧するもので、spec ではありません - プロジェクトが既にカバーしている
内容は表示されません。似た名前を新たに導入するのではなく、既存ケイパビリティの正確な
パスを再利用してください。フィルタ付きの読み取りはあくまで概要です。何が既に
カバーされているか、何を変更すべきかを判断する前に、関連する各 spec をシナリオも含めて
全文を `openspec show "<spec-id>" --type spec` で読んでください（`--store` の規則は同じ）。
ここに列挙した各ケイパビリティには、対応する spec ファイルが必要です。

すべての変更は、少なくとも 1 つのケイパビリティ（新規または変更）を宣言するか、
spec を明示的にオプトアウトする必要があります: 変更の `.openspec.yaml` に
`skip_specs: true` が設定されていない限り、デルタが 0 件の変更は `openspec validate` に
よって拒否されます。`skip_specs: true` は spec レベルの振る舞いが変わらない場合
（純粋なリファクタリング、ツール、ドキュメント）にのみ使用します - spec は振る舞いを
記述するものなので、振る舞いが変わらないなら spec も変更すべきではありません。
バリデーションを通すためだけに要件をでっち上げないでください。

簡潔に保ってください（1〜2 ページ）。「why」に焦点を当て、「how」には踏み込まないで
ください - 実装の詳細は design.md に属します。

これは基盤です - specs、design、tasks はすべてこれの上に構築されます。

デルタ spec（spec.md）

どの振る舞いが変わるかを定義します。proposal に列挙されたケイパビリティごとに 1 つのデルタ spec を作成します。

各デルタ spec は、そのケイパビリティフォルダ内の spec.md です。specs/ 配下の他のファイル（例: specs/user-auth.md）に書かれたデルタセクションは、openspec validate と openspec archive によって拒否されます。archive はそれらをマージしないためです。

構造

エージェントが出力フォーマットとして受け取るテンプレート（templates/spec.md）:

# Spec Delta

## Purpose
<!-- New capabilities only: one or two sentences (50+ characters) on what this capability is for. Delete this section for an existing capability. -->

## ADDED Requirements

### Requirement: <!-- requirement name -->
<!-- requirement text -->

#### Scenario: <!-- scenario name -->
- **WHEN** <!-- condition -->
- **THEN** <!-- expected outcome -->

指示

この成果物を作成する際にエージェントへ送られる指示（schema.yaml より）:

システムが何を行うべきか（WHAT）を定義する spec ファイルを作成します。

spec は振る舞いの契約であり、実装計画ではありません。

良い spec の内容:
- ユーザーまたは下流のシステムが依存する、観測可能な振る舞い
- 入力、出力、エラー条件
- 外部制約（セキュリティ、プライバシー、信頼性、互換性）
- テストまたは明示的に検証できるシナリオ

spec で避けるべきもの:
- 内部的なクラス名／関数名
- ライブラリやフレームワークの選択
- 段階的な実装詳細
- 詳細な実行計画（これらは design.md または tasks.md に属します）

簡単なチェック: 外部から見える振る舞いを変えずに実装を変更できるなら、
それはおそらく spec に属しません。

proposal の Capabilities セクションに列挙されたケイパビリティごとに、1 つの spec ファイルを
作成します。`<capability-path>` は `specs/` からの相対パスである spec ディレクトリです（例:
`user-auth` または `identity/user-auth`）。パス全体を維持してください:
- 新規ケイパビリティ: proposal の正確なパスを `specs/<capability-path>/spec.md` として使用します。
  proposal で新たに導入するパスセグメントは kebab-case でなければなりません。プロジェクトの
  既存の構成に従ってください。プロジェクトがフラットなレイアウトを使用している場合は、
  新しいドメインレベルを追加しないでください。
- 変更ケイパビリティ: `specs/<capability-path>/spec.md` にデルタを作成する際は、
  `openspec/specs/<capability-path>/` 配下の既存の正確なパスを使用します。デルタを書く前に
  `openspec list --specs` を実行してそのパスを確認し、`--store "<id>"` は登録済みの
  スタンドアロンストアの場合にのみ付けてください - 誤って入力したパスやでっち上げたパスは、
  意図したケイパビリティではなく存在しないケイパビリティを対象にしてしまいます。
  ケイパビリティを移動したり名前を変更したりしないでください。

ユーザーが進捗を確認でき、実行が中断されても既に書き込んだファイルが残るよう、
spec ファイルは 1 つずつ作成してください:
- 何かを書き始める前に、proposal に列挙されたケイパビリティと、既に存在する
  `specs/<capability-path>/spec.md` ファイルを比較し、ファイルがまだない最初の
  ケイパビリティから始めます。ユーザーから依頼されない限り、既存のファイルを
  書き換えないでください。
- 各ファイルを書く前に、どのケイパビリティを書いているかを 1 行で伝えます。
- 各ファイルは作成し終えたらすぐに書き込みます。最初のファイルを書く前に、
  すべてのファイルの計画を立てないでください。
- proposal に列挙されたすべてのケイパビリティにファイルが揃ったら停止します。

変更の `.openspec.yaml` に `skip_specs: true`（spec レベルの振る舞いの変更なし）が
設定されていない限り、少なくとも 1 つの spec ファイルが必要です - そのマーカーがない
デルタ 0 件の変更は `openspec validate` によって拒否されます。proposal にケイパビリティが
列挙されておらず、`skip_specs` も設定されていない場合は、まず proposal を見直してください。

デルタ操作（`##` 見出しを使用）:
- **ADDED Requirements**: 新規ケイパビリティ
- **MODIFIED Requirements**: 振る舞いの変更 - 更新後の内容を完全に含める必要があります
- **REMOVED Requirements**: 非推奨となった機能 - **Reason** と **Migration** を含める必要があります
- **RENAMED Requirements**: 名前の変更のみ - FROM:/TO: 形式を使用します

フォーマット要件:
- 各要件: `### Requirement: <name>` に続けて説明
- 規範的な要件には SHALL/MUST を使用します（should/may は避けます）
- 各シナリオ: `#### Scenario: <name>`、WHEN/THEN 形式
- **重要**: シナリオは必ず 4 つのハッシュタグ（`####`）を使用する必要があります。3 つのハッシュタグや箇条書きを使用すると、エラーにならずに無視されます。
- すべての要件には少なくとも 1 つのシナリオが必要です。
- すべてのシナリオには WHEN/GIVEN ステップ（そのトリガー）と THEN ステップ（その結果）が必要です。AND 行のみ、または素の散文しかないシナリオもシナリオとしてカウントされますが、`openspec validate` はそれを警告として報告します: 通常のバリデーションは通りますが、`openspec validate --strict` は失敗します。
- 各要件の説明（`### Requirement:` と最初のシナリオの間のテキスト）は 500 文字以内に保ってください。`openspec validate` は、ADDED 要件およびメイン spec 内の長すぎる説明を警告として報告します。これは警告です: 通常のバリデーションは通りますが、`openspec validate --strict` は失敗します。新しい要件を書くときは、1 つの要件につき 1 つの振る舞いを記述してください: 例やエッジケースはシナリオに移し、複数の振る舞いを扱う要件は、それぞれ独自のシナリオを持つ別々の `### Requirement:` ブロックに分割します。MODIFIED では、既存の要件ブロックをそのまま保ち、長さを満たすためだけに既存テキストを分割・削除・書き換えしないでください。既存の長い要件を分割するのは、ユーザーがそれを求めた場合に、そのための変更の中で行います: MODIFIED では、ヘッダーとすべてのシナリオを保持し、意味を変えずに説明を 1 つの振る舞いまで削ります。その後、削除した各振る舞いを、それぞれ独自のシナリオを持つ ADDED 要件として追加します。

新規ケイパビリティのみ: デルタ spec の最初のセクションは `## Purpose` です -
そのケイパビリティが何のためのものかを記述する 1〜2 文（50 文字以上。短すぎる場合、
`openspec validate --strict` が報告します）。archive はこれを、作成するメイン spec に
コピーします。これがない場合、新しいメイン spec には `TBD ... Update Purpose after archive`
というプレースホルダーが残り、手作業で記入する必要があります。既存ケイパビリティの
デルタに `## Purpose` を追加しないでください - その spec には既に Purpose があり、
デルタのものは無視されます。既存ケイパビリティの Purpose（残っている `TBD`
プレースホルダーを含む）を変更するには、`<planningHome.root>/openspec/specs/<capability-path>/spec.md`
を直接編集します。`planningHome.root` は `openspec instructions ...
--json` のレスポンスから取得します。リポジトリ相対パスではなく、必ずこれを使用してください:
変更がストア内にある場合（`--store`、プロジェクトの `store:` ポインタ、グローバルデフォルト
ストアのいずれに由来する場合でも）はストアに解決され、それ以外は現在のリポジトリに
解決されます。どのケースに該当するかを判断しようとしないでください。このフィールドが
既に示しています。

MODIFIED 要件のワークフロー:
1. `<planningHome.root>/openspec/specs/<capability-path>/spec.md`（上記と同じストア対応のルート）で既存の要件を特定します
2. 要件ブロック全体（`### Requirement:` からすべてのシナリオまで）をコピーします
3. `## MODIFIED Requirements` の下に貼り付け、新しい振る舞いを反映するように編集します
4. ヘッダーテキストが完全に一致することを確認します（空白は無視されます）

一般的な落とし穴: MODIFIED を部分的な内容で使用すると、archive 時に詳細が失われます。
既存の振る舞いを変えずに新しい関心事を追加する場合は、ADDED を使用してください。

例（新規ケイパビリティなので、最初のセクションは `## Purpose`）:
```
# Spec Delta

Purpose

ユーザーが製品からデータをポータブルな形式で取り出せるようにする。

ADDED Requirements

Requirement: User can export data

システムはユーザーがCSV形式でデータをエクスポートできるようにしなければならない。

Scenario: Successful export

• WHEN ユーザーが「Export」ボタンをクリックしたとき
• THEN システムはすべてのユーザーデータを含むCSVファイルをダウンロードする

REMOVED Requirements

Requirement: Legacy export

Reason: 新しいエクスポートシステムに置き換えられたため Migration: 新しいエクスポートエンドポイント /api/v2/export を使用すること

スペックはテスト可能であるべき - 各シナリオは潜在的なテストケースとなる。

design.md

変更の実装方法を説明する。変更に必要がある場合のみドラフトされる。

Structure

エージェントが出力形式として受け取るテンプレート（templates/design.md）：

# Design

## Context

<!-- アプローチを形成する現在の状態と制約。動機については proposal.md を参照 - ここでは繰り返さないこと -->

## Goals / Non-Goals

**Goals:**
<!-- この設計が達成することを目指すもの -->

**Non-Goals:**
<!-- 明示的に範囲外のもの -->

## Decisions

<!-- 主要な設計判断とその根拠、検討された代替案 -->

## Risks / Trade-offs

<!-- 既知のリスクとトレードオフ -->

Instructions

この成果物のドラフトを作成する際にエージェントに送信される指示（schema.yaml から）：

変更の実装方法（HOW）を説明する設計ドキュメントを作成する。

design.md を含めるタイミング（いずれかに該当する場合のみ作成）：
- 横断的な変更（複数のサービス/モジュール）または新しいアーキテクチャパターン
- 新しい外部依存関係または重大なデータモデル変更
- セキュリティ、パフォーマンス、または移行の複雑さ
- コーディング前に技術的決定から恩恵を受ける曖昧さ

セクション：
- **Context**: アプローチを説明するために必要な現在の状態と制約のみ。動機については proposal.md を参照し、ここでは繰り返さないこと（例：「proposal.md - Why を参照」）。
- **Goals / Non-Goals**: この設計が達成することと明示的に除外すること。提案の範囲を繰り返さず、設計レベルの境界のみを追加すること。
- **Decisions**: 主要な技術的選択とその根拠（なぜYではなくXなのか）。各決定について検討された代替案を含めること。
- **Risks / Trade-offs**: 既知の制限、問題が発生しうること。形式：[リスク] → 軽減策
- **Migration Plan**: デプロイ手順、ロールバック戦略（該当する場合）
- **Open Questions**: スペック、アプローチ、またはタスク分解を変更することなく後で安全に回答できる未知の事項。ない場合は省略。

Open Questions は本当に延期可能な未知の事項のためのものであり、スキップした決定のためのものではない。質問がスペック、選択したアプローチ、またはタスク分解を変更する場合は、推測するのではなく今すぐユーザーに確認して解決すること。

アーキテクチャとアプローチに焦点を当て、行ごとの実装には触れないこと。
提案はなぜ（Why）と何を（What）をカバーし、設計はどのように（How）をカバーする。動機については提案を参照し、記述後は要件についてスペックを参照 - セクションがそれらを繰り返すだけの場合は、代わりにそれらを指し示すこと。

優れた設計ドキュメントは、技術的決定の「なぜ」を説明する。

tasks.md

実装をチェック可能なタスクに分解する。apply はこちらで進捗を追跡する。

Structure

エージェントが出力形式として受け取るテンプレート（templates/tasks.md）：

# Tasks

## 1. <!-- タスクグループ名 -->

- [ ] 1.1 <!-- タスク説明 -->
- [ ] 1.2 <!-- タスク説明 -->

## 2. <!-- タスクグループ名 -->

- [ ] 2.1 <!-- タスク説明 -->
- [ ] 2.2 <!-- タスク説明 -->

Instructions

この成果物のドラフトを作成する際にエージェントに送信される指示（schema.yaml から）：

実装作業を分解したタスクリストを作成する。

タスクを書く前に、design.md の Open Questions を確認する。それらのいずれかが構築内容を変える場合は、タスクリストに言及されていない前提を組み込まないよう、まずユーザーに確認して解決すること。

**重要：追跡対象タスクには以下のテンプレートに従うこと。** apply フェーズは
チェックボックス形式を解析して進捗を追跡する。`x` のみが入ったボックスは完了とみなされ、
大文字小文字およびスペースの有無は問わないため、`- [ x]` も完了となる。
それ以外のマーカー、`- [~]`、`- [-]`、空の `- []` はすべて未完了と読み取られる。
チェックボックスのない行は追跡対象外となる。

ガイドライン：
- 関連する追跡対象タスクを ## 番号付き見出しの下にグループ化する
- 各追跡対象タスクはチェックボックスでなければならない：`- [ ] X.Y タスク説明`
- タスクは1セッションで完了できる十分な小ささにする
- タスクを依存関係（最初にやるべきこと）の順に並べる
- アーカイブ前に完了できる実装と検証作業を追跡する。要求されたワークフローにアーカイブやこの変更のアーカイブが必要な作業が含まれる場合は、それらの手順を tasks.md の末尾に任意の `## Workflow follow-up` セクションとしてプレーンバレットで保持する。これらのバレットは追跡タスクの進捗の外にある参照情報である。
- 各タスクは完了の検証方法（テスト、コマンド、観測可能な動作、または成果物）を明記すること。検証はそのタスクのチェックボックスの説明に含める。複数の実装タスクにまたがるより広範な統合やシステム動作をチェックする場合にのみ、独立した検証タスクを使用すること。
- 各タスクグループは、自身の作業が必要とするテストとドキュメントを必ず含めること。テストやドキュメントを最終グループに集約してはならない - 後のグループが前のグループの作業を初めて実行する際、失敗は途中のすべてのグループに連鎖し、手戻りを強制する。足場作りや依存関係のセットアップなど、作業がどちらも必要としないグループは、どちらも含めない。最終グループは統合チェックのみのためのものであり、前のグループが負っていたテストやドキュメントのためのものではない。

例：
```
# Tasks

## 1. Setup

- [ ] 1.1 新しいモジュール構造を作成し、期待されるファイルが存在することを確認する
- [ ] 1.2 依存関係を package.json に追加し、パッケージのインストールが成功することを確認する

## 2. Core Implementation

- [ ] 2.1 データエクスポート関数を実装し、エクスポートテストがパスすることを確認する
- [ ] 2.2 CSVフォーマットユーティリティを追加し、単体テストがクォートとデリミタをカバーしていることを確認する
- [ ] 2.3 エクスポートAPIを docs/export.md にドキュメント化し、記載されたコマンドが記載通りに実行されることを確認する
```

該当する場合、ワークフローフォローアップをプレーンバレットとして追加する。例：
```
## Workflow follow-up

- プロジェクトのレビュー要件が満たされた後に変更をアーカイブする。
- アーカイブ結果を確認する。
```

構築すべき内容はスペックを参照し、構築方法は設計を参照すること。

Apply

計画から実装への引き継ぎ。Apply は tasks.md を進めるフェーズであり、成果物ではない。

• 開始: tasks.md が存在し、少なくとも1つのタスクがリストされているとき。
• 追跡: tasks.md のチェックボックス。チェックを入れることが進捗記録となる。
• 終了: すべてのチェックボックスにチェックが入ったとき。OpenSpec はその後、変更のアーカイブを提案する。

Settings

apply の設定（schema.yaml から）：

apply:
  requires: [tasks]
  tracks: tasks.md
  # instruction: shown below

Instructions

実装開始時にエージェントに送信される指示（schema.yaml から）：

コンテキストファイルを読み、保留中のタスクを進め、完了したらマークを付ける。
ブロッカーに遭遇した場合や確認が必要な場合は一時停止する。

schema.yaml

完全な schema.yaml。指示本文は省略。各々は上記のセクションで全文を示している。

name: spec-driven
version: 1
description: Default OpenSpec workflow - proposal → specs → design → tasks
artifacts:
  - id: proposal
    generates: proposal.md
    description: Initial proposal document outlining the change
    template: proposal.md
    # instruction: shown in full under proposal.md above
    requires: []

  - id: specs
    generates: "specs/**/*.md"
    description: Detailed specifications for the change
    template: spec.md
    # instruction: shown in full under Delta specs above
    requires:
      - proposal

  - id: design
    generates: design.md
    description: Technical design document with implementation details
    template: design.md
    # instruction: shown in full under design.md above
    requires:
      - proposal

  - id: tasks
    generates: tasks.md
    description: Implementation checklist with trackable tasks
    template: tasks.md
    # instruction: shown in full under tasks.md above
    requires:
      - specs
      - design

apply:
  requires: [tasks]
  tracks: tasks.md
  # instruction: shown in full under Apply above