Spec Kit 설치 방법: specify-cli와 /speckit-* 명령어 변경점

Spec Kit은 GitHub이 공개한 스펙 기반 개발(Spec-Driven Development) 툴킷입니다. 먼저 명세를 쓰고, 이어서 계획과 작업을 만든 뒤, AI 코딩 어시스턴트가 작업을 구현하게 합니다. 명령줄 도구 이름은 specify이며 specify-cli 패키지로 제공됩니다.

인터넷의 많은 튜토리얼이 아직도 예전 설치 명령, --ai 옵션, /speckit.specify 같은 명령 이름을 쓰고 있어서 그대로 따라 하면 오류가 나는 경우가 많습니다. 이 문서는 공식 문서를 기준으로 현재의 올바른 방법을 정리하고, 무엇이 바뀌었는지 보여 줍니다.

확인 시점

Spec Kit 공식 문서를 기준으로 2026-10-26에 확인했습니다. 프로젝트가 빠르게 바뀌므로 내용이 다르면 이 문서보다 내 컴퓨터의 specify --help와 공식 문서를 우선하세요.

이런 분께 맞습니다

Claude Code, GitHub Copilot, Gemini CLI, CodeBuddy CLI, Pi, Oh My Pi 같은 AI 코딩 어시스턴트에서 스펙 기반 흐름을 써 보고 싶은 분.
예전 튜토리얼대로 Spec Kit을 설치했다가 지금은 오류가 나거나 명령이 보이지 않는 분.

사전 준비

항목	요구 사항
OS	Linux, macOS 또는 Windows(PowerShell 스크립트는 WSL 없이 동작)
Python	3.11 이상
패키지 관리자	uv(권장) 또는 pipx
AI 코딩 어시스턴트	지원되는 어시스턴트 아무거나. 공식 문서에 수십 개의 통합이 나와 있습니다
Git	선택 사항. git 확장을 켤 때만 필요

Spec Kit 자체는 Node.js가 필요하지 않습니다. 어시스턴트를 npm으로 설치한다면 먼저 AI Agent CLI 설치를 확인하세요.

specify-cli 설치

방법 1: PyPI에서 설치(가장 짧음)

# 권장: uv
uv tool install specify-cli

# 또는 pipx
pipx install specify-cli

# 또는 pip
pip install specify-cli

버전을 고정하려면 uv tool install specify-cli==0.12.11처럼 씁니다(버전은 릴리스 페이지에서 확인하세요).

방법 2: GitHub 릴리스 태그에서 설치

공식 문서가 재현 가능한 권장 방식으로 소개합니다. uv가 필요합니다.

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

vX.Y.Z를 Releases의 태그로 바꾸세요. 맨 앞의 v는 반드시 남겨야 합니다. 예: v0.12.11.

설치 확인

specify version
specify self check

specify version은 명령이 동작하는지 확인하고 버전을 출력합니다. specify self check는 읽기 전용이며 더 새로운 릴리스가 있는지 알려 줍니다.

프로젝트 초기화

specify init my-project --integration claude
cd my-project

--integration으로 AI 어시스턴트를 고릅니다. 자주 쓰는 값은 claude, copilot, gemini, codebuddy, pi, omp입니다. 유용한 옵션은 다음과 같습니다.

--script sh|ps|py: 스크립트 종류를 고릅니다. 기본값은 Windows에서 ps, 그 외에는 sh입니다.
--here --force: 이미 있는 비어 있지 않은 디렉터리에서 초기화합니다. --force는 병합 경고를 확인했다는 뜻이므로 먼저 로컬 변경 사항을 커밋하거나 백업하세요.
--non-interactive: CI용입니다. --integration을 주지 않으면 기본으로 GitHub Copilot이 선택되니 주의하세요.

명령 이름: `/speckit-*`

초기화한 뒤에는 터미널이 아니라 AI 어시스턴트의 채팅창에서 다음 명령을 실행합니다.

