AI 에이전트를 활용해 GitLab의 레이트 리미팅을 마이그레이션한 방법
GitLab은 3명의 엔지니어와 AI 에이전트를 활용해 레거시 애플리케이션·Rack 기반 레이트 리미팅을 `labkit-ruby` 단일 구현으로 통합했다. 에이전트는 코드 탐색, 사양 작성, 반복적인 구현과 테스트에는 효과적이었지만, 아키텍처 결정·점진적 롤아웃·관측성 설계·최종 판단은 여전히 사람의 책임이었다. 프로젝트의 성공을 결정한 것은 에이전트 자체보다 명확한 작업 루프, 작은 변경 단위, 점진적 배포, 그리고 실패를 되돌릴 수 있는 운영 체계였다. ## 레거시 레이트 리미팅 통합의 목표 - GitLab에는 다음 두 가지 레이트 리미팅 경로가 수년간 공존했다. - 애플리케이션 수준의 `Gitlab::ApplicationRateLimiter` - Rack 수준의 별도 레이트 리미터 - 목표는 두 시스템을 `labkit-ruby`의 단일 구현으로 통합하는 것이었다. - 새로운 구현은 다음 조건을 만족해야 했다. - 모든 요청에 적용될 만큼 안정적일 것 - 동작을 관측하고 테스트할 수 있을 것 - 장애 발생 시 되돌릴 수 있을 것 - 모놀리스와 다른 환경에서 동일하게 운영할 수 있을 것 - 기존 시스템에는 121개의 레이트 리미팅 키가 존재했다. ## 3명으로 구성된 포드와 AI 에이전트의 역할 - 포드는 세 명의 GitLab 엔지니어를 중심으로 구성됐다. - 모놀리스 측 구현과 롤아웃 담당 - `labkit-ruby`와 아키텍처 담당 - 범위 관리와 초기 gem 코드 작성 담당 - AI 에이전트는 다음 작업을 수행했다. - 코드와 기존 맥락 분석 - 기술 사양 초안 작성 - 범위가 제한된 변경 구현 - 테스트 작성 - 머지 리퀘스트 사전 검토 - GitLab Duo Code Review도 머지 리퀘스트의 품질 검토에 활용됐다. - 사람은 다음을 직접 맡았다. - 작업 범위 결정 - 아키텍처 설계 - 배포 및 롤아웃 판단 - 최종 리뷰와 승인 ## 사양-구현-검증 반복 루프 - 팀은 다음과 같은 엄격한 순서를 적용했다. 1. 에픽과 기존 코드 읽기 2. 사양 작성 3. 적대적 리뷰로 사양의 문제점 검토 4. 차단 이슈가 해결된 뒤 구현 5. 명시적인 증거를 바탕으로 검증 6. 머지 리퀘스트에 대한 적대적 리뷰 7. 필요 시 사람에게 에스컬레이션 8. 머지 - 적대적 리뷰는 최대 두 번의 해결 라운드까지만 허용하고, 이후에는 사람의 판단을 받도록 했다. - 프로젝트에서는 14개의 번호가 매겨진 사양과 30개가 넘는 `labkit-ruby` 머지 리퀘스트가 만들어졌다. - 레거시 코드처럼 맥락 파악과 반복 검증이 중요한 작업에서는 이처럼 제한된 루프가 에이전트 활용에 적합했다. ## 단계적 롤아웃과 에이전트가 잘한 작업 - 첫 번째 코호트에서는 트래픽이 많은 5개 키를 다뤘다. - `pipelines_create` - `notes_create` - `user_sign_in` - 그 외 주요 키 - 트래픽 비율을 `1% → 10% → 50% → 100%`로 단계적으로 높였고, 2026년 5월 5일 100% 배포를 완료했다. - 기존 `ApplicationRateLimiter`와 새 구현의 결과가 일치하는지 확인했지만, 단순히 불일치가 없다는 사실만으로 성공을 판단하지 않았다. - 실제로 제한에 걸릴 정도의 트래픽이 발생하지 않았을 가능성도 있기 때문이다. - 두 번째 코호트에서는 모놀리스 83개와 EE 12개를 포함한 95개 호출 지점을 두 개의 기능 플래그로 통합했다. - 이 작업을 수작업으로 했다면 약 95개의 플래그 변경과 190개의 YAML 수정이 필요했을 수 있지만, 에이전트는 이런 반복적인 코드베이스 전반의 변경에 특히 강했다. ## 관측성은 있었지만 실패 유형을 구분하지 못함 - 두 번째 코호트는 며칠간 섀도 모드에서 기존 구현과 비교되었고, 대체로 일치했다. - 그러나 강제 적용 모드로 전환한 뒤 인증되지 않은 일부 경로에서 식별자가 조용히 유실되는 문제가 발생했다. - 원인은 세 개의 `String` 값이 두 개의 원시 슬롯에 압축되면서 잘못된 값이 식별자를 덮어쓴 구조적 충돌이었다. - 일부 사용자는 짧은 시간 동안 일반적인 오류 메시지를 받았다. - 비교 시스템은 해당 키의 불일치를 이미 감지했지만, 대시보드가 다음을 구분하지 못했다. - 정상적인 동작 차이 - 데이터 구조 충돌 - 사용자에게 영향을 줄 수 있는 치명적 불일치 - 팀은 즉시 강제 적용 플래그를 끄고, 이틀 뒤 긴급 수정 사항을 배포했다. - 문제는 사양, 적대적 리뷰, 구현, 코드 리뷰, 점진적 롤아웃을 모두 통과했으므로, 단순히 “에이전트가 위험하다”기보다는 관측성이 충분히 세분화되지 않았던 것이 핵심 교훈이었다. ## 전체 키 인벤토리 관리의 실패 - 처음에는 다섯 개 코호트로 마이그레이션을 끝낼 계획이었다. - 마스터 브랜치 감사 과정에서 누락된 항목이 발견되어 여섯 번째 코호트를 추가했다. - Claude가 놓친 항목에는 다음이 포함됐다. - EE 전용 `notification_emails` - 일부 EE 레지스트리 항목 - 웹훅 관련 키 3개 - 1초 미만 주기의 `partner_*` 키 3개 - 고립된 어댑터 행 - 총 121개 키 중 17개가 초기 코호트에서 빠져 있었다. - 각 항목이 특정 코호트에 쉽게 들어가지 않는 이유는 있었지만, 목록에서 보이지 않아도 될 이유는 없었다. - 근본적인 실수는 에이전트와 사람이 전체 키 인벤토리 대비 진행 상황을 지속적으로 집계하도록 요구하지 않았다는 점이다. ## Redis 인프라 병목과 운영 판단 - `redis-cluster-ratelimiting`은 4개 샤드 클러스터로 운영됐다. - 마이그레이션으로 사용량이 증가하면서 기존에 알려져 있던 인프라 병목이 다시 나타났다. - 팀은 `maxclients`를 단계적으로 높였지만, 연결 수를 100,000까지 밀어붙이지 않고 75,000에서 중단했다. - 더 많은 연결을 허용하면 각 프라이머리의 CPU가 포화될 수 있었기 때문이다. - 각 샤드는 명령 실행에 하나의 코어를 사용했고, 수직 확장으로 해결할 여지도 제한적이었다. - 따라서 에이전트가 코드를 생성하더라도, 실제 배포 속도와 범위는 인프라 용량과 운영자의 판단에 의해 결정됐다. ## AI 에이전트가 바꾼 병목 - 에이전트 덕분에 코드 작성 자체는 더 이상 가장 느린 단계가 아니었다. - 대신 병목이 다음 영역으로 이동했다. - 사람의 리뷰 처리 용량 - 롤아웃 시점과 범위에 대한 판단 - 운영 중인 시스템을 주의 깊게 관찰하는 능력 - 에이전트는 요청하면 95개의 기능 플래그 같은 반복 작업도 만들어내지만, 그런 설계가 실제로 필요한지는 판단하지 못한다. - 예를 들어 코호트 1 이후 팀은 레이트 리미트마다 별도 기능 플래그를 두는 방식이 과도하다고 판단해 이후 마이그레이션에서는 적용하지 않기로 했다. - 에이전트와 협업하는 방법 자체도 학습이 필요했으며, 때로는 에이전트와 반복적으로 막혀 직접 처리하는 편이 빠르다고 느끼는 순간도 있었다. ## 최종 상태와 실용적인 교훈 - 2026년 6월 중순 기준으로 여섯 개 코호트가 모두 100% 롤아웃됐다. - `ApplicationRateLimiter`의 121개 키가 새 프레임워크를 통해 동작하게 되었고, 감사로 결과를 확인했다. - 이 사례에서 권장할 만한 방식은 다음과 같다. - 에이전트에는 반복적이고 범위가 명확한 변경을 맡긴다. - 아키텍처, 위험 허용 수준, 배포 중단 기준은 사람이 결정한다. - 전체 마이그레이션 대상을 인벤토리로 관리하고 누락 여부를 자동 검증한다. - 단순한 불일치 감지를 넘어 실패 원인과 심각도를 구분하는 관측성을 구축한다. - 기능 플래그와 점진적 롤아웃으로 즉시 되돌릴 수 있게 한다. - 코드 생성 속도가 빨라져도 리뷰와 운영 관찰에 필요한 사람의 시간을 충분히 확보한다.
원문 읽기(새 탭에서 열림)
