spec-driven-development

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·행동 스펙을 문서화하고, 테스트·린터·포매터를 자동 실행하며, 핵심 검증을 로컬에서 빠르게 끝낼 수 있게 만드는 것이 효과적이다. 에이전트의 성능을 높이는 가장 현실적인 방법은 더 많은 일을 맡기는 것이 아니라, 실패를 즉시 알려 주고 스스로 수정할 수 있는 짧은 피드백 루프를 구축하는 것이다.

AI 에이전트끼리 토론한다면? 멀티 에이전트 협업으로 재설계하는 개발 프로세스 (새 탭에서 열림)

AI 코딩의 병목은 코드 생성 속도가 아니라 의도 정의, 가정 검증, 구현 확인, 리뷰 준비를 사람이 직접 조율하는 데 있다. LY Corporation은 이를 해결하기 위해 제안자와 도전자 AI 팀이 스펙·빌드·전달의 세 단계에서 토론하고, 조율자가 수정·상위 보고·진행 여부를 결정하는 파이프라인을 설계했다. 목표는 사람의 판단을 없애는 것이 아니라, 사람이 검토하기 전에 AI가 자신의 작업을 근거와 함께 입증하도록 만드는 것이다. ## 사람이 조율하는 AI 보조 방식의 한계 - 기존 방식에서는 AI가 스펙 작성, 코드 생성, 테스트, PR 설명 등을 빠르게 수행한다. - 그러나 각 단계 사이에서 사람이 다음 작업을 요청하고, 실패 결과를 전달하고, diff와 PR을 검토해야 한다. - 따라서 개별 작업은 빨라져도 의도·구현·검증·리뷰·전달 사이의 조율 비용은 그대로 남는다. - 진정한 생산성 향상은 각 단계를 단순히 가속하는 것이 아니라, 수동 인수인계를 프로세스에서 제거하는 데 있다. ## 제안자와 도전자로 나뉜 AI 협업 - 제안자는 산출물을 작성하고 단계가 진행될수록 이를 발전시킨다. - 도전자는 제안자의 결과를 검증하며, 단계별로 서로 다른 관점에서 문제를 제기한다. - 스펙 단계: 소크라테스식 질문으로 모호성·누락을 찾는다. - 빌드 단계: 테스트와 실행 결과 등 근거를 바탕으로 반론한다. - 전달 단계: 구현과 PR이 최종 리뷰에 충분한지 점검한다. - 역할을 분리하면 하나의 AI가 스펙, 구현, 검증, 리뷰를 모두 낙관적으로 처리하는 문제를 줄일 수 있다. - 사람은 시작 시 의도를 정의하고, 결과를 승인하거나, 해결하기 어려운 문제가 상위 보고될 때 주로 개입한다. ## 스펙·빌드·전달 파이프라인 ### 스펙: 이후 작업의 계약 정의 - 스펙은 다음 내용을 포함한다. - 목표와 제약 조건 - 해석된 요구 사항 - 명시적 가정 - 미해결 질문 - 제안된 접근 방식 - 완료 정의 - 빌드 에이전트는 “합리적으로 보이는” 구현을 임의로 선택하지 않고, 승인된 스펙에서 테스트와 검증 계획을 도출한다. - 스펙이 부실하면 이후 구현과 리뷰의 기준도 불명확해지므로 전체 파이프라인이 약해진다. - 기존 API, 테스트, 의존성, 코딩 관습, Jira·Confluence·설계 문서 등을 조사해 질문과 가정을 구체화한다. ### 빌드: 테스트 우선 구현과 반론 - 제안자는 코드를 수정하기 전에 스펙을 다음 항목으로 변환한다. - 예상 동작 - 에지 케이스 - 추가·수정할 테스트 - 실행 명령 - 도전자는 구현 전이나 구현 중에 검증 설계 자체를 문제 삼을 수 있다. - 제안자가 도전자의 이의를 거부하려면 실행 경로, 컴파일·린트 출력, 실패 테스트 등 구체적인 증거를 제시해야 한다. - 단순히 테스트가 녹색이라는 사실만으로 검증 누락을 숨길 수 없도록 설계됐다. ### 전달: 리뷰 가능한 PR 패키지 - 최종 산출물은 코드뿐 아니라 리뷰어가 신뢰할 수 있는 PR 패키지다. - 패키지에는 다음 정보가 포함된다. - 무엇이 변경되었는가 - 어떤 파일과 영역을 먼저 봐야 하는가 - 어떤 검사와 테스트를 통과했는가 - 남은 위험과 불확실성은 무엇인가 - 도전자가 어떤 문제를 제기했고 어떻게 처리했는가 - 전달 단계의 조율자는 중재자라기보다 출시 가능성을 판단하는 심사위원 역할을 한다. ## 조율자와 구조화된 토론 프로토콜 - 조율자는 제안자와 도전자 사이에서 토론을 관리한다. - 주요 책임은 다음과 같다. - 논의가 주제에서 벗어나면 방향 수정 - 교착 상태 해소 - 산출물 수정 요청 - 안전하지 않은 불확실성의 상위 보고 - 다음 단계 진행 여부 결정 - 스펙과 빌드에서는 수렴을 이끄는 중재자 역할을 하고, 전달 단계에서는 근거가 충분한지 판정한다. - 각 에이전트는 제한된 프롬프트와 자체 컨텍스트를 사용하며, 공통으로 접근하는 것은 워크스페이스·산출물·조율자가 누적한 기록이다. - 에이전트 간 실시간 공동 컨텍스트 대신 구조화된 산출물과 transcript를 통해 협업한다. ## JSON 기반 상태 머신 - 각 토론 라운드는 제안자와 도전자의 교환 및 조율자의 결정을 포함한다. - 에이전트는 긴 에세이가 아니라 조율자가 파싱할 수 있는 엄격한 JSON을 반환한다. - JSON에는 상태, 요약, 전문가 의견, 판단 근거, 요구 사항, 제약, 완료 정의, 가정, 질문 등이 담긴다. - 예를 들어 `/api/search`만 변경할지 인접한 검색 엔드포인트까지 포함할지 불명확하면, 도전자는 범위 경계를 명시적인 질문으로 제기한다. - 모호성이 작고 기존 근거로 안전하게 판단할 수 있으면 제안자가 가정으로 기록하고 진행한다. - 반대로 답이 없으면 위험하거나 파괴적이거나 되돌리기 어려운 문제라면 추측하지 않고 사람에게 상위 보고한다. ## 전문 역할과 근거 중심 검증 - 각 단계에는 목적에 맞는 전문 역할이 배정된다. - `requirements-synthesizer`: 요구 사항 정리 - `security-analyst`: 보안 위험 분석 - `test-coverage-reviewer`: 테스트 범위 검토 - `technical-writer`: 전달 문서 작성 - `evidence-verifier`: 구현과 검증 근거 확인 - 중요한 판단은 직감이 아니라 코드, 테스트, 문서, 실행 결과 같은 근거에 기반한다. - 핵심은 여러 AI를 단순히 병렬 실행하는 것이 아니라, 서로 다른 책임과 관점을 부여해 주장과 반론을 구조화하는 데 있다. ## 실용적인 결론 AI 코딩 시스템을 설계할 때는 코드 생성 에이전트 하나를 더 빠르게 만드는 것보다, 스펙부터 PR 전달까지의 인수인계를 자동화하는 것이 더 큰 효과를 낼 수 있다. 특히 스펙을 계약으로 명확히 만들고, 단계별 도전과 근거 제출을 강제하며, 위험한 가정은 사람에게 상위 보고하도록 구성하는 것이 핵심이다.

