작업을 잃지 않고 Coding Agent나 모델을 전환하는 방법
구조화된 handoff로 secrets를 넘기지 않고, 집중된 검증과 함께 Coding Agent와 모델 사이에서 작업을 전달합니다.
목차
복잡한 엔지니어링 문제를 다룰 때 개발자는 Coding Agent를 자주 전환합니다. 예를 들어 Claude Code에서 아키텍처 계획을 시작한 뒤, 알고리즘 리팩터링이나 테스트 생성을 Codex 또는 다른 모델에서 시도할 수 있습니다. 하지만 이전 대화 로그 전체를 새 Agent에 넣으면 오래된 가설이 컨텍스트를 채워 Token과 개발 시간을 낭비하게 됩니다.
모델 전환은 끝없는 채팅 기록을 옮기려 할 때가 아니라, 형식화되고 이식 가능한 handoff 카드와 집중된 검증 단계에 기반할 때만 효과적입니다.
1. 전환 비교: 모델, 도구, API 제공자
근본적으로 다른 다음 세 가지 작업을 혼동하지 마세요.
| 구분 | Agent 내부에서 모델 변경 | 도구 전환(Claude Code ↔ Codex) | API 제공자 변경 |
|---|---|---|---|
| 변경되는 것 | 구성의 Model ID 파라미터 | CLI 클라이언트, 프로토콜, 도구 오케스트레이션 | Endpoint, Base URL, 인증 키 |
| 작업 컨텍스트 | 현재 세션 안에 유지됨 | 세션이 완전히 초기화되므로 깔끔한 handoff가 필요 | 로컬 환경 구성에 유지됨 |
| API 프로토콜 | Anthropic 또는 OpenAI(변경 없음) | Anthropic Messages에서 OpenAI Responses API로 전환 | Base URL과 API Key 그룹 구성 |
| 권장 시나리오 | reasoning 수준을 빠르게 높일 때 | 깔끔한 worktree에서 대안 가설을 시험할 때 | 로컬 또는 전용 gateway를 통해 라우팅할 때 |
2. 시나리오별 도구 선택
현재 작업의 요구 사항에 맞는 방식을 선택하세요.
- 옵션 1(Claude Code): 코드베이스를 대화형으로 탐색하거나, 여러 파일에 걸친 복잡한 아키텍처 리팩터링을 수행하거나, 유연한 shell 도구가 필요할 때 적합합니다.
- 옵션 2(Codex CLI / Custom Provider): 결정적인 테스트 생성, OpenAI 호환 Responses API를 통한 직접 실행, 준비된 diff에 대한 독립적인 세컨드 오피니언이 필요할 때 적합합니다.
3. 이식 가능한 handoff 프로토콜
프롬프트를 어지럽히지 않고 작업 상태를 안정적으로 넘기려면, 검증된 사실만 담은 구조화된 handoff 카드를 작성하세요.
### Task Handoff: Database Connection Pool Limits
- **Goal**: Enforce max_connections=20 and add a 5s connection acquisition timeout.
- **Current State**: Branch `perf/db-pool-limits` created; modified `config/database.go`.
- **Verified Progress**: Test `go test ./config -run TestPoolLimits` passes.
- **Unresolved Blocker**: Under `wrk` load, pool exhaustion crashes without returning HTTP 503.
- **Target Check for Next Agent**: Implement 503 error handling on pool timeout and verify with a test.[!IMPORTANT] handoff에 secrets를 넣지 마세요: handoff 카드에 API Key, 인증 Token,
.env파일 내용을 절대 포함하지 마세요. 각 CLI 도구는 로컬 환경 변수에서 자격 증명을 읽습니다. Claude Code와 Codex 설정 안내는 BetterToken Docs에서 확인하세요.
4. 단계별 전환과 검증
다른 Agent에게 작업을 넘길 때 다음 5단계 절차를 따르세요.
- 1단계: Git 상태를 저장합니다. 커밋되지 않은 변경을 검토하고 stash합니다:
git status --short. 그런 다음 구조화된 handoff 카드를 저장합니다. - 2단계: 새 세션을 시작합니다. 격리된 Git worktree 또는 깨끗한 터미널 창에서 보조 Agent를 시작합니다.
- 3단계: handoff 카드만 전달합니다. 새 Agent에게 이전 채팅 기록 없이 작업 목표와 검증 단계를 제공합니다.
- 4단계: 집중된 검증을 실행합니다. Agent가 대상 테스트를 실행하고 변경된 파일을 검사하게 합니다:
git diff --check. - 5단계: 관찰 가능한 출력으로 결정합니다. 보조 모델이 blocker를 깔끔하게 해결하면 그 branch에서 계속합니다. 그렇지 않으면 회귀 부담 없이 주 세션으로 돌아갑니다.
이 방식은 프롬프트 비대화를 막고 모델 전환을 객관적이고 측정 가능한 엔지니어링 실험으로 바꿉니다.
