変更のレビュー

OpenSpec の約束は、コードを書く前にあなたと AI が 何を構築するかに合意すること です。その合意が意味を持つのは、AI の下書きを実際に読む場合だけです。このページでは、2分間の確認に何をどの順で開き、何を確認するかを説明します。

考え方は簡単です。1段落の計画にある誤りなら、ほぼ無料で見つけられます。同じ誤りを300行のコードから見つけるのは簡単ではありません。レビューは、この利点を活用する場です。

レビューを行う2つのタイミング

レビューのタイミングは正確に2回です。

/opsx:propose ──► 計画をレビュー ──► /opsx:apply ──► コードをレビュー ──► /opsx:archive
                  (コードを書く前)                   (/opsx:verify)

1. /opsx:propose（または /opsx:ff）の後、/opsx:apply の前 — 計画がまだ文章のうちに確認します。
2. 実装後に /opsx:verify で — コードが計画どおりに実装されたか確認します。

最初のレビューは最も効果が大きい一方で、最も省略されがちです。このページでは主にそこを扱います。

この順で読む

change は openspec/changes/<name>/ にある通常の Markdown ファイルの集まりです。問題があれば最も早く作業を止められる順に読みます。

openspec/changes/add-dark-mode/
├── proposal.md      1. 目的と範囲             ← 誤りがあればここで止める
├── specs/…/spec.md  2. 要件                   ← レビューの中心
├── design.md        (大きな変更の場合のみ) — 技術的な方針
└── tasks.md         3. 作業計画

すべての行を読む必要はありません。各ファイルについて1つずつ、3つの質問に答えます。

提案: 適切な問題を扱っているか？

最初に proposal.md を開きます。「なぜ」と「何を」、つまり目的、範囲、方針を1〜2段落で説明します。

望ましい状態: 明確な目的、把握できる範囲、今これを行う価値のある理由がある。

注意すべき点:

• 依頼した内容とは少し 異なる 問題を解決しようとしている。
• 範囲が広がっている — テーマ切り替えを依頼したのに、「ついでに」認証にも手を加える提案になっている。
• 曖昧である。「設定ページを改善する」は範囲ではありません。「OS の設定に従うダークモード切り替えを追加する」なら範囲が明確です。

確認すること: 実際に依頼した内容と一致しているか、余計な作業が紛れ込んでいないか。 答えが「いいえ」ならそこで止め、先を読まずに提案を修正してください（異議を伝えるを参照）。

仕様の差分: 完了条件は正しく定義されているか？

ここがレビューの中心です。specs/ 以下の差分仕様では、change のリリース時に 実現していること を、要件とそれを証明するシナリオで説明します。

## ADDED Requirements

### Requirement: ダークモードの切り替え
システムは、ユーザーがライトテーマとダークテーマを切り替えられるようにしなければならない。

#### Scenario: 初回読み込み時に OS の設定を反映する
- GIVEN テーマを設定したことがないユーザーがいる
- WHEN ダークモードに設定されたデバイスでアプリを開く
- THEN アプリがダークモードで表示される

望ましい要件: テスターに渡せる明確な SHALL/MUST 文が1つあり、その文を実際に検証する GIVEN/WHEN/THEN のシナリオが1つ以上ある。

注意すべき点:

• 曖昧な要件。 「システムは高速でなければならない」では実装もテストもできません。どの程度の速さでしょうか？
• シナリオのない要件、またはその要件を検証していないシナリオ。
• 最も価値ある指摘: 抜けている内容。 AI はあなたが 言ったこと を忠実に記述します。あなたの役割は 言い忘れたこと に気付くことです。OS 設定のケースを最も重視していたのに、シナリオに含まれていないなら、レビューによって価値が生まれています。

差分を読みながら、システムがここに書かれたことだけを正確に実行したとして、満足できるか を考えてください。まだコードには関わらないため、この段階なら低コストで変更できます。

タスク: 作業計画は妥当か？

最後に tasks.md を開きます。AI が実装を進めるためのチェックリストです。

望ましい状態: 順序立てた手順があり、それぞれの根拠となる要件を確認でき、内容が明確である。

注意すべき点:

• 対応する要件のないタスク（どこから出てきたのでしょうか？）。
• 実際の判断事項が隠れてしまう、「機能を実装する」という巨大なタスクが1つだけある。
• 先ほど承認した範囲外に触れるタスクがある。

ここで見積もりや細かな管理をする必要はありません。すでに承認した要件に計画が一致しているか確認します。

異議を伝えるのは簡単

3つの質問のどれかへの答えが間違っている場合は、そう伝えてください。フェーズも固定事項もないので、直して先へ進めます。変更の編集と同じく、方法は2つあります。

• 自分でファイルを編集する。 通常の Markdown なので、範囲の記述を変えたり、要件を明確にしたり、タスクを削除したりできます。
• AI に問題点を伝えて修正してもらう。 「認証の変更は範囲外なので外して」、「ユーザーがすでにテーマを選択している場合のシナリオを追加して」、「タスク3をスキーマと UI に分けて」 などと伝えます。

変更した箇所を読み直します。自分の名前を添えて承認できる計画になるまで下書きを修正します。このやり取りこそが製品の機能です。

実装後: verify

実装後の2回目のレビューには /opsx:verify を使います。成果物とコードを再度読み込み、次の3つの観点で不一致を報告します。

観点	確認内容
完全性	すべてのタスクが完了し、すべての要件が実装され、シナリオが網羅されている
正確性	実装が仕様の意図に沿い、境界ケースが処理されている
一貫性	設計上の判断がコードに反映されている

あなた: /opsx:verify

AI:  add-dark-mode を検証しています...

     完全性
     ✓ tasks.md の8つすべてのタスクにチェック済み
     ✓ specs のすべての要件に対応するコードがある
     ⚠ シナリオ「初回読み込み時に OS の設定を反映する」がテストでカバーされていない

問題を CRITICAL、WARNING、SUGGESTION として示しますが、アーカイブを妨げることは ありません。不足を示して、判断はあなたに委ねます。これによって「AI がコードを書いたか」と「合意したものを実装したか」の違いが分かります。

/opsx:verify は expanded プロファイルに含まれています。使えない場合は、openspec config profile で有効にしてから openspec update を実行するか、自分で change と差分を読み直してください。

レビューの規模を適切にする

すべての change に詳細なレビューが必要なわけではありません。1つのファイルのタイプミス修正なら、20秒ほどの確認で十分です。認証、決済、復元できないデータに関わる change なら、上記の質問すべてを確認してください。大切なのは形式的な手順ではなく、誤りのコストが大きい箇所に注意を払い、そうでない箇所は簡単に目を通すことです。

2分間のチェックリスト

• 提案の目的が、依頼した内容と一致している。
• 余計な内容が範囲に入り込んでいない。
• すべての要件がテストできるほど具体的である。
• すべての要件に、それを実際に検証するシナリオがある。
• 最も重視するケースが網羅されている。
• タスクが要件に対応しており、不明点や範囲外の内容がない。
• AI がここに書かれたことだけを実装しても問題ない。

7項目すべてに問題がなければ、自信を持って /opsx:apply を実行してください。問題があっても後退ではありません。2分間の確認が役立ったということです。

次に読むページ

• 良い仕様を書く — 承認に値する要件とシナリオを下書きする方法
• 変更の編集と反復 — 開始後に計画を変更する方法
• ワークフロー — 全体の流れにおけるレビューの位置付け