AI 바이브 코딩의 신뢰성 높이는 법

Github Spec Kit 4단계 프로세스

Oct 3. 2025

Spec Kit 4단계 프로세스: AI 바이브 코딩의 신뢰성 높이는 법

핵심 요약 (TL;DR)

GitHub이 AI와 함께 개발할 때의 문제점을 해결하기 위한 새로운 오픈소스 툴킷 **"Spec Kit"**을 공개했습니다. 기존 "바이브 코딩" 방식의 한계를 극복하고, 체계적인 명세서 기반 개발로 AI 코딩의 정확성과 신뢰성을 높이는 것이 목표입니다.

AI가 코드 짜는 시대, 그런데 뭔가 이상하다

요즘 AI로 코딩한다는 게 대세잖아? "ChatGPT야, 쇼핑몰 만들어줘" 하면 뚝딱뚝딱 코드가 나온다. 그런데 막상 돌려보면... 어? 안 돌아간다. 아니면 돌아가긴 하는데 뭔가 내가 원한 게 아니다.

이런 경험 있을 거다. 코드는 그럴듯해 보이는데 실제로는 엉망이거나, 일부는 맞는데 정작 핵심은 빠져있거나. 아니면 아예 컴파일도 안 되거나. 심지어 기술 스택도 내가 원한 게 아니고.

이게 바로 "바이브 코딩"의 함정이다. Andrej Karpathy가 만든 용어인데, "느낌으로" 코딩하는 걸 말한다. "대충 이런 느낌으로 만들어줘"라고 하면 AI가 "네, 이런 느낌이죠?" 하면서 코드를 던져준다. 프로토타입 만들 때는 괜찮다. 하지만 진짜 서비스를 만들거나 기존 시스템에 뭔가 추가할 때는? 재앙이다.

문제는 우리가 AI를 잘못 쓰고 있다는 거다. AI를 구글 검색하듯이 쓰고 있었던 거다. 그런데 AI는 검색엔진이 아니다. 오히려 말 그대로 받아들이는 페어 프로그래머에 가깝다. 패턴 인식은 엄청 잘하는데, 마음을 읽지는 못한다. 명확한 지시가 필요하다는 얘기다.

0d9576cf-b3c1-450b-884e-d69c0ccb1be4 - 복사본.png

GitHub의 답: Spec Kit

그래서 GitHub이 뭘 했냐면, "Spec Kit"이라는 걸 만들었다. 오픈소스로 공개했는데, 이게 바로 AI 코딩의 게임체인저가 될 것 같다.

핵심은 간단하다. "코드부터 짜고 나중에 문서 쓰기"가 아니라 "명세서부터 쓰고 나중에 코드 짜기"다. 명세서가 코드 동작의 계약서 역할을 하고, AI 도구들이 사용할 진실의 원천이 된다. 추측할 필요가 없어진다.

예전에는 명세서를 써놓고 그냥 서랍에 처박아뒀다. 하지만 AI 시대에는 명세서가 살아있는 문서가 된다. 명세서가 바뀌면 코드도 바뀌고, 뭔가 이상하면 명세서로 돌아가서 확인한다.

4단계 마법이 시작된다

Spec Kit은 4단계로 작동한다. 각 단계마다 명확한 역할이 있고, 다음 단계로 넘어가기 전에 반드시 검증을 한다. 여기서 핵심은 각 단계가 특정 역할을 하고, 그 단계를 완전히 검증하기 전에는 다음으로 넘어가지 않는다는 거다.

첫 번째, Specify 단계다.

개발자가 높은 수준에서 "뭘 만들고 싶은지, 왜 만드는지" 얘기하면, AI가 상세한 명세서를 만들어준다. 여기서 중요한 건 기술 스택이나 앱 디자인 얘기가 아니라는 거다. 사용자 여정, 경험, 성공이 뭔지에 집중한다. "누가 이걸 쓸 건지, 어떤 문제를 해결해줄 건지, 어떻게 상호작용할 건지, 어떤 결과가 중요한지" 이런 것들. 마치 만들고 싶은 사용자 경험을 지도로 그리는 것 같다. AI가 세부사항을 채워넣고. 중요한 건 이게 살아있는 아티팩트라는 거다. 사용자와 그들의 니즈에 대해 더 알게 되면 계속 진화한다.

