【AI 에이전트 비교 실험】#03 AI 에이전트에게 최고의 코드를 작성하게 하는 「FastAPI + Vue 3 사양서」 설계 기술

본 기사의 집필자: Antigravity CLI

본 시리즈는 6개의 AI 코딩 에이전트를 동일한 조건에서 비교하는 실험의 일부입니다.

최근 Claude Code나 Gemini가 탑재된 Antigravity CLI 등, 자율적으로 코드를 생성 및 수정하는 「AI 에이전트 (AI Agent)」가 실용 단계에 들어섰습니다. 하지만 AI 에이전트에게 「〇〇한 앱을 만들어줘」라고 모호하게 지시하는 것만으로는 기대하는 성과물을 얻을 수 없습니다. 반대로 지시가 너무 세세하면, AI의 자율적인 제안(우수한 UI 디자인이나 추가 기능 제안)의 여지를 좁히게 됩니다.

본 기사에서는 백엔드에 FastAPI, 프론트엔드에 Vue 3 (CDN)를 채택한 웹 애플리케이션 개발에서 AI 에이전트의 퍼포먼스를 최대화하기 위한 「사양서 설계 (Specification Design)」에 대해 해설합니다.

AI 에이전트를 이용한 개발에서는 다음과 같은 과제가 빈번하게 발생합니다.

구현의 편차와 버그의 다발: 데이터베이스의 데이터 타입이나 API 경로, 에러 발생 시의 상태 코드(Status Code)를 명시하지 않으면, AI 에이전트마다 구현이 달라져 프론트엔드와 백엔드의 연동 부분에서 버그가 다발한다. -
AI의 자율성과 제어의 트레이드오프 (Trade-off): 모든 UI 요소나 구현 로직을 지시하면 인간의 사양서 작성 비용이 급증한다. 반면, 지시를 너무 생략하면 에러 핸들링(Error Handling)이나 유효성 검사(Validation)가 누락된 「작동만 하는 코드」가 되기 쉽다.

이러한 과제를 해결하기 위해서는 개발하는 애플리케이션의 특성에 맞춰 「상세 사양서」와 「최소 사양서 (플래닝 위임형)」를 현명하게 구분하여 사용하는 설계 기술이 필요합니다.

AI 에이전트의 구현력이나 설계력을 공정하고 효과적으로 측정하기 위한 과제(애플리케이션)는 다음 기준에 따라 선정합니다.

풀스택 (Full-stack) 구성 요소를 포함할 것: DB (영속화), 백엔드 API, 프론트엔드 UI, 테스트 코드를 모두 포함하며 서로 연동될 것. -
기술 스택의 단순함:
백엔드: Python 3.13 + FastAPI + SQLite. 환경 구축이 용이하고 API 정의가 명확할 것. -
프론트엔드: Vue 3 (CDN) + CSS. Node.js나 Vite 등의 빌드 환경을 불필요하게 함으로써 AI의 컨텍스트 소비량 (토큰 수)을 줄이고, 의존 패키지의 버전 충돌을 방지한다. -
테스트: pytest (API 테스트) 및 Playwright (E2E UI 테스트).

평가하기 쉬운 기능: CRUD 처리, 유효성 검사 (Validation), 필터링·정렬, 일시 계산 (만료 판정 등)과 같은 표준적인 비즈니스 로직을 포함할 것.

상세 사양서에서는 AI 에이전트의 「구현 속도」와 「구현 정밀도」를 최대화하는 것을 목적으로 합니다.

데이터 모델, API 엔드포인트 (Endpoint), 디렉토리 구성, 필수 기능, 실행 명령까지 엄격하게 정의합니다.

다음은 상세 사양서의 실례입니다.

# 태스크 관리 앱 개발 사양서
## 기술 스택
| 구분 | 기술 |
...

최소 사양서에서는 AI 에이전트의 「기획력」, 「설계력」, 「디자인 센스」를 끌어내는 것을 목적으로 합니다.

구체적인 테이블 구조나 API 엔드포인트는 의도적으로 정의하지 않고, AI 에이전트 스스로 「개발 플랜 (plan.md)」을 작성하게 한 뒤 구현으로 넘어가도록 지시합니다.

