대규모 소프트웨어 유지보수를 자동화하는 백그라운드 코딩 에이전트를 운영할 때, 가장 큰 도전은 '에이전트에게 무엇을 할지 어떻게 알려줄 것인가' 입니다. 단순히 에이전트를 실행시키는 것에서 한 걸음 더 나아가, 신뢰할 수 있고 머지 가능한 풀 리퀘스트(PR)를 생산하기 위해서는 정교한 콘텐츠 엔지니어링이 필수적입니다. 이 글은 Spotify가 수백 개의 저장소에 걸쳐 수천 개의 PR을 자동으로 생성하며 쌓은 경험을 바탕으로, 효과적인 프롬프트 작성법과 에이전트 도구 설계에 대한 깊이 있는 고찰을 담고 있습니다. 자세한 근거자료는 원문에서 확인할 수 있습니다.
프롬프트 작성의 함정과 교훈
초기 오픈소스 에이전트나 자체 구축한 에이전트 루프를 사용하며 Spotify 팀은 두 가지 주요 안티패턴을 발견했습니다.
- 과도하게 추상적인 프롬프트: 에이전트가 텔레파시처럼 의도를 추측하도록 기대하는 프롬프트입니다. "코드를 개선하라"는 지시는 검증 가능한 목표가 없어 에이전트를 혼란스럽게 합니다.
- 과도하게 구체적인 프롬프트: 모든 경우를 다 커버하려다가 예상치 못한 상황에서 망가지는 프롬프트입니다. 단계별 지시가 너무 엄격하면 에이전트의 유연성을 죽이고, 복잡한 다단계 변경 시 컨텍스트 창을 빠르게 소모하게 만듭니다.
Claude Code로 전환하며 얻은 핵심 교훈은 다음과 같습니다.
- 에이전트에 맞게 프롬프트를 맞춤화하라: Claude Code는 최종 상태를 설명하고 도달 방법을 스스로 찾을 여지를 주는 프롬프트에서 더 잘 작동합니다.
- 사전 조건을 명시하라: "Java 11 미만 저장소에서는 작업을 수행하지 마라"와 같이, 작업이 불가능한 상황을 사전에 차단하는 지시를 포함시켜야 합니다.
- 예시를 사용하라: 구체적인 코드 예시 몇 개가 결과에 지대한 영향을 미칩니다.
- 검증 가능한 목표를 정의하라: 이상적으로는 테스트 형태로 원하는 최종 상태를 정의하세요. 에이전트가 해결책을 반복적으로 개선할 수 있는 기준이 필요합니다.
- 한 번에 하나의 변경만 하라: 여러 관련 변경을 하나의 정교한 프롬프트로 합치면 편리해 보이지만, 컨텍스트 창 고갈이나 부분적 결과물을 초래할 가능성이 높습니다.
- 에이전트에게 프롬프트 피드백을 요청하라: 작업 세션 후, 에이전트 자체가 프롬프트에 무엇이 부족했는지 놀라울 정도로 잘 알려줄 수 있습니다.
예측 가능성을 위한 도구 제한의 미학
복잡한 작업을 위해 에이전트에 수많은 도구(MCP 툴 등)를 연결해 동적으로 컨텍스트를 가져오게 할 수 있습니다. 하지만 이는 테스트 가능성과 예측 가능성을 떨어뜨립니다. 도구가 많을수록 예측 불가능성의 차원이 늘어납니다.
Spotify는 백그라운드 코딩 에이전트의 도구와 훅을 매우 제한적으로 유지하여, 프롬프트로부터 올바른 코드 변경을 생성하는 데 집중하도록 설계했습니다.
현재 제공하는 핵심 도구:
verify도구: 포매터, 린터, 테스트를 실행합니다. 수천 개의 서로 다른 빌드 설정을 가진 저장소에서 작동해야 하므로, 에이전트가 이해하기 쉬운 형태로 로그를 요약하여 제공합니다.- Git 도구: 제한적이고 표준화된 Git 접근을 제공합니다.
push나origin변경 같은 위험한 명령은 노출하지 않고, 커미터 설정이나 표준 커밋 메시지 형식 사용은 표준화합니다. - Bash 도구:
ripgrep같은 몇 가지 허용 목록 명령어에만 접근할 수 있는 엄격한 Bash 도구입니다.
주목할 점은, 코드 검색이나 문서화 도구는 현재 에이전트에 노출되지 않았다는 점입니다. 대신 사용자에게 관련 컨텍스트를 프롬프트에 사전에 응축하도록 요구하거나, 별도의 워크플로우 에이전트를 통해 코딩 에이전트용 프롬프트를 생성하도록 유도합니다.
한국 개발 생태계에서의 적용 맥락
국내 SI 환경이나 레거시 코드베이스가 많은 프로젝트에서 대규모 마이그레이션은 빈번한 과제입니다. 자동화 에이전트를 도입할 때, 표준화되지 않은 빌드 과정과 복잡한 모듈 간 의존성이 가장 큰 장벽이 될 수 있습니다. Spotify의 verify 도구 접근법처럼, 내부 빌드 시스템 호출 방식을 에이전트용으로 추상화하는 노력이 선행되어야 합니다. 또한, '한 번에 하나의 변경' 원칙은 특히 중요합니다. 한국 프로젝트에서는 여러 기술 부채 해결을 한번에 해보려는 유혹이 크지만, 이는 에이전트의 실패 확률을 급격히 높입니다.
이 접근법의 한계와 주의사항
현재의 에이전트와 프롬프트 엔지니어링은 여전히 많은 부분이 직관과 시행착오에 의존합니다. 어떤 프롬프트나 모델이 가장 성능이 좋은지 평가할 구조적인 방법이 부족하며, 머지된 PR이 원래 문제를 실제로 해결했는지 검증하는 피드백 루프는 아직 초기 단계입니다. 에이전트가 생성한 코드의 장기적 유지보수성에 대한 영향도 아직 명확하지 않습니다.
다음 단계 학습 방향
이 기술의 진정한 성숙은 측정 가능한 피드백 루프 구축에 달려 있습니다. PR 머지율뿐만 아니라, 생성된 코드의 품질, 리뷰 시간 단축 효과, 그리고 최종적으로 시스템 안정성에 미치는 영향을 정량적으로 평가하는 방법을 탐구해야 합니다. 또한, 프롬프트를 '코드'처럼 버전 관리하고 테스트하는 문화를 팀 내에 정착시키는 것이 지속 가능한 자동화의 핵심입니다.