コンテンツにスキップ

カスタマイズ

SpecBind のライフサイクルと検証はそのままに、成果物の書き方、プロジェクト固有の判断基準、運用手順、役割ごとに使うモデルを、プロジェクトに合わせて調整できます。

このページでは、何を変えたいときにどこを編集するのかをまとめます。通常は場所を先に調べて手作業する必要はありません。コーディングエージェントへ設定したい結果を伝えると、 sb-configureが現在値を調べ、必要な変更、検証、アフターケアまで完遂します。

specbind configuration show

このコマンドは、エージェントと役割設定、テンプレート、ルール、アダプター、Steering の現在値を読み取り専用で要約します。current-defaultは現在の組み込み既定値と完全一致するという機械的な事実、project-contentは異なるという事実だけを表し、意図的に設定済みかどうかは断定しません。

変更したいことから選ぶ

変更したいこと 編集する場所 主な確認方法
Requirements や Design などの構成、見出し、例 .specbind/settings/templates/ specbind template list、specbind template read
Requirements、Design、Contract、Tasks、Steering の書き方や判断基準 .specbind/settings/rules/ specbind rule list、specbind rule read
リリース、Git、保留した指摘の届け先、実装完了時に追加する検証手順 .specbind/settings/adapters/ specbind adapter list、specbind adapter read
プロジェクトについてエージェントが長く参照する知識 .specbind/steering/ specbind steering list、specbind steering read
Spec の置き場所、成果物の言語、使うエージェント .specbind.jsonとspecbind installのオプション specbind install --dry-run ...
役割ごとのモデルと推論の深さ .specbind.jsonのagentRoles 設定後にspecbind install --dry-run

このページでは、Spec の置き場所が既定値の.specbindである前提でパスを書きます。 .specbind.jsonのspecDirを変えている場合は、その値に読み替えてください。

成果物テンプレート

テンプレートは、新しい成果物の構成と初期内容を決めるひな形です。見出し、節の分け方、例、テンプレート内のspecbind:instructionコメントを調整できます。

初回のインストールでプロジェクト側にコピーされるのは、構成をプロジェクトで所有する次の 4 つです。

  • settings/templates/specs/requirements.md
  • settings/templates/specs/design.md
  • settings/templates/specs/ui.md
  • settings/templates/roadmap.md

design.md と ui.md はいずれも Design の候補です。候補が存在するだけですべての Spec に生成されるわけではありません。 settings/rules/design-template-selection.mdが各design/<artifact_id>を required、conditional、disabledのいずれかに分類します。標準設定では design/mainは必須、design/uiは画面、操作、表示状態、レスポンシブ動作、 アクセシビリティなどのユーザー可視な責任がある場合だけ選択されます。

独自の Design テンプレートを追加する場合は、同じセレクターの分類と、 conditionalなら適用条件もこの Rule に追加してください。テンプレートとの対応が欠落、重複、または不明な場合、ルールの読み取りは安全側に停止します。

Roadmap テンプレートは、マイルストーン全体の変更要求、境界、分解判断、依存関係の理由を書く本文だけをカスタマイズします。milestone_id、基準、対象リリース、 作業項目は CLI が所有するため、このテンプレートには書けません。

Brief、Research、Contract、Implementation Notes の Spec テンプレートと、Steering のテンプレートも CLI に埋め込んであります。変更したいプロジェクトだけが、CLI の一覧に出てくるtemplate_pathへコピーして上書きしてください。

specbind template list spec
specbind template read spec requirements
specbind template list steering
specbind template read steering document
specbind template list milestone
specbind template read milestone roadmap

特定 Spec へ新しく配置するパスまで確認する場合は、次の読み取り専用コマンドを使います。

specbind template resolve spec <spec> <selector>

結果にはテンプレートのSourceと、設定済みの Spec ルートを含むプロジェクトルート相対の Project pathが含まれます。ファイル操作ではProject pathをそのまま使用します。

成果物を初めて作るときは、元のテンプレートとそのcreate指示をエージェントが読み、成果物として生成します。Markdown 本文では、プロジェクトが任意の名前付き生成出力を {{名前}}の形式で参照できます。名前は空ではなく、空白と波括弧を含まない必要がありますが、日本語を含む Unicode 名を使用できます。

specbind template read spec <selector>

異なる名前ごとに、対応するcreate output=<名前>指示がちょうど 1 つと、参照が 1 つ以上必要です。エージェントは指示を 1 回実行し、短い文字列または Markdown 断片全体を生成できます。同名の参照はすべてその同じ出力で置換します。CLI はこの対応だけを検証し、内容の生成や比較は行いません。

