Claude CodeとAntigravity：スコープドリフトを防ぐタスク委任契約

ターミナル型エージェントの Claude Code とエージェント開発環境 Antigravity を連携させる際、最も頻繁に発生する課題はコード生成の精度ではなく、コンテキストや作業範囲のドリフト（Scope Drift）です。「モジュールを最適化してテストを更新して」といった曖昧な指示を出すと、無関係な設定ファイルが書き換えられたり、想定外のトークン消費が発生したりします。

AIエージェント間の確実な委任には、編集可能なファイル一覧の明示、シークレットの分離、再現可能な検証コマンド、そしてGit diffによる手動受け入れを定めた明確なハンドオフ契約（Handoff Contract）が必要です。

制約のないタスク委任がドリフトを生む理由

エージェントは与えられたワークスペース全体に対して忠実に動作します。境界を設定しない場合、以下の3つの典型的な問題が発生します。

1. 作業範囲の肥大化: 関連のないユーティリティ関数を勝手にリファクタリングしたり、全体のフォーマットを変更したりします。
2. シークレットの流出: .env などの設定ファイルを読み込み、テストログや生成コードにAPIキーを出力してしまいます。
3. 設計方針の衝突: Claude CodeとAntigravityが異なる前提でインポートパスを書き換えることがあります。

環境変数やAPIキーはタスクのコンテキストから完全に分離して管理する必要があります。BetterToken経由でClaude Codeを利用する場合、認証はターミナルレベルの環境変数で設定され、プロンプト内に秘密情報を含める必要はありません。BetterTokenダッシュボードでリクエストごとのトークン消費量をリアルタイムに把握できます。

ハンドオフ契約（Handoff Contract）の設計

自然言語による曖昧な指示の代わりに、明確なマニフェストを作成します。

契約項目	役割	設定例
Goal	単一の測定可能な目標	parser.py 内のJSONパース処理を最適化
Allowed Scope	変更を許可するファイル一覧	src/parser.py, tests/test_parser.py
Forbidden	明示的な禁止事項	config/, .env* の変更禁止、公開APIシグネチャの維持
Verification Command	自動検証コマンド	pytest tests/test_parser.py -v
Stop Conditions	即時中断の条件	スコープ外のテスト失敗、型エラーの発生

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. 自動検証コマンドを実行する

エージェントによるコード変更後、契約で指定されたテストコマンドを実行します。

pytest tests/test_parser.py -v

ステップ 4. Git Diffによる手動受け入れ

最終的なマージ判断は必ず開発者が行います。

git diff src/parser.py
git status --short

シナリオ別のおすすめ設定

• 個別関数のリファクタリング: 小さなハンドオフ仕様書とローカルテストを活用します。
• 外部APIの連携: BetterToken公式ドキュメントを確認し、環境変数経由でエンドポイントを設定します。

トラブルシューティング

1. スコープ外のファイルが変更された場合: Allowed Scope のホワイトリストを厳格化します。
2. テスト修正の無限ループ: エージェントの自動リトライ回数に上限を設定します。
3. 認証エラーやタイムアウト: BetterTokenドキュメントでBase URLとアカウント残高を確認してください。