우리의 내부 코딩 에이전트 오케스트레이션 도구인 Bottega를 오픈 소스로 공개합니다

지난주 우리는 내부 에이전트 오케스트레이션 (agent orchestration) 도구를 통해 1,000번째 사용자 스토리 (user story)를 완료했습니다. 이를 기념하여, Bottega 저장소 (repo)를 오픈 소스로 공개합니다.

우리는 현재 1년 이상 Claude Code를 사용해 오고 있습니다. 개발 속도 (Velocity)가 크게 향상되었으며, 코드 품질 (code quality) 또한 높아졌습니다.

지난 8개월 동안, 프로덕션 코드 (production code)의 100%가 에이전트 (agents)에 의해 작성되었습니다. 사양 (specs)에서 제안하는 워크플로우 (workflow)는 그 결과물입니다. 인간은 계획 (plan)과 리뷰 (review)를 담당하고, 에이전트는 그 외의 나머지 작업을 수행합니다.

직접 작성하는 코드 (hand-written code)에 반대하려는 것은 아닙니다. 우리는 단지 리드 타임 (lead time)을 줄이고 코드 품질을 높일 수 있는 워크플로우를 발견했을 뿐입니다. 우리의 맥락 (context)에서는 이 방식이 효과적입니다.

무엇이 작동하고 무엇이 작동하지 않는지에 대한 저의 결론을 공유하고자 합니다.

우리는 현재의 워크플로우를 공식화하기 위해 이 도구를 구축했습니다. 우리는 미니멀리스트 (minimalist)적이고, 사용자 친화적 (user-friendly)이며, 적응하기 쉬운 도구를 원했습니다.

무엇이 작동하지 않았는지, 그리고 왜 이 도구를 만들었는지

우리는 코딩 에이전트 (coding agents)를 사용한 첫 6개월 동안 직면했던 문제들을 해결하기 위해 작년 말에 이 도구를 만들었습니다.

실패 모드: PR이 쌓이는 문제

근본적인 원인은 대개 다음과 같은 요소들의 조합이었습니다:

• 최종 PR (Pull Request)은 그럴듯하지만, 병합 가능한 상태 (mergeable state)로 만들기 위해 에이전트와 많은 대화 (back & forth)가 필요함.
• PR은 괜찮아 보이지만 수동 테스트 (manual testing) 결과 문제가 발견되어, 실제로 병합하기 전에 에이전트와 다시 많은 반복 (iteration) 과정을 거쳐야 함.
• 에이전트가 리뷰하기 복잡한 대규모 PR을 생성함.

우리는 이 모든 문제들을 개발이 시작되기 전, 즉 계획 (planning) 단계에서 해결하기로 결정했습니다.

이것은 새로운 아이디어가 아닙니다. 우리는 이 주제에 대해 20년 동안 축적된 Agile, XP, BDD 문헌을 가지고 있습니다. 다만 이를 에이전트에 적용했을 때 마법 같은 일이 일어난다는 것을 깨달았을 뿐입니다.

• Fowler의 Conversational Stories
• Jeffries의 Card, Conversation, Confirmation
• Adzic의 Specification by Example

인간과 에이전트가 공동 작성한 구체적인 예시 (concrete examples)들은 코드가 작성되기 전 이견을 드러낼 수 있는 가장 비용이 적게 드는 지점입니다.

계획(plan)은 에이전트 중심 개발 사이클(agentic development cycle)의 핵심입니다. 최종 출력물의 품질은 이 계획의 품질과 직접적인 상관관계가 있습니다.

우리의 실패 사례는 계획 산출물(plan artifact)을 일회용으로 취급했다는 점이었습니다:

• 우리는 작업에 대한 설명(가벼운 프롬프트)을 제공했습니다.
• Claude Code는 계획을 임시 폴더에 작성했습니다.
• 계획은 오직 세션에 종속된 가이드라인으로만 존재했습니다.

작업(task)은 프롬프트가 아닙니다. 작업은 수락 기준(acceptance criteria)을 갖춘 요구사항(requirement)입니다.

작업 그 자체, 즉 요구사항과 기술 사양(technical specification)은 단일 세션에 대한 일시적인 입력값이 아니라, **구현과 함께 공존하는 지속적인 산출물(enduring artifacts)**로서 존재해야 합니다.

