GitHub에서 새롭게 공개한 Spec Kit는 AI 코딩 에이전트의 최대 약점인 모호한 프롬프트 문제를 해결해 명세서 기반의 체계적 개발 프로세스를 제공합니다.
AI 코딩 도구가 발전하면서 많은 개발자들이 같은 경험을 하고 있습니다. 목표를 설명하면 그럴듯한 코드가 나오지만, 막상 실행해보면 컴파일이 안 되거나 의도와 다르게 작동하는 일이 허다합니다. 이른바 ‘감으로 때려맞추기(vibe-coding)’ 방식의 한계입니다.
GitHub는 이 문제를 해결하기 위해 Spec Kit이라는 오픈소스 도구를 출시했습니다. 기존의 ‘감으로 때려맞추기’ 방식을 버리고 체계적인 명세서 기반 개발을 가능하게 만드는 혁신적인 접근법입니다.
Spec-Driven Development가 바꾸는 개발 방식
기존 개발에서 명세서는 초기에 작성하고 버려지는 임시 문서였습니다. Spec Kit는 이 개념을 뒤집어 명세서를 프로젝트의 중심으로 만듭니다.
핵심은 명세서를 실행 가능한 아티팩트로 만드는 것입니다. 코드가 아닌 의도가 개발의 소스가 되는 셈입니다. AI가 명세서를 바탕으로 자동으로 코드를 생성하기 때문에, 명세서가 곧 실제 구현을 결정합니다.
Spec Kit는 GitHub Copilot, Claude Code, Gemini CLI 등 주요 AI 코딩 도구와 연동되며, 다음과 같은 구조화된 프로세스를 제공합니다.
4단계로 완성하는 체계적 개발 프로세스
1단계: 명세 작성 (Specify)
프로젝트의 무엇과 왜에 집중합니다. 기술 스택은 언급하지 않고 사용자 여정과 경험, 성공 기준에 대해 설명합니다.
/specify 명령어 사용
- 누가 이 제품을 사용할 것인가?
- 어떤 문제를 해결하는가?
- 사용자는 어떻게 상호작용하는가?
- 어떤 결과가 중요한가?AI 에이전트가 이 정보를 바탕으로 상세한 기능 명세서를 생성합니다. 이 명세서는 프로젝트가 진행되면서 지속적으로 발전하는 살아있는 문서가 됩니다.
2단계: 기술 계획 수립 (Plan)
원하는 기술 스택, 아키텍처, 제약사항을 제시하면 AI가 종합적인 기술 계획을 만듭니다.
/plan 명령어 사용
- 회사 표준 기술 스택 명시
- 레거시 시스템 통합 요구사항
- 성능 목표 및 규정 준수 사항여러 계획안을 비교 검토할 수도 있고, 내부 문서를 AI에게 제공하면 조직의 아키텍처 패턴과 표준을 자동으로 반영합니다.
3단계: 작업 분할 (Tasks)
AI가 명세서와 계획을 바탕으로 실제 작업을 작은 단위로 분할합니다.
/tasks 명령어 사용
- 각 작업은 독립적으로 구현하고 테스트 가능
- "인증 구축" 대신 "이메일 형식을 검증하는 사용자 등록 엔드포인트 생성"이는 AI 에이전트를 위한 테스트 주도 개발과 같은 역할을 합니다. 각 작업이 명확하기 때문에 AI가 자신의 작업을 검증하고 올바른 방향을 유지할 수 있습니다.
4단계: 구현 (Implement)
AI 에이전트가 작업을 하나씩 처리합니다. 중요한 점은 수천 줄의 코드 덤프를 검토하는 대신, 특정 문제를 해결하는 집중된 변경사항만 검토하면 된다는 것입니다.
실전 활용 가이드: 설치부터 실행까지
설치 및 초기 설정
먼저 specify 명령줄 도구를 설치합니다:
uvx --from git+https://github.com/github/spec-kit.git specify init <PROJECT_NAME>현재 디렉토리에서 초기화하려면:
specify init --here --ai claude
specify init --here --ai gemini
specify init --here --ai copilot프로젝트 구조 확인
설치 후 다음과 같은 프로젝트 구조가 생성됩니다:
├── memory/
│ ├── constitution.md
│ └── constitution_update_checklist.md
├── scripts/
├── specs/
└── templates/
├── CLAUDE-template.md
├── plan-template.md
├── spec-template.md
└── tasks-template.md실제 사용 예시
팀 생산성 플랫폼 ‘Taskify’를 만든다고 가정해봅시다:
1단계 – 명세 작성:
/specify
팀 생산성 플랫폼 Taskify를 개발합니다. 사용자가 프로젝트를 생성하고,
팀원을 추가하며, 작업을 할당하고, 칸반 스타일로 작업을 이동할 수 있어야 합니다.
초기 버전에는 미리 정의된 5명의 사용자(제품 관리자 1명, 엔지니어 4명)와
3개의 샘플 프로젝트가 있어야 합니다...2단계 – 기술 계획:
/plan
.NET Aspire를 사용하고, 데이터베이스는 Postgres를 사용합니다.
프론트엔드는 드래그 앤 드롭 작업 보드와 실시간 업데이트가 가능한
Blazor Server를 사용하고, 프로젝트 API, 작업 API, 알림 API가 포함된
REST API를 생성해야 합니다.3단계 – 작업 분할:
/tasksAI가 명세서와 계획을 바탕으로 구체적인 작업 목록을 생성합니다.
4단계 – 구현:
implement specs/001-create-taskify/plan.mdAI가 실제 구현을 시작하고, 빌드 오류가 발생하면 자동으로 해결을 시도합니다.
효과적인 3가지 활용 시나리오
신규 프로젝트 (제로 투 원)
새 프로젝트를 시작할 때 바로 코딩에 들어가는 대신, 소량의 사전 작업으로 명세서와 계획을 만들면 AI가 의도한 대로 정확히 구축합니다. 일반적인 패턴이 아닌 실제 요구사항에 맞는 솔루션을 얻을 수 있습니다.
기존 시스템 기능 추가 (N에서 N+1)
복잡한 기존 코드베이스에 기능을 추가하는 것은 어려운 작업입니다. 새 기능의 명세서를 작성하면 기존 시스템과의 상호작용이 명확해지고, 계획에 아키텍처 제약사항이 인코딩되어 새 코드가 프로젝트에 자연스럽게 통합됩니다.
레거시 시스템 현대화
오래된 시스템을 재구축할 때 원래 의도가 시간과 함께 사라지는 경우가 많습니다. Spec Kit을 사용하면 핵심 비즈니스 로직을 현대적인 명세서로 캡처하고, 새로운 아키텍처를 설계한 후 AI가 기술 부채 없이 시스템을 처음부터 재구축할 수 있습니다.
성공하는 이유: 패턴 완성 vs 마음 읽기
이 접근법이 성공하는 이유는 언어 모델의 작동 방식과 관련이 있습니다. AI는 패턴 완성에는 뛰어나지만 마음을 읽지는 못합니다.
“앱에 사진 공유 기능 추가”같은 모호한 프롬프트는 AI로 하여금 수천 개의 명시되지 않은 요구사항을 추측하게 만듭니다. 합리적인 가정을 하겠지만 일부는 틀릴 수 밖에 없고, 구현 과정에서 이를 발견하게 됩니다.
반면 명확한 명세서, 기술 계획, 집중된 작업을 제공하면 AI가 추측하는 대신 정확히 무엇을 구축해야 하는지 알게 됩니다. 이는 Python, JavaScript, Go 등 어떤 기술 스택에서든 동일하게 작동합니다.
대규모 조직에서는 보안 정책, 규정 준수 규칙, 디자인 시스템 제약사항 등을 어디에 두어야 할지 고민이 많습니다. 이런 정보들이 누군가의 머릿속에만 있거나, 아무도 읽지 않는 위키에 묻혀있거나, 찾기 어려운 슬랙 대화에 흩어져 있는 경우가 대부분입니다.
Spec Kit에서는 이 모든 것이 명세서와 계획에 들어가므로 AI가 실제로 활용할 수 있습니다. 보안 요구사항은 나중에 추가하는 게 아니라 처음부터 명세서에 포함되고, 디자인 시스템도 나중에 붙이는 게 아니라 구현을 안내하는 기술 계획의 일부가 됩니다.
개발 패러다임의 변화
우리는 “코드가 진실의 원천”에서 “의도가 진실의 원천”으로 이동하고 있습니다. AI와 함께 작업할 때 명세서가 진실의 원천이 되어 무엇을 구축할지 결정합니다.
이는 문서화가 더 중요해져서가 아닙니다. AI가 명세서를 실행 가능하게 만들기 때문입니다. 명세서가 자동으로 작동하는 코드로 바뀌면, 그것이 무엇을 구축할지 결정하게 됩니다.
GitHub는 이런 변화를 현실화하는 실험으로 Spec Kit을 오픈소스로 공개했습니다. 이 접근법은 특정 도구나 회사를 넘어서는 더 큰 의미를 가지며, 진정한 혁신은 프로세스 자체에 있다고 봅니다.
앞으로 VS Code 통합, 여러 구현의 비교 및 차이 분석, 조직 차원의 명세서와 작업 관리 등 더 많은 기능이 추가될 예정입니다. AI를 활용해 인간의 창의성을 작동하는 소프트웨어로 더 잘 번역하는 방법을 찾아가는 여정이 계속됩니다.
참고자료:
Comments