두 번째, Plan 단계에서 기술적으로 들어간다.

이제 원하는 기술 스택, 아키텍처, 제약사항을 AI한테 알려주면, AI가 포괄적인 기술 구현 계획을 세워준다. 회사에서 표준으로 정해진 기술들이 있다면 여기서 말하면 되고, 레거시 시스템과 연동해야 한다거나 규제 요구사항이 있다거나 성능 목표가 있다면 이것도 다 여기 들어간다. 여러 가지 계획안을 비교해달라고 할 수도 있다. 내부 문서를 AI가 볼 수 있게 하면, 회사의 아키텍처 패턴과 표준을 계획에 직접 반영할 수도 있다. 결국 AI가 게임을 시작하기 전에 게임의 룰을 이해해야 한다는 거다.

세 번째, Tasks 단계에서 AI가 명세서와 계획을 받아서 실제 작업으로 분해한다.

작고 리뷰 가능한 조각들로 나누는데, 각각이 퍼즐의 특정 부분을 해결한다. 각 작업은 독립적으로 구현하고 테스트할 수 있어야 한다. 이게 중요한 이유는 AI가 자신의 작업을 검증하고 궤도를 유지할 방법을 제공하기 때문이다. 테스트 주도 개발 프로세스를 AI 에이전트를 위해 만든 것 같다. "인증 구축하기" 대신 "이메일 형식을 검증하는 사용자 등록 엔드포인트 만들기" 같은 구체적인 작업들이 나온다.

네 번째, Implement 단계에서 AI가 작업들을 하나씩(또는 병렬로) 처리한다.

여기서 다른 점은 천 줄짜리 코드 덤프를 리뷰하는 게 아니라, 특정 문제를 해결하는 집중된 변경사항들을 리뷰한다는 거다. AI는 뭘 만들어야 하는지 알고 있고(명세서가 알려줬으니까), 어떻게 만들어야 하는지도 안다(계획이 알려줬으니까), 정확히 뭘 해야 하는지도 안다(작업이 알려줬으니까).

중요한 건 개발자의 역할이 단순히 방향을 제시하는 게 아니라는 거다. 검증도 해야 한다. 각 단계에서 반성하고 개선한다. "이 명세서가 정말 내가 만들고 싶은 걸 담고 있나? 이 계획이 현실의 제약사항을 고려했나? AI가 놓친 부분이나 엣지 케이스가 있나?" 프로세스에 명시적인 체크포인트가 있어서 생성된 것들을 비판하고, 빈 곳을 찾고, 진행하기 전에 방향을 수정할 수 있다. AI가 아티팩트를 생성하고, 사람이 그게 맞는지 확인한다.

실제로 써보자

설치는 간단하다. 먼저 specify 명령줄 도구를 설치한다. 프로젝트를 초기화하고 필요한 구조를 설정해준다.

uvx --from git+https://github.com/github/spec-kit.git specify init <PROJECT_NAME>

프로젝트가 초기화되면,

/specify

명령으로 높은 수준의 프롬프트를 제공하면 AI가 전체 명세서를 생성한다. 프로젝트의 "무엇"과 "왜"에 집중하고, 기술적 세부사항은 말하지 않는다.

다음으로

/plan

명령을 써서 AI가 기술적 구현 계획을 만들도록 한다. 여기서 높은 수준의 기술적 방향을 제공하면, AI가 아키텍처와 제약사항을 존중하는 상세한 계획을 생성한다.

마지막으로

/tasks

명령으로 AI가 명세서와 계획을 실행 가능한 작업 목록으로 분해하게 한다. AI는 이 목록을 사용해서 프로젝트 요구사항을 구현한다.

