GitHub Spec Kit이 AI 개발 전에 요구사항을 정리한다

GitHub Spec Kit은 AI 에이전트에 구현을 맡기기 전에 프로젝트의 요구사항과 기술 계획을 정리하도록 돕는 오픈소스 도구다. 개발팀은 명세와 작업 단계를 검토·수정한 뒤 에이전트에 구현을 요청할 수 있다.

이 도구는 명세 기반 개발(Spec-Driven Development, SDD)을 위한 CLI와 템플릿·도우미 스크립트로 구성된다. SDD는 방대한 요구사항 문서를 만들거나 워터폴 방식으로 계획하는 대신, 기술적 결정과 그 이유를 명시하고 프로젝트와 함께 갱신하는 접근법이다. 글은 이런 명세가 팀의 공통 맥락을 만들고, AI 에이전트가 요구사항에 맞는 구현을 하도록 안내한다고 설명한다. 명세를 바탕으로 서로 다른 구현이나 디자인 방향을 만들어 비교하는 데도 활용할 수 있다.

설치를 시작하려면 uvx 안내를 참고해 다음 명령을 실행한다.

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

CLI는 지원되는 코딩 에이전트를 선택하도록 안내하고, 프로젝트에 맞는 템플릿과 SDD 작업 구조를 설정한다. POSIX 호환 시스템에서는 셸 스크립트를, Windows 환경에서는 PowerShell 스크립트를 사용할 수 있다. 템플릿은 GitHub 저장소의 Releases 탭에서 받아 프로젝트 폴더에 직접 풀 수도 있다. 프로젝트 개요는 안내 영상에서도 확인할 수 있다.

초기 설정 후에는 .github와 .specify 폴더가 만들어진다. .specify에는 명세·기술 계획·작업 템플릿과 선택한 플랫폼의 스크립트가 들어간다. 에이전트별 폴더에는 SDD 절차를 따르기 위한 프롬프트가 배치되며, GitHub Copilot에서는 /specify, /plan, /tasks 명령을 사용할 수 있다. 프로젝트의 필수 원칙과 관례는 constitution.md에 기록한다.

세 명령은 순서대로 사용한다. /specify는 프로젝트나 기능의 목적과 기능 요구사항을 정리하고 기술적 결정을 제외한다. /plan은 프레임워크·라이브러리·데이터베이스·인프라 등 구현 방식을 계획하며, 조사 자료와 데이터 계약, 시작 안내도 만든다. /tasks는 명세와 계획을 에이전트가 수행할 수 있는 단계별 작업으로 나눈다. 이후 작업 목록을 바탕으로 구현을 요청하면 된다.

초기 프롬프트에 원하는 결과와 피하고 싶은 결과, 중요한 사용자 경험, 기술 선택 조건을 구체적으로 담으면 생성되는 문서를 다듬는 시간을 줄일 수 있다고 안내한다. 생성된 자료는 specs 폴더의 마크다운 파일이며 직접 수정하거나 에이전트의 도움을 받아 고칠 수 있다. 기본 템플릿에는 프로젝트 구성 방식에 관한 가정이 있으므로, 필요하면 .specify 안의 프롬프트와 템플릿을 조직의 요구에 맞게 바꿀 수 있다.

GitHub Spec Kit은 아직 실험 단계다. GitHub는 기능을 개선하기 위해 저장소의 이슈를 통해 피드백을 받고 있다.