[Spec Kit ②] Spec Kit 시작하기 — specify CLI 설치부터 Claude Code 연동까지

1부에서 우리는 바이브 코딩이 무너지는 지점과, 명세를 진실의 원천으로 두는 Spec-Driven Development(SDD)의 발상을 짚었습니다. 이론은 충분합니다. 이번 글에서는 말을 멈추고 손을 움직입니다. specify CLI를 설치하고, 빈 디렉터리에 SDD 스캐폴딩을 깔고, Claude Code 안에서 /speckit.* 명령이 살아나는 데까지 — 정확히 한 번에 — 따라가 봅니다. 우리가 시리즈 내내 함께 만들 예제 프로젝트, 실시간 데이터 품질 모니터링 서비스(dq-monitor) 의 첫 골격도 이 과정에서 함께 세웁니다.

이 글에서 배우는 것

• specify CLI를 설치하기 위한 전제 조건(Python 3.11+, Git, uv)과 설치 절차
• specify init으로 프로젝트를 부트스트랩하고 AI 에이전트를 연결하는 법
• 생성된 .specify/ 스캐폴딩의 해부 — 어떤 디렉터리가 무엇을 담당하는가
• Claude Code 안에서 /speckit.* 슬래시 커맨드가 활성화되는 원리
• 시리즈 전체를 관통하는 /speckit.* 명령 로드맵 미리보기

이 글은 Spec Kit 시리즈의 2부입니다. 1부 왜 Spec-Driven Development인가에서 다룬 "명세가 진실의 원천"이라는 전제를 실제 도구 설치로 옮기는 단계입니다. 1부를 아직 읽지 않았다면 먼저 훑어보길 권합니다 — 이 글의 모든 명령은 그 전제 위에서 의미를 가집니다.

1. 전제 조건 — 무엇이 필요한가

specify CLI는 Python으로 작성됐고, 프로젝트 부트스트랩 과정에서 Git을 사용합니다. 시작 전 다음 세 가지를 준비합니다.

uv는 Python 패키지·도구를 빠르게 설치하고 전역 오염 없이 격리해 주는 관리자입니다. Spec Kit 공식 문서가 권장하는 설치 경로이며, pipx도 대안으로 쓸 수 있습니다. 아직 uv가 없다면 한 줄로 설치합니다.

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
 
# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

설치 후 새 셸을 열거나 source로 PATH를 갱신한 뒤, 세 도구가 모두 잡히는지 확인합니다.

python3 --version   # Python 3.11.x 이상
git --version       # git version 2.x
uv --version        # uv 0.x

uv 대신 pipx를 선호한다면, 아래 설치 명령에서 uv tool install을 pipx install로 바꾸면 됩니다. 이 글은 공식 권장인 uv를 기준으로 진행합니다.

2. Specify CLI 설치

전제가 갖춰졌다면 CLI 본체를 설치합니다. Spec Kit은 PyPI 패키지가 아니라 GitHub 저장소에서 직접 설치하며, 설치 시점에 릴리스 태그를 고정하는 것을 권장합니다. 고정하지 않으면 기본 브랜치의 변동에 영향을 받아 재현성이 떨어집니다.

uv tool install specify-cli \
  --from git+https://github.com/github/spec-kit.git@vX.Y.Z

여기서 vX.Y.Z는 최신 릴리스 태그로 바꿔야 합니다. 최신 태그는 저장소의 Releases 페이지에서 확인할 수 있습니다. 예를 들어 최신 릴리스가 v0.0.42라면 다음과 같이 적습니다.

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

설치가 끝나면 specify 명령이 PATH에 등록됩니다. 정상 설치 여부를 확인합니다.

specify --help
specify check     # 필요한 런타임·도구가 갖춰졌는지 환경 점검

specify check는 Python·Git 등 런타임이 제대로 잡히는지 사전 점검하는 명령입니다. 여기서 빠진 게 있으면 init 단계에서 실패하므로, 먼저 통과시켜 두는 편이 좋습니다.

팁 — 버전 고정의 이유. SDD는 명세 파일을 진실의 원천으로 삼습니다. 그런데 그 명세를 다루는 템플릿 자체가 버전마다 바뀝니다. 팀 전체가 같은 태그를 쓰도록 고정하면, 같은 /speckit.specify가 같은 산출물 형태를 내놓아 일관성이 유지됩니다. 업그레이드는 의식적으로, 태그를 바꿔 다시 설치하는 방식으로 진행하세요.

3. 프로젝트 초기화 — specify init

