軽量SDD（Spec-Driven Development）ワークフロー。大規模コードベースへの機能追加・改修で、複数の機能追加・改修をまとめてリリースする場合に使用する。検討漏れ・デグレードを抑え、仕様と設計判断を恒常配置ドキュメント（リリース後も残る仕様書）に残すために使う。基本は`/agent-toolkit:spec-driven`でのユーザー明示起動。ただし既にspec-drivenで開発している形跡（恒常配置`docs/features/`・`docs/topics/`が整備済み、または`CLAUDE.md`でspec-driven採用が明記されている）があり、かつ大規模な機能追加・既存機能改修の相談を受けた場合で、ユーザーが呼び忘れていると判断できるときは、ユーザーに起動可否を確認した上で自動起動してもよい。
大規模コードベースへの機能追加・改修で、既存機能調査・仕様策定・設計・実装・クリーンアップを段階化する。 調査と実装はサブエージェントへ分業し、メインセッションのコンテキスト消費を抑える。
初めに開発中バージョンディレクトリ（既定ではdocs/v{next}/配下）に作業版ドキュメントを作成し、実装と設計判断をそこへ集約する。
リリース済み機能の最新仕様は恒常配置（既定ではdocs/features/・docs/topics/）を正とし、開発中の変更は恒常配置を直接編集しない。
開発中バージョンのリリース後、ディレクトリの内容を恒常配置ドキュメントへマージする。
適用対象:
非適用:
plan-modeスキルを使う）plan-modeスキルを使う）spec-driven-initスキルを使う）spec-driven-promoteスキルを使う）本スキルで共通に使う用語を以下にまとめる。
具体パス表記はすべて既定値で、プロジェクトのドキュメントで別の配置が規定されている場合はそちらを優先する（以降のreferences/配下でもこの前提に従う）。
プロジェクトがspec-drivenを採用しない旨を明記している場合は、本スキル群（spec-driven・spec-driven-init・spec-driven-promote）を起動せず、その旨ユーザーに伝える。
正式語として対称形「作業版ドキュメント」「恒常配置ドキュメント」を使う。
ファイルパスを直接指し示す文脈に限り、短縮形「作業版.md」「恒常配置.md」を使ってよい。
「恒久ドキュメント」「恒久.md」のような総称表現は用いない（指す対象が文脈ごとに揺れるため）。
docs/features/・docs/topics/配下。プロジェクトの既存機能仕様すべての正となる.md。既定はdocs/features/{機能名}.md（機能ドキュメント）とdocs/topics/{トピック名}.md（横断ドキュメント）docs/v{next}/配下。リリース完了後にspec-driven-promoteスキルで恒常配置へマージ統合され、物理ディレクトリは消滅するdocs/v{next}/）。ディレクトリ作成・削除など物理操作を指すときに使う{next}）: 次期リリースのバージョン番号。ステップ1でユーザーと合意の上で確定する。末尾が.0で終わる成分は末尾から順に省略する（例: 3.0.0→v3.0→v3、1.2.0→v1.2、1.2.3はそのままv1.2.3）。バージョン番号が定まらないプロジェクトでは、日付ベース（v2026-04-18）や単純連番（v1）も使ってよいSSO追加。恒常配置の機能単位と1対多・多対1・1対1のいずれにもなりうる.md（例: docs/v{next}/SSO追加.md）。恒常配置の対応先・背景・スコープ・受け入れ基準・主要設計判断・却下した代替案・既存改修時は改修前スナップショットを集約するspec-designerがステップ2後半で一括生成する作業版ドキュメントの初版。テンプレートの節を立て、計画ファイルの要点を転記した状態を指す~/.claude/plans/{自動生成ファイル名}.md（Claude Code標準のplan fileパスをそのまま使う）。## 却下した代替案・## 変更履歴節が判断経緯の一次記録となる恒常配置と開発中配置のパス一覧、および開発中配置に置く一時ファイルのサフィックス規則をまとめる。
docs/features/{機能名}.mddocs/features/ユーザー認証.md）docs/topics/{トピック名}.mddocs/v{next}/{作業テーマ名}.md・docs/v{next}/{トピック名}.mddocs/features/認証.md）を明示する.md内に「改修前スナップショット」節を設け、恒常配置の該当節を改修前にコピーする。昇格時は恒常配置へマージせず破棄するREADME.md（次期バージョン全体の概要と目次）
docs/v{next}/README.mddocs/v{next}/.cache/{作業テーマ名}.research-{nn}.md — spec-researcher出力（観点ごとに1ファイル、{nn}はゼロパディング2桁の連番）docs/v{next}/.cache/{作業テーマ名}.review-spec.md — spec-reviewer指摘（差し戻しループでは上書き）docs/v{next}/.cache/{作業テーマ名}.review-quality.md — code-quality-reviewer指摘（差し戻しループでは上書き）.cache/配下に置きgit管理から外す。.gitignoreへのdocs/v*/.cache/追記はspec-driven-initスキルが担当する。pyfltrなど品質ツール群の多くが.cacheをデフォルト除外対象とするため、品質チェックの干渉を受けずに済む恒常配置と開発中配置はドキュメントの粒度が異なりうる。
認証.md）。機能の全体像を網羅するSSO追加.md）。今回のリリースで加える変更を集約する例えば既存の認証.mdに対してSSO対応を追加する改修では、開発中配置にはSSO追加.mdを置き、昇格時に認証.mdへマージ統合する。
大きな新機能の追加などで単純な1対1対応になる場合もある。
docs/v*/群から恒常配置の初版を整備する作業）はspec-driven-initスキルで扱うspec-driven-promoteスキルで扱うどちらも手動起動または本スキルからの明示呼び出しでのみ使用する（ユーザー相談への自動起動対象ではない）。
横断ドキュメントと機能ドキュメントは命名規則とテンプレートが同じで、用途と配置ディレクトリのみ異なる。
判断基準は「複数機能で参照される設計判断・ガイドライン・共通用語」にあたるかどうか。
該当するなら恒常配置ではdocs/topics/、開発中配置ではdocs/v{next}/（作業テーマと同居）へ置く。
迷う場合は機能ドキュメントへ書き、後から必要に応じてdocs/topics/へ昇格する段階的運用を推奨する（早期の抽象化で維持コストが増えるのを避けるため）。
最終判断はステップ2後半でspec-designerが行う。判定が曖昧な場合はspec-designerからエスカレーションされるため、メインがユーザーへ確認する。
詳細情報はreferences/配下に委譲している。必要なテーマに応じて読み込む。
| 参照ファイル | 対象情報 |
|---|---|
references/workflow.md | 3ステップの詳細手順・既存機能改修フローとの差分・サブエージェント呼び出しテンプレート |
references/templates.md | 作業版ドキュメント・恒常配置ドキュメント・README.md・参照コメント・レビュアー呼び出しの書式テンプレート |
references/operations.md | 中断・再開の判定基準 |
| ステップ | 目的 | 主な成果物 | 主担当 |
|---|---|---|---|
| 1. Setup&Explore（plan mode前） | 要件・作業テーマ・次期バージョンの確定、恒常配置と開発中配置の場所特定、既存機能の並列調査 | リサーチ結果ファイル群（{作業テーマ名}.research-{nn}.md） | メイン＋spec-researcher |
| 2. Plan&Implement（plan mode 1回出入り） | 計画ファイル1本（大枠＋実装詳細）作成・codexレビュー合格、ExitPlanMode直後の設計ドキュメント立ち上げと実装 | 計画ファイル（~/.claude/plans/）、作業版ドキュメントの骨子・README.mdエントリ、実装差分 | メイン＋plan-mode＋spec-designer＋spec-implementer |
| 3. Cleanup（plan mode後） | 検証・ドキュメント整合性レビュー・コード品質レビュー・一時ファイル削除・コミット | format/lint/test合格、両レビュー合格、一時ファイル群削除、コミット | メイン＋spec-reviewer＋code-quality-reviewer |
ステップ終端にユーザー確認ゲートは置かない（ステップ間の進行許可は求めない）。ただし作業テーマ名・バージョン番号・横断ドキュメント化の要否など内容的な判断は都度ユーザーに確認する。 恒常配置と開発中配置の両方が常時参照対象となる。関連する既存機能は恒常配置を起点に特定し、進行中の関連仕様変更がある場合は開発中配置から取得する。 進行管理はメインのTaskCreateで行い、残タスクと開発中バージョンディレクトリ配下のファイル存在から再開ポイントを判断する。 初回導入時は小さな題材で3ステップを一度通しておくと期待動作を掴みやすい。
本スキルは条件付きで自動起動もありうる（description参照）。
自動起動した場合は、必ず最初にユーザーへ「本スキルで進めてよいか」を確認する（副作用の大きい多段作業のため）。
ユーザーが別方式を希望すればスキルを抜ける。
ステップ2ではplan-modeスキルを内部呼び出しし、計画ファイル作成とcodexレビューを委譲する。
codexレビュー手順・MCP優先／CLIフォールバックの切り替え・指摘への対応フローはplan-modeに従う。
本スキル側ではcodexレビュー手順を再記述しない（SSOTをplan-modeに置き、保守性を確保するため）。
ステップ2ではplan modeへ1回だけ出入りし、計画ファイルを1本作成する。
前半冒頭でEnterPlanModeツールを明示的に呼び出し、大枠方針・主要設計判断・実装詳細（file:line・変更内容）を同一計画ファイルにまとめ、codexレビュー合格でExitPlanModeする。
計画ファイルの## 却下した代替案・## 変更履歴節が判断経緯の一次記録となる。
ExitPlanModeの直後にメインが以下を行う。
spec-designerを呼び出し、計画ファイルとステップ1のリサーチ結果ファイル群を入力に、作業版ドキュメントの骨子・docs/v{next}/README.mdエントリ・必要なら横断ドキュメントを一括生成させる。計画ファイルの判断経緯のうち将来参照される要点は作業版.mdの「主要設計判断」「却下した代替案」節へ転記させるBASE_SHAとして記録するspec-implementerへ順次委譲する計画ファイル（~/.claude/plans/{自動生成ファイル名}.md）はcodex向けの照合材料として機能し、恒常配置ドキュメント（および作業版.md）は将来の人間向け参照資料として機能する。
3ステップを通じて起動するサブエージェントの役割と起動条件をまとめる。
いずれもmodel: sonnetで起動し、コンテキストはサブエージェント側に閉じ込めてメインの消費を抑える。
spec-researcher: 既存機能調査・影響範囲分析を担う。観点ごとに並列起動可。結果は呼び元指定の{作業テーマ名}.research-{nn}.mdへ書き出し、戻り値はファイルパスと短いサマリーに絞るspec-designer: ExitPlanMode直後に起動する設計ドキュメント立ち上げ担当。計画ファイルとリサーチ結果ファイル群を入力に、作業版ドキュメントの骨子・README.mdエントリ・必要なら横断ドキュメントを一括生成する。実装コードは編集しないspec-implementer: タスク単位の実装を担う。依存関係の都合から原則順次起動spec-reviewer: 仕様適合性・ドキュメント整合性レビューを担う。機能単位（全タスク完了・format/lint/test合格後）に1回起動。指摘は{作業テーマ名}.review-spec.mdへ書き出し、戻り値は判定と件数に絞るcode-quality-reviewer: コード品質レビューを担う。spec-reviewer合格後に機能単位で起動。指摘は{作業テーマ名}.review-quality.mdへ書き出し、戻り値はAssessmentと件数に絞るhaikuを呼ぶ運用上の原則は以下のとおり。
plan-mode呼び出しに集中する。調査・実装・レビューのコンテキストはサブエージェントに閉じ込めてメイン側のコンテキスト汚染を避けるformat/lint/test → spec-reviewer → code-quality-reviewerの順序を固定する（品質レビューは仕様適合性を前提に成立するため、順序を逆転させない）spec-implementerへ差し戻し、両レビュアーが合格を返すまでループするコードから恒常配置ドキュメントへの参照コメントは最小限に絞る。 過剰な参照はコード可読性を損ねるため。
.mdのみを指す（例: # 仕様: docs/features/ユーザー認証.md）docs/features/・docs/topics/）を指す。参照先の安定性を保つためdocs/v{next}/{作業テーマ名}.md）を指してよい。spec-driven-promoteスキルによるマージ統合時に、恒常配置のパス（該当機能ファイル）へ一括書き換える.research-*.md・.review-*.mdは参照しない（実装完了時に削除されるためリンク切れを招く）既存ファイルへの小さな追加や、恒常配置ドキュメントで直接触れられていない細部には参照コメントを書かない。
言語別の具体的な書式例はreferences/templates.mdを参照する。
運用上発生しやすい失敗パターンと対処方針をまとめる。 Cleanupステップ前や自動トリガー起動時には該当テーマの節に目を通す。
.research-*.md・.review-spec.md・.review-quality.mdはいずれもCleanupステップで削除する.research-{nn}.mdはゼロパディング2桁の連番で統一する（並列起動時の割り当て重複や順序揺れを避けるため）。レビュアー出力は作業テーマ単位で固定名とし、差し戻しループごとに同一ファイルを上書きするdocs/v{next}/.cache/ディレクトリが未作成だとspec-researcherの出力ファイル書き込みが失敗する。新規バージョンの最初の作業テーマに着手する際、メインはdocs/v{next}/.cache/の空ディレクトリのみ先行作成する（骨子・README.mdの生成は引き続きspec-designerが担う）.gitignoreへのdocs/v*/.cache/追記漏れ: 通常はspec-driven-initスキルが追記するが、本スキルを直接使い始めた場合は追記されていないことがある。初回起動時に.gitignoreを確認し、未登録なら手動で追記する（未登録のまま進めると中間成果物がgit管理下に混入し、pyfltrなど品質ツールの対象として拾われる）README.mdの更新漏れ: 作業テーマや横断ドキュメントを追加したのにdocs/v{next}/README.mdの一覧へ反映し忘れると入口が陳腐化する。ステップ2でspec-designerが作業テーマ一覧にエントリを追加し、横断ドキュメントを新設した場合は横断ドキュメント一覧にも追加する。Cleanupステップで最終確認する.mdの転記漏れ: spec-designerが計画ファイルの判断経緯を作業版.mdの「主要設計判断」「却下した代替案」節へ転記する。spec-reviewerの観点で転記漏れを検査するが、メイン側でもspec-designerの戻り値を確認し、実装着手前に転記完了を確かめるREADME.mdとの相互矛盾はspec-reviewerの責務で検査する。メイン側で見落としてもレビュアーで捕捉する前提だが、Cleanupステップの順序を守り最終反映後にレビュアーへ渡す.mdの情報重複: 計画ファイルはcodex向け照合材料、作業版.md（および恒常配置ドキュメント）は将来の人間向け参照資料、という関心の違いを意識するspec-driven-promoteスキルの実行時に恒常配置のパスへ一括書き換える。書き換え漏れは昇格後のリンク切れを招くため、昇格スキル内の検証手順を必ず踏む.mdを新規作成して行い、恒常配置を直接編集しない（昇格前に恒常配置と実装が乖離するのを避けるため）。恒常配置の既存記述は作業版.mdの「恒常配置の対応先」節で参照する.mdへ貼り付ける「改修前スナップショット」節はBefore/After検証専用であり、昇格時には恒常配置へマージせず破棄する。spec-driven-promoteスキル側で除外手順を踏む.mdの命名: 恒常配置の機能名と同じ名前で作業版を置くと単純上書き運用を誘発し、粒度差が隠れる。作業テーマを端的に表す名前（例: SSO追加.md）を付け、昇格時のマージ対象機能を「恒常配置の対応先」節に明示する