Claude Code e Antigravity: como delegar tarefas sem desvio de escopo

Quando desenvolvedores conectam dois agentes de programação avançados — o agente de terminal Claude Code e o ambiente Antigravity — o principal obstáculo não é a qualidade da geração de código, mas o desvio de escopo (scope drift). Uma instrução genérica pode resultar em alterações indesejadas na estrutura do projeto e consumo excessivo de tokens.

Uma delegação confiável exige um contrato de transferência rigoroso: lista explícita de arquivos autorizados, proteção de credenciais, comando de validação reproduzível e revisão manual com Git diff.

Por que a delegação sem limites gera desvios

Agentes de IA operam sobre todo o repositório visível. Sem limites definidos, três problemas acontecem com frequência:

1. Expansão desnecessária do escopo: O modelo decide alterar arquivos auxiliares fora da tarefa.
2. Vazamento de segredos: O agente lê arquivos .env e expõe chaves em logs de testes.
3. Conflitos de padrões: Claude Code e Antigravity adotam convenções incompatíveis de importação.

Chaves de API e configurações de ambiente devem permanecer isoladas. Ao utilizar o Claude Code com BetterToken, a autenticação é configurada diretamente via variáveis de ambiente no terminal. No painel do BetterToken, você acompanha o consumo real de tokens para cada requisição.

O contrato de transferência (Handoff Contract)

Utilize um manifesto estruturado para delimitar a execução:

Campo do contrato	Objetivo	Exemplo
Goal	Meta mensurável	Otimizar parsing JSON em parser.py
Allowed Scope	Arquivos permitidos	src/parser.py, tests/test_parser.py
Forbidden	Ações proibidas	Não alterar config/, .env ou assinaturas públicas
Verification Command	Comando de teste	pytest tests/test_parser.py -v
Stop Conditions	Critérios de parada	Falha em testes externos, erros de tipagem

Processo de delegação passo a passo

Siga estes quatro passos para transferir tarefas com segurança:

Passo 1. Definir a especificação em arquivo separado

Crie um arquivo de especificação (task_handoff.md) sem segredos:

## 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`.

Passo 2. Isolar o ambiente e permissões

Mantenha arquivos .env no .gitignore e não insira credenciais no texto da tarefa.

Passo 3. Executar a verificação automatizada

Rode o comando de teste definido no contrato:

pytest tests/test_parser.py -v

Passo 4. Revisão e aceitação manual com Git Diff

O desenvolvedor aprova cada alteração antes do merge:

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

Recomendações por cenário

• Refatoração isolada: Use contratos objetivos e testes unitários rápidos.
• Integração de APIs: Consulte a documentação do BetterToken para configurar endpoints com segurança.

Diagnóstico de problemas

1. Arquivos alterados fora do escopo: Definir uma lista branca clara em Allowed Scope.
2. Loops de repetição com alto consumo: Limitar tentativas automáticas de correção.
3. Erros de autenticação ou timeout: Verificar a Base URL e o saldo no BetterToken Docs.