단계	명령	하는 일
1	`/speckit-constitution`	이후 단계가 기준으로 삼는 프로젝트 원칙을 작성합니다. 프로젝트당 한 번
2	`/speckit-specify`	만들 기능을 일상 언어로 설명하면 `spec.md`를 만듭니다
3	`/speckit-clarify`	명세의 빈틈을 질문하고 답을 명세에 반영합니다
4	`/speckit-plan`	기술 스택에 맞춰 `plan.md` 등 설계 산출물을 만듭니다
5	`/speckit-checklist`	요구 사항 품질 체크리스트를 만듭니다
6	`/speckit-tasks`	의존 순서대로 정렬된 `tasks.md`를 만듭니다
7	`/speckit-analyze`	읽기 전용으로 `spec.md`, `plan.md`, `tasks.md` 사이의 충돌과 누락을 점검합니다
8	`/speckit-implement`	`tasks.md`를 순서대로 실행합니다
9	`/speckit-converge`	코드를 명세와 대조하고 빈틈이 있으면 작업을 추가합니다. `Converged`가 나올 때까지 implement와 converge를 반복합니다

가장 짧은 경로는 specify → plan → tasks → implement → converge입니다. constitution, clarify, checklist, analyze는 전체 경로에만 들어갑니다.

어시스턴트에 따라 표기가 다를 수 있습니다

공식 빠른 시작은 하이픈이 들어간 /speckit-* 이름을 씁니다(GitHub Copilot의 기본 스킬 모드). 예전 튜토리얼과 업그레이드 안내에는 /speckit.specify처럼 점으로 쓴 형태도 남아 있습니다. 호출 형식은 어시스턴트와 모드마다 다르므로, 초기화 후 어시스턴트의 명령 목록에 실제로 나타나는 이름을 따르세요.

예전 튜토리얼과 달라진 점

예전 튜토리얼에서 흔한 방식	현재
`uv tool install ... --from git+https://...`만 가능	`specify-cli`가 PyPI에도 올라와 uv, pipx, pip로 설치할 수 있고, GitHub 태그 설치도 여전히 지원됩니다
`specify init --ai claude`	공식 문서는 모두 `--integration claude`를 씁니다
`/speckit.specify`, `/speckit.plan`	빠른 시작은 `/speckit-specify`, `/speckit-plan`을 쓰며 `/speckit-converge`가 추가되었습니다
`/constitution`이 템플릿과 명령 파일까지 갱신	이제 `.specify/memory/constitution.md`만 갱신합니다. 예전 동작을 되살리려면 `specify preset add constitution-sync`를 실행하세요
git 기능이 항상 켜져 있음	이제 선택 확장입니다: `specify extension add git`
Git 브랜치로 현재 기능을 판단	`.specify/feature.json`이 현재 기능 디렉터리를 기록합니다

업그레이드

명령줄 도구 자체를 업그레이드합니다.

specify self check                 # 읽기 전용: 새 릴리스가 있는지 확인
specify self upgrade --dry-run     # 업그레이드하지 않고 미리 보기
specify self upgrade               # 최신 안정 버전으로 업그레이드
specify self upgrade --tag vX.Y.Z  # 릴리스 태그 고정

기존 프로젝트 안의 파일을 업그레이드하려면 프로젝트 디렉터리에서 실행합니다.

specify integration status         # 설치된 통합과 수정된 파일 확인
specify integration upgrade <key>  # 설치된 통합마다 한 번씩 실행
specify extension update           # 모든 확장 업데이트

--force는 specify integration upgrade가 로컬에서 수정된 관리 대상 파일이 있다고 알려 주고 그 차이를 검토까지 마쳤을 때만 붙이세요.

자주 발생하는 문제

command not found: uv: uv를 먼저 설치한 뒤 설치 명령을 다시 실행하세요.
No such option: --integration: PATH 앞쪽에 아주 오래된 specify(예: 0.1.6)가 있습니다. 처음 설치할 때 쓴 도구로 다시 설치하고(예: uv tool install --force specify-cli) specify version으로 확인하세요.
두 벌이 설치됨: uv, pipx, pip로 각각 설치하면 사본이 따로 남습니다. 같은 도구로 업그레이드하고 섞어 쓰지 마세요.
PyPI 설치는 저절로 업그레이드되지 않음: 설치한 버전이 그대로 유지되므로 위의 업그레이드 명령을 사용하세요.
기존 디렉터리에서 초기화가 거부됨: 커밋이나 백업을 마친 뒤 --here --force를 붙이세요.