![Featured image for [AI] Spec-kit 사용 후기](https://tired-i.com/wp-content/uploads/2026/01/ai-spec-kit-image.png)
1. Speck-kit이란?
GitHub Spec Kit은 스펙 기반 개발(Spec-Driven Development)을 위한 오픈소스 바이브코딩 툴킷이다.
이는 명세(Specification)를 개발 프로세스의 중심에 두는 새로운 접근 방식이다.
스펙을 먼저 정의하고, AI 코딩 에이전트가 이를 기반으로 구현과 아키텍처를 생성합니다.
제멋대로 동작하는 7살 남자아이 같은 우리의 AI들을 다른 생각하지 못하게 Context라는 울타리를 치는 것과 같다.
개인적으로 앞서 소개한 3-file system의 연장선에 있다고 생각한다.
2. install
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git
# 또는
brew install specify # macOS
Code language: PHP (php)3. 개발 프로세스
specify init [OPTIONS]
Code language: CSS (css)사용하는 모든 툴(claude code, github copilot, opencode …)에 앞서 spec-kit을 실행한다.
AI assistant 선택, spec-kit 기능을 사용할 수 있는 명령어 추가, git 초기화까지도 spec-kit의 초기화 과정에 포함되어있다.
.specify, .git, ai 툴 파일을 생성해 준다.
참고로 본격적으로 구현하기 전에 .gitignore도 추가하는 과정이 준비되어 있으니 따로 추가하지 않아도 된다.
간략하게 살펴보면 사용하는 ai 툴에 spec-kit의 커스텀 명령어를 추가하는 방식으로 동작한다.
각 명령어를 보조하는 템플릿과 터미널 명령어로 구성된다.
또한 프로젝트에서 반드시 지켜져야 할 “헌법(constitution)”을 정의한다.
전체적인 개발 프로세스는 다음과 같다.
초기화
-> constitution
-> specify
-> clarify (optional)
-> plan
-> checklist (optional)
-> tasks
-> analyze (optional)
-> implement
바이브코딩의 개발과정이라고 믿기지 않을 정도로 체계적이다.
각 단계를 수행하면 반드시 마크다운으로 작성된 출력물을 생성한다.
해당 출력물이 있어야 다음 단계로 나아갈 수 있다.
(optional은 생략가능)
4. 사용
WordPress로 개발 블로그를 옮겨볼까 한다. (귀 막아 tistory)
이왕 하는 거 Notion에서 작성한 초고를 WordPress로 자동으로 업로드하는 툴을 개발해 보았다.
정말 이게 되네 싶다.
개발하기로 결심하고 MVP까지 완성하는데 단 3일밖에 걸리지 않았다.
spec-kit을 처음 사용한 점을 고려한다면 2일 정도면 충분히 개발할 수 있었을 것 같다.
정말 과장하지 않고 Typescript를 단 한 단어도 입력하지 않았다.
(정확히는 Typescript를 모른다.)
문서만 잔뜩 읽고 수정사항만 짚어주고, 마지막에 에러메시지만 붙여 넣었을 뿐이다.
기능이 마냥 단순한 것도 아니다.
일정시간마다 Notion에서 새로 작성된 글을 가져온 다음, 이를 WordPress로 업로드한다.
이때 가장 마지막에 스캔한 시간으로부터 후에 작성된 글만 가져온다.
이미지는 따로 정리해서 Notion에서 다운로드한 후 WordPress로 업로드한다.
이 과정에서 필요한 API 요청은 모두 실패를 가정해서 최대 3회 재시도(지수 백오프)한다.
업로드 과정 중 오류가 발생하면, 시스템은 생성된 WordPress 리소스(포스트/미디어)를 가능한 범위에서 롤백하고, Notion 페이지의 status를 error로 변경한다.
그리고 이러한 성공과 실패는 모두 Telegram으로 알린다.
5. 후기
가. 손대지 마라 인간
처음에 직접 개발문서를 수정하려고 시도했다.
얼마 안 가 뭔가 잘못된 것을 깨달았다.
방대한 개발문서를 일관성 있게 관리하는 것이 어렵다.
때문에 수정 사항을 정리하여 AI agent에게 수정하도록 요청해야 한다.
사실상 코드가 아니라 채팅만 치면 된다.
나. 내가 짐이다.
이 시스템은 문제가 있다.
바로 수시로 병목현상이 발생한다.
그리고 “내”가 그 병목이다.
난가?
내가 문제다.
인정할 수밖에 없었다…
개발자의 개입이 필요 없는 상황에서 가장 생산성이 높을 수밖에 없다.
다. 그래도!
아직 개발자는 쓸모 있다.
누군가의 지갑이 연결되어 있기 때문이다.
박명수 무한도전 대역죄인 짤
개발자는 책임을 지는 존재다.
바이브코딩으로 만든 프로그램을 세상에 자신 있게 내보일 수 있을까?
나는 자신 없다.
만드는데 3일 걸렸지만 모든 코드를 분석하고 잠재된 문제를 찾아서 해결하는데 더 많은 시간이 필요할 것 같다.
결국 누군가는 책임져야 하기 때문에 아직 개발자는 필요하다.
라. 배신감 MAX
실제로 코드를 열어보았다. 그러자 혈압이 상승했다.
- 구버전의 의존성을 설치한다.
- 기껏 구현해 놓은 함수를 사용하지 않고 있다.
- 리터럴 값을 남발해 놓았다.
- 필요 없는 기능까지 구현.
이외에도 아주 유지보수에 아주 불리한 코드를 작성해 놓았다.
6. 결론
사용하면 느낀 장단점을 조금 정리해 보았다.
- 장점
- 작성하는 개발 문서의 수준이 높다. 굉장히 논리적, 합리적이다.
- 기존의 바이브코딩과 비교해서 개발 과정이 체계적이다.
- 별다른 노력 없이 한 번에 코드를 작성한다.
- 쓸데없는(?) 디테일이 좋다.
README.md,quickstart.md등 문서화에 진심이다. - 어쨋든 동작한다.
- 단점
- 구현 단계에 들어서면 급격하게 불투명해진다. 구현 단계에서 개발자가 코드의 흐름을 이해할 기회가 없다. 조금 느려도 질문을 하던가, 단계를 나눠갔으면 좋겠다.
- 구현을 끝나도 정상적으로 동작하기 위해선 많은 디버깅이 필요함. 물론 디버깅해도 문제없이 동작할거란 보장은 없음. 개인적으로 가챠를 돌리는 것 같았음.
- 유지보수가 불가능한 코드를 작성함.
- 동작은 하지만 이상하게 동작함.
- 무엇보다 기분이 나쁘다. 이런 식의 바이브코딩은 개발자들이 원하지 않을 것 같다. 마법같이 “짠”하고 만들어 내는 것은 보기엔 멋있지만 “책임질 수 있는” 코드는 아니다.
- 0-1의 Greenfield에는 적합하지만, 1-N의 Brownfield에는 부적합함.
한번에 너무 많은 기능을 기획, 구현하려는 것 같다.
그것보다는 “테스트 가능한 최소한의 단위”로 기획, 구현을 반복하는 것이 더 적합해 보인다.
그래야 개발자가 개발의 흐름을 파악하기 쉽고, 코드에 대한 신뢰가 쌓일 것 같다.
어쨌든 확실한 것은 이게 바이브코딩의 옳게 된 방향성이다.
당장은 아쉬운 점이 있어도 빠르게 개발되고 있는 프로젝트인 만큼 앞날이 기대된다.
여담이지만 vscode에서 agent가 터미널 명령어를 실행할 때 자꾸 멈춘다.
애초에 TUI를 사용하면 문제가 생기지 않기 때문에 opencode로 넘어갔다.