既存プロジェクトで OpenSpec を使う

最初にコードベース全体を文書化する必要はありません。これから変更する部分だけを仕様化します。 既存プロジェクトに OpenSpec を導入するうえで最も重要なポイントであり、OpenSpec が既存システムでの利用を重視して設計されている理由です。

よくある心配はこうです。「自分のアプリは8万行もあります。OpenSpec が役立つようになる前に、全部の仕様を書かなければなりませんか？」いいえ。そんな作業は嫌になるでしょうし、私たちも勧めません。OpenSpec では、変更のたびに仕様を少しずつ増やします。最初の変更でその対象範囲を文書化し、次の変更では次の範囲を文書化します。数か月かけて、実際に行う作業に沿って仕様が自然に充実していきます。

このガイドでは、最初からすべてに取り組まず、初日から始める方法を説明します。

30秒で分かる手順

$ cd your-existing-project
$ openspec init          # openspec/ と AI ツールのコマンドを追加

続いて、AI とのチャットで次を実行します。

/opsx:explore            # 任意: 変更対象の領域を AI に調査してもらう
/opsx:propose <実際に必要な小さな変更>
/opsx:apply
/opsx:archive

これで仕様には、その change が触れたシステムの部分だけが記述されます。それで正解です。残りの8万行について心配する必要はありません。

差分を先に書くことが重要な理由

OpenSpec の change は 差分（ADDED、MODIFIED、REMOVED）として記述します。差分はシステム全体ではなく、現在の動作から何が変わるかを表します。

これは既存システムの作業に最適です。何もないところから構築することはまれです。フィールドの追加、リダイレクトの修正、タイムアウトの短縮などを行います。差分を使えば、周辺のすべてを40ページの仕様にまとめることなく、その変更だけを正確に仕様化できます。

したがって openspec/specs/ は、最初から完全な状態ではなく、ほぼ空の状態から始まり、徐々に充実します。アーカイブした change ごとに差分がマージされます。auth/ の仕様は、認証関連の変更をいくつか行った後で初めて詳細になります。それこそ、詳細な仕様が必要になるタイミングです。

詳しい仕組みについては、概念: 差分仕様を参照してください。

実際のコードベースで最初の変更を行う

実際に必要な小さな変更を選びます。練習用でも全面書き換えでもなく、今週行う予定だった変更にしましょう。最初の変更を小さくすれば、リスクを抑えてワークフローを学べます。

手順1: AI に関連領域を読ませる。 見慣れない、または大規模なコードベースでは、ここで /opsx:explore が役立ちます。これから変更する部分を指定し、提案する前にどのように動作するかを調べてもらいます。

あなた: /opsx:explore

AI:  何を調べましょうか？

あなた: 公開 API にレート制限を追加したいのですが、リクエストが現在どのように
     ミドルウェアを通過するのか分かりません。

AI:  処理の流れを追ってみます... [ルーター、ミドルウェアスタック、設定を確認]
     リクエストは Express に到達し、認証ミドルウェアを通ってからコントローラーに
     渡されます。現在、レート制限レイヤーはありません。認証の直後に
     ミドルウェアを挿入するのが最もすっきりしています。範囲を整理しましょうか？

AI が実際の構造を理解したので、汎用テンプレートではなく、コードに合った提案を作成できます。大規模なコードベースでは、この習慣だけで多くの手間を省けます。まず Exploreを参照してください。

手順2: change を提案する。 提案と差分仕様には、この変更だけを記述します。

You: /opsx:propose add-api-rate-limiting

手順3: 構築してアーカイブする。 他の change と同様に /opsx:apply と /opsx:archive を使います。アーカイブ後には、もともと必要だった変更を通じて、レート制限の動作を説明する実際の仕様が得られます。

手順に沿って試すには onboard を使う

自分のコードで一連の作業を説明付きで体験したい場合は、拡張コマンド /opsx:onboard を使います。コードベースを調べて安全な小規模改善を見つけ、各手順を説明しながら提案、実装、アーカイブまで案内します。

まず拡張コマンドを有効にします。