계획이 충분히 상세해지고, 워크플로(workflow)가 에이전트로 하여금 이를 엄격하게 실행하도록 보장하게 되면서, 우리는 마침내 피드백(back & forth)이 전혀 없거나 최소화된 상태로 머지(merge)할 수 있는 PR(Pull Request)을 생성할 수 있게 되었습니다. PR이 쌓이는 현상이 멈췄습니다.

저는 "자율 코딩 에이전트(autonomous coding agent)"라는 용어가 매우 오해의 소지가 있다고 생각합니다. 이 용어는 시간 투자(time investment)보다는 시간 단축(time reduction)에 초점을 맞추고 있습니다. 우리는 프로세스의 HITL(Human-in-the-loop) 부분, 즉 '우리가 어디에 시간을 써야 하는가? 워크플로의 어느 단계에서? 무엇을 생산하기 위해?'로 초점을 옮긴 후에 훨씬 더 나은 결과를 얻었습니다.

우리가 프로세스의 마지막 단계에서 시간을 낭비하고 있다는 사실이 매우 명확해졌습니다. PR 단계는 자연스럽게 병목 현상(bottleneck)을 만들어냅니다. 우리는 대신 프로세스의 시작 단계에 시간을 투자하고, 워크플로의 모든 하위 단계(downstream steps)를 가능한 한 자율적으로 운영할 수 있도록 돕기 위해 이 도구를 만들었습니다.

마침내 성공한 방법

우리가 Claude를 인간 개발자와 똑같이 행동하도록 만드는 데 성공했을 때, 비로소 훌륭한 결과들을 얻기 시작했습니다.

전형적인 웹 개발 워크플로:

• 계획(Plan)
• 구현(Implement) + 단위 테스트(unit tests)
• 로컬에서 수동 테스트(Manual testing)
• PR 생성 -> CI 통과(green)
• 팀원이 PR을 리뷰하고 피드백을 남김. PR 작성자(에이전트)가 알림을 받고 PR을 업데이트함.

진행 과정에서 내린 주관적인 결정들

Bottega는 이 워크플로를 단순하고 사용자 친화적인 방식으로 자동화하려는 시도입니다.

더 많은 작업을 병렬로 실행함에 따라, 우리는 개발자의 노트북에서 이 워크플로를 실행하는 것이 의미가 없다고 판단했습니다. 내가 노트북을 닫는다고 해서 작업이 멈춰야 할 이유가 있을까요?

우리는 빠르게 이 도구를 원격 VPS (Virtual Private Server)에 구축하기로 결정했습니다.

보너스 1: 보안 측면에서, 권한 건너뛰기 (skip-permission) 상태로 이러한 에이전트들을 실행하는 것은 로컬 노트북보다 샌드박스화된 (sandboxed) VPS에서 훨씬 덜 위험합니다. 보너스 2: 도구에 단순한 브라우저로 접속할 수 있게 되자, 개발자뿐만 아니라 회사 내의 모든 사람이 사용하기 시작했습니다 (이에 대해서는 나중에 더 자세히 다루겠습니다).

일등 시민으로서의 계획 (Plan as the first-class citizen)

우리는 계획 템플릿 (plan template)을 사용합니다. 계획 에이전트 (planning agent)의 목표는 단 하나입니다. 작업 요구사항에서 시작하여 상세한 기술적 구현 계획으로 계획 템플릿을 채우고, 사용자와 인터뷰하며, 질문을 던지는 등의 과정을 수행하는 것입니다.

개발자는 이 계획을 검토합니다.

개인적인 결론은, 최종 PR (Pull Request)의 품질은 거의 전적으로 이 계획의 품질에 달려 있다는 것입니다.

이 계획을 만드는 것은 시간이 많이 걸리는 작업입니다. 저는 이 단계에서 시간의 50% 이상을 소비합니다. 목표는 PR 단계에서 발생할 수 있는 의외의 상황(surprise)을 최소화하는 것입니다. 만약 PR이 단순히 계획을 그대로 반영한 것이라면, 대개 PR은 즉시 승인될 수 있습니다.

매우 상호작용적인 단계입니다.

계획과 100% 일치하는 구현물 얻기

