LY Corporation 의 Flava API Gateway 개발팀이 AI 코딩 에이전트 도입 후 직면한 "빠른 코드 생성 vs 느린 검증" 문제를 해결한 전략을 공유한다. 스펙 주도 개발, 검증 자동화, 로컬 환경 재현성의 세 축으로 접근해 AI 에이전트가 즉각적인 피드백 루프 안에서 안정적으로 작동할 수 있는 개발 기반을 구축했다.
핵심 포인트- 코드 작성 전 OpenAPI 스펙을 먼저 정의하는 스펙 주도 개발로 AI 에이전트의 설계 비결정성을 억제했다.
- Nickel 언어로 장황한 YAML을 선언형 코드로 변환하고, OpenSpec 도구로 제안·설계·델타 스펙·작업 목록 4가지 산출물을 자동 생성한다.
- 2,754개 테스트를 단위/통합/E2E 세 계층으로 구성해 약 15초 내에 전체 스위트가 완료되도록 최적화했다.
- API 모든 응답이 OpenAPI 스펙을 준수하는지 자동 검증하는 래퍼를 공통으로 추가해 계약 위반을 조기에 감지한다.
- Devenv와 Nix로 macOS/Linux 동일 환경을 선언해 CI 없이도 에이전트가 로컬에서 즉각 피드백을 받을 수 있게 했다.
상세 정리- 문제 정의: AI 에이전트는 코드를 빠르게 생성하지만 검증 속도가 따라가지 못하면 신뢰성이 무너진다. 팀은 "에이전트를 믿기 위한 피드백 루프" 구축을 핵심 과제로 정했다.
- 스펙 주도 개발 도입: 코드 작성 전 OpenAPI 스펙을 먼저 정의해 AI 에이전트가 자체적으로 설계 결정을 내리며 비결정성을 키우는 문제를 차단했다.
- Nickel 언어 활용: YAML의 장황함을 줄이기 위해 Nickel을 도입하고 선언형 코드로 API 스펙을 기술했다.
- OpenSpec 도구: 스펙 문서에서 제안(Proposal), 설계(Design), 델타 스펙(Delta Spec), 작업 목록(Task List) 4가지 산출물을 자동으로 생성한다.
- 테스트 계층화: 2,754개 테스트를 단위/통합/E2E 3계층으로 분리하고, 전체 스위트가 약 15초 내에 완료되도록 병렬화 및 최적화했다.
- 응답 검증 래퍼: API의 모든 응답이 OpenAPI 스펙을 준수하는지 자동 검증하는 래퍼를 공통으로 추가해 계약 위반을 에이전트가 곧바로 인식하게 했다.
- 린터 옵트아웃 구성: golangci-lint, Semgrep 등 다양한 린터를 옵트아웃 방식으로 기본 활성화해 코드 품질 기준을 강제했다.
- 로컬 환경 재현성: Devenv와 Nix로 macOS와 Linux에서 동일한 개발 환경을 코드로 선언하고, PostgreSQL·Athenz 인증 시스템 등 복잡한 의존성을 로컬에서 자동 프로비저닝했다.
- 즉각 피드백 루프: 에이전트가 CI를 기다리지 않고 로컬에서 전체 테스트 스위트를 실행할 수 있어 수정 사이클이 단축됐다.
- 핵심 교훈: 이러한 실천 방식은 예전부터 유용했지만 AI 시대에는 중요성이 더 커졌다. 견고한 기반이 있으면 AI가 품질을 향상시키지만, 없으면 문제가 증폭된다.
왜 읽나AI 코딩 에이전트를 도입한 팀에서 스펙 주도 개발·테스트 자동화·로컬 환경 재현성의 세 축으로 신뢰성 있는 개발 기반을 구축하려는 백엔드/인프라 엔지니어에게 구체적인 도구와 전략을 제공한다.