Zup 의 내부 코딩 에이전트 'CodeGen' 구축: 교훈과 열린 질문

(Building an Internal Coding Agent at Zup: Lessons and Open Questions) 기술 요약

이 논문은 브라질의 Zup Innovation 에서 개발 및 배포된 내부 코딩 에이전트 CodeGen의 아키텍처, 엔지니어링 의사결정, 그리고 프로토타입에서 프로덕션 환경으로의 전환 과정에서 얻은 교훈을 다룹니다. 저자들은 LLM(대형 언어 모델) 의 기술적 성능만으로는 에이전트의 성공이 보장되지 않으며, 도구 설계, 안전성 강화, 상태 관리, 인간 신뢰 보정과 같은 엔지니어링 결정이 실제 가치 창출에 더 결정적임을 강조합니다.

1. 문제 정의 (Problem)

기업 환경에서 코딩 에이전트를 구축할 때 다음과 같은 간극 (Gap) 이 존재합니다:

• 프로토타입 vs 프로덕션: 벤치마크나 시연 환경에서 성능이 좋은 에이전트가 실제 개발자의 일상 업무에서 신뢰를 얻고 사용되기까지의 격차.
• 기술적 한계: 모델의 품질만으로는 복잡한 빌드 시스템, 내부 도구 연동, CI/CD 파이프라인과의 상호작용, 그리고 개발자의 신뢰를 확보하기에 부족함.
• 위험 요소: 전체 파일 재작성 시 발생할 수 있는 잘림 (truncation) 오류, 무제한 쉘 접근으로 인한 파괴적 명령 실행 (rm -rf 등) 과 같은 안전 사고.
• 지식 부재: 이러한 실용적 엔지니어링 과제에 대한 공유 지식이 부족하여, 여러 조직이 동일한 실패 패턴을 독립적으로 반복하는 비효율 발생.

기존 연구는 모델 성능, 프롬프트 엔지니어링, 추론 전략에 집중했으나, **프로덕션 환경에서의 성공을 결정하는 엔지니어링 의사결정 (도구 설계, 안전 정책, 상태 관리 등)**에 대한 보고는 부족했습니다.

2. 방법론 및 아키텍처 (Methodology & Architecture)

Zup 은 StackSpot AI 플랫폼의 일부가 아닌 독립적인 프로토타입으로 시작하여 CodeGen 을 개발했습니다. 시스템은 ReAct(Reasoning + Acting) 패러다임을 기반으로 하며, 다음과 같은 3 계층 아키텍처로 구성됩니다:

1. CLI 인터페이스 (Node.js):
   • 다양한 IDE(VSCode, IntelliJ 등) 에 대한 네이티브 플러그인 개발 부담을 줄이기 위해 CLI 를 주 인터페이스로 채택.
   • 개발자의 실제 환경에서 도구를 실행하여 프로젝트 상태를 정확히 반영.
   • IDE 플러그인 및 VM 실행기 등 다양한 클라이언트 타입을 동일한 프로토콜로 지원.
2. 백엔드 API (FastAPI):
   • 클라이언트 연결 관리, 인증, 요청 라우팅 담당.
   • WebSocket: 양방향 도구 디스패치가 필요한 실행기 클라이언트 지원.
   • SSE (Server-Sent Events): 웹 포털용 읽기 전용 스트림 지원.
   • 비동기 처리 (asyncpg) 를 통해 동시성 확보.
3. Maestro (오케스트레이션 엔진):
   • 에이전트 루프를 제어하는 핵심 컴포넌트.
   • 부트스트랩 단계에서 환경 메타데이터 (OS, 디렉토리, Git 히스토리 등) 수집.
   • LLM 에게 시스템 프롬프트, 대화 기록, 도구 명세 (Tool Manifest) 를 전달.
   • LLM 의 도구 호출 요청을 CLI 로 전달하고 결과를 다시 LLM 에게 피드백하는 사이클 반복.

상태 관리 및 회복성:

• PostgreSQL: 영구적인 이벤트 타임라인 및 세션 상태 저장.
• Redis: 캐싱 레이어 및 메시징 백본 (Redis Streams) 으로 사용, 24 시간 TTL 적용.
• 재연결 지원: 네트워크 불안정으로 연결이 끊겨도 이전 컨텍스트를 유지하며 작업 재개 가능.

3. 주요 기여 및 핵심 설계 결정 (Key Contributions & Design Decisions)

저자들은 13 가지 구체적인 설계 결정을 통해 4 가지 핵심 차원 (모델 전략, 프레임워크 전략, 도구 전략, 인간 감독 전략) 을 다뤘습니다.

A. 아키텍처 및 프레임워크 전략

• 수동 구현 후 프레임워크 채택: 초기에는 LangChain 이 순차적 체인 모델에 적합하지 않아 에이전트 루프를 직접 구현 (Maestro). 이후 LangGraph 등 최신 프레임워크가 유사한 패턴을 지원하게 되면서 전환. 이는 추상화보다 실행 흐름에 대한 명확한 이해를 가능하게 함.
• 비동기 백엔드: FastAPI 와 Redis Streams 를 사용하여 다중 테넌트 환경에서의 수평 확장성 확보.
• LLM 기반 추론 위임: 오케스트레이터가 구조적 틀 (컨텍스트, 도구 호출) 을 제공하고, 추론은 LLM 에게 위임 (Thinking Effort 파라미터로 제어).

