version-implement

# version-implement: 計画確定から実装完了までの自律進行手順 > **skill version**: 1.3.0 セッション内で初めて本スキルを使用するときは「version-implement スキル v1.3.0 を使用します」と宣言する。 version-startで作成した実装計画を確定し、完了要件を満たすまで**できる限りユーザーに戻らず**実装を進めるためのゲート式手順書。ただし自律の範囲は計画書に書かれた決定木の内側に限る。**§0が未回答なら実装に入らない。決定木にない未決事項が現れたら即中断してユーザーに方針を確認する** — この2つは他のすべてに優先する。 ## 前提と一般化ルール - 対象プロジェクトの言語・技術スタック・文書規約はハードコードしない。実装計画書(命名はプロジェクトの慣行による。例: `vX.Y実装計画.md`)と既存文書・既存コードから読み取る。 - 実装計画・実装記録の置き場の名前やフォーマットはプロジェクト毎に異なる。進行文書(プロジェクトのコンセプトと各版の計画概要を記載した文書。名称・形式はプロジェクトによって異なる)内の参照と、直近版の同種文書を踏襲する。 - 委譲の運用はグローバル指示書(`CLAUDE.md` / `AGENTS.md`)のモデル・サブエージェント運用方針に従う(エージェントの同時実行制約を含む): 実装の委譲先は実装計画書の指定に従い、委譲プロンプトは自己完結させ、サブエージェントの成果は必ずメインセッションがdiffレビューしてから次へ進む。 - ユーザーに選択肢を提示するときは、何を決めるのか・各選択肢を採るとどうなるか・推奨案とその理由を、計画書もコードも精読していない読み手が判断できる日本語で書き、ファイル名・ブランチ名・コマンドは補足に留める(理由: コードを読まないと答えられない問いは、それ自体が進行のボトルネックになる)。 ## 版の状態の見分け方 > この節は 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字。詳細は計画書と実装記録に書く。ユーザー記載は消さない。旧形式(版ごとに設計／実装完了／リリースのエントリを足す形)が既にある進行文書では、既存の版は旧形式のまま読み、新しい版から集約する。旧形式のエントリしか無い版(移行期)は、そのエントリを当該版の記載として更新するか、新しい形へ写してから更新する。 ## ゲート ### G0: 入場ゲート — 状態照合・回答照合・再開判定 **G0-1 版の状態照合。** 「版の状態の見分け方」の表を引いて証拠を集め、要約を表示する。本スキルが期待する状態は**設計済み**(再開なら実装中)。判定は次の表を上から順に当てる。 | 判定 | 扱い | 選択肢 | |---|---|---| | 未着手・設計中(前工程が未了) | **準備未了と判定し、実装に入らず停止する。** 何が欠けているか(計画書・作業ブランチ・進行文書の当該版の記載)を列挙し、`/version-start X.Y` の実行または再開(あるいは欠けているものの手動準備)をユーザーに促す。**計画書やブランチをこのスキルが代わりに作成することは禁止する**(それはversion-startの領分)。リモートにだけブランチがあるときは、別マシンで進行中の可能性を1句添える | 出さない | | 実装完了・リリース中・リリース済み(後工程に進んでいる) | 停止し、次に使う手順を案内する(実装完了ならversion-release、リリース済みなら次版のversion-start) | 出さない | | 飛び越し(下位に着手済みで未リリースの版がある) | 情報を提示して尋ねる | (a) **停止して確認**(推奨。実装順が入れ替わると、後から実装する下位の版の扱いが問題になる) (b) 指定版で続行(理由を実装記録に記す) (c) 下位の版に切り替える(その版が設計済み以上のとき) | | 実装中(自スキルの途中) | G0-3の再開判定へ | — | | 一致(設計済み) | 進む。**確認は取らない** | — | 不在は準備未了に含まれる(計画書が無いので準備未了として停止する。要約には不在の旨を書く)。要約にリポジトリ名と直近リリース版が出るので、別プロジェクトの版番号を打った場合も目に入る。 **G0-2 §0の回答照合。** 実装計画書を読み、**§0ユーザー確認事項の全項目について回答の有無を照合**する。回答は (a)計画書に記入済み、(b)スキル呼び出しプロンプト内、のどちらでもよい。**1項目でも未回答または曖昧なものがあれば実装に入らず**、未回答項目を列挙して回答を求めて停止する。推測やデフォルト採用で埋めることを禁止する。 **G0-3 再開判定**(状態が実装中のとき)。実装記録が示す進捗と、gitに残った事実を突き合わせ、正しい位置から再開する。 - (1) 実装記録の進捗管理の表から各タスクの状態を読む。**前回の中断論点が未解決のまま残っている場合は停止して回答を求める。** - (2) 作業ブランチのコミット一覧(既定ブランチとの分岐点以降)を読み、各コミットをタスクに対応づける(件名・変更パス・実装記録のコミット欄)。 - (3) 作業ツリーの未コミット変更を読み、変更パスを計画書の各タスクの対象パスに対応づける。 - (4) 次の表で突き合わせる。 | 実装記録 | コミット | 判定 | |---|---|---| | 完了 | ある | 完了。飛ばす | | 完了 | 無い | 記録が先行している(コミットの直前で止まった)。**未完了として扱い**、対応する未コミット変更があればそのタスクの途中と見る | | 未着手・途中 | ある | コミットが先行している(記録の更新の前で止まった)。記録を完了に更新して飛ばす。検証が通っていたかは(6)で確かめる | | 未着手・途中 | 無い | 未完了。再開位置の候補 | - (5) **未コミット変更は決して消さない。** どのタスクの途中かを示し、選択肢を提示する: (a) **その変更を引き継いで当該タスクから再開**(推奨) (b) 復元できる形で退避(gitのstash相当)して当該タスクを最初からやり直す (c) 停止。どのタスクにも対応づけられない変更は本版と無関係の可能性があるので、G0-4の規則(停止して確認)に回す。 - (6) **再開前の検証。** 計画書指定の検証一括スクリプトを実行する。未コミット変更が無いのに落ちるなら、前回のサイクルが検証の前で止まった可能性があるので停止して報告する。未コミット変更があって落ちるのはタスクの途中なので想定内。記録に書いて続行する。 - (7) **再開位置**は依存順で最初の未完了タスク。再開の表(タスク/記録の状態/コミット/判定)を出力し、実装記録に「再開」の行(日付・再開位置・未コミット変更の扱い)を足してからG2へ。 - (8) 計画書が「ドラフト」のまま実装記録がある(G1の途中で止まった)場合は、G1を先に完了させる(G1は冪等)。 **G0-4 ブランチと作業ツリー。** 作業ブランチ(version-startが作成したもの)に切り替わっていること、作業ツリーに本版と無関係な未コミット変更がないことを確認する(G0-3の(5)で本版のタスクに対応づけられた変更は無関係ではない)。問題があれば停止して確認する。 ### G1: 計画フィックス - プロンプトで受けた回答を§0へ転記し、回答内容を計画本文の該当節(技術設計・タスク分割等)へ反映する。本文が回答と矛盾する箇所は回答に合わせて修正する。 - 前付けの状態を「ドラフト、ユーザーレビュー待ち」→「確定(日付)」へ更新する。 - 実装記録ファイルを作成(既存なら追記)し、進捗管理節を設ける(タスク毎の状態: 未着手/完了/中断、採った決定木分岐の記録欄)。 ### G2: 実装ループ — 自走と中断の判定規則 タスクT1..Tnを依存順に消化する。各タスクのサイクル: 1. 実装する。**実装の進め方(テスト駆動開発を採るかどうか、その進め方を含む)はグローバル指示書(`CLAUDE.md` / `AGENTS.md`)の方針に従う。本スキルは特定の実装スタイルを強制しない**。委譲先は計画書の指定に従い、委譲プロンプトは自己完結させる(対象パス・確定済み設計・完了要件・確認コマンド)。独立したタスクは並列に委譲してよい(エージェントの同時実行制約の範囲内で)。 2. 成果をメインがdiffレビューする(計画との整合・解釈の誤り・潜在バグ)。 3. 検証一括スクリプト(計画書指定のもの)を実行し全pass。失敗は解析(必要なら解析専任サブエージェントへ委譲)→修正→再実行。**テスト側を弱めて通すことは禁止**。 4. サイクル単位でコミットし、実装記録の進捗管理節を更新する。 **継続/中断の判定**: 実装中に問題・分岐が生じたら、まず計画書のリスク決定木C1..Cnに該当するかを確認する。 - **該当する** → 決定木の指示に従って自律継続する。採った分岐を実装記録に記録する。 - **該当しない**(計画にない設計判断、スコープ・完了要件の変更、外部仕様との矛盾、§0で扱わなかった新論点) → **即中断**。進行中サイクルはコミットせず(完了済みサイクルのコミットは保持)、実装記録に進行状態と論点を書き残した上で、論点を推奨案付きで整理してユーザーに提示して停止する。**独断で決めて進むことを禁止する**。回答後は本スキルの再実行でG0の再開判定から続きに入る。 軽微な実装判断(命名、テストケースの追加など計画の意図が明確なもの)は中断対象ではない。迷ったら「決定木に書いてあるか」で機械的に判定する。 ### G3: 完了ゲート 1. **完了要件R1..Rnを計画書記載の検証コマンドで全数照合**し、「要件 → 検証コマンド → 実測結果」の表で表示する。未達があればG2へ戻る(原因が決定木にないものなら中断規則に従う)。 2. 実装記録を完成させる(実施内容・判断記録・次版への申し送り)。直近版のフォーマットを踏襲する。**申し送りは「申し送りの扱い」の節に従って3段階に分類**し、実装記録の申し送り節と申し送り文書の両方に書く(文書側は新規に ID を採番し、既存項目は状態列を更新する。文書が無ければ作る)。環境の事実・教訓は実装記録だけに書く。 3. 進行文書の当該版の記載を更新する(「申し送りの扱い」の「進行文書の記載」に従う。状態=実装完了、日付、要点。設計時の記載があればそれを更新し、無ければ足す。**エージェント記載であることと日付を明示**。ユーザー記載部分は削除しない)。 4. リモートがあればブランチの全コミットをpushする。pushが権限・認証エラーで落ちた場合は、**ホスティングサービスのCLIのアクティブなアカウントがリモートの所有者と異なる**可能性を疑う(CLIが複数アカウントを保持できる構成がある)。確認し、異なっていればユーザーの承認を得て一時的に切り替え、**作業後に必ず元へ戻す**。承認を求める際も手順は停止せず、その場で方針を聞いて継続する。 ## 完了報告 要件照合表、タスク消化状況、コミット一覧、決定木で処理した分岐、申し送り事項(3段階ごとに ID 付きで)を整理して報告し、**リリース作業(/version-release)はユーザーの指示を待つ**と明記して停止する。