<!-- specbind:instruction create output=components
新設または変更する責任境界ごとにH3小節を1つ生成する。
各小節に実際のコンポーネント名を付け、その責任を記載する。
-->

{{components}}

componentsの出力は、それぞれ異なる複数の H3 小節を含められます。それでも生成結果全体が 1 つの Markdown 断片です。既定テンプレートのspecとartifact_idも特別な組み込み出力ではありません。それぞれのcreate output指示が、現在の作成時の文脈やリテラルな Front Matter から内容を生成するようエージェントへ指示します。

出力宣言の欠落、重複、未使用、create以外での宣言、Front Matter での参照はテンプレート診断になります。未展開の参照が残った成果物も無効です。template readは出力参照と指示を含む元のテンプレートをバイト単位でそのまま返します。

read 結果は未記入のひな形であり、そのまま有効な成果物とは限りません。既定の Requirements は実際の Requirement と Acceptance Criterion を書くまで検証に失敗します。 Brief、Research、Implementation Notes も、見出しやコメントだけでは有効になりません。 作成指示に従って実内容を埋め、createコメントを除いてから有効な成果物として検証・保存してください。

テンプレートを変えても、すでにある成果物は書き換わりません。変更後に新しく作る成果物から、新しいテンプレートが使われます。

sb-configureはテンプレート変更後に、既存成果物も合わせるかを確認します。 同意した時点では候補と影響のプレビューだけを作り、format-only、instruction-update、 structural、semantic、conflictに分類します。実際の書き換えは別に確認し、意味を変える変更は Requirements や Design など、その成果物を所有するスキルへ引き渡します。Gate、 完了記録、リリース済みアーカイブ、CLI 所有の構造化状態は、テンプレートに合わせるという理由で直接書き換えません。

specbind:instructionコメントには、用途を必ず 1 つ指定します。

<!-- specbind:instruction create 初回の識別子を決める。 -->
<!-- specbind:instruction maintain 既存IDを振り直さずに更新する。 -->
<!-- specbind:instruction consume これは補助情報であり権威ではない。 -->
  • createは初回作成時だけ従い、成果物には残しません。
  • maintainは初回作成時に成果物へコピーし、以後の更新時にも読み、残します。
  • consumeも成果物へコピーし、その成果物を入力として参照するときだけ読みます。

用途なし、または未知の用途はテンプレート診断になります。既存成果物は、作成時にコピーされたmaintainとconsumeを自分で所有します。テンプレート側だけを変更しても、 既存成果物の指示は変わりません。

成果物または Steering を用途別に読むと、CLI は反対側の永続指示だけを除いて返します。 --forを省略した場合は、指示コメントを含む元の Markdown をそのまま返します。

specbind artifact read <spec> <selector> --for maintain
specbind artifact read <spec> <selector> --for consume
specbind steering read <selector> --for maintain
specbind steering read <selector> --for consume

Warning

type、artifact_id、必須の識別子や対応関係など、CLI が読み取る構造は残してください。自由に変えられるのは、この機械可読な部分を保った範囲だけです。

共有ルール

共有ルールは、複数のエージェントが共通で参照する、プロジェクト固有の執筆方針と判断基準です。内容は強めても、緩めても、書き換えても、削除しても構いません。

テンプレート指示とルールを使い分ける

どこに指示を書くか迷ったときは、その指示が 1 つの成果物に閉じるか、複数の作業で共有されるかで判断します。

指示や基準の性質 置く場所
そのテンプレートから作る成果物だけの作成、更新、読み方 テンプレート内のspecbind:instruction
複数の成果物、エージェント、作成、検証、レビューで共有するプロジェクト判断基準 settings/rules/
プロジェクトが弱められない製品共通の意味や品質基準 製品 protocol （カスタマイズ対象外）
作業の順序、分岐、停止条件 製品管理のスキル（カスタマイズ対象外）
必須構造、状態遷移、機械的な整合性 CLI （カスタマイズ対象外）

テンプレートのmaintainとconsumeは、初回作成時に成果物へコピーされ、その後は各成果物が所有します。テンプレートを更新しても、既存成果物の指示は変わりません。 一方、共有ルールはスキルが作成時だけでなく検証やレビュー時にも読みます。既存成果物を含めて次の作業から同じ方針を適用したい場合や、Design 作成と Contract review のように複数の作業で同じ判断基準を使う場合は、独立した共有ルールに置きます。