레거시 프로젝트에서 AI 드리븐 프로젝트로 전환, AX 로드맵 (새 탭에서 열림)

AX는 AI 도구를 개별적으로 사용하는 데서 그치지 않고, 개발 사이클 전체를 AI 중심으로 재설계하는 전환 과정이다. 성공적인 전환을 위해서는 보안·컴플라이언스 기반을 먼저 마련하고, 팀 차원의 활용 표준화와 명세 기반 개발 자동화를 단계적으로 추진해야 한다. 특히 SDD와 사람의 승인 게이트를 결합하면 AI의 생산성을 활용하면서도 품질과 통제력을 유지할 수 있다. ## AI 드리븐 프로젝트와 SDD - AI 드리븐 프로젝트는 AI를 스펙 작성, 코드 생성, 테스트, 리뷰, 머지 등 개발 전 과정에 통합하는 방식이다. - 사람은 세부 구현보다 요구사항과 방향 설정, 품질 판단에 집중한다. - 핵심 방법론은 명세 주도 개발(SDD)이다. - 요구사항, 구현 범위, 예외 상황, 검증 기준을 먼저 정의한다. - AI는 명세를 바탕으로 계획을 세우고 코드를 생성·검증한다. - AI는 패턴 완성에는 강하지만 추상적인 의도 파악에는 한계가 있으므로, 명확한 스펙이 결과 품질을 좌우한다. ## 1단계: AI-Ready — 보안과 컴플라이언스 기반 AI 도입 전 민감 정보와 핵심 자산이 외부 모델에 노출되지 않도록 안전한 사용 환경을 구축한다. - API 키, DB 비밀번호, 내부 IP 등의 하드코딩을 제거한다. - Secrets Manager 같은 전용 서비스를 사용하고 런타임에 시크릿을 주입한다. - 이름, 이메일, 전화번호 등 PII는 AI에 전달하기 전에 마스킹하거나 토큰화한다. - 핵심 알고리즘과 경쟁력 있는 아키텍처는 별도 저장소에서 관리하거나 AI 접근 권한을 제한한다. - 초기에는 모든 시스템을 한 번에 이관하기보다 다음을 우선 적용한다. - 핵심 컴플라이언스 요건 선별 - 파일 시스템·네트워크 격리를 통한 샌드박싱 - 격리 상태에서 실제 정보가 노출되지 않는지 검증 - 기대 효과: - 코드와 프로젝트 맥락을 AI에 안전하게 제공 - 디버깅, 문서화, 반복 코드 작성 속도 향상 - 팀원들이 AI를 안전하게 활용하는 경험 축적 ## 2단계: AI-Assist — 팀 단위 활용 표준화 개인별로 제각각인 AI 사용 방식을 프로젝트 공통 워크플로로 통합한다. 이 단계에서 AI는 코드를 직접 작성하기보다 사람이 작성한 코드를 검토하고 보조한다. - 프로젝트 루트에 AI용 가이드라인을 작성한다. - 프로젝트 개요 - 코딩 컨벤션 - 아키텍처 원칙 - 도메인 용어집 - 코드 리뷰, 브레인스토밍, 작업 계획 수립 등에 사용할 표준 프롬프트와 스킬을 구축한다. - `superpowers`와 같은 플러그인을 활용해 다음 작업을 표준화할 수 있다. - `brainstorming` - `writing-plans` - `subagent-driven-development` - CI/CD와 AI를 연동해 PR 생성 시 자동 코드 리뷰를 수행한다. - 스타일 위반 탐지 - 잠재적 버그 확인 - 보안 취약점 점검 - 사람 리뷰어는 반복적인 지적보다 복잡한 비즈니스 로직과 정책 판단에 집중한다. - 측정 가능한 KPI: - 사람이 직접 남기는 반복 리뷰 코멘트 수 - 테스트 커버리지 변화 - 배포 안정성 및 테스트 통과율 - 기대 효과: - 팀 전체의 AI 활용 수준 상향 평준화 - 리뷰어의 인지 부하 감소 - 코드 품질과 컨벤션의 일관성 확보 ## 3단계: AI-Development — 명세 기반 개발 자동화 사람이 작성한 스펙이 AI를 통해 구현 계획, 테스트 계획, 코드, PR로 이어지는 자동화 파이프라인을 구축한다. - 전체 흐름은 다음과 같다. 1. 사람이 요구사항과 범위, 엣지 케이스, 검증 기준을 스펙으로 정의 2. AI가 구현 계획과 테스트 계획 작성 3. AI 서브 에이전트가 계획에 따라 작업을 순차적으로 수행 4. 코드 리뷰 후 PR 생성 및 머지 - 세 개의 Human Gate를 둔다. - **Human Gate 1:** 스펙 검토 및 승인 - **Human Gate 2:** 구현 계획과 테스트 계획 검토 및 승인 - **Human Gate 3:** 최종 코드 검토 및 승인 - AI가 프로젝트에 맞는 코드를 만들 수 있도록 도메인 지식을 구조화한다. - 아키텍처 원칙 - 비즈니스 로직의 예외와 특이사항 - 시스템 구성도 - 기존 스펙 및 기술 문서 - 지식은 전용 디렉터리, AI 커스텀 스킬, RAG 시스템 등을 통해 AI가 필요할 때 조회하도록 구성한다. - `/specs` 같은 디렉터리에 새 스펙 파일이 추가되면 CI가 이를 감지해 다음 단계를 실행하도록 이벤트 트리거를 설정한다. - CI 내부에 Approval Step을 배치해 사람의 승인 없이는 AI가 다음 단계로 진행하지 못하게 한다. - 초기에는 핵심 비즈니스 로직보다 테스트 코드나 보일러플레이트처럼 위험도가 낮은 영역부터 자동화를 적용하고, 신뢰가 쌓이면 AI의 담당 범위를 확대한다. ## 단계적 도입이 필요한 이유 - AI 활용 효과는 팀의 문서화 수준, 테스트 품질, 도메인 복잡도에 크게 좌우된다. - 처음부터 모든 구현을 AI에 맡기면 프로젝트 맥락을 이해하지 못한 코드가 생성될 수 있다. - 낮은 위험도의 테스트와 반복 코드부터 시작하면 품질을 검증하면서 팀의 신뢰를 확보할 수 있다. - 각 단계는 독립적으로도 효과가 있으므로 모든 단계를 한 번에 완료할 필요는 없다. 보안 기반을 먼저 확보한 뒤 프로젝트 규칙과 지식을 문서화하고, 자동 리뷰와 테스트 생성부터 시작하는 접근이 현실적이다. 이후 명확한 스펙과 사람의 승인 게이트를 중심으로 코드 생성 범위를 점진적으로 넓히는 것이 안전한 AX 전략이다.