배경 코딩 에이전트를 위한 컨텍스트 엔지니어링 (Honk Part 2)

Spotify의 배경 코딩 에이전트 Honk 시리즈 2편으로, 대규모 마이그레이션에서 신뢰할 수 있는 PR을 만드는 프롬프트 엔지니어링과 도구 제한 전략을 다룬다. 약 50개 마이그레이션에 적용했고 Claude Code가 가장 좋은 성능을 냈다.

핵심 포인트

Fleet Management 확장 뒤 에이전트에게 무엇을 어떻게 지시할지가 새 문제였고 수천 레포에서 병합 가능한 PR을 안정적으로 뽑아야 했다.
자체 에이전틱 루프는 파일 목록과 빌드 피드백에 최대 10턴과 3회 재시도 구조였는데 git-grep 패턴 선택 실패와 다중 파일 연쇄 수정, 컨텍스트 윈도우 한계로 무너졌다.
Claude Code로 전환해 고수준 목표 해석과 할일 목록과 서브에이전트 자동 관리를 얻었다.
도구를 늘릴수록 예측 불가능성이 커진다는 원칙 아래 verify와 제한된 git과 허용목록 bash만 노출했다.

상세 정리

배경: Fleet Management로 변경을 확장한 뒤 프롬프트 작성과 검증 난이도가 급격히 올랐다.
오픈소스 한계: Goose와 Aider는 단일 레포엔 좋지만 대규모 마이그레이션에서 안정성이 부족했다.
자체 루프 실패: 사용자 프롬프트에 범위 내 파일 목록을 주고 빌드 피드백으로 편집하는 구조를 10턴과 3회 재시도로 만들었으나 git-grep 패턴이 너무 넓으면 컨텍스트가 넘치고 좁으면 정보가 부족했다.
자체 루프 실패 2: public 메서드 변경이 모든 호출부 수정으로 번지는 연쇄 수정에서 턴 수를 넘겼고 컨텍스트를 채우면 원래 작업을 잊었다.
Claude Code 전환: 고수준 목표를 해석하고 할일 목록과 서브에이전트를 자동 관리하며 작업 지향 프롬프트를 지원해 채택했다.
프롬프트 안티패턴: 너무 일반적이면 의도를 추측하게 하고 너무 구체적이면 예외에 대응 못 한다.
효과적 기법: 최종 상태를 기술하고 언제 행동하지 말지 사전조건을 명시하며 구체적 코드 예시와 테스트로 목표를 정의하고 한 번에 한 변경만 하며 에이전트 자체 피드백을 활용한다.
사례: AutoValue에서 Java Records로 가는 마이그레이션 프롬프트를 공개했다.
도구 제한: verify는 포매터와 린터와 테스트를 돌리고 로그를 에이전트용 요약으로 바꾸며 git은 push나 origin 변경을 막고 커밋터와 메시지를 표준화하고 bash는 ripgrep 같은 엄격한 허용목록만 준다.
미노출 결정: 코드 검색과 문서 도구는 노출하지 않고 대신 사용자가 관련 컨텍스트를 프롬프트에 미리 압축해 넣는다.
한계: 대부분 직감으로 운영 중이라 구조화된 프롬프트와 모델 성능 평가가 없고 PR 머지 후 원 문제 해결 검증법도 아직 없어 Part 3의 피드백 루프로 이어진다.