Spec Kit: 명세 기반 개발을 활용한 바이브 코딩

Tech

2025. 12. 29.

바이브 코딩의 한계 보완: AI 컨텍스트 파일(claude.md, agents.md)의 역할

컨텍스트 파일의 구조적 제약: 명세 기반 개발(SDD)이 필요한 이유

SDD 도구: GitHub ‘Spec Kit’의 등장

1. SDD(Spec-Driven Development)란?

2. 스펙킷(Spec Kit)이란?

2.1 파일 아키텍처

2.2 Spec Kit의 8단계 워크플로우: 원칙 수립부터 구현까지

[실습] Spec Kit으로 챗봇 개발하기 (소요시간: ~2h)

- 실행 과정

- 챗봇 구현 결과

저자 및 출처

바이브 코딩의 한계 보완: AI 컨텍스트 파일(claude.md, agents.md)의 역할

2025년 2월, AI 연구자 Andrej Karpathy는 자연어 설명만으로 LLM이 코드를 생성하는 바이브 코딩(Vibe coding)이라는 용어를 소개했습니다. 바이브 코딩은 누구나 쉽게 소프트웨어를 개발할 수 있도록 도와주었으나, AI가 프롬프트의 맥락을 완벽히 이해하지 못해 버그, 보안 취약점, 그리고 예상과 다른 결과를 초래하는 등 여러 문제가 발생했습니다[1].

이를 보완하기 위해 claude.md, agents.md 같은 컨텍스트 파일이 등장했습니다.

claude.md는 Anthropic이 2025년 5월 공개한 Claude Code의 프로젝트 가이드 파일로, 대화를 시작할 때 자동으로 로드됩니다. 코드 베이스를 분석해 스스로 컨텍스트 파일을 생성할 수 있어, 초기 설정에 대한 사용자의 부담을 줄여주며 외부 도구 연계, 사용자 지정 명령 등 다양한 기능을 제공합니다[2].
agents.md는 2025년 8월, OpenAI를 비롯한 AI 코딩 에이전트 개발사들이 협력하여 만든 에이전트 전용 표준 파일입니다. 다양한 환경에서 자유롭게 사용할 수 있는 공통 규칙을 지향하기 때문에, 하나의 파일로 프로젝트 내용을 공유할 수 있습니다. 현재 6만 개 이상의 오픈소스 프로젝트에 채택되었으며, 15개 이상의 주요 AI 에이전트를 지원합니다[3].

이를 보완하기 위해 claude.md, agents.md 같은 컨텍스트 파일이 등장했습니다.

claude.md는 Anthropic이 2025년 5월 공개한 Claude Code의 프로젝트 가이드 파일로, 대화를 시작할 때 자동으로 로드됩니다. 코드 베이스를 분석해 스스로 컨텍스트 파일을 생성할 수 있어, 초기 설정에 대한 사용자의 부담을 줄여주며 외부 도구 연계, 사용자 지정 명령 등 다양한 기능을 제공합니다[2].
agents.md는 2025년 8월, OpenAI를 비롯한 AI 코딩 에이전트 개발사들이 협력하여 만든 에이전트 전용 표준 파일입니다. 다양한 환경에서 자유롭게 사용할 수 있는 공통 규칙을 지향하기 때문에, 하나의 파일로 프로젝트 내용을 공유할 수 있습니다. 현재 6만 개 이상의 오픈소스 프로젝트에 채택되었으며, 15개 이상의 주요 AI 에이전트를 지원합니다[3].

컨텍스트 파일의 구조적 제약: 명세 기반 개발(SDD)이 필요한 이유

이러한 파일은 기본적인 명세 제공에는 유용했지만, 작업을 구조화하기에는 부족했습니다. 표준화된 작성 방식, 명확한 작업 순서와 판단 기준이 정의되어 있지 않았기 때문입니다. 공식 문서 역시 “프로젝트 아키텍처나 워크플로우를 설명하라”는 수준의 추상적인 안내에 그쳐, 실제 실행 로직은 개발자들이 시행착오를 통해 개별적으로 설계해야 했고, 그로 인해 결과의 일관성을 보장하기 어려웠습니다[4].