逆に、特定の見出しをどう埋めるか、その成果物の ID を更新時にどう保つかなど、1 つの成果物だけに必要な指示は共有ルールへ重複させず、テンプレートの指示に置きます。

ファイル 書けること
ears-format.md Requirements の EARS 表現、主語の立て方、テストしやすさの好み
design-principles.md アーキテクチャ、インターフェース、データ、エラー処理、記述の細かさ
design-template-selection.md 各 Design テンプレートを必須、条件付き、無効のどれにするか
contract-principles.md 所有境界、外部へ公開する接点、互換性、依存の向きに関する方針
tasks-generation.md Task の大きさ、分割の仕方、テスト作業の扱い
steering-principles.md Steering に残す知識の粒度、例の書き方、更新の方針
language-style.md 正確な識別子を保ちながら、成果物とスキルの報告を自然な日本語で書く方針

v1 のスキルが読むのは、この 7 つのパスだけです。別の名前でルールファイルを足しても読み込まれません。

初回インストールでは、どの言語でも使う 6 つの既定ルールに加えて、--language jaを選んだ場合だけ日本語のlanguage-style.mdを作成します。このルールは任意で、 プロジェクトが所有します。すべての製品スキルが成果物や報告を書く前に読みますが、 ファイルがなくても設定言語で出力するという製品の契約は変わりません。後からインストールを実行しても、既存の内容は上書きされません。

specbind rule list
specbind rule read ears-format --for consume
specbind rule read ears-format --for maintain

一覧は既知の 7 件と、各ファイルがプロジェクトに存在するかを返します。スキルが判断基準として使うときは--for consume、ルール自体を更新するときは--for maintainを指定します。 省略すると、指示コメントを含む Markdown をそのまま返します。ルール内でも specbind:instruction maintainとconsumeを使用できますが、初回作成専用のcreateは使用できません。ファイルがない場合はNO_CHANGE RULE_ABSENTとなり、製品 protocol は引き続き適用されます。

また、ルールで弱められないものがあります。成果物の必須構造、Gate、承認、状態の遷移、スキルの必須手順、CLI の検証です。

運用アダプター

アダプターは、プロジェクトごとに違う運用のやり方を、自然言語でエージェントに伝える場所です。本文は自由に書けます。コードブロックを書いても、自動実行されるフックにはなりません。

ファイル 伝える内容
release.md リリースの準備、公開、検証、後片付け
git.md どの単位で区切るか、ステージング、コミットメッセージ、ブランチ、push の方針
deferred.md Gate を止めるほどではない指摘を残す先（ Issue tracker、wiki、ファイルなど）
validation.md Spec 全体の実装を最終検証するとき、プロジェクト固有で追加して行う手順 
specbind adapter list
specbind adapter read git

一覧のstateは、ファイルがないabsent、まだ書き換えられていないscaffold、実際に従う方針があるactiveを区別します。deferredには最初から動作する既定値があり、 既定のspecDirでは OKF 準拠の.specbind/deferred.mdへ全 Spec の保留指摘を記録します。 この記録は作業キューではなく、人が Roadmap へ採用するまでスコープにはなりません。

未編集のひな形には、完全な HTML コメント <!-- specbind:adapter-scaffold -->が入っています。このマーカーがある間は本文全体が方針として扱われません。内容を具体化したらマーカーを削除します。テンプレート用の specbind:instructionはアダプターの状態には影響しません。

release.mdが未設定のままリリースを始めると、Release スキルがリポジトリ内のワークフロー、 バージョンマニフェスト、ビルドスクリプト、既存ドキュメントを調べて具体案を提示します。 承認した実行ではrelease.mdだけを保存・ローカルコミットして停止し、公開は行いません。 この設定変更後は完了記録を再検証してから、改めてリリースします。プロジェクト固有の作業が本当に不要なら、Front Matter を残して本文を空にすることで明示できます。

gitにも動作する既定値があります。Discovery の完了、各 Gate の承認、Contract レビューの受理、各実装 Task の完了、sb-configureによる 1 つの設定変更など、スキルが定めた安全な完了単位ごとに、関係するパスだけをローカルコミットします。現在のブランチを使い、既定ではpushやamendなどの履歴書き換えを行いません。初回のリリースアダプター設定と、release finalizeが生成するログ・アーカイブ・後片付けも、それぞれ公開対象とは別のローカルコミットになります。自動コミットを望まない場合はgit.mdの本文を空にしてください。ファイルを削除しても実行時は同じですが、次のインストールで既定値が再作成されます。既存のプロジェクト所有ファイルは、インストールを再実行しても上書きされません。

