05. Spec Kit과 Specify CLI로 시작하는 Spec-Driven Development 환경 구축

Spec Kit + Specify CLI로 SDD 시작하기

• GitHub의 SDD(Spec-Driven Development)를 실제로 적용하기 위한 개발 환경을, Spec Kit과 Specify CLI로 단계별 구축한다.
• 핵심 메시지
  • 이 가이드는 “SDD 개념 소개”가 아니라, SDD를 바로 실행 가능한 형태로 셋업하는 실습형 문서입니다.
  • Spec Kit(템플릿/구조)과 Specify CLI(초기화/자동화)를 사용하면 체계적인 개발 프로세스(명세→계획→태스크)를 빠르게 시작할 수 있습니다.
• 읽는 사람이 여기서 얻어야 하는 것
  • “환경 구축을 끝내면 무엇이 가능해지는가?” → 다음 페이지부터 설치 → 프로젝트 초기 구조 → 가상환경 → Spec Kit 초기화 순으로 바로 실행합니다.

---

Spec Kit과 Specify CLI 설치하기 — 사전 요구사항 + 설치/확인/업데이트

사전 요구사항(설치 전 반드시 준비)

• Python 3.11 이상
• Git 버전 관리 시스템
• uv 패키지 관리자
• 코딩 에이전트( GitHub Copilot 권장 )
• Linux/macOS 또는 Windows WSL2

추가 안내(문서 하단): Windows 11 사용자라면 PowerShell에서도 Specify CLI가 정상 동작하며, WSL2 없이도 실습 진행이 가능합니다.

Specify CLI “영구 설치”(Persistent Installation)

공식 README에서 권장하는 방식으로 설치합니다.

uv tool install specify-cli --from git+https://github.com/github/spec-kit.git

 

설치 확인

설치가 정상인지 바로 확인합니다.

specify --help

업데이트가 필요한 경우(강제 재설치)

버전 꼬임/업데이트가 필요하면 --force로 다시 설치합니다.

uv tool install specify-cli --force --from git+https://github.com/github/spec-kit.git

---

실습 프로젝트 초기 구조 만들기 — 폴더 생성 + Git 초기화 + 원격 저장소 연결

01) 프로젝트 폴더 생성 및 Git 초기화

먼저 실습용 프로젝트 디렉터리를 만들고, Git 저장소로 초기화합니다.

 

mkdir web-calculator-speckit
cd web-calculator-speckit
git init

(선택이 아니라 “필수 흐름”) 원격 저장소 연결

원격 저장소까지 연결해두면 이후 작업이 깔끔해집니다.

git remote add origin https://github.com/[사용자명]/web-calculator-speckit.git

 

 

02) 개발 환경 디렉토리 구성(이 단계의 의미)

• 이 단계에서 프로젝트의 기본 뼈대가 완성됩니다.
• Git으로 버전 관리가 시작되고, 다음 단계에서 Spec Kit 구조가 프로젝트에 추가됩니다.
• 즉, “먼저 Git으로 뼈대 고정 → 그 위에 SDD 구조 얹기” 흐름을 따릅니다.

---

Python 가상환경 구성하기 — venv 생성/활성화 + VS Code 인터프리터 설정 + 실행 정책 해결

1) 가상환경 생성 및 활성화(Windows PowerShell 기준)

프로젝트별로 독립적인 Python 패키지 환경을 유지하기 위해 .venv를 사용합니다.

python -m venv .venv
.\.venv\Scripts\Activate.ps1

• 가상환경을 사용하면 프로젝트마다 패키지 버전 충돌을 방지하고, SDD 도구/스크립트 실행 환경이 안정화됩니다.

 

2) VS Code에서 인터프리터 설정

가상환경을 만들었으면 VS Code가 그 Python을 사용하도록 지정합니다.

1. File → Open Folder로 web-calculator-speckit 폴더 열기
2. 커맨드 팔레트(CTRL + SHIFT + P) 실행
3. Python: Select Interpreter 선택
4. .venv\Scripts\python.exe 선택

 

3) 실행 정책 에러 해결(가상환경 활성화가 막힐 때)

PowerShell에서
“이 시스템에서 스크립트를 실행할 수 없습니다” 같은 메시지가 뜨면 아래를 실행합니다.

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

 

• 이 설정은 로컬에서 작성한 스크립트 실행을 허용해, 가상환경 활성화/도구 설치가 정상 진행되도록 합니다.

---

Spec Kit으로 SDD 프로젝트 초기화 — specify init --here + 생성 구조/역할 정리

1) Spec Kit 초기화(가상환경 활성화 상태에서 실행)

가상환경이 활성화된 상태에서 아래 명령으로 SDD 구조를 생성합니다.

specify init --here

 

• 실행 중 “코딩 에이전트 선택 화면”이 나오면 GitHub Copilot을 선택합니다.

 

2) 초기화 후 자동 생성되는 파일 구조

초기화가 완료되면 아래와 같은 디렉터리/파일이 생성됩니다.

.github/
  prompts/
    plan.prompt.md
    specify.prompt.md
    tasks.prompt.md

.specify/
  memory/
    constitution.md
    constitution_update_checklist.md

scripts/
  powershell/...

templates/...

 

 

3) 각 구성요소의 역할(무조건 이해하고 넘어가야 하는 부분)

• .github/prompts/
  • AI 에이전트를 위한 프롬프트 템플릿이 위치합니다.
  • specify / plan / tasks 단계별로 “어떤 형식으로 작성해야 하는지”를 강제합니다.
• .specify/memory/
  • 프로젝트의 히스토리/컨텍스트를 저장하는 공간입니다.
  • SDD가 “명세를 살아 있게 유지”하려면 여기의 컨텍스트가 기준점이 됩니다.
• constitution.md
  • 프로젝트의 핵심 원칙(가드레일)과 가이드라인입니다.
  • 이후 생성되는 명세/계획/태스크/코드가 이 원칙을 따라야 일관성이 유지됩니다.
• scripts/
  • 자동화를 위한 스크립트 모음입니다.
  • 환경별 실행(예: PowerShell)과 반복 작업을 안정적으로 수행하기 위해 사용됩니다.
• templates/
  • SDD 산출물(명세/계획/작업)의 기본 템플릿이 들어가는 영역입니다.
  • 팀 표준 형식을 만드는 핵심 재료가 됩니다.

---

이 문서의 최종 결과(이 상태가 “완료”)

여기까지 끝내면 프로젝트는 다음을 만족합니다.

• Git으로 버전 관리가 시작되어 있고
• .venv로 실행 환경이 고정되어 있으며
• specify init --here로 **SDD 작업 구조(프롬프트/메모리/헌법/템플릿)**가 생성된 상태

즉, 이제부터는 “명세 → 계획 → 태스크” 기반으로 SDD 개발을 바로 진행할 수 있습니다.