이러한 한계는 단순한 프로젝트 안내를 넘어, 작업 과정을 구조화하고 검증 가능한 형태로 관리할 수 있는 새로운 접근의 필요성을 드러냈습니다. 이 지점에서 다시 주목받은 개념이 있는데, 바로 명세 기반 개발(Spec-Driven Development, SDD)입니다.

SDD 도구: GitHub ‘Spec Kit’의 등장

지난 12월 3일 열린 GitHub Universe ’25 Recap Seoul 행사에서 Microsoft의 개발자 Justin Yoo는 SDD 도구 Spec Kit을 소개했습니다[5]. 이번 포스팅에서는 기존 바이브 코딩의 한계를 극복하기 위해 등장한 SDD의 개념을 소개하고, 대표적인 도구들을 비교합니다. 또한 파일 아키텍처는 어떻게 구성되었는지 살펴보려고 합니다. 마지막으로, 직접 따라 해볼 수 있는 Spec Kit 예제까지 함께 준비해보았습니다.

1. SDD(Spec-Driven Development)란?

1975년 소프트웨어 요구사항 명세(Software Requirements Specification, SRS)를 시작으로, 개발 과정에서의 기능 요구사항과 이해관계자 간의 합의를 명세로 정리했습니다. 다만 구현과 직접 연결할 수 있는 수단이 부족해, 실제 개발 과정에서는 점차 형식적인 문서로 남게 되었습니다[6].

최근 다양한 AI 에이전트가 등장하면서, 명세를 실행 가능한 입력으로 활용할 수 있는 환경이 마련되었고, 이에 따라 SRS는 SDD라는 형태로 재정의되며, 바이브 코딩의 한계를 보완하는 대안으로 주목받고 있습니다.

SDD의 핵심은 코드를 작성하기에 앞서 “명세(spec)”를 먼저 완성해야한다는 것입니다. 요구사항, 설계, 에러 조건, 보안 기준을 사전에 명확히 정의함으로써 의도한 결과를 안정적으로 구현하는 것을 목표로 합니다. 이때 명세는 소프트웨어의 의도와 동작을 구조화한 파일이자, AI 코딩 에이전트의 행동을 직접 제어하는 기준으로 작동합니다.

이미지 1. SDD 워크플로우 (제논 재구성). 출처: Marmelab[7]

현재 SDD는 아직 명확하게 정립된 개념이 아니며, 도구와 접근 방식에서 다양한 형태로 발전하고 있습니다. 세계적인 IT 컨설팅 기업 소트웍스(Thoughtworks)의 AI 서비스 전문가 Birgitta는 아래 두 가지 기준을 바탕으로 SDD를 세 가지 유형으로 분류했습니다.

개발 완료 이후에도 초기 명세 파일을 유지하는가
인간이 코드를 직접 관리하는가, 혹은 명세(spec)만 관리하는가

이미지 2. SDD 분류 (제논 재구성). 출처: Thoughtworks[8]

첫번째, 명세 우선(Spec-first) 방식에서 명세는 초기 기능 개발을 돕기 위한 일회성 파일이며, 코드 작성 이후에는 삭제되고 별도로 관리되지 않습니다. 따라서 수정이 필요할 때는 명세 파일을 새롭게 작성해야 합니다.

두번째, 명세 고정(Spec-anchored) 방식에서 명세는 개발 이후에도 코드와 함께 지속적으로 관리됩니다. 이로 인해 기능 변경으로 명세 수정이 필요할 경우, 기존 명세를 불러와 내용을 갱신할 수 있습니다.

세번째, 명세 소스(Spec-as-source) 방식에서 개발자는 명세만 수정하며 코드는 수정하지 않습니다. 또한 명세 고정 방식과 마찬가지로, 수정된 명세는 관리되며 계속 사용됩니다. 이 방식에서는 명세 자체가 주요 소스 파일로써 동작합니다.

이제 SDD가 무엇인지 살펴보았으니, SDD 도구인 Spec Kit에 대해 알아보겠습니다.

이미지 1. SDD 워크플로우 (제논 재구성). 출처: Marmelab[7]

개발 완료 이후에도 초기 명세 파일을 유지하는가
인간이 코드를 직접 관리하는가, 혹은 명세(spec)만 관리하는가

