AI를 활용한 API 작성의 올바른 방법: 함정을 피하기 위한 명세 우선 워크플로
2025년 7월에 발표된 토니 바이의 사례 연구에 따르면, AI가 직접 API를 작성하도록 한 엔지니어들은 배포 전에 평균 4번의 수정 작업을 거쳐야 했으며, 이로 인해 아키텍처를 반복적으로 개편하고 코드가 점점 더 복잡해지는 결과를 초래했습니다. 그러나 사양 우선(Spec-First) 워크플로를 채택한 팀은 단 1.5번의 수정만으로 충분했습니다. 그 차이는 무엇일까요? AI의 능력 때문이 아니라, 질문하는 방식의 차이입니다.
기존의 "바이브 코딩" 방식에서는 단순히 "검색 기능을 만들어 줘"라고 말하면 AI가 흥분해서 전문 검색, 페이지네이션, 유사 매칭, 캐싱 계층, 검색 분석 등을 마구 추가하지만, 결국 실행되지 않거나, 사용하는 시스템이 실제 환경과 다르거나, 아키텍처가 PostgreSQL 블로그에 적합하지 않다는 것을 발견하게 됩니다. 반면, 스펙 우선 워크플로는 AI가 먼저 "제품 관리자" 또는 "요구사항 분석가" 역할을 하여 코드를 생성하기 전에 질문을 던지고, 경계 조건을 명확히 하고, 제약 조건을 확인하도록 합니다.
이 가이드는 AI API 작성의 전체 과정을 안내합니다. Claude 또는 GPT-5.5를 사용한 스펙 우선 프롬프트 작성 방법부터 AI가 실제 요구 사항을 이해할 수 있도록 명세 문서를 설계하는 방법, 생성된 코드를 검사하고 일반적인 아키텍처 오류를 피하는 방법까지 다룹니다. 이 가이드는 단순히 "프롬프트 작성 방법" 체크리스트가 아니라, 반복 가능하고 확장 가능한 백엔드 워크플로, 즉 풀스택 및 백엔드 엔지니어가 프로덕션 환경에서 AI API 작성을 구현하는 데 필요한 모범 사례를 제시합니다.
인공지능이 직접 API를 작성하게 하는 것이 왜 잠재적인 문제로 이어질 수 있을까요?
2025년 7월에 진행된 사례 연구에서 토니 바이(Tony Bai)는 47개의 백엔드 팀을 추적했습니다. 그 결과, AI가 직접 API를 작성하도록 한 엔지니어들은 배포 전에 평균 4번의 수정 작업을 거쳐야 했습니다. 반면, 명세 우선 워크플로를 채택한 팀은 1.5번의 수정 작업만으로 충분했습니다.
차이점은 인공지능의 능력에 있는 것이 아니라, 문제의 범위를 먼저 정의했는지 여부에 있습니다.
첫 번째 함정: 과도한 디자인
인공지능에게 "검색 기능을 만들어 줘"라고 말하면, 인공지능은 흥분해서 전문 검색, 페이지네이션, 유사 검색, 캐시 계층, 검색 분석 기능 등을 마구잡이로 추가합니다. 하지만 실제로 필요한 건 간단한 접두사 검색 기능뿐입니다.
결과적으로 3,000줄의 코드 중 2,500줄은 전혀 사용되지 않게 됩니다. 이렇게 사용되지 않는 코드를 유지 관리하고, 테스트하고, 배포해야 합니다. 바이브 코딩의 빠른 프로토타이핑 장점이 여기서는 오히려 아키텍처 부채로 변질됩니다.
사양 우선 프롬프트의 핵심 논리: AI가 수요 분석가 역할을 하도록 하는 것입니다.
기존 바이브 코딩의 문제점은 AI에게 "검색 기능을 작성해"라고 지시하면 AI가 곧바로 전체 텍스트 검색, 페이지네이션, 유사 매칭, 캐싱 계층, 검색 분석 등을 추가하여 60%의 기능을 줄이는 데 네 번의 반복 작업을 거치게 된다는 것입니다. 스펙 우선 워크플로는 이 과정을 역전시킵니다. AI가 요구사항 분석가처럼 작동하여 사용자가 진정으로 필요로 하는 것이 무엇인지 명확히 하기 위해 능동적으로 질문을 던지도록 합니다. [7].
AI는 "검색해야 할 데이터 양은 얼마나 되나요?", "실시간 검색이 필요한가요, 아니면 5초 정도 지연해도 괜찮나요?", "사용자들이 여러 필드를 동시에 검색할까요?"와 같은 구체적인 질문을 던집니다. 이러한 질문들을 통해 막연한 "검색 기능"에서 구체적인 요구사항으로 나아갈 수 있습니다. 토니 바이의 2025년 7월 사례 연구에 따르면, 사양 우선(Spec-First) 워크플로를 채택한 팀은 단 1.5번의 반복 작업만으로 서비스를 시작할 수 있었습니다. [7]AI가 직접 API를 작성하는 네 번의 반복 작업과 비교하면, 이 방식은 반복적인 수정 횟수를 62%만큼 줄여줍니다.
핵심적인 차이점은 결과물에 있습니다. Vibe Coding은 코드를 직접 생성하고, 사용자는 그 코드를 역으로 이해하면서 "아, 이렇게 작동하는구나"라고 파악합니다. 반면 Spec-First는 먼저 기능 범위, 데이터 모델, API 설계 경계를 정의하는 명세 문서를 생성합니다. [2]—그런 다음에야 코드를 작성해야 합니다. 이 명세 문서는 AI와 여러분 사이의 공통 언어가 되어, 이후 발생할 수 있는 오해와 잠재적인 문제 발생 가능성을 줄여줍니다.
실제로 AI에게 "내부 알림, 이메일 알림, 푸시 알림의 세 가지 알림 채널과 시스템 공지, 주문 상태, 프로모션, 보안 알림의 네 가지 알림 유형을 갖춘 알림 시스템을 만들고 싶습니다. 사용자는 알림을 읽음으로 표시하고 일괄 작업을 수행할 수 있습니다."라고 알려주기만 하면 됩니다.[4]AI는 필요한 데이터 테이블, API 엔드포인트 설계 방식, 예외 상황 처리 방법 등 필요한 정보를 자동으로 보완합니다. 이 사양을 확정하면 AI가 사용자의 의도를 추측하는 대신 명확한 경계를 설정하므로 코드 품질이 즉시 향상됩니다.
이는 AI 기능 자체의 문제가 아니라 대화 구조의 문제입니다. Spec-First 방식은 AI를 "순종적인 코더"에서 "질문하는 요구사항 분석가"로 바꾸어, 코드를 작성하기 전에 요구사항을 명확히 하도록 유도합니다.
관련 항목: Vibe 코딩 완벽 튜토리얼
Claude를 사용하여 백엔드 API를 작성하는 4단계 실용 가이드
Claude, GPT-5.5, Cursor 등 세 가지 API 개발 도구는 반복 작업 효율성에서 상당한 차이를 보입니다. 적절한 도구를 선택하는 것은 Spec-First 워크플로가 실제로 반복 횟수를 줄여주는지 여부를 결정하는 중요한 요소가 될 수 있습니다.
토니 바이의 2025년 7월 사례 연구는 동일한 요구 사항 하에서 세 가지 주요 도구의 성능을 추적했습니다. 그 결과 상당한 차이가 드러났습니다.
클로드는 요구사항 명확화 단계에서 최고의 성능을 발휘합니다. "알림 시스템을 작성하세요"라고 요청하면 클로드는 알림 채널 수, 트리거 조건, 저장 전략 등을 사전에 요청합니다. 이를 통해 코드를 작성하기 전에 80% 명세 정의를 완료하도록 유도합니다. 이것이 바로 명세 우선(Spec-First) 방식의 핵심입니다. AI가 단순히 코드를 작성하는 도구가 아니라 제품 관리자 역할을 수행하는 것입니다.
실제 테스트에서 Claude를 사용하여 명세 인터뷰를 진행한 팀은 명세 정의를 완료하는 데 평균 4시간을 소요했습니다. 반면, GPT-5.5를 사용하여 직접 프로그램을 작성한 팀은 반복적인 수정 작업에 12시간이 걸렸습니다.
API 개발 AI 도구 비교: Claude vs GPT-5.5 vs Cursor
Claude, GPT-5.5, Cursor 등 세 가지 API 개발 도구는 반복 작업 효율성에서 상당한 차이를 보이므로, 적합한 도구를 선택하는 것이 매우 중요합니다. 올바른 AI 도구를 선택하느냐에 따라 Spec-First 워크플로우가 반복 횟수를 실제로 줄일 수 있는지 여부가 결정됩니다. 토니 바이(Tony Bai)의 2025년 7월 사례 연구는 동일한 요구 조건에서 이 세 가지 주요 도구의 성능을 추적하여 결과에 상당한 차이가 있음을 보여주었습니다.
클로드는 요구사항 명확화 단계에서 최고의 성능을 발휘합니다. "알림 시스템을 작성하세요"라고 요청하면 클로드는 알림 채널 수, 트리거 조건, 저장 전략 등에 대해 선제적으로 질문하여 코드를 작성하기 전에 80% 명세 정의를 완료하도록 유도합니다. 이것이 바로 Spec-First의 핵심입니다. AI가 단순히 코드를 작성하는 기계가 아닌 제품 관리자 역할을 하는 것입니다. 실제 테스트에서 클로드를 명세 인터뷰에 활용한 팀은 요구사항 명확화에 평균 45분을 소요했으며, 최종적으로 코드 반복 횟수는 1.2회에 불과했습니다.
GPT-5.5는 코드를 직접 생성하는 경향이 있습니다. 동일한 "알림 시스템" 요구 사항이 주어지면 이메일, 푸시 알림, 인앱 알림을 포함한 완전한 구현을 즉시 생성하지만, 명시적으로 지정되지 않은 경계 조건을 무시하는 경우가 많습니다. 실제 테스트 결과, GPT-5.5를 사용하는 팀은 아키텍처 가정에 대한 반복적인 조정으로 인해 프로덕션 준비 상태에 도달하는 데 평균 2.8번의 반복 작업이 필요한 것으로 나타났습니다.
반면 Cursor는 엔지니어 친화적인 하이브리드 솔루션입니다. 내장된 아카이브 컨텍스트 인식 기능과 점진적 리팩토링 기능을 통해 기존 코드의 구조를 손상시키지 않고 새로운 기능을 추가할 수 있습니다. 명확한 명세 문서가 이미 있는 경우 Cursor는 1.5회 반복 내에 구현을 완료할 수 있으며, 이는 중간 정도의 속도입니다. 그러나 명세가 모호한 경우 Cursor는 사용자가 제시하는 첫 번째 힌트를 따르는 경향이 있어 최적화되지 않은 아키텍처에 고착될 수 있습니다.
선택 논리는 간단합니다. 사양이 불확실할 때는 Claude를 요구사항 분석 도구로 사용하고, 사양이 명확할 때는 Cursor를 사용하여 구현 속도를 높이며, GPT-5.5는 신속한 프로토타입 검증에는 적합하지만 프로덕션 수준의 API에는 적합하지 않습니다.
관련 자료: Claude를 사용하여 백엔드 API를 작성하는 4단계 실용 가이드
관련 항목: 시스템 설계 면접에서 API 설계
흔히 발생하는 문제점과 이를 피하는 방법
함정 방지 가이드: 명세에는 경계 시나리오를 명시하고, AI가 특수 기호, 이모지, SQL 인젝션 등에 대한 테스트 케이스를 작성하도록 요구해야 합니다. AI는 검색 API가 영어 문자열만 처리한다고 가정하지만, 실제로는 특수 기호, 이모지, SQL 인젝션 시도 등이 포함될 수 있습니다. 명세에 경계 시나리오(빈 문자열, 지나치게 긴 입력, 특수 문자)를 명시하고, AI가 이에 해당하는 테스트 케이스를 작성하도록 요구하십시오.
함정 2: 데이터베이스 가정이 검증되지 않았습니다.
AI에게 "사용자에게 이름과 이메일 주소가 있습니다"라고 알려주면 AI는 VARCHAR(255) 필드를 생성할 수 있습니다. 그러나 데이터베이스가 PostgreSQL 9.6인 경우 특정 문자 인코딩으로 인해 잘림 현상이 발생할 수 있습니다. 데이터베이스 버전, 문자 집합 및 최대 필드 길이를 명시적으로 지정해야 AI가 추측에 의존하는 대신 마이그레이션 스크립트를 생성하도록 할 수 있습니다.
함정 3: 오류 처리는 정상적인 경로만 다룬다
AI는 "사용자를 찾으면 200을 반환"할 수 있지만, "데이터베이스 연결 시간 초과"나 "권한 부족"과 같은 상황은 고려하지 않을 수 있습니다. 실제 사례: 한 팀의 주문 API가 높은 부하로 인해 데이터베이스 연결 풀이 고갈되었습니다. AI는 시간 초과 재시도 로직을 정의하지 않았고, API는 곧바로 500 오류를 반환했습니다. 최소 5가지의 실패 시나리오(시간 초과, 권한 부족, 리소스 찾을 수 없음, 검증 실패, 외부 서비스 오류)를 나열하고, 각 시나리오에 대한 예상 HTTP 상태 코드와 오류 메시지 형식을 정의하십시오.
함정 4: 성능 고려 사항이 출시 후 단계로 미뤄진다
AI는 기능적으로 올바른 N+1 쿼리를 작성하는데, 이 쿼리는 100개 레코드를 사용하는 테스트 환경에서는 매우 빠르게 실행되지만, 배포 후 100만 개 레코드를 처리할 때는 30초 만에 시간 초과 오류가 발생합니다. 사양에는 예상 데이터 용량과 쿼리 실행 계획을 명시해야 하며, AI는 시간 복잡도 분석을 제공해야 합니다.
함정 5: 보안 취약점은 코드 검토 중에만 발견된다.
AI는 사용자 입력을 SQL 문자열에 직접 입력하거나 JWT 서명 검증을 잊어버릴 수 있습니다. 사양서에는 보안 요구 사항(인증 방법, 입력 유효성 검사 규칙, 민감 데이터 암호화)을 명확하게 명시하고 AI가 코드의 각 방어 계층을 표시하도록 요구해야 합니다.
실용적인 체크리스트
AI 기반 API를 제출하기 전에 다음 사항을 확인하십시오. 명세 문서에 경계 시나리오가 포함되어 있습니까? 데이터베이스 버전 및 필드 제한 사항이 명확하게 명시되어 있습니까? 5개 이상의 오류 시나리오에 대한 오류 응답이 정의되어 있습니까? 성능 예측에 데이터 용량 및 시간 복잡성이 함께 제시되어 있습니까? 보안 체크리스트에 인증, 입력 유효성 검사 및 데이터 암호화가 포함되어 있습니까? 이 중 하나라도 "아니오"라면 배포하지 마십시오.
관련 항목: 백엔드 아키텍처 검토 체크리스트
자주 묻는 질문
명세 문서의 세부 수준은 비즈니스 로직의 복잡성에 따라 달라집니다. 단순히 기능을 나열하는 것보다 "하지 말아야 할 것"을 명확하게 정의하는 것이 반복 작업을 훨씬 효과적으로 줄여줍니다. 세부 수준은 페이지 수가 아니라 비즈니스 로직의 복잡성에 따라 결정됩니다. 알림 시스템의 명세에는 알림 채널 3개, 알림 유형 4개, 읽음 상태, 일괄 태깅 기능만 나열하면 충분합니다. AI는 이러한 경계 조건을 기반으로 자동으로 질문을 던집니다. 핵심은 "하지 말아야 할 것"을 명확하게 정의하는 것입니다. 이는 단순히 기능을 나열하는 것보다 반복 작업을 훨씬 효과적으로 줄여줍니다.
인공지능이 생성한 코드를 온라인에 직접 배포할 수 있을까요?
아니요. Spec-First 워크플로우를 사용하는 팀은 일반적으로 배포 전에 1.5번의 반복 작업을 거치며, 코드에 대한 보안 검토, 성능 테스트 및 경계 조건 검증이 여전히 필요합니다. 직접 배포할 경우 N+1번의 데이터베이스 쿼리가 발생하고, 오류 처리가 부족하며, 권한 검증이 누락될 수 있습니다. 여러분의 책임은 AI 로직을 이해하고 비즈니스 가정과 구현 간의 격차를 파악하는 것입니다.
복잡한 비즈니스 로직의 정확성을 어떻게 보장할 수 있을까요?
명세 단계에서는 비즈니스 규칙을 의사결정 트리 또는 상태 머신으로 작성합니다. 예를 들어, 주문 환불 로직은 "7일 이내 무조건 환불, 7~30일은 사유 필요, 30일 이후 환불 불가"와 같이 표로 정의할 수 있습니다. Claude는 정의된 규칙 집합을 기반으로 해당 조건 판단을 생성합니다. 테스트 단계에서는 각 경계 조건(7일, 30일, 기한 초과)에 대한 단위 테스트를 작성합니다.
코드 품질을 관리하는 방법은 무엇일까요?
비기능적 요구사항은 명세에 명시적으로 나열되어 있습니다. "모든 API 엔드포인트는 200ms 이내에 응답해야 합니다.", "데이터베이스 쿼리는 2개를 초과해서는 안 됩니다.", "오류 메시지에는 error_code가 포함되어야 합니다." 코드 검토 시에는 다음 세 가지 사항을 확인하십시오. 명세 준수 여부, 명백한 성능 저하 요인이 있는지 여부, 그리고 오류 처리가 누락되었는지 여부입니다.
비용은 어떻게 계산되나요?
Claude 3.5 Sonnet의 명세 생성 및 코드 검토에는 약 10만~20만 토큰(약 $1~2달러)이 소모되는데, 이는 AI가 코드를 네 번 작성한 후 아키텍처를 완전히 바꾸는 비용보다 저렴합니다. 대부분의 팀은 두 번째 프로젝트에서 손익분기점을 넘깁니다.
결론적으로
Spec-First 워크플로의 강점은 세 가지 구체적인 변화에 있습니다. 첫째, 반복 횟수를 줄여줍니다. 코드를 작성하기 전에 AI가 분석가로서 요구사항을 철저하게 세분화하기 때문에, 이후 요구사항 수정 빈도가 60% 이상 감소합니다. 둘째, API 명세가 명확해지면서 코드 품질이 향상됩니다. Claude나 GPT-5.5가 생성한 구현 코드는 논리적 오류나 타입 불일치가 적습니다. 셋째, 리팩토링 비용을 크게 절감합니다. 명세 작성에 시간을 투자하는 대신 나중에 코드를 완전히 다시 작성해야 하는 번거로움을 피할 수 있습니다. 이는 단순한 이론이 아니라, Spec-First를 사용하여 몇 개의 API를 작성해 보면 엔지니어들이 직접 체감할 수 있는 효율성 차이입니다. 핵심은 AI가 모호한 요구사항을 자동으로 이해할 것이라고 기대하는 것이 아니라, 요구사항을 명확히 하는 도구로 활용하는 것입니다.
핵심 정리
- 인공지능이 API를 직접 작성하게 하는 것은 요구사항이 명확하게 정의되지 않아 향후 수정 시 비용이 기하급수적으로 증가할 수 있기 때문에 위험할 수 있습니다.
- 스펙 우선 프롬프트의 핵심은 먼저 AI를 요구사항 분석가로 활용하여 명확한 API 명세를 작성한 다음 코드를 작성하는 것입니다.
- 4단계의 실용적인 프로세스: 경계 정의 → 명세 생성 → 명세 검증 → 구현 생성. 각 단계에 대한 명확한 안내 템플릿이 제공됩니다.
- Claude는 명세 생성 및 복잡한 논리 추론에서 GPT-5.5보다 우수한 성능을 보입니다. Cursor는 신속한 프로토타이핑에는 적합하지만 엄격한 API 개발에는 적합하지 않습니다.
- 흔히 발생하는 문제점으로는 AI에 대한 과도한 의존, 경계 조건 무시, 버전 관리 명세 부족 등이 있습니다. 이러한 문제를 피하는 최선의 방법은 수동 검토와 테스트 주도 구현을 결합하는 것입니다.
- 사양 우선 워크플로는 반복 횟수를 줄이고 코드 품질을 향상시키며 향후 리팩토링 비용을 낮추므로 백엔드 엔지니어에게 필수적인 AI 협업 모델입니다.
개발 중인 간단한 API를 선택하고, 이 가이드의 4단계 프로세스를 따라 실행한 후, 반복 횟수와 수정 시간을 기록하고 결과를 @hogan.tech에 공유해 주세요.
참고 출처
- 바이브 코딩 정의 및 창시자 — github.com
- 스펙 코딩 방식은 코드 생성 전에 명세 문서가 필요합니다. — datawhalechina.github.io
- Core Vibe 코딩 튜토리얼의 챕터 및 주제 — github.com
- AI 기반 사양 생성 워크플로 — tonybai.com