B. 도구 설계 및 안전성 (가장 중요한 교훈)

• 도구 설계의 중요성: 프롬프트 엔지니어링보다 도구 설명, 파라미터 스키마, 오류 계약을 정교하게 만드는 것이 에이전트 신뢰성 향상에 더 큰 영향을 미침.
• Targeted Edit (타겟팅 편집): 전체 파일 재작성 대신 문자열 교체 (String Replacement) 방식 사용. LLM 의 긴 파일 작성 시 발생하는 잘림 오류 방지.
• Read-Before-Edit 정책: 편집 전 반드시 파일 읽기 (read) 를 수행하도록 프롬프트에 명시하여, 오래된 컨텍스트나 환각 (Hallucination) 에 의한 편집 방지.
• 계층적 안전 가드레일: shell 도구는 가장 유용하지만 위험하므로, 명령어 차단, 승인 모드 (Approval Mode), 전체 감사 로그 등 다중 레이어 보호 적용.
• 정책의 일관성: 하나의 도구를 막는 것만으로는 불충분함 (예: 파일 삭제 도구 차단 시 shell 로 우회 가능). 전체 도구 명세 (Tool Manifest) 에 걸쳐 일관된 안전 정책이 필수적.

C. 인간 감독 및 채택 전략

• 점진적 신뢰 보정 (Progressive Trust): 개발자가 '승인 모드 (Approval Mode)'에서 시작하여 스스로 '자율 모드 (Autonomous Mode)'로 전환하도록 유도. 강제적 신뢰가 아닌 유기적 채택 유도.
• 계획 (Planning) 과 실행 분리: 복잡한 작업 시 실행 전 LLM 이 제안한 행동 계획을 사용자가 검토/수정할 수 있는 '계획 모드' 도입.
• 점진적 배포: 개발 -> 스테이징 -> 프로덕션 단계를 거치며 조직 차원의 신뢰를 구축.

4. 결과 및 성과 (Results)

• 신뢰성 향상: 프롬프트 튜닝만으로는 개선이 제한적이었으나, 도구 설계 (특히 문자열 교체 방식) 와 안전 가드레일 강화로 에이전트의 실패율 감소 및 신뢰도 향상.
• 유기적 채택: 승인 모드에서 자율 모드로의 점진적 전환 전략이 기업 환경에서의 에이전트 도입 장벽을 낮추고 개발자들의 수용을 촉진.
• 엔지니어링 통찰: 모델 자체의 성능보다 **모델을 둘러싼 엔지니어링 결정 (도구 설계, 상태 관리, 안전 정책)**이 실제 가치 창출의 핵심임을 입증.

5. 의의 및 열린 질문 (Significance & Open Questions)

이 논문은 코딩 에이전트를 프로토타입에서 프로덕션으로 이동시키는 데 필요한 실용적인 엔지니어링 프레임워크를 제시합니다. 특히 모델 성능 최적화보다 도구 인터페이스 설계와 안전 정책의 일관성이 더 중요함을 강조합니다.

저자는 향후 해결해야 할 6 가지 열린 질문을 제시합니다:

1. 도구 명세 설계: 모델 오남용을 최소화하고 정확한 호출을 극대화하기 위한 체계적인 도구 명세 설계 방법론 및 평가 프레임워크 필요.
2. 추론과 제어의 경계: 모델 위임 추론과 오케스트레이터 강제 제어 사이의 최적 경계 설정.
3. 교차 도구 안전 정책: 중복 기능을 가진 도구들 간의 일관된 안전 정책을 정의하고 검증할 수 있는 형식적 방법론 필요.
4. 적응형 신뢰 모델: 이진 (승인/자율) 모드 대신 작업 복잡도, 성공률, 행동의 가역성 등에 기반한 동적 인간 감독 수준 조정 메커니즘.
5. 장기 에이전트 메모리: 세션 간 기억과 신뢰성, 최신성 (staleness) 관리 사이의 균형.
6. 품질 보증 통합: 에이전트가 생성한 코드를 기존 QA 파이프라인 (정적 분석, 테스트 등) 에 효과적으로 통합하는 새로운 검증 메커니즘.

결론

Zup 의 CodeGen 사례는 코딩 에이전트의 성공이 단순히 "더 똑똑한 모델"을 선택하는 문제가 아니라, 신뢰할 수 있는 도구 설계, 강력한 안전 장치, 그리고 점진적인 인간-기계 상호작용 전략을 어떻게 엔지니어링하느냐에 달려 있음을 보여줍니다. 이 연구는 기업 내 에이전트 개발자들이 프로토타입의 함정을 피하고 실제 가치를 실현하는 데 중요한 길잡이가 될 것입니다.