이미지 2. SDD 분류 (제논 재구성). 출처: Thoughtworks[8]

이제 SDD가 무엇인지 살펴보았으니, SDD 도구인 Spec Kit에 대해 알아보겠습니다.

2. 스펙킷(Spec Kit)이란?

이미지 3. 바이브코딩의 끝, Spec Kit. 출처: Meta-Quantum[9]

Spec Kit[10]은 2025년 8월 GitHub가 공개한 오픈소스 CLI 도구로 Claude, Copilot, Gemini 등 다양한 AI 코딩 어시스턴트에 맞는 작업 공간을 자동으로 구성합니다. 초기 작업 공간 구조가 설정되면, 사용자는 명령어를 통해 AI 에이전트와 단계적으로 상호 작용할 수 있으며, 아래에 정리한 세 가지 SDD 도구 중에서도 사용자 정의에 유연한 편에 속합니다.

	Kiro[11]	Spec Kit[10]	Tessl[12]
개발 및 운영	AWS	GitHub	Tessl
방식	명세 우선(Spec-first) 방식	명세 고정형(Spec-anchored) 방식	명세 고정형(Spec-anchored) 접근 방식, 명세 소스(Spec-as-source)로 활용 탐구 중
워크플로우	Requirements→ Design → Tasks → Implements	Constitution → Specify → Plan → Tasks → Implements	Plan → Specify → Implements → Test
지원	다중 모드 입력(codebase, file, docs 등)	커맨드 기반 명령어로 워크플로우 실행	CLI가 MCP 서버 역할 수행
Memory bank	- steering - product.md, tech.md, structure.md	- memory - constitution.md	- .tessl/framework - agents.md, bootstrap.md, plan-files.md, tessl-system-prompt.md - knowledge.md, agents.md
배포	IDE	CLI	CLI
운영체제	Window, macOS, Linux	Window, macOS, Linux	macOS, Linux (x64,arm64), WSL2
기타	-	- 패키지 매니저 : `uv` - Git	- Node.js v22.17.0+
Specs 네이밍 방식	category-label-enhancement	specs/[숫자]-[기능명]	[기능명].spec.md
Specs 구성 파일	- requirements.md - design.md - tasks.md	- data-model.md - plan.md - tasks.md - research.md - spec.md - contracts(api.md, component.md)	단일 spec 파일
명세-코드 매핑	1:n	1:n	1:1
코드 수정	O	O	X
다중 파일 생성	O	O	X (향후 가능성 언급됨)

표 1. SDD 도구 비교표 Kiro vs Spec Kit vs Tessl

이미지 3. 바이브코딩의 끝, Spec Kit. 출처: Meta-Quantum[9]

	Kiro[11]	Spec Kit[10]	Tessl[12]
개발 및 운영	AWS	GitHub	Tessl
방식	명세 우선(Spec-first) 방식	명세 고정형(Spec-anchored) 방식	명세 고정형(Spec-anchored) 접근 방식, 명세 소스(Spec-as-source)로 활용 탐구 중
워크플로우	Requirements→ Design → Tasks → Implements	Constitution → Specify → Plan → Tasks → Implements	Plan → Specify → Implements → Test
지원	다중 모드 입력(codebase, file, docs 등)	커맨드 기반 명령어로 워크플로우 실행	CLI가 MCP 서버 역할 수행
Memory bank	- steering - product.md, tech.md, structure.md	- memory - constitution.md	- .tessl/framework - agents.md, bootstrap.md, plan-files.md, tessl-system-prompt.md - knowledge.md, agents.md
배포	IDE	CLI	CLI
운영체제	Window, macOS, Linux	Window, macOS, Linux	macOS, Linux (x64,arm64), WSL2
기타	-	- 패키지 매니저 : `uv` - Git	- Node.js v22.17.0+
Specs 네이밍 방식	category-label-enhancement	specs/[숫자]-[기능명]	[기능명].spec.md
Specs 구성 파일	- requirements.md - design.md - tasks.md	- data-model.md - plan.md - tasks.md - research.md - spec.md - contracts(api.md, component.md)	단일 spec 파일
명세-코드 매핑	1:n	1:n	1:1
코드 수정	O	O	X
다중 파일 생성	O	O	X (향후 가능성 언급됨)

