既存プロジェクトで始める¶
このページでは、既存のプロジェクトに SpecBind を導入し、コーディングエージェントと一緒に、最初の変更を計画・実装・検証まで進めてみます。
まだ実装を始めていない場合は、新規プロジェクトで始めるへ進んでください。必要な環境とエージェントについては、 ルートを選ぶの「どちらのルートでも必要なもの」を確認しておいてください。
用語について
出てくる用語（ Spec、Steering、Milestone、Gate など）は基本概念 にまとめています。先に目を通しても、出てきたときに参照してもかまいません。
1. SpecBind をインストールする¶
未コミットの変更が残っている場合は、内容を確認していつもの手順でコミットしておいてください。そのうえで、両ルート共通の SpecBind をインストールするを実行します。
mise use github:Huruikagi/specbind
mise lock
specbind install --agent codex --language ja --project-instructions
エージェントの選び方、--dry-runでの事前確認、書き込まれるファイル、コミットとセッションの開き直しは、そのページを参照してください。
インストールが済んだら、このページへ戻ってきてください。以降のスキル呼び出しは
Codex の表記（$）で示します。Claude Code では/に読み替えてください。
2. 最初の進め方を選ぶ¶
既存プロジェクトには、目的の異なる 2 つの始め方があります。
| 目的 | 次に使うワークフロー |
|---|---|
| これから行う変更を SpecBind で進める | このページの続きを進める |
| すでに動いている実装から、現在の基準となる Spec を確立する | 既存実装から Spec を確立する |
最初の小さな変更を進めるなら、既定値のまま通常のライフサイクルを一周する方法が分かりやすいでしょう。実際に合わないと分かった面だけ、あとから カスタマイズで調整できます。そのままこのページを続けてください。
すでに相当量のコードがある一方で信頼できる Spec がまだなく、まず現在のプロダクトを Spec として固定したい場合は、既存実装から Spec を確立するへ進んでください。Steering と共通設定を整えてから、Requirements、Design、Contract Review までを確定し、非リリースの基準履歴として閉じる経路です。
3. 最初の変更を選ぶ¶
最初は、1 つの振る舞いを追加するだけの小さな変更を選んでください。複数の機能やリリース作業をまとめて試すのは避けます。
このガイドでは、既存のアプリケーションに次の変更を加える例で説明します。
一覧画面に表示している内容を、CSV ファイルとしてダウンロードできるようにしたい。
この例は、プロジェクトが持ち続ける新しい振る舞いと境界を作るため、該当する既存 Spec がなければ新規 Spec に分類される想定です。出力する CSV の列や形式は、 あとから他の機能や利用者が依存する外部との約束になるので、Contract としても扱いやすい題材です。実際に試すときは、自分のプロジェクトにある同じくらいの規模の変更に置き換えてください。
4. Discovery でスコープを確認する¶
変更内容を添えて、discovery スキルをエージェントに依頼します。関連する issue やメモがあれば、その場所も伝えます。
細かい要件や設計はこのあとの Plan で詰めるので、ここで全部渡す必要はありません。 使う技術や実装方針の選定も Discovery の仕事ではありません。
Discovery は、プロジェクトの現在の状態（ Spec、Steering、Milestone ）を読んだうえで、 変更を Direct（既存の仕様を変えずにできる小さな変更）、既存 Spec の更新 （すでにある能力の振る舞いや境界を変える）、新規 Spec（プロジェクトに新しい責務を 1 つ増やす）のいずれかに分類します。
用語: Spec
Spec は「プロジェクトが持ち続ける 1 つの能力の境界」で、責務を表す短い kebab-case の ID が付きます（用語は基本概念）。
分類の結果は、次の項目にまとめて提案されるので、確認してください。
- 作業項目（ Work items ） — 今回行う作業の一覧
- 新規 Spec （ New Specs ） — 新しく作る責務の境界
- Gate の無効化（ Gate invalidations ） — やり直しになる既存の承認
- 依存関係（ Dependencies ） — 作業どうしの依存関係
ここでの結論が以降のワークフロー全体の前提になります。分類と境界を必ず読んでから承認してください。承認すると、CLI が Milestone と Spec の状態を作り、エージェントが、
その変更の要点をまとめた作業メモ（brief.md）を書きます。
途中で状態を確認したくなったら、次のように依頼できます。
このスキルは読み取り専用で、承認したり成果物を書き換えたりはしません。
5. 計画と実装の進め方を選ぶ¶
最初のcsv-exportを段階ごとに確認する場合は、sb-planのフェーズを明示して順に進めます。
$sb-plan csv-export requirements
$sb-plan csv-export design
$sb-contract-review
$sb-plan csv-export tasks
$sb-implement csv-export
$sb-validate-implementation csv-export
各段階で確認する内容、承認、上流へ戻る場合の扱いは、 1 件ずつ計画・実装するにまとめています。
複数の Spec や Direct 項目を含む Milestone では、$sb-plan --allのあとに
$sb-driveを使います。保留、別項目への継続、停止条件は
Plan と Drive で Milestone を進めるを参照してください。
どちらの経路もリリース前で停止します。
6. 生成された成果物を見る¶
Spec の成果物は、既定では.specbind/specs/<spec>/にできます。
.specbind/
├─ steering/roadmap.md
└─ specs/csv-export/
├─ spec.yaml
├─ brief.md
├─ requirements.md
├─ design.md
├─ contract.yaml
└─ tasks.yaml
spec.yaml、roadmap.md、tasks.yamlに入っている実行状態は、CLI の持ち物です。
状態を進める目的で手編集しないでください。Requirements、Design、Contract、
Tasks の計画部分は、sb-planの対応するフェーズを通して保守します。
現在の状態は、CLI から直接確認することもできます。
specbind milestone status
specbind spec status csv-export
specbind tasks list csv-export
specbind artifact list csv-export
周辺ツールやスクリプトから Milestone と Spec の状態を読む場合に限り、2 つの
statusコマンドはコマンド固有の JSON 出力も提供します。通常の利用では既定の簡潔なテキスト出力をそのまま使います。
次に読む¶
- 基本概念
- 1 件ずつ計画・実装する
- Plan と Drive で Milestone を進める
- 既存実装から Spec を確立する — 現在のコードを基準 Spec にする
- リリースする — Milestone を実際に締めるとき
- カスタマイズ — 一周して調整したい点が見えてから
- 現在のスキル一覧（英語）
- 現在の成果物一覧（英語）