이 구조화된 워크플로가 애매한 프롬프트를 명확한 의도로 바꿔서 AI가 신뢰성 있게 실행할 수 있게 해준다. GitHub Copilot이든 Claude Code든 Gemini CLI든 다 된다.

왜 이 방법이 통할까

이 접근법이 "그냥 AI한테 물어보기"가 실패하는 곳에서 성공하는 이유는 언어 모델이 어떻게 작동하는지에 대한 기본적인 진실 때문이다. 패턴 완성은 엄청 잘하지만, 마음은 읽지 못한다.

"내 앱에 사진 공유 기능 추가해줘" 같은 애매한 프롬프트는 모델이 수천 개의 명시되지 않은 요구사항들을 추측하도록 강요한다. AI가 합리적인 가정들을 할 테고, 그 중 일부는 틀릴 거다. 그리고 구현 깊숙이 들어가서야 어떤 게 맞지 않는지 발견하게 된다.

반대로 처음부터 명확한 명세서를 제공하고, 기술 계획과 집중된 작업들까지 주면, AI가 훨씬 명확해진다. 사용자의 니즈를 추측하는 대신, 뭘 만들어야 하는지, 어떻게 만들어야 하는지, 어떤 순서로 해야 하는지 안다.

이게 다양한 기술 스택에서 작동하는 이유이기도 하다. Python으로 만들든, JavaScript로 만들든, Go로 만들든, 근본적인 도전은 같다. 의도를 작동하는 코드로 번역하는 것. 명세서가 의도를 명확하게 담아내고, 계획이 그걸 기술적 결정들로 변환하고, 작업들이 구현 가능한 조각들로 분해하고, AI가 실제 코딩을 처리한다.

큰 조직에게는 또 다른 중요한 문제를 해결해준다. 보안 정책, 규제 규칙, 디자인 시스템 제약사항, 통합 니즈에 대한 모든 요구사항을 어디에 둘까? 종종 이런 것들이 누군가의 머리 속에만 있거나, 아무도 읽지 않는 위키에 묻혀있거나, 나중에 찾을 수 없는 슬랙 대화에 흩어져 있다.

Spec Kit을 쓰면, 이 모든 것들이 명세서와 계획에 들어간다. AI가 실제로 사용할 수 있는 곳에. 보안 요구사항이 나중에 생각할 일이 아니라, 첫날부터 명세서에 들어간다. 디자인 시스템도 나중에 붙이는 게 아니라, 구현을 가이드하는 기술 계획의 일부가 된다.

이 접근법의 반복적인 특성이 힘을 주는 부분이다. 전통적인 개발이 초기 결정에 묶여있는 반면, 명세서 주도 개발은 방향을 바꾸는 걸 간단하게 만든다. 그냥 명세서를 업데이트하고, 계획을 다시 생성하고, AI가 나머지를 처리하게 하면 된다.

특히 빛을 발하는 세 곳

이 방법이 특히 유용한 시나리오가 세 가지 있다.

새 프로젝트를 시작할 때(0에서 1로). 새 프로젝트를 시작할 때는 그냥 코딩부터 시작하고 싶은 유혹이 있다. 하지만 처음에 조금만 투자해서 명세서와 계획을 만들면 AI가 실제로 의도한 것을 만들어준다. 공통 패턴을 기반으로 한 일반적인 솔루션이 아니라.

기존 시스템에 기능 추가할 때(N에서 N+1로). 이게 명세서 주도 개발이 가장 강력한 곳이다. 복잡한 기존 코드베이스에 기능을 추가하는 건 어렵다. 새 기능에 대한 명세서를 만들면, 기존 시스템과 어떻게 상호작용해야 하는지 강제로 명확해진다. 그러면 계획이 아키텍처 제약사항들을 인코딩해서, 새 코드가 덧붙인 것처럼 느껴지는 대신 프로젝트에 자연스럽게 느껴지게 한다. 이게 지속적인 개발을 더 빠르고 안전하게 만든다. 이게 작동하게 하려면 고급 컨텍스트 엔지니어링 기법들이 필요할 수 있는데, 그건 따로 다룰 예정이다.