표 1. SDD 도구 비교표 Kiro vs Spec Kit vs Tessl

2.1 파일 아키텍처

아래 이미지 4에서 보이는 것처럼 Spec Kit은 3개의 주요 폴더으로 나눌 수 있습니다.

이미지 4. Spec Kit 파일 아키텍처(제논 재구성). 출처. Thoughtworks[8]

첫 번째, memory 폴더는 Spec Kit 명령어를 처음 실행할 때 자동으로 생성되며 내부에 constitution.md 파일을 포함합니다. 이 파일에는 speckit.constitution 명령어를 통해 기술 스택, 보안 원칙, 코드 스타일 등 프로젝트 전반에 적용되는 불변 원칙을 정의할 수 있습니다. 또한 모든 Spec Kit 명령어 실행 시 AI 에이전트가 자동으로 참조하여 작업 일관성을 유지합니다.
두 번째, templates 폴더는 plan.md, spec.md, tasks.md 파일들의 기본 작성 형식이 정의되어 있습니다. 각 파일은 해당하는 template.md 파일을 기반으로 생성되며, 이는 에이전트가 명세를 해석하는 방식을 하나로 고정하기 위함입니다. 명세 구조가 고정되지 않으면 동일한 요구사항도 매번 다르게 해석될 수 있기 때문에, 템플릿을 통해 해석 기준을 일관되게 유지합니다. 이러한 기준(constitution.md, template.md)을 바탕으로 AI 에이전트는 Spec Kit 명령어를 통해 작업 산출물을 Specs 폴더에 생성합니다.
세 번째, Specs 폴더에는 /speckit.specify 명령어와 함께 사용자가 원하는 기능에 대한 프롬프트를 입력하면 [번호]-[기능이름] 형식(예: 001-when-a-user)의 폴더가 생성됩니다. 이때, 번호는 001부터 순차적으로 부여되며 중복되지 않기 때문에, 여러 브랜치에서 동시에 작업하더라도 파일명 충돌이 발생하지 않습니다. 또한 기능을 삭제하더라도 번호는 유지되어, 프로젝트의 히스토리 관리에도 용이합니다. 해당 폴더 안에는 기능의 요구사항을 담은 spec.md가 생성됩니다.

이후 /speckit.plan 명령어를 실행하면, 해당 기능을 어떻게 구현할지에 대한 내용이 자동으로 확장됩니다. 이 과정에서 plan.md를 포함하여 data-model.md, research.md, contracts(api.md, component.md), quickstart.md 파일들이 함께 생성됩니다.

이미지 5. /speckit.plan 명령어로 생성되는 파일(제논 재구성). 출처. medium[13]

마지막으로, /speckit.tasks 명령어를 사용해 plan 단계에서 생성된 파일들을 종합적으로 분석하여, 구현 작업 목록을 단계별로 분해하고 tasks.md에 정리합니다. 이렇게 Spec Kit을 활용하면 기존에 바이브 코딩 시간을 크게 단축시키며, 기능 명세부터 구현 계획, API·데이터 모델, 테스트 시나리오, 버전 관리된 파일까지 한 번에 완성할 수 있습니다.

아래 이미지 4에서 보이는 것처럼 Spec Kit은 3개의 주요 폴더으로 나눌 수 있습니다.

이미지 4. Spec Kit 파일 아키텍처(제논 재구성). 출처. Thoughtworks[8]

