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

Spotify가 수천 개 저장소에 걸친 코드 마이그레이션 자동화를 위해 오픈소스 에이전트에서 Claude Code로 전환하고, 에이전트가 좋은 결과를 내도록 컨텍스트를 구성하는 방법을 학습한 과정을 다룬다. 프롬프트 설계, 도구 제한, 컨텍스트 윈도우 관리가 에이전트 성능을 결정한다는 것이 핵심 결론이다.

핵심 포인트

Goose/Aider 같은 오픈소스 에이전트는 단일 저장소에서 효과적이지만 수천 개 저장소 확장 시 좋은 프롬프트 작성과 머지 가능한 PR 검증이 병목이 됐다.
자체 구축한 에이전트 루프는 컨텍스트 윈도우 초과와 복잡한 다중 파일 변경에서 한계를 보였고, Claude Code 전환 후 약 50개 마이그레이션에 적용돼 대부분의 PR이 프로덕션에 머지됐다.
과도하게 일반적이거나 과도하게 구체적인 프롬프트가 모두 실패하며, Claude Code는 단계별 지시보다 최종 상태 설명이 더 효과적이다.
Spotify는 도구를 verify/git/bash 세 가지로 제한하고, 코드 검색과 문서 도구는 노출하지 않아 에이전트가 사전 제공된 컨텍스트에만 집중하게 한다.
에이전트가 세션 후 스스로 프롬프트의 부족한 점을 지적할 수 있어, 이 피드백을 프롬프트 개선에 활용한다.

상세 정리

초기 문제: Goose와 Aider 사용 시 각 저장소마다 좋은 프롬프트를 수동 작성해야 했고, git-grep으로 파일을 선택해야 해서 수천 개 저장소 확장이 불가능했다.
자체 에이전트 루프 구조: 프롬프트 + 파일 목록 입력 → 최대 10턴 × 3회 재시도. 패턴이 너무 넓으면 컨텍스트 초과, 너무 좁으면 문제 미해결이라는 딜레마가 있었다.
Claude Code 전환 이유: 더 자연스러운 작업 지향 프롬프트, 내장 Todo 관리, 서브에이전트 효율적 생성, 긴 작업에서 컨텍스트 제약 완화가 가능했다.
Claude Code 성과: 현재 최고 성능 에이전트, 약 50개 마이그레이션 적용, 대부분 PR이 프로덕션 머지. AutoValue에서 Java records로의 마이그레이션이 대표 사례다.
프롬프트 안티패턴 1: 과도하게 일반적 프롬프트는 에이전트가 의도를 추측해야 해 예상치 못한 변경을 만들어낸다.
프롬프트 안티패턴 2: 과도하게 구체적 프롬프트는 모든 경우를 나열하려다 예상 밖 상황에서 실패한다.
프롬프트 설계 원칙: 에이전트 스타일에 맞추기(Claude Code는 최종 상태 설명 선호), 전제조건 명시(언제 행동하지 말 것), 구체적 코드 예제 포함, 한 번에 하나의 변경만.
도구 제한 철학: 큰 정적 프롬프트 선호(테스트·버전 관리 용이), MCP 도구는 동적 컨텍스트를 주지만 예측 불가능성이 증가한다.
Verify 도구: 포매터/린터/테스트를 실행하고 로그를 에이전트 친화적 형식으로 요약. 수천 개 저장소의 다양한 빌드 구성을 단일 인터페이스로 지원한다.
Git 도구 제한: push, origin 변경 같은 위험한 서브커맨드를 차단하고 커미터·커밋 메시지 형식을 표준화한다.
Bash 도구: 허용목록 기반으로 ripgrep 같은 명령어만 허용. 코드 검색/문서 도구는 미노출해 에이전트가 사전 제공된 컨텍스트에만 의존하게 한다.
향후 과제: 프롬프트·모델 성능 평가 프레임워크 구축, 마이그레이션이 원래 문제를 실제로 해결했는지 확인하는 방법 개발.

왜 읽나대규모 코드베이스 마이그레이션에 자율 코딩 에이전트를 도입하려는 플랫폼팀에게 Spotify의 프롬프트 설계·도구 제한·에이전트 선택 경험이 실용적 참조가 된다.

Spotify Engineering 블로그

원문은 여기서 이어서 읽을 수 있어요

원문 읽기

읽음 (0)

·takedown 요청

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

이 글과 비슷한

에이전틱 SDLC를 QA 엔지니어링 마인드셋으로 구축하기

보안 업무를 위한 AI 에이전트 플랫폼 「SAGE」 개발기 1편: 판단은 사람에게 남기는 설계

실리콘투의 사내 지식 MCP 게이트웨이 구축기