AI가 코드를 빨리 쓰는 시대에 팀이 먼저 마주치는 병목은 코딩 속도가 아닙니다. "우리가 만들려는 것이 정확히 무엇인가"를 사람이 정리하는 속도입니다.
GitHub Spec-Kit은 이 긴장을 정면으로 다룹니다. 최근 MarkTechPost도 이를 AI 코딩 에이전트와 명세 주도 개발을 연결하는 오픈소스 툴킷으로 소개했습니다1. 핵심은 새 코딩 도구 하나가 더 나왔다는 데 있지 않습니다. AI가 코드를 쓰기 전에, 팀의 의도와 제약을 실행 가능한 명세로 바꿔야 한다는 문제 제기입니다.
문제는 "AI가 못 짠다"가 아니라 "우리가 덜 정했다"일 수 있다
GitHub가 설명하는 Spec Kit의 기본 전제는 분명합니다. 기존 개발에서 명세는 종종 초기에 쓰고 버리는 문서였지만, Spec-Driven Development에서는 명세가 구현, 체크리스트, 작업 분해를 이끄는 중심 산출물이 됩니다2.
흐름은 대략 이렇습니다. /speckit.constitution으로 프로젝트 원칙을 정하고, /speckit.specify로 무엇을 왜 만들지 적습니다. 이후 /speckit.plan에서 기술 스택과 아키텍처를 정하고, /speckit.tasks로 구현 가능한 작업으로 쪼갠 뒤, /speckit.implement로 AI 에이전트가 작업을 수행합니다3.
여기서 중요한 점은 Spec-Kit이 마법처럼 요구사항을 검증해주는 제품 관리 도구가 아니라는 점입니다. 실제로는 CLI와 템플릿, 프롬프트, 에이전트별 명령 구성을 통해 Copilot, Claude Code, Gemini CLI 같은 도구가 "명세 중심으로 일하도록" 환경을 깔아주는 쪽에 가깝습니다4.
따라서 실패 원인을 구분해야 합니다. 모델이 약해서 실패한 것인지, 프롬프트가 짧아서 실패한 것인지, 아니면 애초에 팀이 성공 조건을 합의하지 못했는지. Spec-Kit이 가장 잘 드러내는 것은 세 번째 문제입니다.
Spec-Kit이 돈값을 하는 구간: 변경 많고, 조율 어렵고, 후회 비용 큰 일
Spec-Kit은 모든 작업에 필요한 도구가 아닙니다. 하지만 특정 구간에서는 꽤 강한 레버리지가 생깁니다.
첫째, 기존 시스템에 기능을 추가할 때입니다. 새 기능은 코드만 새로 쓰는 일이 아니라 기존 인증, 데이터 모델, 디자인 시스템, 권한 정책과 맞물립니다. 이때 명세와 계획 단계에 제약을 적어두면 AI가 "그럴듯하지만 낯선 코드"를 붙이는 위험을 줄일 수 있습니다.
둘째, 컴플라이언스나 보안 요구가 있는 워크플로입니다. 보안 정책, 성능 목표, 테스트 기준이 위키나 슬랙에 흩어져 있으면 AI는 그것을 모릅니다. Spec-Kit의 constitution과 plan은 이런 조직 규칙을 에이전트가 참고할 수 있는 문맥으로 끌어옵니다.
셋째, 레거시 현대화입니다. 오래된 시스템은 코드가 남아 있어도 의도는 사라진 경우가 많습니다. 이때 "현재 코드가 어떻게 생겼는가"보다 "비즈니스 규칙이 무엇인가"를 먼저 명세화하면, AI를 단순 변환기가 아니라 재구현 보조자로 쓸 수 있습니다.
현장 사용기를 보면 /clarify가 모호한 부분을 질문으로 드러내고, /analyze가 산출물 간 일관성을 점검하는 식의 보조 단계도 활용됩니다5. 이 기능들은 거창해 보이지만 실무적으로는 "AI가 코드를 쓰기 전에 우리 팀이 무엇을 모르는지 확인하는 절차"에 가깝습니다.
실패하는 도입: 더 예쁜 마크다운 관료주의
반대로 Spec-Kit이 오히려 속도를 늦추는 경우도 있습니다.
탐색형 프로토타입이 대표적입니다. 아직 사용자가 원하는지, 화면 흐름이 맞는지, 문제 자체가 유효한지 모르는 단계에서 명세를 촘촘히 쓰면 학습보다 문서 정리에 시간을 씁니다. 이때는 바이브 코딩이 나쁜 것이 아니라, 일부러 싼 비용으로 틀려보는 전략일 수 있습니다.
또 하나의 함정은 "명세가 있으니 검증됐다"고 착각하는 것입니다. 잘 쓴 spec.md는 팀의 합의를 표현할 수는 있지만, 시장 검증이나 사용자 검증을 대신하지 못합니다. 명세는 진실이 아니라 가설에 가깝습니다. 다만 AI가 실행하기 좋은 형태로 정돈된 가설입니다.
그래서 Spec-Kit 도입의 기준은 문서화 의지가 아니라 후회 비용이어야 합니다. 잘못 구현했을 때 되돌리기 비싼가? 여러 사람이 동시에 만지는가? 정책과 예외가 많은가? 그렇다면 명세를 계약으로 만드는 편이 유리합니다. 아니라면 과할 수 있습니다.
가볍게 시작하려면: 기능 하나, 제약 하나, 검증 가능한 약속 하나
처음부터 전사 표준 프로세스로 밀어붙일 필요는 없습니다. 가장 좋은 시작점은 작고 경계가 분명한 기능 하나입니다.
예를 들어 "사진 앨범을 날짜별로 묶고 드래그앤드롭으로 재정렬한다"처럼 사용자 행동이 분명한 기능을 고릅니다. 먼저 /specify에서는 기술을 말하지 말고 사용자 약속을 적습니다. 그다음 /clarify로 애매한 예외를 드러내고, /plan에서 스택과 저장 방식, 성능 제약을 넣습니다. /tasks 결과가 리뷰 가능한 단위로 나뉘는지 본 뒤 구현을 맡깁니다.
도입 후 봐야 할 지표는 단순합니다. 코드가 빨리 나왔는가보다, 리뷰에서 "이게 원래 의도였나?"라는 논쟁이 줄었는가. 테스트와 작업 단위가 명세와 연결됐는가. 다음 사람이 기능 의도를 더 빨리 이해했는가.
Spec-Kit을 신경 써야 할 팀은 AI 코딩 도구를 이미 쓰고 있지만 결과물이 자주 빗나가는 팀입니다. 특히 제품 규칙이 자주 바뀌고, 여러 개발자와 에이전트가 같은 코드베이스를 만지고, 잘못된 구현의 후회 비용이 큰 팀이라면 지금 실험해볼 만합니다. 핵심은 문서를 더 쓰는 것이 아니라, AI가 코드를 쓰기 전에 무엇을 계약으로 고정할지 고르는 일입니다.
참고
1Meet GitHub Spec-Kit: An Open Source Toolkit for Spec-Driven Development with AI Coding Agents
2Spec-driven development with AI: Get started with a new open source toolkit
3GitHub - github/spec-kit: 💫 Toolkit to help you get started with Spec-Driven Development · GitHub
4Spec Kit | Spec Kit Documentation
5GitHub의 'Spec Kit'을 사용해 보기ー사양 주도 개발로 시작하는 새로운 개발 흐름ー - cocone engineering
이 노트는 보도·비평·교육·연구 목적으로 작성되었습니다. 저작권 문의가 있으시면 에서 알려주세요.