codely-openspec-spec-create-from-code

🧬 既存のコードから OpenSpec の仕様を作成する方法

OpenSpec の変更では、openspec/specs/ にすでに存在する要件のみを MODIFY または REMOVE できます。チームが OpenSpec を採用する前に構築された動作には仕様がないため、その動作に対する変更はすべて ADDED として扱われ、仕様には以前の状態が記載されません。このスキルでは、すでに提供されている動作についてのメイン仕様という、欠けているベースラインを作成します。

ベースラインとは、その機能が OpenSpec を使って構築されていた場合に、OpenSpec がアーカイブしていたはずの仕様です。つまり、実装され、検証された意図です。すべての文がコードと一致し、すべての要件が誰かの意図に基づいています。コードを実態以上によく見せるベースラインは、ないよりも悪いものです。次の提案がその上に積み重ねられるためです。

📥 入力

引数は自由形式のテキストです。次のいずれかとして読み取ってください。

入力	例	範囲
何も指定されていない、または仕様がないものについての質問	which features have no spec?	resources/evidence-guidelines.md にある一覧です。一覧を作成し、ユーザーが項目を選ぶまで待ちます。
機能	checkout	その機能です。
ユーザーがこれから行おうとしている変更	add discount coupons to checkout	変更が影響する現在の動作です。新しい動作はベースラインではなく、変更に含めます。
パスまたは画面	src/app/admin/orders	そのパスが提供するビジネス上の概念を、パスからたどって特定します。

🪜 手順

1. 前提条件を確認する

• openspec --version を実行します。CLI が見つからない場合は中止し、インストールするようユーザーに依頼します。
• OpenSpec のルートを特定します。これは config.yaml を含む openspec/ フォルダーです。その設定ファイルがストアを指定している場合、仕様はそのストアにあります。
• config.yaml の context: を読みます。ここで仕様の言語が決まります。指定がない場合は英語で記述します。

CLI が応答し、仕様を配置するフォルダーがわかった時点で完了です。

2. 機能の範囲を定める

• 機能とは、openspec/specs/ の下にあるフォルダー1つです。クラス名、テーブル名、フォルダー名ではなく、ビジネス上の概念に基づく kebab-case の名前を付けます（checkout、order-management など）。
• openspec list --specs を実行します。既存の仕様が動作の一部をすでに網羅している場合は、その仕様を拡張します。
• 関連する領域に共通のビジネス上の概念がない場合、複数の機能として扱います。ユーザーに分割案を提示します。
• ユーザーがこれから行おうとしている変更の場合、その変更が影響する既存の動作を列挙し、範囲についてユーザーの確認を取ります。
• openspec list を実行し、アクティブな変更ごとに openspec/changes/<change>/specs/<capability>/ を確認します。アクティブな変更にその機能のデルタがある場合、メイン仕様の拡張によってその変更のアーカイブが壊れる可能性があることをユーザーに伝え、続行するか確認します。

各機能について、新規作成か拡張かも含め、ユーザーの確認が取れた時点で完了です。

3. 根拠を収集する

resources/evidence-guidelines.md を読み、そこに記載されたサブエージェントを起動します。調査は委任してください。あなたの役割は、コードベースを読むことではなく、報告内容を照合することです。

各機能の各領域について報告があり、そこにあるすべての候補となる動作に根拠が示された時点で完了です。

4. 分類する

候補となる動作をすべて、resources/evidence-guidelines.md にある4つのケースに分類します。そのファイルの説明に従い、曖昧な候補について、まとめて一度にユーザーへ質問します。ユーザーに質問するためのツールがある場合は、それを使ってください。

すべての候補にケースが割り当てられ、曖昧な候補すべてについてユーザーの判断が得られた時点で完了です。

5. 仕様を記述する

resources/spec-format.md を読み、意図され、検証済みの動作のみを記載した openspec/specs/<capability>/spec.md を作成します。

既存の仕様を拡張する場合は、要件とシナリオを追加し、既存のものはすべてそのまま保持します。コードと矛盾する既存の要件は「乖離」に該当します。これはレポートに記載し、変更は OpenSpec の変更として行います。

意図され、検証済みの候補がすべて、仕様の要件またはシナリオになったら完了です。

6. 検証する

作成したすべての仕様に対して openspec validate <capability> --type spec --strict を実行し、すべてのエラーと警告を修正して、再度実行します。

すべての仕様が厳密な検証に合格したら完了です。

7. 報告して終了する

ユーザーが使用した言語で回答します。次の順に報告します。

1. 作成または拡張した仕様。それぞれに capability ID を記載します。
2. スコープの判断：分割、拡張、スコープから除外した内容とその理由。
3. 仕様から除外した候補。それぞれのケースと根拠を記載します。
4. 既存の要件とコードとの乖離。

仕様の内容を言い換えて説明しないでください。成果物はファイルです。その後、この実行で判明した事実に応じて、以下の手順をこの順に示して終了します。ユーザーの言語に翻訳してください。

• 必ず、レビュー：

  Review <spec paths>: they come from the code, and from now on agents will treat them as the truth. Once you agree with them, commit them with `/codely-git-conventional-commit`.
  

• 入力がユーザーがこれから行う変更だった場合、その変更に戻る方法：

  With the baseline ready, go on with your change: `/openspec-explore <the change, as the user described it>`
  

• バグを仕様から除外した場合、バグごとに、根拠を含めた貼り付け可能なコマンドを 1 つ：

  ⚠️ <n> inconsistencies left out of the spec. To fix one:
  - `/openspec-explore <the behaviour the intent asks for> fails when <the case that breaks> (<file:line>; <the test that covers it, or "no test covers it">)`
  

🧱 境界

• openspec/specs/ の下にのみ書き込みます。変更、config.yaml、コードには手を加えません。
• 仕様はコミットせずに残します。コミットはユーザーのレビュー後に行います。