첫 번째, memory 폴더는 Spec Kit 명령어를 처음 실행할 때 자동으로 생성되며 내부에 constitution.md 파일을 포함합니다. 이 파일에는 speckit.constitution 명령어를 통해 기술 스택, 보안 원칙, 코드 스타일 등 프로젝트 전반에 적용되는 불변 원칙을 정의할 수 있습니다. 또한 모든 Spec Kit 명령어 실행 시 AI 에이전트가 자동으로 참조하여 작업 일관성을 유지합니다.
두 번째, templates 폴더는 plan.md, spec.md, tasks.md 파일들의 기본 작성 형식이 정의되어 있습니다. 각 파일은 해당하는 template.md 파일을 기반으로 생성되며, 이는 에이전트가 명세를 해석하는 방식을 하나로 고정하기 위함입니다. 명세 구조가 고정되지 않으면 동일한 요구사항도 매번 다르게 해석될 수 있기 때문에, 템플릿을 통해 해석 기준을 일관되게 유지합니다. 이러한 기준(constitution.md, template.md)을 바탕으로 AI 에이전트는 Spec Kit 명령어를 통해 작업 산출물을 Specs 폴더에 생성합니다.
세 번째, Specs 폴더에는 /speckit.specify 명령어와 함께 사용자가 원하는 기능에 대한 프롬프트를 입력하면 [번호]-[기능이름] 형식(예: 001-when-a-user)의 폴더가 생성됩니다. 이때, 번호는 001부터 순차적으로 부여되며 중복되지 않기 때문에, 여러 브랜치에서 동시에 작업하더라도 파일명 충돌이 발생하지 않습니다. 또한 기능을 삭제하더라도 번호는 유지되어, 프로젝트의 히스토리 관리에도 용이합니다. 해당 폴더 안에는 기능의 요구사항을 담은 spec.md가 생성됩니다.

이미지 5. /speckit.plan 명령어로 생성되는 파일(제논 재구성). 출처. medium[13]

2.2 Spec Kit의 8단계 워크플로우: 원칙 수립부터 구현까지

이미지 6. Spec Kit 워크플로우. 출처. 제논

Spec Kit은 요구사항을 정리하는 단계부터 구현까지 순서대로 진행하는 워크플로우를 제공하며, 각 단계의 역할과 결과물이 명확히 구분되어 있습니다.

단계	명령어	명령어 유형	역할 (무엇을 하는 단계인가)	핵심 목적	명령어에 포함해야 할 것	명령어에 포함하면 안 되는 것
원칙 수립	`constitution`	핵심 (Core)	프로젝트 전반에 적용되는 기본 원칙 정의	일관된 개발 기준 확립	품질 기준, 정확성, UX 원칙, 제약 조건	기능 요구사항, 기술 선택
요구사항 명세	`specify`	핵심 (Core)	무엇을, 왜 만들 것인지 정리	문제와 목표 명확화	사용자 질문, 기능 범위, 성공 기준	기술 스택, 시스템 구조
요구사항 명확화	`clarify`	선택 (Optional)	애매한 요구사항을 질문과 답변으로 정리	요구사항 명확화	-	새로운 기능 추가, 구현 방법 제시
구현 계획	`plan`	핵심 (Core)	구현 방법과 구조 결정	구현 방향 수립	기술 스택, 시스템 구조, 데이터 흐름	요구사항 변경
명세 점검	`checklist`	선택 (Optional)	요구사항과 설계 내용 점검	누락·모호함 확인	-	코드, 실제 구현 내용
작업 분해	`tasks`	핵심 (Core)	구현 작업을 실행 단위로 분해	바로 실행 가능한 작업 정리	-	추상적인 설계 논의
사전 검증	`analyze`	선택 (Optional)	파일 간 내용이 잘 맞는지 확인	누락·불일치 방지	-	요구사항 추가, 코드 수정
구현	`implement`	핵심 (Core)	앞 단계에서 정리한 내용을 바탕으로 코드를 작성하는 단계	기능 구현	-	요구사항·계획 변경

표 2. Spec Kit의 워크플로우[10]

이미지 6. Spec Kit 워크플로우. 출처. 제논

