OpenSpec で既存コードの変更を差分の仕様として残す

既存のアプリに機能を 1 つ足すとき、なぜ変えるのか・何が変わるのかを書き残す場所がないと、その判断は AI との会話ログに埋もれます。OpenSpec は、変更を差分の仕様（delta spec）として扱う SDD（Spec Driven Development: 仕様駆動開発）ツールです。最小の ToDo アプリへ期限日の表示を追加すると、proposal・spec・design・tasks の 4 ファイルが順に出来上がり、そのまま実装まで一巡しました。

会話だけで進めると判断が会話ログに散る

AI との会話だけで実装を進めると、次の情報が会話ログに分散します。

• なぜ作るのか
• 何が変わるのか
• どう検証するのか
• 実装中の発見をどこへ戻すのか

仕様をファイルに置けば、レビュー・実装・検証で同じ内容を参照できます。これが SDD の出発点で、考え方の全体像は仕様駆動開発にまとめています。

Spec Kit は仕様から実装へ進む道筋を持つ

GitHub の Spec Kit は、AI と進める Spec-Driven Development のツールキットです。constitution → specify → plan → tasks → implement → converge というフェーズを持ち、各フェーズの成果物をファイルとして管理します。

OpenSpec は変更を差分として扱う

OpenSpec は、既存コードへの変更を意識した SDD フレームワークです。現在の仕様と、変更ごとの提案・差分を別のディレクトリに置きます。

openspec/
├── specs/                    # 現在の仕様
└── changes/<change-name>/    # 変更の提案と差分
    ├── proposal.md
    ├── specs/
    ├── design.md
    └── tasks.md

変更が完了したら、changes/ 配下の delta spec を specs/ の現在の仕様へ sync し、その change を archive します。archive した change は、その変更をなぜ入れたのかの記録として残せます。 設計判断の記録を ADR として別管理している場合は、archive をその置き場に寄せる選択もできます。

Spec Kit と OpenSpec の違い

どちらも、実装前の判断を成果物として残すための道具です。差分の管理を第一級に置いているところが OpenSpec の側の特徴です。

最小の ToDo アプリに期限日を足す

初期状態のアプリには、タスク追加・完了切替・完了済みフィルターだけがあります。ここへ「期限日と期限超過の表示」を入れる change を作ると、4 つの artifact が生成されます。

openspec/changes/add-task-due-date/
├── proposal.md
├── specs/task-due-date/spec.md
├── design.md
└── tasks.md

4 ファイルが揃ったら、change として妥当かを検証します。

openspec validate add-task-due-date --strict
# Change 'add-task-due-date' is valid

proposal.md: 変更の理由と範囲

なぜその変更を入れるのか（Why）と、何が変わるのか（What Changes）を書きます。あわせて、追加・変更する capability と、触るファイルの範囲を宣言します。

## Why
未完了タスクだけでは、いつまでに着手すべきかを判断できない。期限日と期限超過を
表示し、優先して取り組むタスクを確認できるようにする。
## What Changes
- タスク登録時に任意の期限日を設定できるようにする。
- 期限日を設定したタスクに期限日を表示する。
- 未完了かつ期限日を過ぎたタスクを期限超過として表示する。

spec.md: 受け入れ条件

要件と、その要件が満たされたと判断できるシナリオを書きます。期限日あり・なし、期限超過、完了後の表示の 4 パターンをここで固定しました。

### Requirement: 任意の期限日を設定する
The system SHALL allow the user to set an optional due date when adding a task.
#### Scenario: 期限日を設定してタスクを追加する
- **WHEN** 利用者がタスク名と期限日を入力してタスクを追加する
- **THEN** 追加したタスクに入力した期限日が表示される

design.md: 設計判断と代替案

実装前に決めておく必要がある点を、代替案とセットで書きます。期限日では次の 2 つが対象になりました。

