Claude Code and Antigravity: How to Delegate Tasks Without Scope Drift

Why Unconstrained Delegation Leads to Scope Drift

AI agents follow instructions literally within their provided context window and file tree. Providing an unconstrained workspace to an agent introduces three major risks:

1. Scope Creep: The model unilaterally decides to "clean up" unrelated helper functions, reformat whitespace, or restructure project layouts.
2. Secret Leakage and Corruption: The agent reads local .env files or credentials and inadvertently leaks them into generated test logs or scripts.
3. Conflicting Architectural Assumptions: One agent assumes a specific abstraction layer while the other refactors import paths under conflicting conventions.

To maintain control, API credentials and environment setups should remain isolated from task context. When running Claude Code with BetterToken, authentication is managed cleanly via environment variables at the terminal level rather than passed through task prompt files. Developers can monitor real-time token consumption across both input and cached context directly in the BetterToken Dashboard, catching unintended retry loops before they inflate costs.

The Handoff Contract Framework

Instead of unstructured natural language descriptions, delegate tasks using a structured handoff contract that clearly defines boundaries:

Step-by-Step Task Delegation Workflow

Follow these four steps to execute clean task delegation between Claude Code and Antigravity:

Step 1. Define the Handoff Specification

Create a dedicated specification file (such as task_handoff.md) containing clear constraints and zero embedded secrets:

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.

Step 2. Isolate Workspace and Permissions

Before invoking Antigravity or transferring tasks into Claude Code, ensure proper environment hygiene:

• Never embed API keys or sensitive credentials into task prompts.
• Verify that .env and local state directories are included in .gitignore.
• Provide relative paths only for files inside the approved scope.

Step 3. Execute Automated Verification

Once the agent completes its code edits, run the exact verification command defined in the contract:

pytest tests/test_parser.py -v

If the verification fails or modifies files outside the permitted scope, halt the workflow immediately without applying the changes.

Step 4. Conduct Manual Diff Review and Acceptance

The human developer retains final merge authority:

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

Verify that only files listed in Allowed Scope have been touched. Discard any unauthorized modifications (git checkout -- <file>) and refine the stop conditions if drift occurred.

Scenario Recommendations

• Single-Function Refactoring: Use a lightweight task_handoff.md and run localized unit tests.
• Integrating External Model APIs: Keep API keys in environment variables and review protocol details in BetterToken Documentation.
• Complex Multi-Step Initiatives: Decompose the project into sequential, single-responsibility handoff contracts rather than one monolithic prompt.

Troubleshooting and Common Edge Cases

1. Agent Edits Files Outside Scope (Modified outside scope):
   • Cause: Ambiguous task prompt or missing negative constraints.
   • Fix: Enforce an explicit file whitelist in Allowed Scope and reject diffs touching other files.
2. Runaway Token Consumption in Retry Loops:
   • Cause: The agent attempts to fix unrelated broken tests autonomously.
   • Fix: Define a hard limit on retry attempts and require the agent to report blocker details to the developer.
3. Authentication or Connection Timeouts:
   • Cause: Incorrect Base URL or depleted account balance.
   • Fix: Verify endpoint configuration against the BetterToken Claude Code guide and check active balances in the workspace dashboard.