Claude CodeとAntigravity：スコープドリフトを防ぐタスク委任契約
Claude CodeとAntigravity間の実践的なハンドオフ契約：ファイル分離、シークレット保護、再現可能なテスト、手動diffレビュー。
ターミナル型エージェントの Claude Code とエージェント開発環境 Antigravity を連携させる際、最も頻繁に発生する課題はコード生成の精度ではなく、コンテキストや作業範囲のドリフト（Scope Drift）です。「モジュールを最適化してテストを更新して」といった曖昧な指示を出すと、無関係な設定ファイルが書き換えられたり、想定外のトークン消費が発生したりします。
AIエージェント間の確実な委任には、編集可能なファイル一覧の明示、シークレットの分離、再現可能な検証コマンド、そしてGit diffによる手動受け入れを定めた明確なハンドオフ契約（Handoff Contract）が必要です。
制約のないタスク委任がドリフトを生む理由
エージェントは与えられたワークスペース全体に対して忠実に動作します。境界を設定しない場合、以下の3つの典型的な問題が発生します。
- 作業範囲の肥大化: 関連のないユーティリティ関数を勝手にリファクタリングしたり、全体のフォーマットを変更したりします。
- シークレットの流出:
.envなどの設定ファイルを読み込み、テストログや生成コードにAPIキーを出力してしまいます。 - 設計方針の衝突: Claude CodeとAntigravityが異なる前提でインポートパスを書き換えることがあります。
環境変数やAPIキーはタスクのコンテキストから完全に分離して管理する必要があります。BetterToken経由でClaude Codeを利用する場合、認証はターミナルレベルの環境変数で設定され、プロンプト内に秘密情報を含める必要はありません。BetterTokenダッシュボードでリクエストごとのトークン消費量をリアルタイムに把握できます。
ハンドオフ契約（Handoff Contract）の設計
自然言語による曖昧な指示の代わりに、明確なマニフェストを作成します。
4つのステップによる安全な委任プロセス
以下の手順でタスク委任を実行します。
ステップ 1. 独立したファイルに契約を定義する
シークレットを含まない専用の仕様ファイル（task_handoff.md など）を作成します。
Handoff Spec: Optimize Parser
Context & Goal
- Module:
src/parser.py - Objective: Reduce memory allocations in
parse_payload()without altering public API.
File Boundaries
- Modifiable:
src/parser.py,tests/test_parser.py - Read-only: all other files.
- Strictly forbidden:
.env*,secrets/*,infrastructure/*
Acceptance Criteria
- All tests pass:
pytest tests/test_parser.py - Benchmark demonstrates >= 20% latency reduction.
- No new dependencies in
requirements.txt.
ステップ 2. ワークスペースと権限を分離する
.env が .gitignore に含まれていることを確認し、プロンプトに認証情報を記載しないでください。
ステップ 3. 自動検証コマンドを実行する
エージェントによるコード変更後、契約で指定されたテストコマンドを実行します。
ステップ 4. Git Diffによる手動受け入れ
最終的なマージ判断は必ず開発者が行います。
シナリオ別のおすすめ設定
- 個別関数のリファクタリング: 小さなハンドオフ仕様書とローカルテストを活用します。
- 外部APIの連携: BetterToken公式ドキュメントを確認し、環境変数経由でエンドポイントを設定します。
トラブルシューティング
- スコープ外のファイルが変更された場合:
Allowed Scopeのホワイトリストを厳格化します。 - テスト修正の無限ループ: エージェントの自動リトライ回数に上限を設定します。
- 認証エラーやタイムアウト: BetterTokenドキュメントでBase URLとアカウント残高を確認してください。