바이브 코딩 다음 단계: 명세 기반 AI 개발을 시작하는 방법

명세는 AI와 사람이 함께 사용할 완료 기준입니다

GitHub의 Spec Kit는 요구사항을 명세, 기술 계획과 실행 작업으로 이어 가는 접근을 제공합니다. 여기서 실무에 가져올 핵심은 문서를 많이 만드는 일이 아니라 구현 전에 무엇을 검수할지 정하는 순서입니다. 자연어로 시제품을 만들었다면 운영에 필요한 조건을 하나씩 명세로 옮겨 보세요.

예약 서비스를 예로 들면 '예약 기능'만으로는 부족합니다. 같은 시간대에 두 사람이 신청하면 누구에게 자리를 배정하는지, 취소 마감 이후에는 어떤 안내를 하는지, 관리자가 시간을 바꾸면 기존 예약에 어떻게 반영하는지가 필요합니다. 화면이 그럴듯해도 이 조건이 비어 있으면 구현자가 매번 다른 판단을 하게 됩니다.

세 가지 문서가 서로 다른 질문에 답하게 합니다

추상적인 표현을 관찰 가능한 결과로 바꿉니다

'빠르게 조회한다'는 문장에는 데이터 규모, 동시 접속 조건과 응답 목표를 붙이세요. '안전하게 처리한다'면 어떤 역할이 무엇을 조회하거나 바꿀 수 있는지 적습니다. 합의하지 않은 성능 수치를 AI가 임의로 채우게 하기보다 미정 항목과 결정 담당자를 표시하는 편이 이후 변경을 관리하기 쉽습니다.

검수 예시는 실제 업무 담당자가 읽고 판단할 수 있어야 합니다. '취소 버튼 클릭 시 성공 메시지가 보인다'에 그치지 않고 예약 상태, 잔여석, 알림 이력이 함께 바뀌는지 확인하세요. 하나의 사용자 동작이 여러 시스템에 미치는 영향을 명세에 남기면 누락된 연동도 발견할 수 있습니다.

명세도 코드처럼 변경 이력을 관리합니다

정책이 바뀐 PR에는 관련 명세와 테스트를 함께 수정합니다. 오래된 문서와 새 코드가 공존하면 에이전트는 어느 쪽을 기준으로 삼을지 알기 어렵습니다. 단순한 오탈자 수정까지 큰 절차를 적용할 필요는 없지만, 데이터 구조·권한·업무 정책이 바뀌는 작업에는 변경 이유를 남기세요.

착수 전에 확인할 질문

• 사용자 역할과 목표를 한 문장으로 설명할 수 있는가
• 정상 처리 외에 동시 요청·실패·취소 조건이 있는가
• 미정 사항을 사실처럼 채우지 않고 표시했는가
• 각 작업의 결과가 명세의 어떤 항목을 충족하는지 알 수 있는가
• 완료 판정에 필요한 데이터와 검수 담당자가 준비됐는가