단계	명령어	명령어 유형	역할 (무엇을 하는 단계인가)	핵심 목적	명령어에 포함해야 할 것	명령어에 포함하면 안 되는 것
원칙 수립	`constitution`	핵심 (Core)	프로젝트 전반에 적용되는 기본 원칙 정의	일관된 개발 기준 확립	품질 기준, 정확성, UX 원칙, 제약 조건	기능 요구사항, 기술 선택
요구사항 명세	`specify`	핵심 (Core)	무엇을, 왜 만들 것인지 정리	문제와 목표 명확화	사용자 질문, 기능 범위, 성공 기준	기술 스택, 시스템 구조
요구사항 명확화	`clarify`	선택 (Optional)	애매한 요구사항을 질문과 답변으로 정리	요구사항 명확화	-	새로운 기능 추가, 구현 방법 제시
구현 계획	`plan`	핵심 (Core)	구현 방법과 구조 결정	구현 방향 수립	기술 스택, 시스템 구조, 데이터 흐름	요구사항 변경
명세 점검	`checklist`	선택 (Optional)	요구사항과 설계 내용 점검	누락·모호함 확인	-	코드, 실제 구현 내용
작업 분해	`tasks`	핵심 (Core)	구현 작업을 실행 단위로 분해	바로 실행 가능한 작업 정리	-	추상적인 설계 논의
사전 검증	`analyze`	선택 (Optional)	파일 간 내용이 잘 맞는지 확인	누락·불일치 방지	-	요구사항 추가, 코드 수정
구현	`implement`	핵심 (Core)	앞 단계에서 정리한 내용을 바탕으로 코드를 작성하는 단계	기능 구현	-	요구사항·계획 변경

표 2. Spec Kit의 워크플로우[10]

[실습] Spec Kit으로 챗봇 개발하기 (소요시간: ~2h)

그럼 이제 직접 사용해볼까요? 차근차근 따라오시기만 하면 됩니다.

이번 실습에서는 Spec Kit을 활용해 서울 윈터페스타 안내 챗봇을 개발합니다.

해당 챗봇은 사용자가 검색하듯 질문하면 공식 웹 정보를 기반으로 확인된 사실만을 간결하게 제공하며, 모든 답변에 출처를 함께 제시합니다. 공식 정보가 확인되지 않거나 관련 내용을 찾을 수 없는 경우에는 그 사실을 명확히 안내합니다.

환경 조건

이번 실습은 다음과 같은 환경을 기준으로 진행합니다.

항목	내용
운영 체제	Linux (Ubuntu 22.04)
Python	Python 3.11
패키지 관리	uv
AI Agent	Codex

표 3. 실습 환경 구성

Specify CLI 설치하기

Spec Kit을 사용하기 위해 Specify CLI를 설치합니다[10]. Specify CLI는 영구 설치 방식과 일회성 실행 방식 두 가지 방법으로 사용할 수 있습니다. 이번 실습에서는 관리와 재사용이 용이한 영구 설치 방식을 사용하며, 설치 없이 한 번만 실행해보고 싶은 경우에는 일회성 실행 방식을 선택할 수 있습니다.

방법 1. 영구 설치

영구 설치 방식은 한 번만 설치하면 이후 어떤 프로젝트에서도 Specify CLI를 바로 사용할 수 있는 방법입니다.

먼저 다음 명령어를 실행하여 Specify CLI를 설치합니다.

uv tool install specify-cli --from git

설치가 완료되면, 아래 명령어를 통해 프로젝트를 초기화합니다.

specify init <프로젝트명> --ai

이번 실습에서 사용하는 프로젝트명은 “Spec-kit-demo”입니다.

이미 작업 중인 디렉터리가 있다면, 현재 위치에서 바로 초기화할 수도 있습니다.

specify init . --ai

또는 다음과 같이 실행할 수도 있습니다.

specify init --here --ai

설치가 정상적으로 완료되었는지 확인하려면 아래 명령어를 실행합니다.

추후 Specify CLI 업데이트가 필요한 경우에는 다음 명령어로 재설치할 수 있습니다.

uv tool install specify-cli --force --from git

방법 2. 일회성 실행

일회성 실행 방식은 Specify CLI를 설치하지 않고 단일 명령어로 실행할 수 있어 테스트용으로 적합합니다.

uvx --from git+https://github.com/github/Spec-kit.git specify init <프로젝트명> --ai

두 가지 방법의 실행 과정을 거치면 생성되는 디렉토리 구조는 2.1 파일 아키텍처의 이미지 4를 참고하면 됩니다.

그럼 이제 직접 사용해볼까요? 차근차근 따라오시기만 하면 됩니다.

이번 실습에서는 Spec Kit을 활용해 서울 윈터페스타 안내 챗봇을 개발합니다.

환경 조건

이번 실습은 다음과 같은 환경을 기준으로 진행합니다.

항목	내용
운영 체제	Linux (Ubuntu 22.04)
Python	Python 3.11
패키지 관리	uv
AI Agent	Codex

표 3. 실습 환경 구성

