[에이전트 파트2]Spotify 코딩 에이전트의 컨텍스트 엔지니어링 6가지 원칙

요약

Spotify의 Fleet Management 시스템 위 백그라운드 코딩 에이전트 시리즈 Part 2. "마이그레이션 해줘" 한 마디로 PR을 안정적으로 만들어내는 게 목표인데, 수천 리포에서 머지 가능한 결과를 내려면 프롬프트와 도구 스택 설계가 제일 큰 변수였음. Goose·Aider 같은 오픈소스 에이전트와 자체 agentic loop를 거쳐 Claude Code에 안착하기까지 정리한 컨텍스트 엔지니어링 원칙 6개와 도구 제한 전략. 약 50건 마이그레이션에 적용 — 백그라운드 에이전트가 만든 PR 다수가 프로덕션 머지.

내용

백그라운드 코딩 에이전트를 한 리포에서 잘 굴리는 일과 수천 리포에서 안정적으로 굴리는 일은 다른 문제. Goose·Aider 같은 오픈소스 에이전트로 시작했을 때는 한 리포 안에서 디스크 탐색·코드 편집을 척척 해주는 인상이 있었지만, 같은 패턴을 다른 형태의 리포 수천 개에 적용해 머지 가능한 PR을 일관되게 만드는 단계로 가면 신뢰도가 떨어짐.

그래서 LLM API 위에 자체 agentic loop를 짬. 작업 단위는 셋 — 사용자가 프롬프트와 작업 대상 파일 리스트를 주면, 에이전트가 빌드 시스템 피드백을 받으면서 몇 턴에 걸쳐 파일을 편집하고, 테스트 통과 또는 한도 도달(세션당 10턴 / 세션 3회 재시도)에 도달하면 종료. deployment manifest 수정·config flag 교체·한 줄 변경 같은 작은 변경엔 잘 작동했지만, 사용자가 직접 git grep -l '*.java' 같은 검색 패턴을 짜야 하는 부담이 있었고 — 너무 넓으면 컨텍스트 윈도우가 폭발, 너무 좁으면 에이전트가 충분한 단서를 못 받음. public method 1개 수정 → 호출 사이트 줄줄이 따라 고치는 multi-file cascading 변경에선 턴이 모자라거나 컨텍스트가 차서 원래 작업을 잊는 문제가 잦았음.

자체 루프의 한계 — rigid한 단계별 지시가 필요하고 multi-step 편집에 약함 — 가 Claude Code 전환의 출발점. Claude Code는 자연어로 task-oriented 프롬프트를 받고, 내장 Todo 리스트 관리와 서브에이전트 spawn으로 더 긴 작업을 다룸. 본문 줄기는 두 갈래 — 어떤 프롬프트가 좋은 마이그레이션 프롬프트인지(컨텍스트 엔지니어링 원칙) + 에이전트에 어떤 도구를 노출할지(도구 스택 설계).

해결 / 접근

컨텍스트 엔지니어링 원칙 6개

직접 부딪혀보면서 정리한 항목들. 일관된 PR을 만들어내는 데 영향이 큰 순서로 잡혀 있음.

