取り組みの背景 — なぜ AI 開発にチェックポイントが不可欠なのか
AI エージェントがコードを書く時代、開発者が直面する新しい課題があります。それは「AI が生成した変更をどう管理し、必要に応じて安全に元に戻すか」という問題です。
従来の Git によるバージョン管理は人間の手動コミットを前提としていましたが、AI エージェントは数秒で数十ファイルを変更することがあります。コミットの粒度が粗すぎれば、問題のある変更だけを切り戻すことが困難になります。逆に細かすぎれば、履歴が膨大になり管理が煩雑になります。
Antigravity のチェックポイント機能は、この課題に対する洗練された解決策です。AI エージェントが行う変更を自動的に記録し、任意の時点に正確にロールバックできる仕組みを提供します。ここで扱うのはこの機能の内部アーキテクチャから実践的な運用パターンまでを体系的に解説します。
この記事を読み終えると、以下のことができるようになります。
- チェックポイントがどのタイミングで、どのように記録されるかを理解できる
- 複数のロールバック手法を使い分けて、最小限の影響で変更を巻き戻せる
- Git ブランチ戦略とチェックポイントを統合した本番運用フローを構築できる
対象読者は、Antigravity を日常的に使用しているソフトウェアエンジニアで、AI エージェントとの協働における変更管理をより堅牢にしたい方です。
チェックポイントの内部メカニズム
自動チェックポイントの動作原理
Antigravity のチェックポイントは、エージェントのターンが完了するたびに自動的に作成されます。具体的には、以下のタイミングで記録が行われます。
- エージェントがファイルの作成・編集・削除を完了したとき
- エージェントのターンが切り替わるとき（ユーザーへの応答を返すタイミング）
- 長時間実行タスクの中間地点（設定可能なインターバル）
チェックポイントの実体は、ファイルシステムのスナップショットです。Git のコミットとは異なり、ステージング不要で自動的に全変更がキャプチャされます。
// チェックポイントの概念的なデータ構造
interface Checkpoint {
id: string; // 一意の識別子
timestamp: number; // 作成時刻（Unix timestamp）
agentTurn: number; // エージェントのターン番号
description: string; // AI が生成した変更の説明
filesModified: string[]; // 変更されたファイルパス一覧
filesCreated: string[]; // 新規作成されたファイルパス一覧
filesDeleted: string[]; // 削除されたファイルパス一覧
parentCheckpointId: string; // 直前のチェックポイントID
}
// チェックポイント一覧の取得（概念的なAPI）
// Antigravity の UI では Timeline パネルで視覚的に確認可能
チェックポイントと Git コミットの違い
チェックポイントと Git コミットは似て非なるものです。両者の違いを正確に理解することが、効果的な運用の第一歩です。
チェックポイントは Antigravity 内部の一時的なスナップショットであり、セッション間で保持されますが、リモートリポジトリにはプッシュされません。作業の「実験」段階を記録するものと考えてください。
Git コミットは永続的な変更履歴であり、チームで共有するための正式な記録です。チェックポイントで十分に検証した変更を、意味のある単位で Git コミットに昇格させるのが理想的なワークフローです。
# チェックポイントの一覧を確認（Antigravity のタイムラインUIで可視化）
# 各チェックポイントにはエージェントの変更説明が自動付与される
# 良いワークフロー: チェックポイントで検証 → Git コミットへ昇格
# 1. エージェントに機能実装を依頼（自動的にチェックポイントが作成される）
# 2. チェックポイント間の差分を確認
# 3. 問題なければ git commit で正式に記録
git add -A
git commit -m "feat: ユーザー認証フローの実装"
ロールバック操作の完全ガイド
基本的なロールバック — タイムラインからの復元
最もシンプルなロールバックは、Antigravity のタイムラインパネルから特定のチェックポイントを選択して復元する方法です。
操作手順は以下の通りです。
- 画面右側のタイムラインパネルを開く
- 復元したい時点のチェックポイントをクリック
- 変更差分を確認し、「Restore」をクリック
- 確認ダイアログで「Yes, restore」を選択
この操作により、選択したチェックポイント以降の全変更が取り消されます。取り消された変更も完全に消えるわけではなく、「取り消し前」のチェックポイントとして記録されるため、ロールバック自体を取り消すことも可能です。
部分ロールバック — 特定ファイルのみ復元
全体ではなく特定のファイルだけを以前の状態に戻したい場合は、部分ロールバックを使用します。これはAI エージェントが複数ファイルを変更したが、一部のファイルの変更だけが問題だった場合に特に有用です。
# エージェントのターミナルでの操作例
# 特定のチェックポイント時点のファイルを確認し、
# 必要なファイルだけを手動で復元する方法
# 1. 差分を確認
# タイムラインで該当チェックポイントの差分表示を開く
# 2. 問題のあるファイルだけを Git で復元
git checkout HEAD~1 -- src/components/Auth/LoginForm.tsx
git checkout HEAD~1 -- src/hooks/useAuth.ts
# 3. 復元した状態をコミット
git add src/components/Auth/LoginForm.tsx src/hooks/useAuth.ts
git commit -m "revert: LoginForm と useAuth を前回の状態に復元"
インタラクティブなロールバック — エージェントとの対話
Antigravity の最も強力なロールバック手法は、エージェントに対して自然言語で復元を指示する方法です。
// エージェントへの指示例
「直前の認証フロー変更で LoginForm のバリデーションが壊れました。
バリデーションロジックだけを2つ前のチェックポイントの状態に戻して、
他の変更は維持してください。」
この指示により、エージェントはチェックポイントの差分を分析し、バリデーションロジックに関連する変更だけを正確に巻き戻します。単純なファイル復元ではなく、コードの意味を理解した上での部分ロールバックが可能になります。
高度なチェックポイント戦略
戦略的チェックポイント — 重要な作業前の手動保存
自動チェックポイントに加えて、重要な変更の前に意図的にチェックポイントを設定する習慣をつけることを推奨します。
// エージェントへの指示例（重要な変更前）
「これからデータベーススキーマの大規模変更を行います。
現在の状態をチェックポイントとして保存してから作業を開始してください。」
特にリスクが高い作業の前には、以下のような「安全ネット」パターンが有効です。
# 安全ネットパターン: 重要変更の前後で明確なマーカーを設置
# Step 1: 現状の Git 状態を確認
git status
git stash # 未コミットの変更があれば退避
# Step 2: 新しいブランチを作成（チェックポイント + Git 二重保護）
git checkout -b feature/db-schema-migration
# Step 3: エージェントに作業を指示
# 「データベーススキーマの変更を開始してください。
# 各テーブルの変更ごとにチェックポイントを確認させてください。」
# Step 4: 問題が発生した場合
git checkout main # ブランチごと破棄してやり直しが可能
チェックポイントのライフサイクル管理
チェックポイントは無限に蓄積されるわけではありません。ストレージ効率のため、以下のライフサイクルで管理されます。
- 直近のセッション: 全チェックポイントが保持される
- 過去のセッション: 各セッションの開始時点と終了時点のチェックポイントが保持される
- 古いセッション: 最終チェックポイントのみ保持される（または設定に応じて削除）
// AGENTS.md でのチェックポイント方針の設定例
// プロジェクト固有のチェックポイントポリシーを定義する
/*
## Checkpoint Policy
- データベース関連の変更: 各マイグレーションファイルごとにチェックポイントを確認
- UI コンポーネントの変更: コンポーネント単位で確認
- 設定ファイルの変更: 変更前に必ずチェックポイントの存在を確認
- テストの追加・修正: テストスイート実行後に確認
*/
Git ブランチ戦略との統合
Feature Branch + Checkpoint パターン
本番環境で最も推奨されるパターンは、Git の Feature Branch とチェックポイントを組み合わせた二層管理です。
# Feature Branch + Checkpoint ワークフロー
# 1. Feature Branch を作成
git checkout -b feature/user-dashboard
# 2. エージェントに機能実装を指示
# → 各ステップでチェックポイントが自動作成される
# 3. チェックポイントで段階的に検証
# → 問題があればチェックポイントでロールバック
# 4. 検証完了後、意味のある単位で Git コミット
git add src/pages/Dashboard/
git commit -m "feat: ダッシュボードの基本レイアウト実装"
git add src/components/Charts/
git commit -m "feat: ダッシュボード用チャートコンポーネント追加"
# 5. main ブランチにマージ
git checkout main
git merge --no-ff feature/user-dashboard
# 6. Feature Branch を削除（チェックポイント履歴はセッションに残る）
git branch -d feature/user-dashboard
Trunk-Based Development との統合
小規模チームやソロ開発者の場合、Trunk-Based Development（直接 main にコミット）とチェックポイントを組み合わせる方法も効果的です。
# Trunk-Based + Checkpoint ワークフロー
# 1. main ブランチで直接作業
git checkout main
# 2. エージェントに小さな単位で作業を指示
# 「LoginForm のメールバリデーションを追加してください。」
# → チェックポイントが自動作成される
# 3. 即座に検証し、問題なければコミット
npm run test
git add src/components/Auth/LoginForm.tsx
git add src/components/Auth/__tests__/LoginForm.test.tsx
git commit -m "feat: メールアドレスバリデーション追加"
git push origin main
# 4. 問題があればチェックポイントでロールバック
# → main ブランチ上でも安全にやり直しが可能
リリース前のチェックポイント活用
リリース前の最終確認では、チェックポイントが強力なセーフティネットになります。
# リリース前チェックリストとチェックポイント活用
# Step 1: リリースブランチを作成
git checkout -b release/v2.1.0
# Step 2: エージェントにリリース前の修正を依頼
# 「以下の Issue を修正してください: #142, #155, #163」
# → 各 Issue の修正ごとにチェックポイントが作成される
# Step 3: CI/CD パイプラインを実行
npm run lint
npm run test
npm run build
# Step 4: 問題が見つかった場合
# → 該当チェックポイントまでロールバック
# → 修正を再実施
# Step 5: 全テスト通過後にタグ付け
git tag -a v2.1.0 -m "Release v2.1.0"
git push origin v2.1.0
災害復旧パターン — 本番環境のリカバリ
パターン1: AI エージェントの暴走からの復旧
AI エージェントが意図しない大規模変更を行った場合のリカバリ手順です。
# 暴走リカバリ手順
# 1. エージェントを即座に停止
# → Cmd+Shift+Backspace（Mac）/ Ctrl+Shift+Backspace（Windows）
# 2. タイムラインで変更範囲を確認
# → 変更されたファイル数と影響範囲を把握
# 3. 暴走開始前のチェックポイントを特定
# → タイムラインで「ここまでは正しかった」地点を見つける
# 4. ロールバックを実行
# → タイムラインから該当チェックポイントを選択して Restore
# 5. Git の状態を確認
git status
git diff # 変更がクリーンに戻っていることを確認
# 6. 安全策として Git でもバックアップ
git stash # 現在の変更を退避（念のため）
パターン2: デプロイ後の問題発覚からの復旧
デプロイ後に問題が発覚した場合、チェックポイントとGit の組み合わせで迅速にリカバリできます。
# デプロイ後リカバリ
# 1. 本番環境の問題を確認
# ログ、モニタリング、ユーザー報告から問題を特定
# 2. Git で直前のリリースに戻す
git revert HEAD # 直前のコミットを取り消し
# または
git checkout v2.0.0 # 前回の安定版タグに切り替え
# 3. 緊急デプロイ
git push origin main # CI/CD が自動的にデプロイ
# 4. Antigravity でチェックポイントを確認し、問題の原因を特定
# → エージェントに依頼: 「v2.1.0 の変更でどこに問題があったか分析してください」
# 5. 修正版を作成
# → チェックポイントを活用して、問題部分だけを特定・修正
パターン3: チーム開発でのコンフリクト解消
複数の開発者が同時に作業した場合のマージコンフリクト解消にも、チェックポイントが役立ちます。
# コンフリクト解消ワークフロー
# 1. マージ時にコンフリクトが発生
git merge feature/payment-flow
# CONFLICT (content): Merge conflict in src/api/checkout.ts
# 2. エージェントにコンフリクト解消を依頼
# 「checkout.ts のマージコンフリクトを解消してください。
# payment-flow ブランチの決済ロジックを優先しつつ、
# main ブランチのバリデーション強化も維持してください。」
# 3. エージェントがチェックポイントを作成しながら解消
# → 各ファイルの解消ごとにチェックポイントが記録される
# 4. 解消結果を確認
git diff --check # コンフリクトマーカーが残っていないか確認
npm run test # テストが通ることを確認
# 5. マージコミット
git add .
git commit -m "merge: payment-flow をマージ（コンフリクト解消済み）"
AGENTS.md でのチェックポイント方針設定
プロジェクトの AGENTS.md にチェックポイント方針を記述しておくと、エージェントが自動的にその方針に従います。
# プロジェクトのAGENTS.md に追加する設定例
## Change Management Policy
### Checkpoint Guidelines
- データベースマイグレーション: 各マイグレーション実行後に
変更内容を説明するチェックポイントメモを残すこと
- API エンドポイント変更: 後方互換性を壊す変更の前に
現在の状態を明示的に確認すること
- 設定ファイル変更: 環境変数やCI設定の変更前に
既存の設定を文書化すること
### Rollback Criteria
- テストが1つでも失敗した場合: 直前のチェックポイントに戻す
- ビルドエラーが発生した場合: エラーの原因を分析してから判断
- パフォーマンスが20%以上劣化した場合: チェックポイントを比較して原因特定
この設定により、エージェントは自動的にこれらの基準に従ってチェックポイントを管理し、問題発生時には適切なロールバック判断を行います。
個人開発者の視点から（実体験メモ）
まとめ
Antigravity のチェックポイント機能は、AI 開発における変更管理の新しい標準を提供します。自動的に記録されるチェックポイントにより、AI エージェントの変更を安全に管理し、問題発生時には迅速にロールバックできます。
重要なポイントを振り返りましょう。
チェックポイントは Git コミットを補完するセーフティネットであり、エージェントのターンごとに自動作成されます。ロールバックには全体復元、部分復元、エージェント対話型の3種類があり、状況に応じて使い分ける点が肝心です。Git ブランチ戦略と組み合わせることで、Feature Branch パターンでも Trunk-Based パターンでも堅牢な変更管理が実現できます。
AI エージェントとの協働において「安心して任せられる」環境を構築するために、チェックポイントを積極的に活用してください。
本記事のテーマをさらに深く