version-start

# version-start: バージョン開発開始の定型手順 > **skill version**: 1.5.0 セッション内で初めて本スキルを使用するときは「version-start スキル v1.5.0 を使用します」と宣言する。 新しいバージョンの「設計」フェーズを、コンテキストゼロの状態から実装計画確定直前まで進めるための手順書。**このスキルの完了地点は「実装計画書のドラフト完成+未回答の確認事項の提示」であり、実装には絶対に入らない**。実装開始はユーザーの明示指示を待つ。 ## 前提と一般化ルール - 対象プロジェクトの言語・技術スタック・文書規約は**ハードコードしない**。すべて**進行文書**と既存文書・既存コードから発見する。 - 本スキルで言う**進行文書**とは、そのプロジェクトのコンセプト・方針・バージョンごとの計画概要を記載した文書を指す。**名称も形式もプロジェクトによって異なる**(`PROJECT.md`、`ROADMAP.md`、`docs/`配下の設計文書、リポジトリのWiki、issueで管理している場合もある)。リポジトリを見て特定する。**進行文書が判別できない場合は手順を進めず、その所在をユーザーに確認する**。 - 実装計画・実装記録の置き場となるフォルダの名前もプロジェクト毎に異なる。進行文書内の参照や既存の配置から特定する。 - 各文書のフォーマット・言語(日本語/英語)は、**同プロジェクトの直近バージョンの同種文書を雛形として踏襲**する。初バージョンで前例が無い場合のみ本スキル末尾の標準構成を使う。 ## 版の状態の見分け方 > この節は version-start / version-implement / version-release の3スキルが**同じ文**で持つ。直すときは3つを同時に直す。 各スキルの入口の手順は、指定された版が**いまどの段階にあるか**を本節の①〜③で決め、要約を表示してから進む。 **① 状態の表。** 表は後ろの状態(リリース済み)から並べてある。判定は**上から順に当て、最初に当てはまった状態を採る**。リリース済みの版はブランチも計画書も持つので、未着手の側から当てると誤る。 | 状態 | 意味 | 見分ける証拠 | |---|---|---| | リリース済み | リリースが完了 | タグがあり、作業ブランチが既定ブランチにマージ済み。進行文書の当該版の記載がリリース済みを示す | | リリース中 | リリース(version-release 相当)が途中 | PR・既定ブランチへのマージ・タグ・リリース文書・進行文書のリリース済みの記載のうち、**一部だけ**がある | | 実装完了 | 実装が完了し、リリース待ち | 実装記録に完了要件の全数照合と申し送りがあり、進行文書の当該版の記載が実装完了を示す。タグが無く、既定ブランチに未マージ | | 実装中 | 実装(version-implement 相当)が途中 | 計画書が「確定」になっている、または実装記録がある。実装記録に完了要件の全数照合が無い。タグが無い | | 設計済み | 設計が完了し、計画は確定待ち | 作業ブランチ・計画書(ドラフト)・進行文書の当該版の記載(設計)があり、実装記録が無い | | 設計中 | 設計(version-start 相当)が途中で止まっている | 作業ブランチと計画書のどちらか一方だけがある。または計画書はあるが、直近版の計画書にある節が欠けている。または両方あるが、進行文書に当該版の記載が無い | | 未着手 | 誰も手を付けていない | 作業ブランチ・計画書・実装記録・タグのいずれも無い | **② 証拠の在処。** 名前や置き場は決め打ちせず、進行文書と既存の配置・慣行から特定する。 | 証拠 | 見る場所 | 注意 | |---|---|---| | 作業ブランチ | ローカルとリモートの両方のブランチ一覧。命名慣行は既存ブランチから読む | **リモートにだけあって計画書が手元に無い**ときは、別マシンで設計中・設計済みの可能性がある(計画書が git 非追跡のプロジェクトで起こる) | | タグ | タグ一覧(リモートから取得してから見る)。命名慣行は既存タグから読む。**直近リリース版は、タグを版番号順に並べた最大** | 取得できなければローカルのタグで判定し、その旨を要約に書く | | マージ状況 | 作業ブランチの先端が既定ブランチに含まれるか | 既定ブランチはリポジトリの実際のものを使う | | PR・リリース文書 | ホスティングサービスの CLI で照会する。**照会するのは version-release だけ**(version-start / version-implement は git の証拠で足りる) | 照会できなければ「未確認」と書く。推測で埋めない。CLI のアカウント確認の規定に従う | | 計画書 | 実装計画の置き場(進行文書の参照と既存の配置から特定)。存在、前付けの状態(ドラフト/確定)、直近版の計画書と比べた節の欠け | 直近版が無い初版は、version-start が定める標準構成と比べる | | 実装記録 | 同じ置き場。存在、進捗管理の表、完了要件の照合の節、申し送りの節、未解決の中断論点 | | | 進行文書 | 当該版の記載(状態〈設計/実装完了/リリース済み〉と日付、要点。旧形式の版ごとのエントリも記載として読む)、次版への要望の反映済みの印、ロードマップ | **進行文書が次に予定している版**はここから読む(未反映の要望、ロードマップの次の版) | | 版宣言ファイル | version-release の G1 が探索するもの(例: `VERSION`)。現在値が直近リリース版と一致するか | 補助。食い違えば要約に書く | **③ 要約の形。期待どおりでも必ず表示する。** - リポジトリ(名前と場所)と進行文書の表題 — 別プロジェクトの版番号を打っていないかを目に入れるため - 直近リリース版(タグ) - 進行文書が次に予定している版 - 着手済みで未リリースの版(ブランチまたは計画書があってタグが無いもの) - 指定された版と、①で決めた状態とその根拠 - 判定: **一致**(このスキルが期待する状態)か、食い違いの種類(下の語彙) **食い違いの語彙。** 版 A.B の「後継」は A.(B+1) または (A+1).0。引数は `X.Y.Z` でも `X.Y` でも受け、ブランチ名とタグ名は慣行に従って読み替える。 | 語 | 定義 | |---|---| | 飛び越し | 指定版より小さい版に、リリースされていないものがある(着手済みで未リリース、または進行文書が予定していて未着手) | | 不在 | 指定版が進行文書のどこにも無く、直近リリース版の後継でも、着手済みで未リリースの版の後継でもない。**別プロジェクトの版番号の疑い** | | 後退 | 指定版が直近リリース版より小さい。タグがあればリリース済みの扱い、無ければ不在の扱い | | 前工程が未了 | 指定版の状態が、このスキルが期待する状態より前 | | 後工程に進んでいる | 指定版の状態が、このスキルが期待する状態より後 | | 自スキルの途中 | 指定版の状態が、このスキル自身の「途中」(設計中/実装中/リリース中)。**再開の対象** | **判定の順**: ①で指定版の状態を決める → 不在(状態が未着手のときだけ起こる) → 飛び越し → スキルごとの入口の判定。不在と飛び越しが同時なら不在を優先する(別プロジェクトの疑いの方が重い)。入口の判定は各スキルの表を上から順に当て、最初に当てはまった行を採る。不在と飛び越しは、行に当たらなくても要約に書く。 **選択肢の出し方。** 食い違いのときは、何が食い違っているか、各選択肢を採るとどうなるか、推奨案とその理由を、計画書もコードも精読していない読み手が判断できる日本語で書く。ブランチ名・ファイル名・コマンドは括弧書きに留める。選択肢を示して回答を得られる対話手段があればそれを使い、無ければ通常の対話で尋ねる。**得た方針でそのまま継続する**(回答を待って中断する形にしない)。「停止」を選ばれたら、要約と次に使う手順を報告して止まる。**期待どおりのときは確認を取らず、要約の表示だけで進む。** ## 申し送りの扱い > この節は version-start / version-implement / version-release の3スキルが**同じ文**で持つ。直すときは3つを同時に直す。 **申し送りとは**、将来の版で行動を要する事項である。環境の事実・教訓・観察の記録は申し送りではなく実装記録に残す(申し送りを必要以上に重く扱わないために、まず「事実」を申し送りから外す)。 **3段階。** 上から順に当て、最初に当たった段階を採る。どれにも当たらなければ Optional。 | 段階 | 定義 | |---|---| | Critical | 近い将来の版で対応が必須のもの。意図的に先送りして実装が存在しない部分、明らかなセキュリティホール、致命的なバグ、依存ライブラリ・外部サービスの仕様変更による動作不能(の予告) | | Recommended | 実装することがプロジェクトの自然な次の版になるもの。大きな性能改善、利用者体験の明確な向上 | | Optional | それ以外。完全性は上がるが前2者ほどの重大性は無いもの | **申し送り文書。** 内部資料置き場(実装計画・実装記録と同じ置き場)に1つ置く。名前は進行文書や既存のファイルに別名があればそれ、無ければ `エージェント申し送り事項.md`。**無ければ最初に必要としたスキルが作る。** 形式は段階ごとの表(列: ID／発生版／要旨／実装すると何が変わるか／望ましい実装／考えられる影響／状態〈未着手・採用(vX.Y)・保留〉)と、末尾の「消去した項目」(ID／消去日／理由)。ID は `H` に通し番号を付け、消去しても再利用しない。 **消去の規則。** version-start と version-release は文書を見直し、obsolete になった項目(実装済み・対象消失・ユーザーが恒久的に対応しないと指示したもの)を本文から消して「消去した項目」に1行残す。消去はユーザーに確認してから行う。 **採用の規則。** 進行文書の要望欄(ユーザー記載)が最上位であり、申し送りはそれを補う参考に過ぎない。version-start は **Critical だけ**「本版で対応するか」をまとめて1回尋ねる(Critical が無ければ尋ねず、その旨を報告する)。Recommended と Optional は件数と要旨の一覧を示すだけで、採用を勧めず、計画に勝手に入れない(ユーザーが選んだものだけ入れる)。採用が決まった項目は version-start が状態列を「採用(vX.Y)」にし、実装が終わった項目は version-implement の G3 で消去の規則に回す(理由は実装済み)。 **進行文書の記載。** 版ごとの記載は進行文書の1か所に集約する(履歴の表の1行など、進行文書の既存の形に従う)。各フェーズ(設計・実装完了・リリース)は追記ではなくその1か所を**更新**し(状態と日付、要点)、合計の目安は200字。詳細は計画書と実装記録に書く。ユーザー記載は消さない。旧形式(版ごとに設計／実装完了／リリースのエントリを足す形)が既にある進行文書では、既存の版は旧形式のまま読み、新しい版から集約する。旧形式のエントリしか無い版(移行期)は、そのエントリを当該版の記載として更新するか、新しい形へ写してから更新する。 ## 手順 ### 1. 版番号の特定と状態照合 - 引数の版番号を採用。引数が無ければ進行文書から「次はvX.Y」を特定し、ユーザーに確認してから進む。 - **「版の状態の見分け方」の表を引いて証拠を集め、要約を表示する。** 本スキルが期待する状態は**未着手**。判定は次の表を上から順に当てる。 | 判定 | 扱い | 選択肢(推奨を先頭に) | |---|---|---| | リリース済み | 停止が基本 | (a) **停止**(推奨) (b) 次の版で始め直す(進行文書が次に予定している版があればそれ、無ければ、まだ着手していない最小の後継の版番号を示す) | | 不在 | **別プロジェクトの版番号ではないか**を明示する | (a) **停止して確認**(推奨) (b) 進行文書が次に予定している版で始める (c) 指定版で続行(進行文書に無い版を新設する。計画書の前付けにその旨を記す) | | 飛び越し | 下位の未リリース版を示す | (a) **下位の版を先に進める**(推奨。未着手ならここで始める。着手済みならその状態に応じた手順を案内して停止) (b) 指定版で続行(意図的な飛び越しや並行開発。前付けに理由を記し、下位の版が残ることを要約に書く) (c) 停止 | | 設計中(自スキルの途中) | 再開する | (a) **再開**(推奨。「中断からの再開」に従う) (b) 停止 (c) リモートにだけブランチがあり計画書が手元に無いなら、別マシンの成果物を持ち込んでから再実行 | | 設計済み・実装中・実装完了・リリース中(後工程に進んでいる) | 停止し、次に使う手順を案内する。選択肢は出さない(採れる行動が一つ) | 設計済みなら「§0 に未回答があれば回答を、確定済みなら version-implement へ」。実装中以降は該当する手順(version-implement / version-release)を案内 | | 一致(未着手) | 進む | **確認は取らない。** 要約の表示だけで手順2へ | - 進行文書の当該版スコープ(ロードマップが別文書ならその該当節も)と、**前版の記載(旧形式なら完了エントリ)**を読み、この版で「やること/やらないこと(スコープ外)」の輪郭を掴む。 ### 2. 文書読解 — 読解手段は内容に応じて選択する 読むべき文書: 進行文書の全体 / ロードマップの該当節 / **申し送り文書**(「申し送りの扱い」の節。無ければ直近1〜2版の実装記録の申し送り節) / 直近1〜2版の実装記録 / 関連する事前調査資料。 読解手段は**メインセッションが文書ごとに選択**する。判断基準: | 手段 | 使いどころ | |---|---| | メインセッション自身が読む | 設計判断に直結する骨幹文書(進行文書、ロードマップ該当節、申し送り文書)。全文のニュアンスが計画品質を左右するもの | | 上位の読解役サブエージェントへ委譲 | 内容の高度な把握・構造化要約が必要な長文資料(過去版の実装計画・実装記録の全体、長い事前調査資料) | | 軽量な読解役サブエージェントへ委譲 | 機械的な抽出・検索で足りるもの(特定節の抜き出し、キーワード該当箇所の収集、ファイル構成の列挙) | 委譲する場合は自己完結したプロンプト(対象パス・抽出してほしい観点・出典付き報告の指示)で、独立したものは**並列**に投げる(エージェントの同時実行制約の範囲内で)。委譲結果は鵜呑みにせず、計画に直結する事実は必要に応じて原典を確認する。 ### 2b. 申し送りの確認 「申し送りの扱い」の節に従う。申し送り文書が無ければ、直近1〜2版の実装記録の申し送り節を読んで本手順を当て、文書は手順5で作る(計画書と同じ置き場。本手順の分類結果を載せる)。 1. **消去**: obsolete の候補(実装済み・対象消失・ユーザーが恒久的に対応しないと指示したもの)を列挙し、消去をまとめて1回確認する(候補が無ければ尋ねない。文書への書き込みは手順5で、作業ブランチ上で行う)。消した項目は「消去した項目」に1行残す。 2. **Critical**: 該当する項目を列挙し、「本版で対応するか」を ID ごとに答えられる形で、選択肢を示して回答を得られる対話手段でまとめて1回尋ねる(手段が無ければ通常の対話で。1の消去の確認と同時に尋ねてよい)。**Critical が無ければ尋ねず「Critical 無し」と報告する。** 見送った項目は状態列を「保留」にする。 3. **Recommended / Optional**: 件数と要旨の一覧を示すだけにする。採用を勧めない。ユーザーが名指しで選んだものだけをスコープに入れる(採用した項目は Critical と同じく状態列を「採用(vX.Y)」にし、完了要件に入れる)。 4. 結果(消去した ID、Critical の有無と ID ごとの採否、ユーザーが選んだ ID。無ければ「なし」)を計画書の §0 に「申し送りの確認の結果」として記録する。中断からの再開で §0 に記録済みなら尋ね直さない。 ### 3. コードベース把握 - この版で触ることになる「接ぎ木点」(変更対象のモジュール、拡張ポイント、既存のインターフェース、設定・CLI・テストの構造)を調査する。手段の選択基準は手順2と同じ(コード調査は読解役・探索役サブエージェントへの並列委譲が基本、設計判断に直結する核心部はメインが読む)。 - 外部仕様の事実確認(ライブラリのバージョン制約、APIの挙動など)が必要ならWeb調査役サブエージェントへ委譲する。**まずローカルのコード・設定・ドキュメントを確認し、不明点は推測せず「仮定」として明記**する(調査ルール)。 ### 4. ブランチ作成 - 作業ツリーがクリーンであることを確認する(未コミット変更があればユーザーに確認)。 - プロジェクトのブランチ命名慣行を`git branch -a`と過去の記録から読み(例: `v0.7`)、**当該版のブランチが無ければ作成**する。リモートがあればpushする。 - pushが権限・認証エラーで落ちた場合は、**ホスティングサービスのCLIのアクティブなアカウントがリモートの所有者と異なる**可能性を疑う(CLIが複数アカウントを保持できる構成がある)。確認し、異なっていればユーザーの承認を得て一時的に切り替え、**作業後に必ず元へ戻す**。承認を求める際も手順は停止せず、その場で方針を聞いて継続する。 - **再開のときは「中断からの再開」に従う**(既にあるブランチを作り直さない)。 ### 5. 実装計画書の作成 **再開のときは「中断からの再開」に従う**(既にあるドラフトを全文読んでから書き、消さない)。 実装計画の置き場に「vX.Y実装計画.md」(命名はプロジェクトの慣行に合わせる)を作成する。**直近版の実装計画のフォーマットを踏襲**すること。**申し送り文書が無ければここで作る**(「申し送りの扱い」の形式。手順2b の分類結果と消去を書く)。あれば、手順2b で確認した消去と、採用した項目の状態「採用(vX.Y)」をここで書く。前例が無い場合の標準構成: 1. 前付け(作成日・作成者・状態=**ドラフト、ユーザーレビュー待ち**・参照資料・新規調査の一覧) 2. **§0 ユーザー確認事項**(回答を得て計画を確定させる論点。推奨案と根拠を添え、番号を振る。書き方は下記「確認事項の書き方」に従う)と、手順2b の結果(「申し送りの確認の結果」)の記録 3. 目的と完了要件(R1..Rn。**検証可能な形**で書く)/ スコープ外(やらないこと) 4. 確定済みの前提(実装担当者が疑わなくてよい事実。出典付き) 5. 成果物一覧(ファイルツリー差分) 6. 技術設計(節分け。テスト戦略と実装の進め方の方針を含む。**どの実装スタイルを採るかはグローバル指示書(`CLAUDE.md` / `AGENTS.md`)に従い、本スキルが特定の手法を強制しない**) 7. リスクと対処の決定木(C1..Cn。実装担当者が上から順に試せる形) 8. タスク分割(T1..Tn+任意タスク。委譲先サブエージェントの役割案と依存関係) 9. 進行ルール(サイクル・コミット単位・コミットメッセージ言語) 10. 申し送りの候補(この版で生じる見込みの申し送りを3段階で。確定は実装完了時に行い、申し送り文書に ID を採番する) **確認事項の振り分け** — §0に積む前に、論点を2つに分ける。 | 振り分け先 | 該当する論点 | 扱い | |---|---|---| | **その場の対話で決める** | 選択肢が数個に絞れ、推奨案を示せ、回答が「どれを採るか」で済むもの | 計画書を書く前に尋ね、**確定として§0に記録する** | | **文書に残して確認する** | 回答が自由記述になる、複数の論点が絡む、資料を見ながら考える必要がある、判断の根拠を後から参照するもの | §0に**未回答のまま**載せ、回答を待つ | - その場で決めるときは、**選択肢を示して回答を得られる対話手段があればそれを使う**。無ければ通常の対話で簡潔に尋ねる。**手段はエージェントによって異なるので、特定の機能があることを前提にしない**。 - **まとめて一度に尋ねる。** 論点を小分けにして往復を増やすと、負担を減らすという目的から外れる。 - **その場で決めた事項も必ず§0に記録する。**「いつ・どちらの手段で決めたか」を残す。記録がないと、後続の実装フェーズが何を確定済みとして扱えるか分からなくなる。 - **§0に未回答で残すのは、文書での検討が本当に要るものだけにする。** ユーザーが文書を読んで回答を書き込む作業は、この工程で最も時間のかかる部分である。数択で決まる論点をここに積むと、計画の確定が不必要に遅れる。 **確認事項の書き方** — §0に載せる論点も、その場の対話で尋ねる質問文も、手順6の報告も、次に従う。 - **主は意味論的な説明にする。** 何を決めるのか、各選択肢を採ると何がどう変わるか、推奨案とその理由を、**計画書もコードも精読していない読み手が判断できる日本語**で書く。進行文書で議論しているのと同じ抽象度にする。 - **コード上の表現は補足に留める。** 変数名・関数名・ファイルパス・フラグ・設定キーは括弧書きや末尾に添える。コード表現だけで意味が決まる書き方はしない。例えば「〈設定キー〉を有効にするか」ではなく、「〈振る舞い〉を既定にするか(設定キーは〈名前〉)」と書く。 - **理由**: 確認事項への回答はこの工程で最も時間のかかる部分であり、**コードを読まないと答えられない問いは、それ自体がボトルネックになる。** 計画書の品質要件: - 完了要件には**検証コマンドを明記**する。lint+テストの検証一括スクリプト(例: `tools/check.sh`)がプロジェクトにあればそれを指定し、**無ければ「検証一括スクリプトの作成」を本版のタスクに含める**ことを提案する(決定論的チェックはスクリプト化してエージェント間で共有するのが方針)。 - リスク決定木(C1..Cn)は**実装中に起こりうる分岐を可能な限り網羅**する。後続のversion-implementは「決定木にある問題は自走、ない問題は中断してユーザー確認」で動くため、決定木の網羅性がそのまま実装の自律性を決める。 - 下位モデルへの委譲を想定し、タスクは「対象パス・確定済み設計・完了要件・確認コマンド」を明記できる粒度で切る。ただしコードそのものは書かない。 ### 6. 進行文書への記載と提示 - **再開のときは「中断からの再開」に従う**(当該版の記載を二重に足さない)。 - 進行文書の**当該版の記載を1か所に足す**(「申し送りの扱い」の「進行文書の記載」に従う。状態=設計〈ドラフト〉、日付、**§0の未回答項目数**、要点を短く。後続フェーズが同じ記載を更新する前提で、設計時点の目安は80字。**エージェント記載であることと日付を明示**し、ユーザー記載部分は削除しない)。 - ユーザーへの報告では、計画の骨子と**§0に未回答で残った項目**を「確認事項の書き方」に従って読みやすく提示し、申し送りの確認の結果(Critical の有無)を1行添えて、回答を求めて**停止**する。**対話で確定済みの項目まで読ませない**(記録は計画書にある)。未回答がゼロならその旨を伝え、計画のレビューを求める。「実装はレビューと§0確定後、ユーザーの開始指示を待って着手する」と明記する。 ## 中断からの再開 手順1で「設計中」と判定し、再開を選ばれたときの扱い。**既存の成果物を消さない・黙って上書きしない。読んで足す。** - **読解(手順1〜3)は省略しない。** 中断でコンテキストは失われている。ただし計画書ドラフトの「本版で新規に行った調査」に残っている調査結果は再利用してよく、再調査は差分に留める。 - **手順4**: 作業ブランチがあれば作らずに切り替える。リモートにあってローカルに無ければ取得する。無ければ作る。 - **手順5**: 計画書のドラフトがあれば**全文を読んでから**書く。①§0 に確定として記録済みの決定(手順2b の結果を含む)は尋ね直さない ②直近版の計画書の節構成と照合して欠けている節を足す ③既に書かれた節は読み直し、矛盾があれば直すが消さない ④前付けの状態欄に中断と再開の日付を記す。 - **手順6**: 進行文書に当該版の記載が既にあればそれを更新し、二重に足さない。再開の旨は進行文書ではなく計画書の前付けに残す(手順5の④)。