AI에게 ‘앱 만들어줘’ 대신 명세를 건네야 하는 이유

핵심 요약 (TL;DR)

AI에게 ‘예약 서비스 앱을 만들어 주세요’라고 말하면 첫 화면은 빠르게 나옵니다. 하지만 다음 날 예약 규칙을 바꾸고, 일주일 뒤 관리자 화면을 붙일 때부터 처음의 대화는 힘을 잃습니다. 최근 공개된 NAEOS는 명세를 한 번 적고, 그 명세를 바탕으로 생성·검증·변경을 연결하려는 오픈소스 엔지니어링 플랫폼입니다. 거대한 플랫폼을 당장 쓰자는 이야기가 아닙니다. 바이브코딩의 품질도 결국 프롬프트의 길이가 아니라, 바뀌지 않는 요구사항의 선명함에서 출발한다는 사례입니다.

명세는 기획서와 무엇이 다를까요?

기획서는 아이디어를 공유하는 데 좋습니다. 명세는 구현과 검증에 쓰기 좋게 약속을 고정합니다. 누가 쓰는지, 사용자가 어떤 순서로 행동하는지, 성공과 실패 때 어떤 화면이 보여야 하는지까지 적습니다. NAEOS의 공개 문서는 명세를 내부 모델과 실행 계획, 생성물, 검증 결과에 계속 연결하겠다는 방향을 설명합니다. 즉 앱을 한 번 생성하고 끝내는 것이 아니라, 이후 변경도 같은 기준으로 관리하려는 접근입니다.

비개발자 MVP에서는 한 페이지짜리 명세면 충분할 때가 많습니다. 예를 들어 예약 폼이라면 사용자 유형, 입력 항목, 제출 후 상태, 관리자에게 전달될 정보, 중복 예약 처리, 확인 방법을 적습니다. ‘예쁘게’ 대신 ‘모바일에서 날짜·시간·연락처를 입력하고 제출하면 완료 문구가 보인다’처럼 관찰 가능한 문장으로 바꾸는 것이 핵심입니다.

바이브코딩 명세에는 무엇을 반드시 넣어야 할까요?

첫째, 이번 주에 만들 단 하나의 사용자 흐름을 적습니다. 둘째, 저장하거나 외부로 보내는 정보를 적고, 개인정보나 결제 정보라면 범위를 더 줄입니다. 셋째, 정상·빈 상태·오류 상태를 나란히 정의합니다. 넷째, 이번 작업에서 하지 않을 일도 명시합니다. 마지막 항목은 에이전트가 선의를 앞세워 범위를 넓히는 일을 막아 줍니다.

그 다음에 AI에게 ‘이 명세에서 빠진 결정과 모호한 문장을 먼저 질문으로 정리해 주세요’라고 요청해 보세요. 바로 코드를 쓰라고 하는 것보다 훨씬 빠르게 위험을 발견할 수 있습니다. 구현을 맡길 때는 명세의 어떤 항목을 반영했는지, 어떤 항목은 아직 검증하지 못했는지 함께 보고하게 합니다.

명세를 고치면 이전 작업이 무의미해지지 않을까요?

좋은 명세는 고정된 계약서가 아니라 변경 이력을 남기는 기준입니다. ‘관리자는 예약을 취소할 수 없다’에서 ‘관리자는 24시간 전까지만 취소할 수 있다’로 바뀌었다면, 바뀐 문장과 영향을 받는 화면을 함께 기록하세요. 그러면 에이전트에게도 전체를 다시 만들지 말고 영향 범위만 확인해 달라고 요청할 수 있습니다.

바이브코딩은 빠른 생성의 기술이기도 하지만, 빠른 수정의 기술이기도 합니다. 처음의 한 장을 잘 쓰면 다음 프롬프트마다 설명을 반복하는 시간을 줄이고, 결과를 승인할 기준도 손에 남습니다.

FAQ: 요구사항이 자주 바뀌면 명세를 쓰는 의미가 있나요?

있습니다. 바뀐 사실과 이유를 남기면 현재 기준이 무엇인지 잃지 않습니다. 문서가 없을 때는 과거 대화와 코드가 서로 다른 답을 내놓습니다.

FAQ: 노션 문서로 시작해도 될까요?

괜찮습니다. 도구보다 문장이 중요합니다. 다만 구현 요청에 붙여 넣을 수 있게 짧고, 확인 가능한 조건으로 작성하세요.

출처: https://github.com/NAEOS-foundation/naeos
Hacker News 게시: https://news.ycombinator.com/item?id=49364661
관찰 시점: 2026-08-20 KST