• 期限日は YYYY-MM-DD の文字列で保持する: HTML の input type="date" が返す値をそのまま持ちます。代替案として UTC の日時を保持する方法も検討しましたが、期限時刻を扱わない要件では日付ずれの原因になるため採っていません。
• 期限超過は「今日より前の未完了タスク」とする: 現在日付をローカルの YYYY-MM-DD に正規化して比較します。当日が期限のタスクは期限超過にせず、翌日から期限超過にします。完了済みのタスクは、期限日を過ぎていても期限超過として表示しません。

tasks.md: 検証を含む作業項目

決めた仕様を、実装と確認の単位へ分解します。「ブラウザで確認する」までが 1 つの task に入っているので、実装したが動作を見ていない状態が残りにくくなっています。

## 2. 期限日と期限超過の表示
- [ ] 2.1 タスクデータに `dueDate` を追加し、期限日あり・なしで追加したタスクの
      表示が変わることをブラウザで確認する
- [ ] 2.2 未完了かつ今日より前の期限日を持つタスクを期限超過として表示し、完了に
      すると期限超過表示が消えることをブラウザで確認する

CLI が次に作れる artifact を示す

OpenSpec CLI は、change の置き場、artifact の依存関係、各 artifact のテンプレートを管理します。

openspec new change    # change を作る
openspec status        # artifact の依存関係と、次に作れる artifact
openspec instructions  # 各 artifact の目的・必須見出し・テンプレート

status は今どの段階にいて次に何を作れるかを示し、instructions はその artifact に何を書くべきかを返します。順番と必須見出しを CLI 側が持っているため、書き手が構成を覚えておく必要はありません。

スキルで下書きを作り、レビューしてから実装する

artifact の生成はスキルから起動できます。/opsx-propose で planning artifact を作り、内容を確認してから /opsx-apply で実装へ進みます。

/opsx-propose 期限日と期限超過を追加したい
  ↓ proposal.md / spec.md / design.md / tasks.md を作成
/opsx-apply
  ↓ tasks.md の内容に沿って実装し、完了した task をチェックする

planning artifact は利用者が手で書くこともできます。通常は AI が下書きを作り、利用者が意図と設計判断をレビューしてから /opsx-apply を実行します。 今回は GitHub Copilot で実行しましたが、スキルの中身はプロンプトなので、他のコーディングエージェントでも同じ流れを再現できるはずです。

/opsx-apply を実行すると tasks.md の順に実装が進み、ToDo アプリに期限日と期限超過の表示が追加されました。

小さい変更では artifact を省ける

期限日の追加では design.md を作りました。日付の保持形式・タイムゾーンの扱い・「今日より前」の定義・完了済みの扱いという、実装前に決めておくべき判断が残っていたためです。

続けてダークモードを追加したときは design.md を作っていません。決めることが表示の切り替えだけで、design に書き残す判断が出てこなかったためです。この規模のアプリでは、1 機能あたり 10 分ほどで一巡しました。OpenSpec は変更の複雑さに応じて、作る artifact を選べます。

出力先は schema で変えられる

artifact の既定の置き場は openspec/ です。ただし custom schema の generates で、artifact ごとの出力パスを定義できます。

# openspec/schemas/**/schema.yaml
artifacts:
  - id: requirements
    generates: docs/specs/my-feature/spec.md

openspec/ は標準 schema の既定値で、OpenSpec 全体の固定ルールではありません。仕様のドキュメントを別の場所で管理しているなら、変更ごとの artifact をそこへ出して管理できます。

確認できた範囲

試したのは ToDo アプリ規模の機能追加が 2 件で、実案件での運用実績はまだありません。schema の設定項目も全部は見ていないため、大きなリポジトリで artifact の粒度をどう置くかは未確認です。

まとめ

• Spec Kit は、仕様から実装へ進むためのツールキット
• OpenSpec は、既存仕様への変更を delta spec として管理するフレームワーク

小さな変更でも、仕様と作業項目をファイルに残しておくと次の変更で参照できます。非定型なインプットから受け入れ基準までを定型フォーマットに落とす進め方は、AIDD 要件定義でも扱っています。お気軽にご相談ください。