基本概念¶

SpecBind は、エージェントにすべてを任せる仕組みでも、どんな変更にも文書作成を求める仕組みでもありません。意味を判断するエージェントと、状態を検証して記録する CLI を組み合わせることで、仕様と実装の関係を長く保ちます。

スキルと CLI¶

SpecBind では、責任を次のように分けています。

担当	主な責任
エージェントのスキル	スコープ判断、Requirements や Design の作成、レビュー、実装、結果の説明
`specbind` CLI	構造検証、トレーサビリティ、承認の証拠、進捗、状態遷移、リリース前チェック
あなた	スコープの確定、必要な承認、プロジェクト固有の判断、公開結果の確認

スキルは CLI が持つ状態を直接書き換えません。逆に CLI は、Requirements の意味が正しいか、Design が妥当かといった判断をしません。両方の層を必ず通すことで、形式だけ整った仕様や、内容はもっともらしいのに状態遷移を飛ばした作業を防ぎます。

Spec¶

Spec は、プロジェクトが持ち続ける 1 つの能力、あるいは責任の境界です。

Spec は変更のたびに使い捨てる計画書ではありません。あとの Milestone で同じ能力を変更するときは、同じ Spec の Requirements、Design、Contract を「現在の姿」として更新します。リリース後も Spec は残り、次の変更の出発点になります。

Spec の既定の置き場所は.specbind/specs/<spec>/です。<spec>には、その責任を表す短い kebab-case の ID を使います。

Milestone と Roadmap¶

Milestone は、1 回のリリースとしてまとめて届ける作業の単位です。Spec に基づく作業項目（ Spec-backed item ）、Direct 項目、項目どうしの依存関係、対象リリースを Roadmap に記録します。

同時に進行できる Milestone は、プロジェクトごとに 1 つだけです。現在の Roadmap は .specbind/steering/roadmap.mdにあり、状態は CLI が管理します。リリースが完了すると、Roadmap の内容はリリースアーカイブへ移ります。

いったん Milestone に入れた作業は、単独なら通常の作業で済むような小さな変更でも、同じリリース境界の中で追跡します。

Spec 項目と Direct 項目¶

Discovery は、ワークフローに入ってきた作業を「誰が所有するか」で分類します。

種類	選ばれる条件	持つもの
既存 Spec の更新	既存 Spec が所有する振る舞いや境界を変更する	更新された Requirements、Design、Contract、Tasks
新規 Spec	プロジェクトに新しい責務を追加し、今後も持ち続ける	新しい Requirements、Design、Contract、Tasks
Direct	どの Spec にも属さず、Requirements、Design、Contract を変えない	Roadmap 上の要約と完了状態

分類を決めるのは作業量ではなく所有権です。大きな変更でも、既存の 1 つの責任の中に収まるなら既存 Spec の更新です。逆に小さな変更でも、新しい責務が生まれるなら新規 Spec になります。

Direct として始めた作業が、実は仕様や Contract の変更を必要とすると分かった場合は、その場で成果物を足さずに、Discovery へ戻して分類をやり直します。

Discovery の Source Collection¶

Discovery には、プロジェクト内の Git で追跡済みのテキストファイルやディレクトリ、または明示した GitHub リポジトリの Milestone を、ひとまとまりの Source Collection として渡せます。Discovery はコレクション全体を棚卸しし、Roadmap にすべての Source Item の振り分けを、各 Brief にその Spec が参照する項目だけを記録します。読めないローカル項目、アクセスできない GitHub 項目、GitHub の不完全なページ送りがあれば、一部だけを使って進めずに停止します。GitHub Milestone はOWNER/REPOと Milestone 番号を別々に指定するか、厳密な正規 URL のhttps://github.com/OWNER/REPO/milestone/NUMBERを指定します。別の URL 形式は受け付けません。open と closed の Issue を対象にします。コメントとタイムラインイベントは入力資料ではありません。

Source Collection は正規の仕様そのものではありません。Requirements と Design は Brief が指定した資料を読み、採用する振る舞いや技術上の結論を自身の成果物へ書き直します。リモートの入力文脈は Discovery 時に確定し、後続の工程で黙って再取得しません。元資料を更新した場合は自動同期されないため、必要な範囲を指定して Discovery を明示的にやり直します。

永続成果物と Milestone 固有成果物¶

Spec 項目の成果物には、リリース後も残るものと、Milestone が進行中の間だけ存在するものがあります。

種類	代表例	ライフサイクル
永続	`spec.yaml`、`requirements.md`、`design.md`、`contract.yaml`、`log.md`	Spec の現在の姿と履歴として残る
Milestone 固有	`brief.md`、`research.md`、`tasks.yaml`	進行中の変更を進めるために使い、リリース完了時に片付ける
プロジェクト全体	`steering/roadmap.md`、Steering 文書、Contract レビュー	複数の Spec にまたがるスコープと判断を保持する