이제 본 게임입니다. 우리 예제 프로젝트 dq-monitor를 부트스트랩합니다.

specify init dq-monitor --integration claude
cd dq-monitor

이 한 줄이 하는 일은 다음과 같습니다.

1. dq-monitor/ 디렉터리를 만들고 Git 저장소로 초기화합니다.
2. 지정한 AI 에이전트(여기서는 Claude Code)에 맞는 템플릿과 슬래시 커맨드 정의를 다운로드해 배치합니다.
3. SDD 워크플로가 동작할 .specify/ 스캐폴딩을 깔아 둡니다.

--integration은 무엇을 결정하는가

specify는 현재 환경을 보고 어떤 AI 에이전트를 쓰는지 자동 감지하려 시도합니다. 하지만 자동 감지는 환경에 따라 빗나갈 수 있으므로, --integration 플래그로 명시적으로 강제하는 편이 안전합니다. 우리는 Claude Code를 쓰므로 --integration claude를 줬습니다.

Spec Kit은 특정 도구에 종속되지 않습니다. 지원하는 에이전트 목록은 다음 명령으로 확인합니다.

specify integration list

이 명령은 30개 이상의 지원 에이전트를 출력합니다 — Claude Code뿐 아니라 GitHub Copilot, Gemini CLI, Cursor, Codex 등이 포함됩니다. 일부 에이전트는 스킬(skills) 모드를 지원하며, 이 경우 옵션을 덧붙입니다.

specify init dq-monitor \
  --integration claude \
  --integration-options="--skills"

핵심: 명세·계획·작업은 텍스트 파일로 남기 때문에 에이전트를 바꿔도 자산이 그대로 남습니다. 오늘 Claude Code로 시작했다가 내일 다른 에이전트로 옮겨도, specs/와 .specify/의 내용은 그대로 재사용됩니다. 이것이 1부에서 강조한 "잠금 없음(no lock-in)"의 실체입니다.

자주 쓰는 init 옵션을 정리하면 다음과 같습니다.

4. 생성된 스캐폴딩 해부

cd dq-monitor 후 디렉터리 구조를 보면, 핵심은 점(.)으로 시작하는 .specify/ 디렉터리에 모여 있습니다. SDD의 "운영 자산"이 여기에 담깁니다.

dq-monitor/
├── .specify/
│   ├── memory/
│   │   └── constitution.md      # 프로젝트를 관통하는 원칙(헌법)
│   ├── templates/               # Spec Kit 핵심 템플릿(spec/plan/tasks 등)
│   ├── presets/                 # 템플릿 커스터마이징 오버라이드
│   └── extensions/              # 서드파티 기능 확장
├── specs/                       # 기능별 산출물이 쌓이는 곳(초기엔 비어 있음)
└── (에이전트별 슬래시 커맨드 정의 파일)

각 디렉터리의 역할을 표로 정리합니다.

specs/는 나중에 이렇게 채워진다

지금 specs/는 비어 있지만, 4부에서 /speckit.specify를 돌리면 기능 단위 폴더가 번호와 함께 생깁니다. 미리 형태를 보여드리면 다음과 같습니다.

specs/
└── 001-freshness-monitor/       # 기능 단위(번호 + 슬러그)
    ├── spec.md                  # 무엇/왜 — 요구사항·유저 스토리
    ├── plan.md                  # 어떻게 — 기술 스택·아키텍처
    ├── tasks.md                 # 의존성 순서가 있는 작업 목록
    ├── data-model.md            # 데이터 모델(엔티티·관계)
    ├── contracts/               # API 계약(인터페이스 정의)
    ├── research.md              # 기술 조사·의사결정 기록
    └── quickstart.md            # 기능 검증용 빠른 시작 시나리오

이 구조가 곧 SDD의 "진실의 원천"입니다. 기능을 바꾸려면 코드가 아니라 이 파일들을 먼저 고치고, 코드는 여기서 다시 생성·검증됩니다. 1부에서 그림으로만 봤던 "명세 → 코드"의 방향이, 디스크 위 실제 파일로 구현된 모습입니다.

5. AI 에이전트 연결 — Claude Code에서 /speckit.* 살리기

스캐폴딩이 깔렸으면, 이제 AI 에이전트가 그것을 인식하게 할 차례입니다. 우리 독자에게 익숙한 Claude Code를 기준으로 봅니다.

핵심 원리는 간단합니다. specify init --integration claude가 프로젝트 루트에 Claude Code가 읽는 형식의 슬래시 커맨드 정의 파일들을 배치했습니다. Claude Code를 이 디렉터리에서 열면, 그 정의를 읽어 /speckit.* 명령들을 프로젝트 로컬 슬래시 커맨드로 등록합니다.

