2026 Spec Kit 완전 사용 가이드: 설치부터 AI 구현까지, Windows·macOS·Linux 명세 주도 개발

GitHub이 유지하는 Spec Kit은 명세 주도 개발을 설치할 수 있는 CLI와 에이전트가 호출하는 스킬 묶음으로 만든다. PyPI 패키지 이름은 specify-cli이고 소스 저장소는 github/spec-kit이다. Cursor, Claude Code, GitHub Copilot, Codex를 대체하지 않는다. 이 에이전트들이 관찰 가능한 행동을 먼저 적고, 기술 선택을 그다음에 적고, 저장소 수정은 마지막으로 하게 순서를 고정할 뿐이다. 2026년 11월 기준으로 Windows는 PowerShell 스크립트를 바로 쓴다. WSL을 먼저 설치할 필요가 없다. 이 글이 다루는 것은 설치, 디렉터리, 명령 순서다. 명세가 코드보다 먼저여야 하는 이유는 명세 주도 개발 완전 가이드를 본다. 스킬 파일을 어디에 두는지는 Agent Skills 가이드를 본다.

「보드 만들어 줘」가 이미 잘못된 시작인 이유

옛 방식과 새 방식의 충돌은 구체적이다. 옛 방식은 세션 우선이다. 목표, 기술 스택, 폴더 구조를 채팅 한 번에 밀어 넣는다. 에이전트는 추측하면서 파일을 고친다. 기기나 사람이 바뀌면 그 맥락은 사라진다. 새 방식은 산출물 우선이다. 원칙은 .specify/memory/constitution.md에 둔다. 행동과 이유는 specs/<feature>/spec.md에 둔다. 기술 스택은 plan.md까지 기다린다. 실행 순서는 tasks.md까지 기다린다. 현재 기능은 .specify/feature.json이 가리키는 디렉터리이지, 지난 대화의 기억이 아니다.

2026년에 이것이 태도의 문제가 아니라 설치의 문제가 된 이유는 세 가지다. 첫째, 호출 철자가 에이전트마다 갈린다. Cursor, Claude Code, Copilot 기본 스킬 모드는 /speckit-specify다. Codex는 $speckit-specify다. 문서의 점 표기는 참조용이다. 둘째, uv와 pipx에 각각 설치하면 specify가 두 개 남는다. PATH 앞의 옛 바이너리가 --integration을 거부한다. 셋째, 선택적 git 확장은 번호 브랜치를 만들 수 있지만 git checkout 자체는 현재 기능을 바꾸지 않는다. 셋 다 제품 코드의 첫 줄보다 앞에서 일어난다.

Spec Kit이 명세 주도 작업을 어떤 층으로 나누는가

아홉 개의 슬래시 스킬을 같은 층의 체크리스트로 다루지 마라. 그것들은 세 종류의 산출물에 내려앉고, 합법적인 경로는 두 개뿐이다.

원칙 층은 저장소마다 한 번이다. /speckit-constitution은 품질, 테스트, 권한, 경험의 단단한 제약을 남기고, 이후 단계는 그 파일을 잣대로 삼는다. 기능 층은 기능마다 한 번이다. /speckit-specify가 답하는 것은 사용자가 관찰할 수 있는 것과 왜 필요한가뿐이다. /speckit-clarify는 모호한 곳을 묻고 답을 명세에 다시 쓴다. 구현 층에서야 프레임워크와 디렉터리가 허용된다. /speckit-plan은 계획, 조사, 데이터 모델, 계약을 만든다. /speckit-tasks는 계획을 의존 순서의 작업으로 나누고 병렬 가능한 항목에 [P]를 붙인다. /speckit-implement는 그 순서로 파일을 고친다. /speckit-converge는 코드와 산출물을 맞추고, 빠진 작업을 덧붙여 Converged라고 보고할 때까지 반복한다.