実装 Task は計画の順に 1 件ずつ実行します。1 回の依頼で複数 Task を進める場合も、各 Task の実装、レビュー、CLI への完了記録が終わった直後に、その Task だけのチェックポイントを作ってから次へ進みます。複数 Task の完了を最後の 1 コミットへまとめるのは既定動作ではありません。Spec 全体の完了記録は、Task の実装コミットとは別です。

アダプターはあくまで方針であり、広い権限を与えるものではありません。変更を伴うスキルの依頼は既定のローカルチェックポイントまでを含みますが、git.mdにpushの方針を書いても、それだけでエージェントがpushできるようにはなりません。pushにはあなたの依頼と実行環境の権限が別途必要です。

validation.mdは、プロジェクトが追加の最終検証手順を定めるまでは未設定のひな形です。 sb-configureは既存のスクリプト、CI、実行手順、fixture、ブラウザや実機の設定、接続済みツールとの連携を調べ、ひな形を置き換える全文または現在の方針への変更案を提示できます。 有効な手順は、必須の completion-verification protocol とリポジトリの標準チェックに追加されます。置き換えたり弱めたりすることはできません。不一致が確認できた場合はNO-GO、 必要な環境、認証、実機、人による確認、ツールなどが利用できず必須手順を実行できない場合は MANUAL_VERIFY_REQUIREDとなります。

本文には、コマンド、ブラウザや実機の操作、MCP サーバーなどの接続済みツール、人による目視確認、準備、合否を判断できる結果、後片付けを記載できます。アダプターだけで認証情報の利用、外部変更、ソース編集、指摘の修正を行う権限は得られません。本文を空にした場合は、 プロジェクト固有の追加手順なしという意味です。完了記録を受理したあとに変更すると、通常のプロジェクト revision の規則によって以前の完了記録は古くなり、再検証が必要になります。

v1 が読むのは上の 4 つだけです。settings/adapters/に好きなファイルを置いて種類を増やす仕組みではありません。

Steering

Steering は、製品の目的、技術方針、構造、テスト方針、セキュリティの考え方など、 これから先の作業でも参照するプロジェクトの知識です。作業中だけのメモや、すぐに変わる状態は書きません。

sb-steeringスキルが、現在の一覧を確認したうえで、初期作成、既存文書の同期、 1 文書の追加を行います。既定のproduct、tech、structureという分け方は提案です。 名前を変えても、統合しても、分割しても、使わなくても構いません。

specbind steering list
specbind steering read <selector> --for consume

Steering は Gate の入力ではなく、古くなったかどうかの判定にも使いません。ただし、 完了記録を受理済みの Milestone の途中で編集すると、完了記録の再検証が必要になることがあります。Milestone を始めてから最初の完了記録までの間か、リリースの後片付けが終わったあとに更新すると、扱いやすくなります。

プロジェクトの形を整えるときの推奨順

初回インストール後の見直しや、テンプレートをどう分けるかがプロジェクト全体の前提に依存する場合は、まず Steering の初期作成または同期を提案します。次に、確定した継続的な方針とリポジトリの事実を、現在の Requirements ・ Design テンプレートと共有 Rule に照らし合わせます。その責任が既存のテンプレートや Rule で共通して扱えるなら更新し、 複数の Spec で独立した設計判断とトレーサビリティを継続して必要とする場合だけ、Design テンプレートを追加します。

Steering が空であること自体は有効な状態です。空だからといって作成せず、欠けているプロジェクト知識を必要としない明示的で狭いテンプレート変更も止めません。Steering はプロジェクトに長く残る事実や方針を記録し、各 Spec にどの候補を適用するかは引き続き design-template-selection Rule が決めます。

Web、モバイル、API、インフラといった技術ラベルだけでテンプレートを増やしません。 ユーザーに見える Web ・モバイルの変更は通常、既存の UI 候補で扱えます。API の互換性やインフラの方針は、まず Steering と Design または Contract の Rule に置きます。design/apiや design/infrastructureのような条件付き候補は、その責任に独立した設計の扱いが繰り返し必要になるときだけ追加し、適用条件にはフレームワークの有無ではなく責任を記述します。

将来の API やインフラに触れる依頼でも、現在の Steering とリポジトリの事実から独立した継続的責任が確認できない場合、sb-configureは既存の面を更新する案と条件付き候補を追加する案を示して、どちらを意図するか確認します。将来使う技術の名前だけから、新しい候補を推定して追加しません。

1 回限りの Design 補足

