AI作業のバージョン管理
AIと反復作業を行うと、良いバージョンが失われることがあります。再生成で上書きされたり、元に戻しすぎたり、会話の流れで見失ったりします。このスキルは、すべての変更に番号付きバージョンを作成し、ユーザーが削除するまで保持するため、任意の以前の状態を表示、比較、復元できます。
3つのルール
- すべての変更にバージョンが付く。 1つのユーザーリクエストでファイルが変更された場合、そのターンの終了時、返信の前に1バージョンとして保存されます。ファイル編集ごとではなく、リクエストごとに保存することで、履歴を読みやすく保ちます。
- 巻き戻してもバージョンは削除されない。
.ai-versions/への書き込みはスクリプトのみが行います。そこにあるものを編集、移動、削除しないでください（たとえクリーンアップを依頼されても）。代わりにbackupをユーザーに案内してください。 - 巻き戻しは新しいバージョンになる。 スクリプトを使って復元します。過去の作業を記憶から再構築しないでください。復元は新しいバージョンとして保存されるため、それも元に戻せます。
スクリプトがすべてのバージョン番号を決定します。推測しないでください。スクリプトが出力する番号を報告してください。
プロジェクトごとにモードを選択
- コマンドの実行とファイルの編集が可能（Claude Code、Cursor、Codex、Windsurf、Copilot、Gemini CLI、Replit Agent、コード実行機能付きのclaude.ai）：以下のファイルモードを使用します。
- プロジェクトに
.github/workflows/ai-versions.ymlがある：GitHubバージョンレイヤーを使用します。initを実行しないでください。代わりに、変更のたびに.ai-versions/pending.jsonを上書きし、巻き戻すときは.ai-versions/restore.jsonを書き込みます。詳細は assets/rules/github-layer-rules.md に記載されています。 - コマンドを実行できない（プレーンチャット）：references/chat-mode.md に従ってください。
- ユーザーがLovable、Bolt、v0（Boltとv0はベータ版：まだライブテスト未実施）、またはFigma Makeで構築しており、そこでバージョン管理する方法を尋ねている場合：references/app-builders.md を読んでください。
ファイルモード
スクリプトは、このスキルフォルダ（このSKILL.mdがあるフォルダ）内の scripts/aiv.py です。フルパスで呼び出し、--root でプロジェクトを指定します。
python3 "<このスキルのフォルダ>/scripts/aiv.py" --root "<プロジェクトフォルダ>" <コマンド>
# Windows：python3 の代わりに py
init 後、各プロジェクトにも独自のコピーが作成されるため、プロジェクトフォルダから python3 .ai-versions/aiv.py <コマンド> でも同じように動作します。以下では、aiv はどちらの形式も意味します。Pythonがインストールされていない場合は、その必要があることをユーザーに伝え（python.org）、インストールされるまではチャットモードを使用してください。
開始
.ai-versions/ がないプロジェクトで最初の編集を行う前に、init を実行してください。現在のファイルをv1.0.0として保存し、ユーザーがいつでも編集前の状態に戻せるようにします。
フォルダにプロジェクト以外のものが含まれている場合（サンドボックス、ホームフォルダ、ダウンロードフォルダなど）、スコープを指定します：init --only poster.html assets/。init はファイル数が5,000を超えるフォルダを拒否します。これは通常、間違ったフォルダを指定していることを意味するからです。
変更後毎回
aiv save --bump minor --summary "価格セクションを3プランで追加" \
--reason "新しいセクション。レイアウトとスタイルは変更なし" --prompt "3プランの価格を追加"
--bump | ユーザーに表示 | タイミング |
|---|---|---|
patch | 小調整 | 同じ機能、小さな調整：テキスト、色、間隔、サイズ、小さな修正 |
minor | 新機能 | 何か新しいもの、同じ方向性：セクション、ページ、コンポーネント、機能 |
major | 大きな変更 | 方向性が変わった：再設計、新しいレイアウト、新しいスタイルシステム、機能の削除 |
1つのリクエストに複数の変更がある場合は、最も高いレベルを採用します。2つのレベルの間で迷った場合は、低い方を採用し、--reason でその旨を伝えてください。エッジケース（ドキュメント、リファクタリング、コンテンツ更新）については references/bump-levels.md を参照してください。
--summary はユーザー向けに書いてください（開発者向けではありません）。「Hero.tsxを更新」ではなく「ヒーロー画像を大きくしました」。--prompt にはユーザーのリクエストを1行に短縮して入れます。
その後、返信を次のような1行で終了します：Saved v1.3.0 (新機能)：価格セクションを3プランで追加しました。
save がファイルが以前のバージョンと完全に一致すると報告した場合、その保存はそのバージョンへの復帰として記録されます。その旨をユーザーに伝えてください。
ユーザーが尋ねたとき
| ユーザーの発言 | 実行 | その後 |
|---|---|---|
| 「バージョンを見せて」「履歴」 | list | 簡易テーブルを表示。視覚的なタイムラインが必要な場合は view を実行し、書き出されたHTMLファイルを共有。 |
| 「v1.3.0で何が変わった？」 | diff v1.3.0^ v1.3.0 | 平易な言葉で説明。vX^ は vX の1つ前のバージョンを意味。 |
| 「v1.2とv2.0を比較して」 | diff v1.2.0 v2.0.0 --stat、詳細が必要なら --stat なし | 何が変わったか、何が良くなったか、何が悪くなったかを説明。作業をレンダリングできる場合（HTML、画像）、両方を並べて表示。 |
| 「v1.2.0に戻して」「元に戻して」 | restore v1.2.0、または元に戻す場合は restore prev | その後、下の手順を実行。 |
| 「古いヘッダーだけ戻して」「古いデザインだけど新しいテキストは残して」 | restore v1.2.0 --path <ファイル> | 該当ファイルのみ変更。小調整として保存。 |
| 「v1.2.0から別の方向を試してみたい」 | restore v1.2.0 | その後、新しい変更を加え、通常通り保存。 |
| 「今のバージョンは？」「未保存の変更は？」 | status | |
| 「v1.2.0をファイルとして出力して」 | export v1.2.0 --out v1.2.0.zip | |
| 「これを別のチャットやツールで続けたい」 | backup --out history.zip | 新しい場所で：import history.zip。 |
ユーザーがバージョンを曖昧に指定した場合（「青いやつ」「再設計の前」）、list を実行してサマリーと照合します。2つのバージョンが当てはまる場合は、どちらか質問してください。
巻き戻した後
完全な復元は、ノートやデータなど、ユーザーが作業の一部と考えていない可能性があるファイルを含む、すべてのプロジェクトファイルを元の状態に戻します。どのファイルが変更されたかをユーザーに伝えてください（スクリプトが一覧表示します）。最初に未保存の作業を保存した場合は、どのバージョンに含まれているかを伝え、restore <そのバージョン> --path <ファイル> で特定のファイルを戻せることを提案してください。リクエストがプロジェクトの一部のみを明確にターゲットにしている場合（「古い色」）、最初から --path を使用してください。
handoff <復元したバージョン> を実行し、次の変更を行う前にその出力を現在の真実として扱います。そのバージョンに至った決定のみをリストし、破棄された決定は名前を挙げないため、放棄された方向からの指示が戻ってくることはありません。会話が長い場合は、新しいチャットで続けることを提案し、ユーザーにハンドオフテキストを貼り付けるよう伝えてください。
保存し忘れのセーフティネット
Claude CodeまたはCursorでは、プロジェクトごとに1回これを提案します：install-hooks claude-code または install-hooks cursor。これにより、保存し忘れた変更を終了時に小調整として保存するフックが追加されます。ツールの設定に書き込むため、ユーザーが同意した後にのみインストールしてください。
バージョンに関する話し方
ユーザーの言葉を使います：小調整、新機能、大きな変更、巻き戻し。バージョン番号は述べますが、コミット、.ai-versions/ 内のファイル、ハッシュは言及しないでください。ツール固有の注意事項（claude.ai、Replit、Windows）は references/tools.md にあります。
ユーザーが巻き戻した場合、ファイルのみが戻ることを1回だけリマインドしてください。データベースの行やその他のライブデータはそのままです。
全コマンド
| コマンド | 機能 |
|---|---|
init [--only PATH...] | 履歴を開始し、v1.0.0を保存 |
save --bump B --summary S [--reason R] [--prompt P] | 現在のファイルを新しいバージョンとして保存 |
status | 現在のバージョンと未保存の変更 |
list [--all] [--json] | バージョンを新しい順に表示 |
show V | 1つのバージョンの詳細と変更されたファイル |
diff [A] [B] [--stat] [--path P...] | 引数なし：未保存の変更。1つ：Aから最新。2つ：AからB |
restore V [--path P...] [--note N] | 巻き戻し（全ファイル、または一部のみ）。最初に未保存作業を保存し、復元を新しいバージョンとして保存 |
handoff [V] | Vから続けるためのクリーンなコンテキスト |
view [--out FILE] | 全バージョンのHTMLタイムライン |
export V --out DIR_or_ZIP | 1つのバージョンのファイルを出力 |
backup --out FILE.zip / import FILE.zip | 履歴全体を移動 |
install-hooks claude-code|cursor | AIが忘れた内容を自動保存 |
setup-github [--with-pill] | アプリビルダーリポジトリにGitHubレイヤーを追加 |
doctor | 履歴に欠落がないか確認 |
バージョンは v1.2.0、1.2.0、latest、prev、v1.2.0^ と記述できます。