중간에 품질 문이 두 개 있다. 「코드가 끝났다」와 섞지 마라. /speckit-checklist가 만드는 것은 검토자가 가진 요구 품질 목록이다. 체크는 요구가 분명하다는 뜻이지, 기능이 구현되었다는 뜻이 아니다. /speckit-analyze는 읽기 전용이다. spec.md, plan.md, tasks.md의 충돌을 보고하고 저장소는 고치지 않는다. 기본 checklists/requirements.md는 specify와 clarify가 유지한다. 사용자 정의 목록은 검토자의 것이다. implement는 체크되지 않았으면 멈추고 묻는다. 대신 체크해 주지 않는다.

짧은 경로는 경계가 이미 분명한 작은 변경에 맞는다. specify, plan, tasks, implement, converge 순이다. 전체 경로는 출시할 기능에 맞는다. constitution은 프로젝트에서 한 번 하고, 그다음 specify, clarify, plan, checklist, tasks, analyze, implement, converge로 간다. 결함은 공식 bug-fixing 퀵스타트로 간다. 아직 만들 가치가 있는지 판단 중인 아이디어는 idea assessment로 간다. 둘 다 이 명세 주도 경로의 선행 단계는 아니다.

Windows, macOS, Linux에 설치하는 방법

공통 전제는 Python 3.11 이상, git 확장을 켤 때만 필요한 Git, 그리고 실제로 코드를 쓸 에이전트다. 지속 설치에는 uv를 쓴다. 터미널은 CLI만 실행한다. 슬래시 스킬은 에이전트 채팅에서 호출한다.

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
uv tool install specify-cli
specify version
specify self check
specify init deskboard --integration cursor-agent --script ps

curl -LsSf https://astral.sh/uv/install.sh | sh
uv tool install specify-cli
specify version
specify self check
specify init deskboard --integration cursor-agent --script sh

설치 뒤에 볼 것은 두 가지다. specify version은 그 명령이 실행되고 버전을 출력한다는 것만 증명한다. 바이너리가 PyPI에서 왔는지 GitHub에서 왔는지는 증명하지 않는다. specify self check는 읽기 전용이다. 새 릴리스가 있는지만 알리고 설치는 바꾸지 않는다. 문서의 예시 태그는 v0.12.11처럼 앞에 v가 붙는다. 소스를 고정하려면 uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@vX.Y.Z를 쓰고 v를 빼지 않는다. PyPI 고정은 uv tool install specify-cli==X.Y.Z다. 업그레이드는 처음에 쓴 도구로 한다. uv tool install --force specify-cli, pipx install --force specify-cli, 또는 pip install --upgrade specify-cli다.

이미 코드가 있는 저장소를 더러운 작업 트리 위에서 초기화하지 마라. 먼저 커밋하거나 백업한 다음 specify init --here --force --non-interactive --integration claude를 실행한다. --force는 템플릿이 기존 파일에 합쳐진다는 것을 알았다는 뜻일 뿐이다. 키보드가 없는 CI에는 --non-interactive가 필요하다. 없으면 초기화가 방향키 메뉴에서 멈춘다. 에이전트 실행 파일이 다른 기기에 있으면 --ignore-agent-tools를 더해 로컬 바이너리 검사를 건너뛴다. 비대화 기본 통합은 Copilot이다. 다른 --integration을 적지 않으면 그렇게 된다.

통합 키를 추측하지 마라. Cursor는 cursor-agent이지 cursor가 아니다. 자주 쓰는 키는 claude, copilot, gemini, pi, omp, codebuddy다. 대화형 터미널은 --integration을 생략하면 고르게 한다. 스크립트와 파이프는 반드시 명시한다.

specify version이 옛 번호를 보여 주면 먼저 which specify로 경로를 본다. 0.1대가 남아 있으면 --integration은 No such option: --integration이 되고, 옛 --ai는 No matching release asset found가 된다. 이것은 네트워크 고장이 아니라 PATH 앞쪽이 다른 설치를 가리킨다는 신호다. 지우는 것은 쓰지 않는 쪽뿐이고, 갱신은 처음 도구에 --force나 --upgrade를 붙여 한다. 두 도구를 번갈아 넣으면 다시 두 개가 된다.

아홉 명령: 어디서 호출하고, 무엇을 바꿔도 되며, 누구를 위한가