Specify CLI 설치하기

방법 1. 영구 설치

영구 설치 방식은 한 번만 설치하면 이후 어떤 프로젝트에서도 Specify CLI를 바로 사용할 수 있는 방법입니다.

먼저 다음 명령어를 실행하여 Specify CLI를 설치합니다.

uv tool install specify-cli --from git

설치가 완료되면, 아래 명령어를 통해 프로젝트를 초기화합니다.

specify init <프로젝트명> --ai

이번 실습에서 사용하는 프로젝트명은 “Spec-kit-demo”입니다.

이미 작업 중인 디렉터리가 있다면, 현재 위치에서 바로 초기화할 수도 있습니다.

specify init . --ai

또는 다음과 같이 실행할 수도 있습니다.

specify init --here --ai

설치가 정상적으로 완료되었는지 확인하려면 아래 명령어를 실행합니다.

추후 Specify CLI 업데이트가 필요한 경우에는 다음 명령어로 재설치할 수 있습니다.

uv tool install specify-cli --force --from git

방법 2. 일회성 실행

일회성 실행 방식은 Specify CLI를 설치하지 않고 단일 명령어로 실행할 수 있어 테스트용으로 적합합니다.

uvx --from git+https://github.com/github/Spec-kit.git specify init <프로젝트명> --ai

두 가지 방법의 실행 과정을 거치면 생성되는 디렉토리 구조는 2.1 파일 아키텍처의 이미지 4를 참고하면 됩니다.

- 실행 과정

Spec Kit은 사용하는 에이전트에 따라 명령어 형식에 약간의 차이가 있습니다. codex 에이전트의 경우 speckit 명령어 앞에 prompts:가 붙는 것이 특징입니다. 파일을 한국어로 생성하기 위해, 모든 명령어에 한국어로 기재하라는 지시를 함께 작성해야 합니다.

이어서 실행 명령어와 생성된 결과 파일의 일부를 함께 살펴보겠습니다.

Constitution

명령어

가장 먼저 /prompts:speckit.constitution 명령어를 실행합니다. 이 단계에서는 프로젝트 전반에 적용될 개발 원칙과 기준을 정리한 constitution.md 파일이 생성되며, 이후 모든 단계에서 적용될 기준을 고정합니다.

이때, Spec Kit 템플릿에서 원칙을 신규로 정하는 경우이므로, 초기 버전은 1.0.0(MAJOR)으로 설정됩니다.

결과

Specify

명령어

이어서 /prompts:speckit.specify 명령어를 실행해 기능을 구체화합니다. 이 과정에서 브랜치와 함께 spec.md, requirements.md가 생성됩니다.

spec.md에는 답변 처리 방식, 연속 질문 처리, 다중 질문 분리 기준, 응답 분량 제한 등 세부 요구사항이 정리되며, 이후 구현 단계의 판단 기준으로 활용됩니다.

추가적으로, requirements.md는 요구사항이 충분히 정의되었는지를 점검하기 위한 파일로, 각 항목에 대한 검토가 완료되면 체크 표시(x)가 추가됩니다.

`spec.md` 결과

`requirements.md` 결과

## Requirement Completeness

- [x] Requirements are testable and unambiguous
- [x] Edge cases are identified
- [x]

Clarify

명령어

/prompts:speckit.clarify는 Specify 단계에서 명확하지 않았던 요구사항에 대해 질문을 생성합니다. 세션은 최대 다섯 번까지 진행되며, 이 과정에서 생성된 질문과 답변은 spec.md의 Clarifications 섹션에 자동으로 정리됩니다.

결과

Plan

명령어

/prompts:speckit.plan을 실행하면, 앞서 정의된 요구사항을 바탕으로 구현 방법과 기술 구성을 정리한 파일이 생성됩니다. 이때, 구체적으로 설정하지 않은 부분도 현재 상황에 맞게 계획됩니다.

결과

Checklist

명령어

선택 명령어인 /prompts:speckit.checklist를 실행하면, 앞서 정의한 내용의 정합을 점검하기 위한 체크리스트가 생성됩니다. 결과에 따라 명세의 일부가 수정될 수 있으며, 필요한 경우에만 plan에 최소한의 보완이 반영됩니다.