# dq-monitor 디렉터리에서
claude

Claude Code가 뜬 뒤 슬래시 메뉴를 열어 /speckit 으로 시작하는 명령들이 보이면 연동 성공입니다. 이제 /speckit.constitution, /speckit.specify 같은 명령을 에이전트 안에서 바로 호출할 수 있습니다.

> /speckit.
  /speckit.constitution    프로젝트 원칙 수립
  /speckit.specify         요구사항 명세
  /speckit.clarify         모호성 제거
  /speckit.plan            기술 설계
  /speckit.tasks           작업 분해
  ... (이하 표 참고)

다른 에이전트도 원리는 같습니다. Spec Kit은 각 에이전트가 슬래시 커맨드를 인식하는 고유 형식에 맞춰 정의 파일을 생성하므로, GitHub Copilot·Gemini CLI·Cursor·Codex 등에서도 동일한 /speckit.* 워크플로를 그대로 쓸 수 있습니다. 도구는 갈아끼우되, 워크플로와 산출물은 보존됩니다.

6. 첫 접촉 — /speckit.constitution 맛보기와 전체 로드맵

연동을 확인했으니, 워크플로의 첫 단추가 무엇인지만 짚고 다음 글로 넘기겠습니다. SDD 워크플로는 항상 헌법(constitution) 에서 시작합니다.

> /speckit.constitution

이 명령은 .specify/memory/constitution.md를 채우는 대화를 시작합니다 — 코드 품질, 테스트 전략, 관측 가능성, 데이터 정확성 같은 프로젝트를 관통하는 원칙을 합의하는 단계입니다. 데이터 팀에 맞는 헌법을 어떻게 세우는지는 3부에서 본격적으로 다룹니다. 지금은 "워크플로가 헌법에서 출발한다"는 것만 기억하면 됩니다.

/speckit.* 명령 로드맵

시리즈 전체에서 우리가 손에 쥘 명령들의 전체 지도입니다. 각 명령은 SDD의 한 단계를 담당하며, 대체로 위에서 아래 순서로 흐릅니다.

다시 강조: 이 명령들은 한 방에 코드를 뽑는 마법이 아닙니다. 각 단계가 끝날 때마다 사람이 산출물을 검토하는 multi-step refinement 구조가 품질의 원천입니다. /speckit.analyze가 /speckit.tasks 뒤·/speckit.implement 앞에 자리하는 것도 이 때문입니다 — 코드를 짜기 전에 명세·계획·작업의 정합성을 먼저 확인하는 게이트입니다.

7. 설치부터 첫 명령까지 — 전체 흐름

지금까지의 과정을 한 장으로 정리하면 다음과 같습니다. 설치는 직선이고, 진짜 반복은 /speckit.* 워크플로 안에서 일어납니다(3부 이후).

이 흐름을 한 번 통과하면, 빈 디렉터리가 SDD를 굴릴 수 있는 작업장으로 바뀝니다. 디스크 위에는 .specify/가, 에이전트 안에는 /speckit.*가 준비된 상태입니다.

마치며

이번 글에서 우리는 이론에서 손으로 내려왔습니다. uv로 specify CLI를 설치하고, 릴리스 태그를 고정하고, specify init dq-monitor --integration claude로 예제 프로젝트의 골격을 세웠습니다. 생성된 .specify/ 스캐폴딩의 각 디렉터리가 무엇을 담당하는지 해부했고, Claude Code 안에서 /speckit.* 명령이 어떻게 살아나는지, 그리고 시리즈 전체에서 우리가 쓸 명령의 전체 지도를 미리 펼쳐 봤습니다.

이제 작업장은 준비됐지만, 아직 단 한 줄의 명세도 쓰지 않았습니다. 좋은 SDD는 코드가 아니라 원칙에서 시작합니다. 다음 3부에서는 워크플로의 첫 단추인 /speckit.constitution을 본격적으로 돌려, 우리 dq-monitor 프로젝트의 헌법(Constitution) 을 세웁니다 — 데이터 정확성, 알림 신뢰성, 관측 가능성처럼 데이터 팀이 양보할 수 없는 원칙들을, 모든 후속 단계가 참조하는 기준으로 못 박는 단계입니다.

참고 자료

• GitHub Spec Kit 저장소
• Spec Kit 공식 문서
• Spec Kit Quickstart
• Diving Into Spec-Driven Development With GitHub Spec Kit (Microsoft for Developers)