다음 두 표는 열을 같이 쓴다. 진짜 차이는 진입점과 실행 경계이지 모델 이름이 아니다.

상황에 따라 짧은 경로와 전체 경로를 고른다

실습 예는 한 대에만 남는 메모 보드다. 업로드하지 않는다. 1기에는 비밀번호가 없다. 미리 정한 세 사람. 프로젝트 아래 네 열. 할 일, 진행 중, 확인 대기, 완료. 카드는 드래그로 열을 바꾼다. 댓글을 고칠 수 있는 사람은 작성자뿐이다. specify에는 이 행동과 이유만 적는다. plan에서야 「로컬 SQLite, 원격 API 없음」을 적는다. 데이터베이스를 specify에 넣으면 첫 기술적 감이 아무도 도전할 수 없는 요구가 된다.

채팅에 붙이는 specify는 이 굵기에서 멈춘다. 고정된 세 사람이 프로젝트를 열고, 네 열 사이에서 카드를 드래그한다. 댓글의 수정과 삭제는 작성자만 한다. 시작 때 비밀번호를 묻지 않는다. 파일 저장 위치, 프레임워크, 테이블 이름은 적지 않는다. 그것을 적는 순간 명세가 계획을 앞지른다. plan으로 넘어간 뒤에 저장은 로컬 SQLite, 화면은 한 페이지, 네트워크로는 나가지 않는다고 기술을 고정한다.

초기화 직후 디스크에서 확인할 파일은 이 글에서 이름을 부른 것과 같다. 원칙은 .specify/memory/constitution.md다. 현재 기능은 .specify/feature.json이 가리킨다. Windows면 스크립트는 .specify/scripts/powershell/, macOS와 Linux면 .specify/scripts/bash/, --script py면 .specify/scripts/python/다. specify 뒤 기능 디렉터리에 spec.md가 있고, plan 뒤에 plan.md와 조사 메모, 데이터 모델, 계약이 늘어선다. tasks 뒤에 tasks.md가 있고, 병렬 가능한 줄만 [P]를 가진다. 이 순서를 건너뛰고 implement를 부르면 에이전트는 빈칸을 추측으로 채운다. 그것이 채팅 한 방으로 돌아가는 길이다.

Cursor에서 스킬이 안 보이면 터미널이 아니라 채팅의 슬래시를 확인한다. 파일은 .cursor/skills/speckit-specify/SKILL.md에 있어야 한다. Claude Code면 .claude/skills/, Copilot 기본이면 .github/skills/다. 점 형태의 /speckit.specify를 쳐서 반응이 없어도 설치 실패가 아닐 수 있다. 철자가 참조 표기 그대로인 경우가 있다.

에이전트, 스크립트 종류, 격리된 기기를 맞춘다

이미 Cursor에서 이 저장소를 쓰고 있다면 cursor-agent와 그 기기의 스크립트 종류를 쓴다. Windows는 ps, macOS와 Linux는 sh다. 초기화 뒤 채팅에서는 짧은 경로나 전체 경로를 한 단계씩 호출한다. 다음 스킬 전에 산출물을 읽는다. 아홉 개를 한 프롬프트에 붙이지 마라.

주로 Claude Code를 쓰면 통합 키는 claude다. 스킬 설명이 맥락을 압박하면 초기화에 --integration-options="--no-model-invocation"을 붙여, 핵심 명령은 /speckit-specify를 쳤을 때만 돌게 한다. Copilot은 기본 스킬 배치를 유지하면 된다. 옛 에이전트 파일이 필요할 때만 --commands를 더한다.

implement는 파일을 고치고 명령을 실행한다. 운영 키가 들어 있는 노트북에서 첫 회전을 하지 마라. 저장소를 원격 Mac에 두고 diff를 읽은 뒤 되돌린다. 노드를 어떻게 주문하는지는 Mac mini 대여, 예산은 요금을 본다. 명세에 macOS 빌드나 서명이 있으면 그 단계는 실제 Mac 노드에서 돌리고, OpenClaw 클라우드 자동화로 일상 노트북과 분리한다. 설치가 실패하면 Spec Kit을 의심하기 전에 도움말 센터의 연결과 시스템 요구를 확인한다.