레거시 현대화할 때. 레거시 시스템을 다시 만들어야 할 때, 원래 의도가 시간 속에서 종종 사라진다. Spec Kit이 제공하는 명세서 주도 개발 프로세스를 쓰면, 핵심 비즈니스 로직을 현대적인 명세서로 담아내고, 계획에서 새로운 아키텍처를 설계하고, AI가 상속된 기술부채를 가져가지 않고 시스템을 처음부터 다시 만들게 할 수 있다.

핵심 이익은 안정적인 "무엇"과 유연한 "어떻게"를 분리하는 거다. 비용이 많이 드는 재작성 없이 반복적인 개발이 가능해진다. 여러 버전을 만들고 빠르게 실험할 수 있게 해준다.

미래는 어떻게 생겼을까

우리는 "코드가 진실의 원천"에서 "의도가 진실의 원천"으로 움직이고 있다. AI와 함께 명세서가 진실의 원천이 되고 뭘 만들지 결정한다. 문서가 더 중요해져서가 아니다. AI가 명세서를 실행 가능하게 만들어주기 때문이다. 명세서가 자동으로 작동하는 코드로 바뀌면, 뭘 만들지 결정하게 된다.

Spec Kit은 그 전환을 현실로 만드는 GitHub의 실험이다. 이 접근법이 특정 도구나 회사보다 크기 때문에 오픈소스로 공개했다. 진짜 혁신은 프로세스에 있다.

곧 더 다룰 게 있는데, 특히 명세서 주도 개발 기법을 컨텍스트 엔지니어링과 결합해서 AI 툴킷에 더 고급 능력을 만드는 방법이다.

GitHub은 사용자들의 경험을 듣고 싶어한다. 특히 궁금한 것들이 몇 가지 있다. 워크플로를 더 매력적이고 사용하기 쉽게 만들기 - 긴 텍스트 읽는 건 지루할 수 있으니까, 이 프로세스를 정말 즐겁게 만들 방법이 뭘까? VS Code 통합 가능성도 탐구하고 있다. 이 워크플로를 VS Code에 직접 가져오는 방법들을 찾고 있는데, 뭐가 가장 자연스러울까? 여러 구현을 비교하고 차이를 보는 것 - 구현들 사이에서 반복하고 차이를 보는 건 창의적인 가능성들을 열어준다. 여기서 뭐가 가장 가치있을까? 조직에서 규모있게 명세서와 작업 관리하기 - 많은 마크다운 파일들을 관리하는 건 부담스러울 수 있다. 정리되고 집중할 수 있게 도와줄 뭐가 있을까?

그래서 뭘 해야 하나

결론적으로, 인간의 창의성을 작동하는 소프트웨어로 번역하는 더 나은 방법들을 AI를 활용해서 찾아내는 걸 보고 싶다고 한다.

다음에 AI로 뭔가 만들 일이 있으면 Spec Kit을 써보자. 설치도 간단하고, GitHub Copilot, Claude Code, Gemini CLI 같은 주요 AI 도구들과 다 호환된다. 특히 기존 코드에 새 기능을 넣어야 할 때 한 번 써보면, 차이를 확실히 느낄 수 있을 거다.

바이브 코딩도 나름 재미있긴 하다. "대충 이런 느낌으로"라고 하면 AI가 뭔가 만들어주는 게 신기하니까. 하지만 진짜 쓸모있는 걸 만들려면, 이제는 좀 더 체계적으로 접근해야 할 때가 온 것 같다. AI는 이미 충분히 똑똑해졌으니까, 이제 우리가 더 똑똑하게 써야 한다.

명세서 주도 개발이 모든 문제를 해결해주는 건 아니다. 하지만 AI와 함께 개발할 때 생기는 가장 큰 문제 - "AI가 내 마음을 읽어주길 바라는 것" - 는 확실히 해결해준다. 이제 AI에게 마음을 읽으라고 하는 대신, 명확히 말해주면 된다. 그럼 AI가 정말 원하는 걸 만들어줄 거다.