• 에이전트별로 프롬프트 스타일을 맞출 것 — 자체 agentic loop는 단계별 지시(step-by-step)에 제일 잘 반응했지만, Claude Code는 최종 상태(end state)를 기술하고 도달 경로를 에이전트에 맡기는 쪽이 더 잘 동작
• 전제조건을 명시할 것 — 에이전트는 프롬프트를 받으면 일단 행동하려는 경향이 강함. 마이그레이션처럼 같은 프롬프트를 여러 리포에 재사용할 때, 대상 리포의 언어 레벨이 안 맞으면 못 할 일을 굳이 시도. "언제 시작하면 안 되는지" 를 프롬프트 안에 적어두는 쪽이 안정적
• 구체 코드 예시를 넣을 것 — 한두 개 concrete example이 결과물에 큰 영향
• 검증 가능한 목표를 정의할 것 — "이 코드를 더 좋게 만들어줘" 같은 프롬프트로는 에이전트가 수렴할 지점을 못 찾음. 이상적으론 테스트 형태로 목표를 줘서 에이전트가 그 테스트에 도달하도록 반복할 여지를 만들어주는 것
• 한 번에 하나만 바꿀 것 — 관련 변경 여러 개를 한 프롬프트에 묶으면 컨텍스트 윈도우가 차거나 결과가 부분만 채워져서 끝남
• 에이전트의 피드백을 받아 프롬프트를 개선할 것 — 세션 끝나고 에이전트 본인에게 "프롬프트에서 빠진 게 뭐였냐"를 물어보면 의외로 정확한 답을 줌. 그 답을 다음 프롬프트에 반영

이 원칙들에 따라 만들어진 실제 프롬프트 예시로 AutoValue → Java records 마이그레이션 프롬프트가 같이 공개됨.

정적 큰 프롬프트 vs MCP 도구 호출

두 갈래 선택지. 첫째는 큰 정적 프롬프트(version-control / test / 성능 평가가 가능, 예측 가능성 ↑). 둘째는 작은 프롬프트 + MCP 도구로 에이전트가 작업 중 컨텍스트를 동적으로 가져오는 방식 — 모호하거나 단계가 많이 갈라지는 작업도 다룰 수 있는 대신 도구가 늘어날수록 unpredictability도 같이 늘어남. Spotify는 첫 번째 — "정적 큰 프롬프트 + 도구 최소화" — 를 택해 백그라운드 에이전트의 결과 일관성을 우선.

노출한 도구 스택

에이전트에 직접 주는 도구는 셋:

• Verify 도구 — 포매터·린터·테스트를 돌리는 도구. 사내 빌드 시스템 호출 방법을 MCP에 넣고(AGENTS.md 같은 파일 의존 ✗), 로그를 에이전트에 맞게 요약해 노이즈 압축. 사내 수천 리포의 빌드 설정이 다 달라서 MCP로 추상화한 게 핵심
• Git 도구 — 표준화·제한된 git 접근. push 차단 / origin 변경 차단 / committer 고정 / 표준 커밋 메시지 포맷 강제
• Bash 도구 — 명시적 allowlist 기반. ripgrep 같은 도구만 허용

빠진 도구가 의도. 코드 검색 도구·문서 도구는 일부러 노출하지 않음 — 에이전트가 탐색에 시간을 쓰기보다 사용자가 관련 정보를 프롬프트에 미리 압축해 넣는 쪽이 더 안정적이라는 판단. 별도 워크플로 에이전트가 사내·외부 소스에서 정보를 모아 코딩 에이전트 프롬프트로 넘겨주는 형태도 같이 사용. 대상 리포에 테스트·린터·API 문서를 깔아두면 그 코드 위에서 도는 모든 프롬프트·에이전트가 그 시그널의 도움을 같이 받음.

결과 / 참고

• Claude Code 적용 마이그레이션 약 50건, 백그라운드 에이전트 PR 다수가 프로덕션 머지
• 자체 agentic loop 한도 — 세션당 10턴 / 세션 3회 재시도
• 미해결 — 프롬프트 품질 평가는 직관·시행착오 단계. 어떤 프롬프트·모델이 가장 잘 도는지 평가하는 체계적 방법은 아직 없음. 머지된 PR이 원래 문제를 풀었는지 확인하는 방법도 미해결
• 시리즈: 본 글은 Part 2 — Part 1은 Spotify 백그라운드 에이전트 도입 (1,500+ PR 머지 사례), Part 3는 피드백 루프
• 인용 — Boris Cherny(Anthropic): "Spotify built a large scale system that used Claude Agent SDK to merge thousands of PRs across hundreds of repositories"
• 출처: Spotify Engineering, "Background Coding Agents: Context Engineering (Part 2)"