Claude Code и Antigravity: как передавать задачу без дрейфа и лишних правок

Почему делегация между агентами приводит к дрейфу

Агенты выполняют инструкции буквально в рамках предоставленного им промпта и рабочего дерева. Если передать агенту весь репозиторий без ограничений, возникают три типовые ошибки:

1. Разрастание зоны ответственности: модель решает попутно «улучшить» вспомогательный утилитный класс или переформатировать весь файл.
2. Утечка и повреждение секретов: агент считывает .env или конфиги с API-ключами и вставляет их значения в логи или код.
3. Конфликтующие предположения: Claude Code строит гипотезу на основе одной структуры, а Antigravity переписывает импорты под другую.

Для безопасной работы API-ключи и конфигурация среды должны быть полностью изолированы от контекста задачи. При использовании Claude Code через BetterToken аутентификация настраивается через переменные окружения разработчика на уровне терминала, а не передаётся в теле промпта или файлах задачи. В панели управления BetterToken можно отслеживать фактический расход токенов по каждому запросу, вовремя замечая аномальные циклы повторных вызовов.

Контракт задачи (Handoff Contract)

Вместо свободного текстового описания агент должен получать структурированный манифест задачи. Этот контракт фиксирует границы выполнения:

Пошаговый процесс передачи задачи

Чтобы передача задачи между Claude Code и Antigravity прошла предсказуемо, следуйте четырём шагам:

Шаг 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. Изолируйте рабочую директорию и права доступа

Перед запуском Antigravity или передачей в Claude Code убедитесь, что агент ограничен текущей веткой и не имеет доступа к глобальным секретам:

• Не передавайте API-ключи в тексте задачи.
• Добавьте .env и секретные файлы в .gitignore.
• Передавайте только относительные пути к целевым файлам.

Шаг 3. Запустите автоматическую верификацию

После завершения генерации агент обязан выполнить тестовую команду, указанную в контракте:

pytest tests/test_parser.py -v

Если агент сообщает об успехе, но тесты завершились с ошибкой или затронули непредусмотренные модули, выполнение немедленно прерывается без применения правок.

Шаг 4. Проведите ручную приёмку через Git Diff

Финальное решение о слиянии изменений всегда остаётся за человеком:

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

Проверьте, что список изменённых файлов строго совпадает с Allowed Scope. Если агент изменил файлы за пределами контракта, отмените эти правки (git checkout -- <file>) и уточните стоп-условия.

Сценарии выбора и рекомендации

• Локальный рефакторинг функции: используйте изолированный task_handoff.md и проверяйте только локальный набор юнит-тестов.
• Интеграция нового API: если вы подключаете внешние модели, изолируйте ключи через переменные окружения и проверяйте документацию на BetterToken Docs.
• Сложная многомодульная задача: разбейте её на серию последовательных handoff-контрактов вместо одной сквозной задачи.

Диагностика и типичные проблемы

1. Агент меняет файлы вне скоупа (Modified outside scope):
   • Причина: Слишком широкая формулировка задачи или отсутствие запрещающего блока.
   • Решение: Укажите явный белый список файлов (Allowed Scope) и проверьте diff перед коммитом.
2. Утечка токенов в бесконечном цикле правок:
   • Причина: Агент пытается самостоятельно починить падающий сторонний тест.
   • Решение: Задайте жёсткое условие остановки: если после двух попыток тест не проходит, агент возвращает отчёт с ошибкой разработчику.
3. Ошибки авторизации или тайм-ауты API:
   • Причина: Неверно заданный Base URL или исчерпанный баланс.
   • Решение: Проверьте параметры эндпоинта по документации BetterToken и статус ключа в личном кабинете.