$ openspec config profile      # 拡張ワークフローを選択
$ openspec update              # このプロジェクトに適用

続いてチャットで実行します。

/opsx:onboard

実際のプロジェクトで最も無理なく導入を試せます。また、保持するか破棄するかを選べる、小規模で実際的な変更が残ります。コマンド: /opsx:onboardを参照してください。

「すでに要件ドキュメントがあります」

PRD、SRS、正式な仕様書、さらには TLA+ モデルがあるかもしれません。それで問題ありません。すべてを一括で取り込む必要も、捨てる必要もありません。

既存のドキュメントは、変換対象の仕様ではなく、調査のための資料として扱います。change を始めるときに、関連する節を貼り付けるか AI に参照させ、そこから焦点を絞った OpenSpec の差分を作成してもらいます。差分には、現在変更する動作を、テスト可能な OpenSpec の要件とシナリオの形式で記述します。元のドキュメントは背景資料としてそのまま残します。

理由は明快です。OpenSpec の仕様は、意図的に動作を中心にし、変更範囲に絞っています。40ページの PRD は目的の異なる成果物です。一度にまとめて変換すると、誰も信頼しない大規模で古い仕様になりがちです。実際の変更に合わせて仕様を育てれば、正確さを保てます。

あなた: /opsx:explore
あなた: これはチェックアウトに関する PRD の節です。次に「ゲスト購入」の要件を
     実装します。
     [関連する要件を貼り付ける]
AI:  [内容を読み、確認事項を質問してから、変更範囲の整理を支援]
あなた: /opsx:propose add-guest-checkout

大規模なコードベースで仕様を整理する

仕様は openspec/specs/ 以下に ドメイン 単位でまとめます。ドメインとは、チームがシステムを理解する方法に沿った論理領域です。最初に分類体系全体を設計する必要はありません。その領域で初めて変更を行うときに、ドメインフォルダーを作成してください。

ドメインを分ける一般的な方法:

• 機能領域ごと: auth/、payments/、search/
• コンポーネントごと: api/、frontend/、workers/
• 境界づけられたコンテキストごと: ordering/、fulfillment/、inventory/

新しく参加した人にも分かりやすい分類を選び、必要に応じて後から見直してください。概念: 仕様を参照してください。

モノレポと複数リポジトリにまたがる作業

モノレポでは、リポジトリのルートに openspec/ ディレクトリを1つ置き、パッケージやサービスに対応するドメインに分けるのが最も簡単です。ほとんどのチームではこれで十分です。

作業が実際に 複数のリポジトリ（または別々に扱う複数のパッケージ）にまたがる場合、OpenSpec のベータ版 stores 機能を利用できます。計画を独立したリポジトリに置き、各コードリポジトリから参照できるため、特定のリポジトリの openspec/ フォルダーに計画を置く必要がありません。ベータ版のため、コマンドや状態は今後変わる可能性があります。全体像と最小限の使い方はStores ユーザーガイドから確認してください。

注意点

• すべての仕様を遡って作成したくなる気持ちを抑える。 変更しないコードまで仕様化すると、作業した気にはなりますが、たいていは役に立ちません。現実に追従させる仕組みがなければ、仕様が古くなるからです。実際の変更に合わせて仕様を作ってください。
• 初期の変更は小さくする。 最初の数回は、リリースだけでなく進め方を身に付ける機会でもあります。範囲を絞ると作業が速くなり、学びにかかるコストも下がります。
• openspec/ を git にコミットする。 仕様とアーカイブは、それが説明するコードとともにバージョン管理します。
• AI に文脈を与える。 強い規約を持つ大規模なコードベースでは、openspec/config.yaml の context: を設定し、すべての提案で技術スタックやパターンを考慮させます。カスタマイズを参照してください。

次に読むページ

• まず Explore — 変更前にコードを理解するための重要な習慣
• はじめに — 最初の変更を一通り体験するガイド
• 変更の編集と反復 — 学びに合わせて change を調整する方法
• 概念: 差分仕様 — 差分で既存システムをきれいに変更できる理由
• カスタマイズ — プロジェクトの規約を OpenSpec に伝える方法