Design の作成中に、ある Spec だけが独立した所有境界や検証上の関心を持つ継続的な責任を含み、既存の選択済み Design では明確に表せないことがあります。その場合、エージェントは artifact ID、対応する Requirements、配置先、既存 Design へ統合する案を記録した Spec ローカルの補足 Design を、現在の Design ドラフトとして作成します。これだけのために確認で止まることはなく、 通常の Design Gate がレビュー境界のままです。

この 1 回限りの文書は、設定済み SpecBind ルート配下の specs/<spec>/design/<artifact_id>.mdに置きます。通常のSpecBind Designなので、 トレーサビリティ、検証、フィンガープリント、Design Gate の対象です。プロジェクト全体のテンプレートやdesign-template-selectionは変更しません。同じ責任が別の Spec でも独立して必要になったときにだけ、エージェントが条件付き候補テンプレートへの昇格を提案します。

プロジェクト設定と役割別モデル

初回のインストールでは、成果物の言語、使うエージェント、Spec の置き場所、ルート指示ファイルへの案内追加を選べます。

specbind install --dry-run --agent codex --language ja --spec-dir .specbind --project-instructions

specDirは初回のインストールで決まり、v1 では導入後に変更できません。言語と、選んだエージェントは.specbind.jsonに保存されます。あとからエージェントを追加することはできます。1 つのエージェントを外すときはspecbind remove-agent、連携全体を外すときは specbind uninstallを使います。詳しくはエージェントの削除とアンインストールを参照してください。

.agents/skills/とAGENTS.mdの共通形式だけを導入する場合は--agent genericを指定します。genericには役割定義がないため、agentRolesの対象にはできません。

実装、レビュー、調査といった役割ごとに、使うモデルを変えることもできます。 .specbind.jsonのagentRolesで上書きしてください。Codex では、あわせて reasoningEffortも指定できます。

{
  "agentRoles": {
    "codex": {
      "implementer": {
        "model": "gpt-5.6-sol",
        "reasoningEffort": "high"
      }
    },
    "claudeCode": {
      "researcher": {
        "model": "sonnet"
      }
    }
  }
}

役割はplanner、implementer、reviewer、debugger、researcherの 5 つです。 指定しなかった役割には、SpecBind の既定のモデルが使われます。

変更したら、リポジトリに未コミットの変更がない状態でドライランの結果を確認し、インストールを実行し直してください。.codex/agents/specbind-*.tomlや.claude/agents/specbind-*.mdは直接編集せず、設定から作り直します。

カスタマイズできないもの

次は SpecBind が管理している製品側の契約です。直接編集しても、サポートされたカスタマイズにはなりません。

  • .agents/skills/sb-*/と.claude/skills/sb-*/のスキル本体
  • .codex/agents/specbind-*.tomlと.claude/agents/specbind-*.mdの役割定義
  • CLI が埋め込むプロトコルとスキーマ
  • Gate、承認、フィンガープリント、状態の遷移、必須のトレーサビリティ
  • spec.yaml、tasks.yaml、Roadmap など、CLI が所有する構造化された状態
  • ルート指示ファイルの中の、SpecBind 管理ブロック

プロジェクト固有の方針を足したいときは、スキル本体を書き換えず、目的に応じてテンプレート、ルール、アダプター、Steering のどれかに置いてください。

変更するときの進め方

通常はコーディングエージェントへ目的を伝え、sb-configureに次の一連の作業を任せます。

  1. configuration showと関係するlist、readで現在値を確認する。
  2. 目的をテンプレート、ルール、アダプター、Steering、インストール設定の所有面へ分類する。
  3. 変更案と影響を示し、必要な確認を得てプロジェクト所有面だけを変更する。
  4. インストールの再実行や専用スキルへの委譲を含め、所有する経路で反映する。
  5. 機械的な検証を再実行し、必須（required）、推奨（recommended）、任意（optional）に分けてアフターケアを 完了または明示的に見送る。

Steering の執筆はsb-steering、成果物の意味変更は各成果物のスキルが所有します。 sb-configureはそれらへ委譲しても、依頼された設定変更全体の完了確認と報告を引き続き担当します。有効な Git アダプターが定める狭いローカルチェックポイントは通常の完了手順に含まれますが、削除、push、ブランチ変更、タグ、履歴操作、外部操作、ライフサイクル変更は別の確認境界です。

インストールされるファイルの全体像は 現在の成果物一覧（英語）で確認できます。

ユーザーガイド | 基本概念 | 現在の成果物一覧（英語）