나머지 작업을 전부 다시 하게 만드는 다섯 가지

1. specify 안에 프레임워크와 데이터베이스를 적는다. 기술 스택은 plan의 것이다. 명세가 「이 라이브러리 필수」라고 하면 clarify와 analyze는 그 선택을 변호하는 데 시간을 쓴다.
2. 터미널에 /speckit-specify를 친다. 슬래시 스킬은 에이전트 채팅에만 있다. 터미널이 실행하는 것은 specify 자체다.
3. 문서의 점 명령을 Cursor에 붙인다. Cursor 스킬은 /speckit-specify다. 점은 참조 표기다.
4. uv와 pipx에 둘 다 설치한다. 옛 0.1.x는 No such option: --integration을 내거나 --ai에서 No matching release asset found를 낸다. 어느 쪽을 지울지 정하기 전에 which specify를 본다.
5. git checkout을 기능 전환기로 쓴다. 바꾸는 것은 .specify/feature.json 또는 SPECIFY_FEATURE_DIRECTORY다. 브랜치만 바꾸면 명령은 이전 기능 디렉터리를 그대로 본다.

일곱 단계

1. uv와 specify-cli를 설치한다. specify version과 specify self check를 실행하고 PATH의 바이너리가 하나인지 확인한다.
2. 운영체제에 맞는 --script, 실제로 쓰는 에이전트에 맞는 --integration을 고르고 specify init한다. 기존 저장소는 먼저 커밋하고 --here --force를 더한다.
3. 에이전트 채팅에서 /speckit-constitution을 한 번만 실행한다. 원칙만 적는다. 입력은 검증한다. 댓글은 작성자만 고친다. 1기는 업로드하지 않는다.
4. /speckit-specify로 메모 보드의 행동과 이유를 적는다. 출시할 것이면 /speckit-clarify를 이어서 드래그, 권한, 빈 프로젝트 세 가지를 끝까지 묻는다.
5. 명세가 안정된 뒤에 /speckit-plan을 실행한다. 이어서 checklist, tasks, analyze. analyze가 충돌을 보고하면 원본 산출물을 고친다. implement 안에서 땜질하지 않는다.
6. 격리된 Mac이나 깨끗한 디렉터리에서 /speckit-implement를 실행한다. 작업이 많으면 단계로 나눈다. tasks.md를 한 번에 삼키지 않는다.
7. /speckit-converge를 Converged가 나올 때까지 실행한다. 그다음 diff를 읽는다. 명세 밖의 파일이 있는지, 비밀이 저장소에 쓰였는지.

설치를 결정하는 질문

Spec Kit과 Cursor에서 채팅하는 차이는 무엇인가

채팅 기록은 그 세션에 남는다. 사람이나 기기가 바뀌면 사라진다. Spec Kit은 원칙, 명세, 계획, 작업을 저장소의 Markdown으로 남긴다. 현재 기능은 .specify/feature.json의 디렉터리이지 지난 스레드의 기억이 아니다.

명령은 /speckit-specify인가 /speckit.specify인가

Cursor, Claude Code, GitHub Copilot 기본 스킬 모드는 하이픈 형태를 에이전트 채팅에서 쓴다. 터미널에 입력하지 않는다. Codex 스킬 모드는 $speckit-specify다. 문서의 점 표기는 참조용이라 Cursor에 붙이지 않는다.

Windows에는 WSL이 먼저 필요한가

아니다. 2026년 Spec Kit은 Windows에서 PowerShell이 기본이다. 초기화 때 --script ps를 붙인다. macOS와 Linux 기본은 bash이고 --script sh에 해당한다.

uv와 pipx에 각각 설치해도 되는가

안 된다. specify가 두 개 남는다. PATH 앞에 있는 옛 버전이 --integration을 거부하거나 No matching release asset found를 낸다. 업그레이드는 처음 도구로 --force 또는 --upgrade를 붙여 한다.

git checkout이 현재 기능을 바꾸는가