계획이 승인되면, 구현 에이전트 (implementation agent)가 이를 실행합니다. 실행이 완료되는 즉시, 적대적 코드 리뷰 에이전트 (adversarial code review agent)가 투입됩니다. 이 에이전트의 역할은 구현 내용이 계획과 엄격하게 일치하는지, 그리고 어떤 체크박스도 조용히 누락되지 않았는지 확인하는 것입니다.

이것은 이제 잘 알려진 개념인 '랄프 위검 루프 (Ralph Wiggum loop)'입니다.

두 에이전트는 리뷰어가 만족할 때까지 반복합니다.

수동 테스트

계획에는 반드시 다음과 같은 수동 테스트 시나리오가 포함되어야 합니다:

• playwright
• curl
• 스크립트 실행
• 기타 등등

에이전트는 개발자가 PR을 올리기 전에 하는 것과 똑같이, 스스로 이러한 시나리오들을 실행합니다.

이 단계가 주요한 돌파구(unlock)였습니다. 지난 몇 달 동안 PR(Pull Request)이 작성된 후 발견된 거의 모든 이슈는 기획 단계에서 간과되거나 놓친 수락 기준(acceptance criteria) 때문이었습니다 (즉, PR의 최종 품질 = 명세(specification)의 품질). 이 단계를 제대로 구축하고 나니, 수동 개발(manual development)과 유사한 수준의 품질에 도달할 수 있었습니다. 소프트웨어는 결코 완벽할 수 없습니다. 버그는 발생하며, 대부분의 경우 기능 설계(feature design) 단계에서 진정으로 놓친 시나리오의 결과입니다.

PR 관리 (PR management)

에이전트는 PR을 생성한 다음, 충돌(conflict)이 없고 CI(Continuous Integration)가 통과(green)될 때까지 반복합니다.

만약 제가 GitHub에 댓글을 남기면, GitHub 콜백(callback)을 통해 새로운 에이전트 실행이 트리거됩니다. 에이전트는 다시 한번 CI가 통과된 상태를 유지하도록 보장하며, 그 사이에 발생하는 새로운 충돌을 해결합니다.

또 다른 오케스트레이션 도구 (Yet another orchestration tool)

우리가 이 작업을 진행하는 동안, 수많은 오케스트레이션(orchestration) 도구들이 등장했습니다. 우리가 수렴하고 있었던 것과 동일한 워크플로(workflow)의 변형들이었습니다.

• Melty Labs (YC S24)의 Conductor
• Steve Yegge의 GasTown
• Garry Tan의 gstack
• GitHub의 SpecKit

우리가 구축한 것과 겹치는 부분이 많습니다. 우리에게 이는 우리가 올바른 길을 가고 있었다는 거대한 확신을 줍니다.

Bottega가 다른 점:

멀티 하네스 (Multi-harness). Bottega는 하나의 인터페이스 뒤에서 Claude Code, Codex, OpenCode를 구동하므로, 동일한 작업 내의 각 역할에 서로 다른 모델을 할당할 수 있습니다.

리모트 퍼스트 및 멀티 플레이어 (Remote-first and multi-player). 노트북에서 실행할 수도 있지만, Bottega는 설계 단계부터 리모트 퍼스트(remote-first)를 지향하며, 우리는 이를 공유 개발 서버(shared dev box)에서 실행합니다. 별도의 설정 없이도 여러 명의 동시 사용자 관리가 가능합니다. 부수적 이점 1: 자율 에이전트(autonomous agents)를 각자의 노트북에서 샌드박싱(sandboxing)하는 것보다 원격 서버에서 샌드박싱하는 것이 우리에게 더 쉬웠습니다. 부수적 이점 2: 많은 비기술직 인원들이 내부적으로 이를 사용합니다.

미니멀리스트 UX (Minimalist UX). 핵심 아이디어는 매우 단순합니다. 우리는 그저 전형적인 웹 개발자 워크플로를 재현하고 있는 것입니다. 그리고 우리는 도구가 그 단순함을 반영하기를 원했습니다. 부수적 이점: 제품 팀 전체가 쉽게 온보딩(onboard)할 수 있습니다.

그것이 핵심입니다. 저장소(repo)는 여기에 있습니다: github.com/vdaubry/bottega.

만약 여러분이 이와 유사한 것을 구축하고 있거나, 이 내용 중 동의하지 않는 부분이 있다면 여러분의 의견을 듣고 싶습니다.