Requirements と Design は差分メモではありません。どちらも、現在有効な契約の全体を表します。以前から変えない記述も、そのまま現在の文書の中に残してください。

Gate と承認¶

Requirements、Design、Tasks にはそれぞれ Gate があります。Gate の承認は単なるチェック印ではなく、レビューした入力のリビジョンとフィンガープリントに結び付いた証拠です。

そのため、上流の成果物が変わると、影響を受ける下流の承認や、完了を裏付ける記録（ completion evidence ）は無効、または古い状態になります。エージェントが古い Design や Tasks のまま黙って進んでしまうのを防ぐための仕組みです。

承認には 2 つの形があります。

明示的な承認（ explicit ） — あなたがその Gate で内容を確認して承認する
委任による承認（ delegated ） — sb-planなど、名前の付いた 1 回の実行に対して、承認をあらかじめ委任する

委任しても、レビューや検査は省略されません。また、承認済み Gate を破棄したり、 Contract レビューを受理したりする権限までは委任されません。

Contract レビュー¶

Design には、その Spec の内部構造だけでなく、外部へ公開する責任、依存、ファイルの所有境界も含まれます。この部分を Contract として維持します。

Tasks を作る前に、進行中の Milestone に含まれる全 Spec の Contract をまとめてレビューします。Spec が 1 つしかない Milestone でも、このレビューは省略しません。所有権の重複、循環依存、互換性の前提、統合時の抜けを、実装前に見つけるためです。

Contract 同士の直接の依存関係は、元のcontract.yamlを変更せずに CLI から確認できます。

specbind contract graph
specbind contract dependencies <spec>
specbind contract consumers <spec>

graphはプロジェクト全体の解決済み参照、dependenciesは指定した Spec が利用する提供側、consumersは指定した Spec を利用する管理対象の利用側を表示します。いずれも直接参照の機械的な投影です。到達可能な Spec が実際に変更の影響を受けるか、 SpecBind 管理外の利用側が存在するかは、Contract レビューで判断します。

無効化とやり直し¶

承認したあとで前提が変わったときは、影響を受ける中でいちばん手前の Gate を、明示的に無効化します。

Requirementsが変わった -> Requirements Gateからやり直す
Design/Contractが変わった -> Design Gateからやり直す
Tasksだけが変わった -> Tasks Gateからやり直す

無効化すると、下流の証拠も消えます。これは失敗ではなく、変わった前提に古い承認を使わないための、通常のやり直しです。

v1 の制限: Requirement の削除

確立済みの Spec から Requirement グループや Acceptance Criterion を削除する場合、 v1 では完全な廃止履歴を残せません。既存 Requirement の削除が必要になったときは、履歴が欠けたまま進めず、その操作の手前で停止します。既存内容の更新と、新しい Requirement の追加は問題なく行えます。

通常のライフサイクル¶

Spec 項目は、だいたい次の順で進みます。

Discovery
  -> Requirements
  -> DesignとContract
  -> Design検証
  -> Milestone全体のContractレビュー
  -> Tasks
  -> 実装とTaskレビュー
  -> 実装検証
  -> リリース

sb-planは、Requirements から Tasks 承認までを進める標準の入口です。Spec を指定するとその 1 件、--allまたは全 Spec という明示的な依頼では Milestone 内の全 Spec を対象にします。対象を付けずに呼び出すと、作業を始める前にどちらかを確認します。各 Gate の承認をこの実行へ委任すれば確認回数を減らせますが、使う成果物、レビュー、CLI の検査は変わりません。 Requirements、Design、Tasks の 1 フェーズだけを扱う場合も、対象 Spec とフェーズを明示して同じsb-planを使います。 sb-implementが実装するのは、1 回につき 1 つの Roadmap 項目だけです。 sb-driveは Milestone 全体から安全に到達可能な所有ワークフローを 1 つずつ選び、各委譲後に CLI 状態を読み直します。局所的な判断待ちは保留して独立項目を続けますが、リリースは実行せず、その手前で停止します。

プロジェクト固有の設定¶

.specbind/settings/以下のテンプレート、ルール、アダプターは、プロジェクトの持ち物です。初回の導入で既定値を作りますが、そのあとspecbind installを実行しても、プロジェクト側の設定を上書きしません。

一方、.agents/skills/sb-*/と.claude/skills/sb-*/は SpecBind 製品側の持ち物です。specbind installを再実行すると、Git に未コミットの変更がないことを確認したうえで、現在の埋め込み版へ更新します。スキルファイルを直接編集するやり方は、サポートしているカスタマイズ方法ではありません。 .agents/skills/は Codex とgenericエージェントで共有されます。genericは、共通形式のスキルとAGENTS.mdだけを導入し、製品固有のサブエージェント定義は作りません。

どの設定に何を書くか、変更できない製品契約との境界、変更後の確認方法はカスタマイズにまとめています。

次に読む¶

ユーザーガイド | 1 件ずつ計画・実装する | Plan と Drive で Milestone を進める