AI 시대의 개발 능력은 검증력으로 결정된다, Flava API Gateway 개발 중 배운 빠른 검증과 로컬 환경 구성 전략 (새 탭에서 열림)
코딩 에이전트는 빠르게 코드를 생성하지만, 설계 불명확성·출력 비결정성·검증 지연 때문에 신뢰할 수 없는 결과를 만들 수 있다. LY Corporation의 Flava API Gateway 팀은 이를 해결하기 위해 **스펙 주도 개발, 검증 자동화, 빠르고 독립적인 로컬 환경**을 구축했다. 결론적으로 AI의 생산성을 활용하려면 개발자의 전문성과 테스트·린터·사전 설계를 오히려 더 강화해야 한다. ## 코딩 에이전트가 만드는 개발 병목 - 에이전트의 코드 생성 속도에 비해 CI 대기, 환경 프로비저닝, 원격 테스트 같은 단계는 느리다. - 에이전트는 다음과 같은 오류를 반복적으로 만들 수 있다. - 컴파일되지 않는 코드 - 존재하지 않는 API 참조 - 명시되지 않은 설계 결정을 임의로 선택 - 동일한 프롬프트라도 실행마다 결과가 달라질 수 있어 출력의 일관성과 역량을 일반화하기 어렵다. - AI가 개발자의 리뷰 속도보다 빠르게 코드를 생성하면, 검토되지 않은 코드가 누적될 위험이 있다. - 따라서 AI 활용의 핵심은 단순한 생성 속도가 아니라, 잘못된 결과를 빠르게 발견하고 수정하는 개발 시스템이다. ## Flava API Gateway와 세 가지 대응책 - Flava API Gateway는 LY Corporation의 사내 프라이빗 클라우드 Flava에서 API를 생성·배포·모니터링하는 제품이다. - Kong이 데이터 플레인을 담당하고, 컨트롤 플레인은 각 팀이 독립적으로 API를 관리할 수 있는 다중 테넌트 REST API를 제공한다. - 팀은 다음 세 가지 원칙을 채택했다. - 코드 작성 전 설계와 요구사항을 확정하는 **스펙 주도 개발** - 테스트와 린터로 에이전트가 스스로 오류를 찾도록 하는 **검증 자동화** - CI를 기다리지 않고 전체 검증 루프를 돌리는 **빠른 로컬 환경** ## 스펙 주도 개발로 구현 방향 고정 - 에이전트가 설계가 정해지기 전에 구현을 시작하면, 에이전트가 임의로 설계 결정을 내리면서 비결정성이 커진다. - Flava 팀은 먼저 OpenAPI 스펙으로 컨트롤 플레인의 전체 설계를 정의했다. - OpenAPI 스펙은 다음 역할을 한다. - 에이전트가 따라야 할 명시적 기준 - 구현 결과가 설계에서 벗어났는지 판단하는 검증 기준 - API 동작 계약의 문서화 - 이후 기능을 작은 단위로 나누고 OpenSpec을 사용해 각 기능을 구현했다. ## Nickel을 활용한 OpenAPI 관리 - 원본 OpenAPI YAML은 반복적이고 장황해 수작업 유지보수가 어렵다. - 스펙과 실제 구현이 어긋나면 에이전트를 통제하는 기준으로서의 가치가 떨어진다. - 팀은 Nickel을 사용해 API 리소스를 선언적으로 정의하고, 이를 전체 CRUD 엔드포인트 스펙으로 변환했다. - 예를 들어 리소스 정의만으로 다음 요소를 일관되게 생성할 수 있다. - 목록·생성·조회·삭제 엔드포인트 - 페이지네이션과 정렬 - 정확히 일치하는 필터와 부분 문자열 필터 - ETag 기반 낙관적 잠금 - 공통 오류 응답 - 이 방식은 반복적인 YAML 작성량을 줄이고, API 설계 규칙을 생성기에 집중시킨다. ## OpenSpec 기반의 협업 워크플로 OpenSpec은 에이전트가 구현 전에 행동 계약에 합의하도록 다음 네 가지 산출물을 요구한다. - **제안(Proposal)**: 무엇을, 왜 변경하는지 설명 - **설계(Design)**: 기술적 결정과 트레이드오프 정리 - **델타 스펙(Delta Specs)**: 변경되는 요구사항을 Given-When-Then 시나리오로 정의 - **작업 목록(Task List)**: 구현 단계를 체크리스트로 분해 워크플로는 다음 순서로 진행된다. - 개발자와 에이전트가 기능, 세부사항, 에지 케이스를 함께 검토한다. - 에이전트가 네 가지 산출물을 작성한다. - 에이전트가 작업 목록을 단계적으로 실행하며 구현한다. - 완료 후 변경 사항을 아카이브하고 델타 스펙을 메인 스펙에 병합한다. - 축적된 델타 스펙은 시간이 지나면서 시스템 전체의 “살아 있는 스펙”이 된다. ## 검증 자동화로 에이전트의 오류 수정 유도 - 프롬프트에 주의사항을 계속 추가하는 방식은 효과가 제한적이며, 제약이 많아질수록 출력 품질이 낮아질 가능성도 있다. - 대신 테스트와 린터가 오류를 구체적으로 드러내도록 구성했다. - 에이전트는 다음과 같은 반복 루프를 수행한다. - 코드를 작성한다. - 테스트·린터·포매터를 실행한다. - 실패 원인을 확인한다. - 코드를 수정한다. - 다시 검증하고 다음 오류로 넘어간다. - 모든 요구사항을 처음부터 프롬프트에 주입하는 대신, 필요한 제약을 실패 시점에 점진적으로 제공하는 방식이다. - 프로젝트별 스킬에 테스트, 린터, 포매터를 묶고 `AGENTS.md`를 통해 언제 해당 스킬을 사용할지 안내했다. - 검사 지침을 매 턴마다 전달하지 않고 필요할 때만 로드해 에이전트의 불필요한 컨텍스트 부담도 줄였다. ## 세 계층 테스트와 완전한 로컬 검증 전체 테스트 모음은 2,754개이며 다음 세 계층으로 구성된다. - **단위 테스트** - 비즈니스 로직을 분리해 검증 - **통합 테스트** - 실제 PostgreSQL 사용 - 제약 조건, 트리거, 소프트 삭제 연쇄, 트랜잭션 검증 - 전체 인프로세스 HTTP 스택 검증 - 모든 응답의 OpenAPI 준수 여부 확인 - **E2E 테스트** - 실제 Athenz 인증 - Kong 데이터 플레인 - API 키 적용 - 멀티 테넌트 격리 - 전체 시스템 동작 검증 ## CI 의존성을 줄인 빠른 개발 환경 - 개발자가 직접 작성할 때는 CI 왕복을 줄이기 위해 어느 정도 완성된 코드를 먼저 제출할 수 있지만, 에이전트는 짧은 간격으로 수많은 시도를 반복한다. - 모든 시도를 원격 CI로 보내면 다음 문제가 생긴다. - 긴 대기 시간 - 반복 과정에서 에이전트가 컨텍스트를 잃을 가능성 - 원격 환경의 로그와 상태를 조사하기 어려움 - 완전한 로컬 환경을 구축하면 에이전트가 즉각적인 피드백을 받고 현재 작업 흐름을 유지할 수 있다. - 로컬 의존성의 로그와 상태를 직접 확인할 수 있어 실패 원인 분석도 쉬워진다. - 전체 테스트는 개발자 기기에서 약 15초 안에 실행되도록 최적화했다. - 이를 위해 테스트를 병렬화하고 테스트 간 격리를 강화했다. 공유 테이블을 매번 삭제하는 방식보다 각 테스트 패키지가 독립적으로 생성한 데이터를 사용해 실행 간 충돌을 줄이는 방향을 택했다. ## 실용적인 적용 권장사항 AI 코딩 에이전트를 도입할 때는 프롬프트를 복잡하게 만드는 것보다 먼저 API·행동 스펙을 문서화하고, 테스트·린터·포매터를 자동 실행하며, 핵심 검증을 로컬에서 빠르게 끝낼 수 있게 만드는 것이 효과적이다. 에이전트의 성능을 높이는 가장 현실적인 방법은 더 많은 일을 맡기는 것이 아니라, 실패를 즉시 알려 주고 스스로 수정할 수 있는 짧은 피드백 루프를 구축하는 것이다.