Tasks

실행 명령어

/prompts:speckit.tasks를 실행하면, plan을 기준으로 실제 구현이 가능한 작업 단위(Task) 목록이 생성됩니다. 각 task는 대응하는 요구사항과 명확히 연결되어 이후 구현 단계의 기준이 됩니다.

결과

## Phase 1: Setup (Shared Infrastructure)

Purpose: 프로젝트 골격과 데모 페이지 기본 틀 구성

- [x] T001 FastAPI 앱 엔트리포인트와 템플릿/정적 경로 마운트 추가 in `src/app.py`
- [x] T002 [P] API 라우터 골격 생성 in `src/api/routes.py`
- [x] T003 [P]

Analyze

명령어

선택 명령어인 /prompts:speckit.analyze를 실행하면 명세, plan, tasks 간의 정합성과 커버리지를 분석한 결과가 출력되며, 누락된 요구사항이나 추가 검토가 필요한 항목을 확인할 수 있습니다.

Implement

/prompts:speckit.implement 실행 시 task를 기준으로 코드 구현이 진행되며, Spec Kit 워크플로우의 기본 흐름이 완료됩니다.

이어서 실행 명령어와 생성된 결과 파일의 일부를 함께 살펴보겠습니다.

Constitution

명령어

이때, Spec Kit 템플릿에서 원칙을 신규로 정하는 경우이므로, 초기 버전은 1.0.0(MAJOR)으로 설정됩니다.

결과

Specify

명령어

이어서 /prompts:speckit.specify 명령어를 실행해 기능을 구체화합니다. 이 과정에서 브랜치와 함께 spec.md, requirements.md가 생성됩니다.

추가적으로, requirements.md는 요구사항이 충분히 정의되었는지를 점검하기 위한 파일로, 각 항목에 대한 검토가 완료되면 체크 표시(x)가 추가됩니다.

`spec.md` 결과

`requirements.md` 결과

## Requirement Completeness

- [x] Requirements are testable and unambiguous
- [x] Edge cases are identified
- [x]

Clarify

명령어

결과

Plan

명령어

결과

Checklist

명령어

Tasks

실행 명령어

결과

## Phase 1: Setup (Shared Infrastructure)

Purpose: 프로젝트 골격과 데모 페이지 기본 틀 구성

- [x] T001 FastAPI 앱 엔트리포인트와 템플릿/정적 경로 마운트 추가 in `src/app.py`
- [x] T002 [P] API 라우터 골격 생성 in `src/api/routes.py`
- [x] T003 [P]

Analyze

명령어

Implement

/prompts:speckit.implement 실행 시 task를 기준으로 코드 구현이 진행되며, Spec Kit 워크플로우의 기본 흐름이 완료됩니다.

- 챗봇 구현 결과

이미지 7. 챗봇 실행 결과. 출처. 제논

Spec Kit을 활용하여 구현한 서울 윈터페스타 챗봇의 실행 결과입니다. 사용자는 데모 페이지에서 질문을 입력하면, 공식·신뢰 가능한 웹 정보를 기반으로 정리된 답변과 함께 출처를 확인할 수 있습니다. 이 챗봇은 복잡한 기능을 많이 포함하고 있지는 않지만, 짧은 시간 안에 검색형 질문에 대응하는 출처 기반의 정확한 챗봇을 구현했다는 점에서 의미가 있습니다.

다만 명세 보존 방식(Spec-anchored)을 사용하는 Spec Kit에서는 생성된 결과를 그대로 신뢰하기보다, 개발자가 직접 검증하는 과정이 권장됩니다. 이번 실습에서도 일부 답변이 2024년 기준 정보를 포함하거나 공식 출처가 아닌 링크를 사용해, 이를 직접 확인해 수정했습니다. 이를 통해 Spec Kit의 핵심은 명확한 명세를 기준으로 AI를 활용하되, 사람의 점검과 보완을 전제로 하는 개발 흐름임을 확인할 수 있었습니다.

이상으로 SDD와 Spec Kit의 개념, 그리고 실습 전 과정을 살펴보았습니다. 직접 명세를 정의하고 구현해 보면서, 개발이 실제로 어떻게 작동하는지 경험해 보시길 바랍니다.