- Published on
GitHub Spec Kit: AI 코딩을 vibe coding에서 스펙 주도 개발로 되돌리는 신호
- Authors
- Name
- Kyunghyun Park
- @devkhpark
GitHub Spec Kit · Spec-Driven Development · AI Coding Agent Workflow
GitHub의 Spec Kit이 흥미로운 이유는 “코딩 에이전트를 하나 더 만들었다”가 아니기 때문이다. 핵심은 정반대다. 에이전트가 코드를 더 빨리 쓰는 시대일수록, 개발자가 다시 무엇을 만들지·어떤 제약을 지킬지·어떤 순서로 검증할지를 더 단단하게 써야 한다는 메시지다.
Spec Kit은 이 방향을 Spec-Driven Development, 즉 스펙 주도 개발로 부른다. 공식 문서는 이를 “코드를 작성하기 전에 무엇을 만들지 정의하고, 구조화된 단계로 정제한 뒤, AI 코딩 에이전트가 구현하게 하는 방식”으로 설명한다. 쉽게 말하면, AI 코딩의 병목을 “프롬프트를 잘 쓰는 사람”에서 “좋은 스펙과 품질 게이트를 운영하는 팀”으로 옮기는 도구다.
이 글은 2026-05-14 기준 GitHub Spec Kit의 공식 저장소, 문서, 템플릿, 통합 목록을 바탕으로 왜 이 도구가 한국 개발자와 빌더에게 중요한 신호인지 정리한다. 특히 “AI가 코드를 많이 쓰게 되었는데 왜 프로젝트는 더 불안정해지는가?”라는 질문에 초점을 둔다.
핵심 한 줄: Spec Kit은 AI 코딩 에이전트를 더 자유롭게 만드는 도구라기보다, AI가 바꿀 수 있는 범위를 Markdown 스펙·계획·작업·헌법으로 제한해 제품 개발을 다시 검증 가능한 프로세스로 묶는 도구다.
왜 지금 Spec Kit인가: 에이전트 경쟁의 다음 병목은 코드 생성이 아니다
지난 1년간 코딩 AI의 경쟁은 대부분 “누가 더 많은 코드를 더 빨리 쓰는가”에 맞춰져 있었다. Claude Code, Codex CLI, Gemini CLI, Cursor, Windsurf, Kiro, Copilot 계열 도구가 모두 이 축에서 경쟁한다. 하지만 현장에서 실제로 터지는 문제는 코드 생성 속도가 아니다.
더 자주 터지는 문제는 이쪽이다.
- 요구사항이 모호한데 에이전트가 그럴듯한 구현을 먼저 만든다.
- 설계 의사결정이 채팅 로그 어딘가에 흩어진다.
- 테스트·성능·보안·배포 제약이 구현 후반에야 등장한다.
- 한 에이전트가 만든 결과를 다른 에이전트나 사람이 이어받기 어렵다.
- “잘 됐다”는 느낌은 있는데, 어떤 사용자 시나리오가 실제로 통과됐는지 불명확하다.
Spec Kit이 건드리는 지점은 바로 여기다. README는 이 도구를 “vibe coding every piece from scratch” 대신 product scenarios and predictable outcomes에 집중하게 해주는 오픈소스 툴킷이라고 소개한다. 즉 문제 정의를 대충 넘긴 채 AI에게 구현을 맡기는 흐름을 끊고, 제품 시나리오와 예측 가능한 결과를 먼저 고정하자는 것이다.
이건 단순한 개발 방법론 문구가 아니다. AI 코딩 에이전트가 강해질수록 더 중요해지는 운영 원칙이다. 모델이 약할 때는 사람이 직접 코드 대부분을 썼기 때문에 잘못된 요구사항이 곧바로 드러났다. 하지만 모델이 강해지면, 틀린 방향의 작업도 아주 빠르게 “완성된 것처럼” 보인다. 그래서 앞으로의 생산성은 더 많은 자동화보다 자동화가 따라갈 올바른 궤도를 만드는 쪽에서 갈린다.
Spec Kit의 워크플로: Spec → Plan → Tasks → Implement
공식 문서의 핵심 구조는 간단하다. Spec Kit은 SDD 프로세스를 Spec → Plan → Tasks → Implement로 묶는다. 각 단계는 채팅 한 줄로 사라지는 중간 생각이 아니라 Markdown 산출물로 남는다.
공식 Quick Start 기준 흐름은 대략 이렇다.
specify init으로 프로젝트를 초기화한다./speckit.constitution으로 프로젝트의 핵심 원칙과 품질 기준을 정의한다./speckit.specify로 기능 요구사항을 스펙으로 만든다./speckit.plan으로 구현 계획과 기술적 판단을 정리한다./speckit.tasks로 실제 작업 목록을 만든다.- 에이전트가 구현을 수행하되, 앞 단계 산출물을 계속 참조한다.
여기서 중요한 건 “명령어가 많다”가 아니다. 각 단계가 서로 다른 종류의 불확실성을 제거한다는 점이다.
1) Spec은 사용자 시나리오를 강제한다
spec-template.md는 기능 명세의 첫 번째 핵심 블록을 User Scenarios & Testing으로 둔다. 사용자 스토리는 우선순위 P1, P2, P3로 나뉘고, 각 스토리는 독립적으로 테스트 가능해야 한다. 또 각 스토리마다 “왜 이 우선순위인가”, “어떻게 독립적으로 검증할 수 있는가”, “Given/When/Then acceptance scenario는 무엇인가”를 요구한다.
이 구조는 AI 코딩에서 특히 중요하다. 프롬프트만 던지면 에이전트는 보통 눈에 보이는 UI나 가장 쉬운 구현부터 만든다. 하지만 스펙이 사용자 여정과 독립 테스트 단위로 쪼개져 있으면, 에이전트는 “그럴듯한 전체”보다 “검증 가능한 한 조각”을 먼저 만들게 된다.
2) Plan은 기술 선택을 뒤늦은 핑계가 아니라 사전 계약으로 만든다
plan-template.md는 언어/버전, 주요 의존성, 저장소, 테스트, 타깃 플랫폼, 성능 목표, 제약, 규모를 명시하게 한다. 그리고 Constitution Check를 계획 단계의 게이트로 둔다. 공식 템플릿에는 “Phase 0 research 전에 통과해야 하고, Phase 1 design 후 다시 확인한다”는 문구까지 들어 있다.
이건 개발팀이 자주 겪는 실패를 예방한다. AI가 만든 구현이 처음에는 빠르게 보이지만, 뒤늦게 “우리 배포 환경에서는 안 된다”, “테스트 전략과 맞지 않는다”, “성능 목표가 없다”, “보안 원칙을 어겼다”가 나오면 생산성은 사라진다. Spec Kit은 이런 판단을 구현 뒤가 아니라 구현 앞에 둔다.
3) Tasks는 작업을 사용자 스토리 단위로 재정렬한다
tasks-template.md는 작업을 user story별로 묶도록 요구한다. 단순히 파일별 TODO를 나열하는 방식이 아니라, 각 사용자 스토리가 독립적으로 구현·테스트·배포·데모 가능해야 한다는 원칙을 유지한다.
이 방식은 에이전트 운영에도 잘 맞는다. 여러 에이전트나 여러 세션이 동시에 작업할 때 가장 위험한 건 경계가 없는 작업이다. 반대로 사용자 스토리 단위의 작업 목록이 있으면, 병렬화 가능한 작업, 선행 의존성이 있는 작업, 테스트가 필요한 작업을 훨씬 쉽게 나눌 수 있다.
“아무 에이전트나 쓸 수 있다”는 점이 더 중요하다
Spec Kit 문서에서 눈에 띄는 부분은 지원 에이전트 통합이다. 공식 docs는 specify init이 선택한 AI 코딩 에이전트에 맞춰 command files, context rules, directory structures를 설정한다고 설명한다. 지원 목록에는 Copilot, Gemini, Codex, Windsurf, Claude, Kiro 등 다양한 도구가 들어 있고, 현재 문서에는 30개 통합이 언급된다.
이건 단순한 호환성 자랑이 아니다. 더 중요한 의미는 스펙 산출물이 특정 에이전트보다 상위 계층에 놓인다는 점이다.
지금 많은 팀의 AI 코딩 도입은 도구 종속적이다. Claude Code에서 만든 작업 맥락은 Claude Code 안에 남고, Cursor에서 만든 규칙은 Cursor 안에 남고, Codex CLI의 히스토리는 또 다른 표면에 남는다. 팀이 도구를 바꾸거나, 모델이 바뀌거나, 특정 에이전트가 한 작업을 다른 에이전트가 이어받아야 할 때 맥락이 부서진다.
Spec Kit은 이 문제를 “모든 에이전트를 하나로 통일하자”로 풀지 않는다. 대신 스펙·계획·작업·헌법이라는 공통 파일 계층을 만든다. 에이전트는 바뀔 수 있지만, 프로젝트의 의도와 제약은 Markdown 산출물로 남는다.
한국 개발팀 입장에서는 이 부분이 꽤 실용적이다. 조직마다 선호 도구가 다르고, 보안 정책 때문에 특정 클라우드/모델을 못 쓰는 경우도 많다. 이때 방법론이 특정 벤더 도구에 묶이면 도입이 어렵다. 반대로 Spec Kit처럼 산출물이 열린 파일 구조로 남으면, 팀은 Claude, Codex, Copilot, Gemini 계열을 상황별로 바꾸면서도 같은 개발 프로세스를 유지할 수 있다.
Constitution이 흥미로운 이유: AI에게 “코딩 스타일”이 아니라 “조직 원칙”을 준다
Spec Kit에서 가장 과소평가되기 쉬운 부분은 constitution이다. 많은 팀이 AI 코딩 도구에 “이런 스타일로 작성해줘”, “테스트도 만들어줘”, “간결하게 해줘” 같은 규칙을 준다. 하지만 constitution은 그보다 한 단계 위에 있다.
constitution-template.md는 프로젝트의 핵심 원칙을 별도 문서로 만들게 한다. 예시 주석에는 Library-First, CLI Interface, Test-First, Integration Testing, Observability, Versioning, Simplicity 같은 원칙이 언급된다. 즉 이 문서는 코드 포맷팅 규칙이 아니라 제품과 엔지니어링 판단의 헌법에 가깝다.
이 구조가 중요한 이유는 AI 에이전트가 판단을 많이 하게 되었기 때문이다. 예전에는 개발자가 “이번에는 간단히 가자”, “이건 라이브러리로 분리하자”, “여기는 통합 테스트가 필요하다”를 직접 결정했다. 이제는 에이전트가 설계와 구현을 함께 제안한다. 그러면 에이전트에게도 팀의 원칙을 줘야 한다.
좋은 constitution은 이런 질문에 답해야 한다.
- 모든 기능은 독립 테스트 가능한 단위로 쪼갤 것인가?
- 라이브러리 우선 구조를 강제할 것인가?
- CLI나 API 계약을 먼저 정의할 것인가?
- 성능 목표와 관측 가능성을 어느 수준부터 필수로 볼 것인가?
- 보안·개인정보·배포 제약을 어떤 단계에서 검사할 것인가?
이 원칙이 없으면 에이전트는 매번 가장 그럴듯한 일반론으로 돌아간다. 반대로 constitution이 있으면, AI 코딩은 “즉흥적인 코드 생성”이 아니라 “조직 원칙을 따르는 자동화된 구현”에 가까워진다.
실무 해석: Spec Kit은 작은 프로젝트보다 ‘반복되는 AI 개발’에서 더 빛난다
Spec Kit을 보고 “그냥 프롬프트 템플릿 묶음 아닌가?”라고 볼 수도 있다. 작은 토이 프로젝트라면 어느 정도 맞다. 간단한 페이지 하나, 스크립트 하나, 일회성 자동화라면 Spec Kit의 단계가 오히려 무겁게 느껴질 수 있다.
하지만 반복되는 제품 개발에서는 이야기가 달라진다.
특히 아래 상황에서는 도입 가치가 커진다.
1) 기능이 계속 추가되는 SaaS나 내부 도구
기능 하나를 AI로 빨리 만드는 것보다 더 어려운 건, 기능 30개가 쌓인 뒤에도 요구사항과 테스트 기준을 잃지 않는 것이다. Spec Kit은 feature branch와 specs/[###-feature] 구조를 통해 기능 단위 산출물을 남기기 때문에, 나중에 “왜 이렇게 만들었는가”를 추적하기 쉽다.
2) 여러 명이 여러 에이전트를 섞어 쓰는 팀
한 사람은 Claude Code, 다른 사람은 Codex, 또 다른 사람은 Copilot을 쓴다면 공통 맥락 계층이 필요하다. Spec Kit의 가치는 여기서 커진다. 에이전트별 채팅 히스토리가 아니라, 저장소 안의 스펙·계획·작업 파일이 협업의 기준점이 된다.
3) 레거시 시스템에 AI를 붙이는 brownfield 작업
공식 SDD 문서는 greenfield뿐 아니라 brownfield modernization과 iterative enhancement도 목표로 둔다. 레거시 시스템에서는 “그냥 고쳐줘”가 가장 위험한 프롬프트다. 기존 제약, 데이터 모델, 배포 방식, 실패 시 영향 범위를 먼저 명시하지 않으면 AI는 새 코드 기준으로만 판단한다.
4) 엔터프라이즈 제약이 있는 조직
Spec Kit 문서는 enterprise constraints도 명시한다. 클라우드 제공자, 기술 스택, 엔지니어링 관행, 디자인 시스템, 컴플라이언스 요구사항을 스펙 프로세스에 넣는 것이 목표다. 한국 기업 환경에서도 이 지점은 중요하다. AI 도입의 실제 병목은 모델 성능보다 보안 정책, 배포 승인, 레거시 시스템, 감사 가능성인 경우가 많기 때문이다.
SEO보다 중요한 검색 의도: “AI 코딩 잘하는 법”의 답이 바뀌고 있다
이 주제는 검색 의도 측면에서도 흥미롭다. 많은 개발자가 “Claude Code 잘 쓰는 법”, “Codex CLI 사용법”, “Cursor 프롬프트”, “AI 코딩 에이전트 워크플로”를 찾는다. 하지만 진짜 문제는 특정 툴의 단축키나 프롬프트 문구가 아니다.
앞으로 더 중요한 질문은 이것이다.
- AI 코딩 에이전트에게 요구사항을 어떻게 구조화해서 줄 것인가?
- 에이전트가 만든 구현을 어떤 기준으로 검증할 것인가?
- 채팅 맥락이 아니라 저장소에 남는 개발 산출물을 어떻게 만들 것인가?
- 여러 모델과 여러 도구를 바꿔 써도 유지되는 개발 프로세스를 어떻게 만들 것인가?
Spec Kit은 이 질문에 대해 꽤 명확한 답을 준다. 답은 “더 긴 프롬프트”가 아니라 “스펙을 실행 가능한 산출물로 만들고, 계획과 작업과 헌법을 저장소에 남겨라”다.
도입할 때의 주의점: 모든 것을 문서화하면 오히려 느려진다
그렇다고 모든 프로젝트에 Spec Kit을 그대로 밀어 넣는 게 정답은 아니다. 몇 가지 주의점이 있다.
첫째, 작은 변경까지 전부 SDD로 처리하면 팀이 피곤해진다. typo 수정, 단순 설정 변경, 명확한 버그 수정에는 가벼운 절차가 더 낫다.
둘째, 템플릿을 채우는 것이 목표가 되면 실패한다. 스펙의 목적은 문서를 예쁘게 만드는 것이 아니라, 에이전트와 사람이 같은 문제 정의를 공유하게 만드는 것이다. NEEDS CLARIFICATION이 남아 있다면 그 자체가 중요한 신호다. 무리해서 빈칸을 그럴듯하게 채우는 순간 SDD의 장점이 사라진다.
셋째, constitution은 처음부터 완벽할 필요가 없다. 오히려 팀이 반복적으로 겪는 실패를 하나씩 원칙으로 승격하는 편이 낫다. 예를 들어 “모든 API 변경은 contract test를 먼저 만든다”, “민감 데이터는 로그에 남기지 않는다”, “사용자 스토리 하나는 독립 데모 가능해야 한다” 같은 식이다.
넷째, 에이전트를 과신하면 안 된다. Spec Kit은 AI가 모든 것을 알아서 하게 만드는 도구가 아니라, AI가 더 안전하게 일하도록 작업 표면을 좁히는 도구다. 좋은 스펙을 쓰는 책임은 여전히 사람에게 있다.
한국 개발자·빌더를 위한 실전 적용법
바로 도입한다면 거창하게 시작할 필요는 없다. 아래 정도면 충분하다.
- 새 기능 하나만 Spec Kit 방식으로 진행한다. 기존 프로세스를 전부 바꾸지 말고, 다음 기능 하나에만 적용한다.
- constitution에는 5개 이하 원칙만 넣는다. 테스트, 보안, 배포, 관측, 단순성처럼 팀이 자주 놓치는 항목 위주로 시작한다.
- spec.md는 사용자 시나리오 중심으로 쓴다. 구현 상세보다 “누가 어떤 상황에서 어떤 결과를 얻는가”를 먼저 고정한다.
- plan.md에는 제약을 명시한다. 언어, 플랫폼, 데이터 저장소, 성능 목표, 배포 환경, 금지된 의존성을 적는다.
- tasks.md는 PR 단위로 쪼갠다. 에이전트가 한 번에 모든 것을 바꾸지 않게 한다.
- 구현 후 산출물을 버리지 않는다. 다음 기능의 맥락과 회고 자료로 남긴다.
이렇게 하면 Spec Kit은 단순 문서 도구가 아니라 AI 개발 운영 체계가 된다. 특히 에이전트가 만든 결과를 리뷰해야 하는 팀 리드, 스타트업 CTO, 내부 도구를 빠르게 만드는 운영 조직에게는 꽤 실용적인 패턴이다.
결론: AI 코딩의 다음 생산성은 “더 빠른 자동완성”보다 “더 좋은 작업 계약”이다
Spec Kit이 보여주는 방향은 분명하다. AI 코딩의 초점은 이제 “모델이 코드를 얼마나 잘 쓰는가”에서 “우리가 모델에게 어떤 작업 계약을 줄 것인가”로 이동하고 있다.
코딩 에이전트는 계속 강해질 것이다. 하지만 강한 에이전트일수록 잘못된 요구사항도 더 빠르게 구현한다. 그래서 앞으로의 개발 생산성은 프롬프트 재주보다, 스펙·계획·작업·헌법을 통해 AI가 움직일 레일을 얼마나 잘 깔아두느냐에서 결정될 가능성이 높다.
GitHub Spec Kit은 그 변화를 꽤 선명하게 보여주는 신호다. AI 코딩을 잘하고 싶다면, 이제 “어떤 에이전트를 쓸까?”만 물을 게 아니라 “우리 팀의 스펙은 실행 가능한가?”를 먼저 물어야 한다.