Claude Code와 Antigravity: 스코프 드리프트 없는 안전한 작업 위임
Claude Code와 Antigravity 간의 실용적인 핸드오프 계약: 파일 격리, 시크릿 보호, 재현 가능한 검증 테스트 및 수동 diff 검토.
터미널 기반 에이전트인 Claude Code와 코딩 환경인 Antigravity를 함께 활용할 때 발생하는 가장 흔한 문제는 코드 생성 성능이 아니라 작업 범위의 이탈(Scope Drift)입니다. "모듈을 리팩터링하고 테스트를 업데이트해줘"와 같은 모호한 요청은 원치 않는 설정 파일 변경과 불필요한 토큰 낭비로 이어지기 쉽습니다.
AI 에이전트 간의 안전한 작업 위임을 위해서는 명확한 핸드오프 계약(Handoff Contract)이 필요합니다. 수정 가능한 파일 목록 지정, 비밀 정보 격리, 재현 가능한 검증 명령어, 그리고 Git diff를 통한 수동 승인이 필수적입니다.
무제한 작업 위임이 스코프 드리프트를 유발하는 이유
에이전트는 제공된 전체 파일 트리를 기반으로 작동합니다. 엄격한 경계가 없으면 세 가지 위험이 발생합니다.
- 작업 범위의 임의 확장: 모델이 관련 없는 유틸리티 함수나 코드 포맷을 임의로 변경합니다.
- 보안 정보 유출:
.env파일을 읽어 테스트 로그나 코드에 API 키를 노출합니다. - 아키텍처 가정의 충돌: 두 에이전트가 상충되는 가져오기 규칙을 적용할 수 있습니다.
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 가이드에서 엔드포인트와 잔액을 확인합니다.