コンテンツにスキップ

既存実装から Spec を確立する

sb-discoveryの明示的なリバースモードは、固定した既存リビジョンがすでに表しているプロダクトについて、永続的な Spec を確立します。動くコードはあるが信頼できる仕様がないプロジェクト向けであり、別の SDD 製品からの移行でも、新しい変更の提供でもありません。

実装は証拠であって、仕様を決める権威ではありません。観察した挙動は、維持する意図、 構造上の制約、歴史的な事情、内部詳細、バグの疑い、または判断が必要な問いになり得ます。

この経路が作るのは、Requirements、Design、Contract Review までを確定した非リリースの基準履歴です。Tasks、実装変更、プロダクトリリースは作りません。次の変更から SpecBind を使いたいだけなら、既存プロジェクトで始める の通常の手順へ進んでください。

前提条件

  • SpecBind をインストール済みである
  • 永続的な Spec がなく、アクティブな Milestone もない
  • Steering がプロダクトの目的、技術制約、構造を扱っている
  • Steering を含むリポジトリがコミット済みで、作業ツリーがクリーンである
  • 対象をリポジトリ全体または具体的な領域として指定する
  • そのリビジョンが表す既存のプロダクトバージョンを指定する

全体の流れ

Steeringを設定してコミット
  -> 対象領域と既存バージョンを指定してsb-discovery
  -> source_revisionを固定
  -> コードとテストを調査
  -> 完全なリバース提案を1回確認
  -> リバースRoadmap、Spec、Brief、Researchを作成
  -> Requirements
  -> Designと独立したDesign検証
  -> Contract Review
  -> adoption finalize

確認が必要なのは、原則としてリバース提案の 1 回だけです。設定とリバース確立は別の実行なので、まず Steering と共通設定を整えてから、Discovery を 1 回だけ回します。

1. Steering を整える

Steering が不足している場合は、先にsb-configureへ初回レビューを依頼します。

$sb-configure 既存実装を採用するための初期設定を、このプロジェクトについて
見直してください。必要なSteeringの作成から始めてください。

sb-configureは最初に機械的に確認できる設定の要約を読みます。継続的に使う方針が必要なら、Steering の初期作成または同期をsb-steeringへ引き継ぎます。提案された Steering を確認してコミットしてから採用を始めてください。Discovery はそのリビジョンを調査の証拠として固定します。

2. 共通設定を対象を絞って見直す

Steering ができたら、もう一度sb-configureに、Steering とリポジトリの事実を Requirements ・ Design テンプレート、共有 Rule と照らし合わせるよう依頼します。

$sb-configure 確定したSteeringとリポジトリの事実を使い、このプロジェクト向けに
Requirements・Designテンプレートと共有Ruleを見直してください。

テンプレート、Rule、エージェント、運用アダプターなど、残る面はそれぞれ別の依頼で見直します。sb-configureは関係する変更ごとに要約を読み直し、必要な aftercare まで完了します。Design テンプレートを増やすのは、独立した責任を繰り返し扱う必要がある場合だけです。技術名だけでは理由になりません。設定変更によって既存の Spec やライフサイクル成果物が暗黙に調整されることもありません。

詳しくはカスタマイズを参照してください。

3. リバース Discovery を開始する

Steering をコミットし、作業ツリーをクリーンにしてから、採用する範囲と既存のプロダクトバージョンを明示して依頼します。たとえばリポジトリ全体なら次のようになります。

$sb-discovery このリポジトリ全体の既存実装を、既存バージョンv2.4.0のSpecとして
確立してください。現在のコードとテストを証拠として調査し、何かを作る前に
Spec境界と維持する意図を私に確認してください。

Discovery は採用用の事前検査を行い、調査したリビジョンを固定します。そのうえで、 baseline_version、reverseSpecs候補、維持する意図と根拠、依存関係、停止が必要な不明点と後回しにできる不明点、バグの疑い、対象外を、1 つの完全なリバース提案として示します。この提案を確認するまで何も作りません。

4. 確認後は基準確立まで進む

提案を確認すると、同じ実行がリバース Milestone を作成し、Requirements、Design の検証と承認、Milestone 全体の Contract Review まで続行します。通常のフェーズ確認では止まらず、 Tasks は作りません。Spec の意味が変わる問い、ソースの変更、ライフサイクル検査の失敗がある場合だけ停止します。

Roadmap はnewSpecsやspecUpdatesではなくreverseSpecsを使い、target_releaseを持ちません。作成した各 Spec には、次の来歴が残ります。

establishment:
  kind: reverse
  source_revision: <固定したGitリビジョン>
  baseline_version: <既存のプロダクトバージョン>
  milestone_id: <リバースMilestone>

リビジョン固定と不明点

specbind adoption preflightが返すsource_revisionを固定します。完了するまで、実装、 テスト、依存関係、設定、Steering を変更できません。リバースのスコープ更新や rebaseline もできません。ソースが変わった場合は停止し、新しいクリーンなリビジョンからやり直します。

維持する挙動を意味のある形で書くために回答が必要なら、その問いは該当 Spec を停止します。 独立した別の Spec は進められますが、Contract Review とファイナライズは待ちます。どの回答になっても現在の Spec の意味が変わらない問いだけ、後回しにできます。

有効な Deferred Findings Adapter があれば、欠陥に見える挙動を、ソースリビジョン、証拠の位置、主張とともに「バグの疑い」として記録できます。自動的にバグや要件にはならず、この経路では修正しません。プロジェクト外への送信には、別の権限が必要です。

Tasks もリリースも作らない

リバースでは、通常の Requirements、Design、Design 検証、Contract Review の担当を再利用します。Design を承認すると、リバース Spec はadoption_readyになります。 tasks.yamlは作らず、実装や実装検証も始めません。Release Adapter、タグ、公開、 target_releaseも作りません。

途中で通常の変更依頼が来た場合は、先にリバースを完了し、その後に新しい通常 Milestone を作ります。緊急時はspecbind milestone reverse abandon --milestone-id <id>で明示的にリバースを中断し、通常 Discovery で変更を進めたあと、新しいリビジョンからやり直します。 ライフサイクル状態を手作業で削除しないでください。

ファイナライズと履歴

すべての Spec がadoption_readyになり、Contract Review が fresh になると、Discovery は次を実行します。

specbind milestone reverse finalize --log-entries <path-or->

ファイナライズは、確立の来歴を残したまま active change を閉じ、一時的な Brief と Research を削除し、各 Spec のlog.mdへベースライン <version>を記録します。Roadmap と Contract Review はbaselines/へ履歴化され、アクティブな Milestone が閉じます。これらは採用の記録であり、プロダクトリリースの記録ではありません。

確立した Spec は、元のリビジョンとバージョンの来歴を保持したまま、以後は通常の既存 Spec として扱われます。次の変更からは、 既存プロジェクトで始めるの通常の手順に合流します。

次に読む

ユーザーガイド | 既存プロジェクトで始める | 基本概念