바꾸지 않는다. 현재 기능은 .specify/feature.json이다. SPECIFY_FEATURE_DIRECTORY로 덮어쓸 수 있다. 선택적 git 확장은 번호 브랜치를 만들지만 체크아웃만으로는 이 상태가 바뀌지 않는다.

올바른 명령을 설치한 뒤에 에이전트가 저장소를 고치게 한다

Spec Kit의 가치는 슬래시가 하나 늘어나는 데 있지 않다. 「명세, 그다음 계획, 마지막에 파일 수정」이 다른 사람이 검토할 수 있는 저장소 안 파일이 되는 데 있다. Windows는 PowerShell, macOS와 Linux는 bash, Cursor는 cursor-agent와 하이픈 스킬을 쓴다. 작은 변경은 짧은 경로, 출시할 기능은 전체 경로, implement는 격리된 노드에서 돌린다. 다음 단계는 프롬프트를 더 모으는 일이 아니다. specify version을 실행하고 눈앞의 바이너리가 방금 설치한 것인지 확인한다. 번호가 기대와 다르면 스킬을 치기 전에 PATH를 고친다. 스킬 이름을 치기 시작하는 것은 버전, 통합 키, 스크립트 종류 셋이 지금 이 기기와 맞은 다음이다. 맞지 않은 채로 implement를 부르면, 옛 CLI가 만든 디렉터리와 새 스킬이 섞여 어느 산출물이 맞는지 나중에 가를 수 없게 된다.

실습을 한 바퀴만 더 좁혀 보면 순서는 이렇게 고정된다. 채팅의 첫 메시지는 원칙이다. 입력은 검증하고, 댓글은 작성자만 고치고, 1기는 업로드하지 않는다. 두 번째 메시지는 관찰 가능한 행동만 담은 specify다. 세 번째는 드래그로 열이 바뀌는지, 빈 프로젝트에서 열이 보이는지, 남의 댓글이 막히는지, 이 세 질문만 clarify로 닫는다. 네 번째에서야 plan이 SQLite와 단일 페이지를 고른다. 다섯 번째는 tasks가 파일 경로와 [P]를 적는다. analyze가 침묵한 뒤에만 implement가 파일을 연다. 이 순서를 한 프롬프트로 합치면, 스펙 키트를 설치한 의미가 사라지고 다시 세션 한 방에 의존하게 된다. 각 단계의 산출물을 저장소에서 열어 본 뒤에 다음 스킬을 친다. 열지 않고 넘어가면, 에이전트는 빈칸을 이전 대화의 추측으로 채운다. 그 추측이 파일로 남으면, 다음 사람이 여는 것은 명세가 아니라 지난 세션의 잔해다. 그래서 짧은 경로조차 specify의 spec.md를 디스크에서 확인하고, plan.md의 기술 선택이 그 명세에 없는 라이브러리를 요구하지 않는지 본 다음에야 tasks로 넘어간다. 이 확인은 새 기능이 아니라, 이미 정한 순서의 일부를 빼먹지 않기 위한 습관이다. 습관을 문서로 남기면 이렇게 적힌다. spec.md의 변경이 plan.md보다 앞이고, plan.md의 변경이 첫 코드 diff보다 앞이다. 그 순서가 깨진 채 Converged만 반복하면, 보고서는 지금 파일을 추인할 뿐 명세가 먼저였다는 증거가 되지 못한다. 증거를 만드는 일은 새 명령을 외우는 일이 아니라, 저장소에 이미 있는 세 파일의 순서를 눈으로 확인하는 일이다. 확인이 끝나면 터미널에는 specify만 남기고, 슬래시 명령은 채팅으로 되돌린다. 그 경계를 지키면 Windows의 PowerShell, macOS와 Linux의 bash, Cursor의 cursor-agent가 같은 산출물을 가리킨다. 같은 산출물을 가리켜야 다음 사람이 채팅 기록 없이 저장소만으로 이어받을 수 있다.

더 읽을 글

• 명세 주도 개발 완전 가이드: 방법론 →
• Agent Skills 설치와 선택 →
• OpenClaw 클라우드 자동화와 원격 Mac →