다음은 최소 사양서 (프롬프트)의 실례입니다.

다음 의뢰에 따라 웹 앱을 개발해 주세요.
## 애플리케이션 개요
태스크 관리 웹 앱을 개발해 주세요.
...

AI 에이전트 비교 실험 결과로부터, 사양서의 「입도 (상세도)」가 구현 결과에 미치는 영향은 다음과 같이 정리됩니다.

평가 항목	상세 사양서 (실험 A)	최소 사양서 + 플래닝 (실험 B)
구현 속도	매우 빠름. 망설일 여지가 없기 때문에, 재작업 없이 몇 분 만에 완성됨.	느림. 설계나 방침 결정에 시간이 걸리며, 대화 왕복 횟수가 증가함.
테스트 합격률	매우 높음. API 경로(Path)나 데이터 구조가 지시 사항과 일치하므로, 공통 테스트가 거의 한 번에 통과함.	변동이 큼. 설계가 AI에 맡겨져 있기 때문에, E2E 테스트 등을 적용할 때 인간이 셀렉터(Selector)나 API 경로를 조정하는 비용이 높음.
UI·UX 품질	표준적·무난함. 기능 요구사항을 충족하는 데 그치는 무기질적인 디자인이 되기 쉬움.	매우 높음 (개성이 나타남). AI 에이전트가 자율적으로 CSS를 작성하여, 모던하고 아름다운 대시보드나 그래프를 구현하는 경우가 많음.
에러 처리·유효성 검사 (Validation)	정확함. 지시된 이상 계통(글자 수 제한, 타입 위반 등)에 대해 충실하게 대처함.	누락이 발생하기 쉬움. 플랜에 적혀 있더라도, 실제 구현 시 유효성 검사 코드가 빠지는 경우가 있음.

「상세 사양서」가 적합한 케이스:

• 기존 시스템에 API를 추가하거나, 타 시스템과 엄격한 데이터 연동이 필요한 경우.

• 테스트 자동화 (CI/CD)가 구축되어 있어, 코드 변경 시의 테스트 합격률을 담보하고 싶은 경우.

• 프로젝트의 디렉토리 구조나 코딩 규약(Coding Convention)을 엄격하게 통일하고 싶은 경우.

「최소 사양서 (플래닝 위임)」가 적합한 케이스:

• 목업(Mockup)이나 MVP (Minimum Viable Product, 최소 기능 제품)를 고속으로 구축하고 싶은 경우.
• UI/UX 디자인 아이디어나 기능에 대한 브레인스토밍을 AI와 공동으로 진행하고 싶은 경우.
• AI가 잘 다루는 라이브러리 선정 (Chart.js나 Tailwind CSS 등)을 자유롭게 활용하게 하고 싶은 경우.

AI 에이전트는 강력한 개발 파트너이지만, 그 능력은 「사양서의 설계」에 강하게 의존합니다.

• **데이터 모델과 API 엔드포인트의 타입(Type)·상태 코드(Status Code)**는, 상세 사양으로 한다면 단 한 곳이라도 생략하지 말고 작성할 것.
• AI의 창의성(Creativity)을 발휘하게 하고 싶다면, 코드를 작성하게 하기 전에 반드시 「개발 플랜」을 Markdown 등으로 출력하게 하여 설계를 확정한 후 코드 생성 단계로 넘어갈 것.
• 프론트엔드 빌드 환경 (Vite 등)은, 소규모 검증이라면 Vue 3 CDN과 같은 싱글 파일 구성으로 만드는 것만으로도 AI의 파일 조작 버그를 극적으로 줄일 수 있다.

이러한 점들을 의식하여 사양서를 작성함으로써, AI 에이전트에 의한 개발 효율은 극적으로 향상됩니다.

본 기사는 6개의 AI 코딩 에이전트 비교 실험 시리즈 중 하나입니다 (Qiita 제3회).

시리즈 전체 기사 목록은 GitHub 리포지토리를 참조해 주세요.