AI에게 “이런 거 만들어 줘” 한 문단만 주면, 적지 않은 부분은 AI가 알아서 정하고 그 결정은 코드 속에 묻힙니다. Spec Kit(스펙 킷)은 GitHub이 만든 무료 오픈소스 도구로, 클로드 코드 같은 코딩 에이전트가 코드를 쓰기 전에 명세(spec), 계획, 작업 목록을 문서로 먼저 쓰게 합니다. 저는 개발 스킬 비교 글에서 쓴 “모임 회비 정산기” 요청문을 그대로 Spec Kit 순서에 넣어 두 번 만들고, 같은 숨은 검사 20개로 채점했습니다.
- Spec Kit이 쓴 명세가 “만원처럼 한글로 쓴 금액은 오류로 알린다”를 미리 정했고, 두 결과물 모두 그 입력을 잡았습니다. Spec Kit 없이 같은 요청을 받은 결과물은 세 번 모두 놓쳤습니다.
- 대신 명세가 “이름에 띄어쓰기를 허용한다”고 정하는 바람에
가은 120 000은 두 번 다 틀렸습니다. 숨은 검사는 19개와 18개로, Spec Kit 없이 만든 18개와 거의 같았습니다. - 정산기 하나에 20~25분, 사용량은 API 단가로 7~10달러어치가 들었습니다. Spec Kit 없이는 3분 안팎, 1달러 아래였습니다. 명세·계획·테스트 파일이 프로젝트에 남는 것이 얻는 쪽입니다.
결과부터: 명세가 정한 것은 지켰고, 명세가 잘못 정한 것은 그대로 틀렸다
아래는 Spec Kit이 첫 단계에서 쓴 명세 문서(spec.md)의 일부입니다. 요청문에는 없던 경계 사례를 Claude가 스스로 정해 적었습니다.
②번 덕분에 “만원”을 잡았고, ①번 때문에 120 000을 놓쳤습니다. 네 결과물에 같은 세 줄을 넣은 장면입니다.
맨 왼쪽은 “가은 120″과 “나래 만원”이라는 사람이 0원을 냈다고 보고 송금 목록을 만듭니다. 가운데 둘과 오른쪽은 2번째 줄을 읽을 수 없다고 알립니다. 이번에는 나래 만원 줄을 빼고 넣었습니다.
Spec Kit 두 결과물도 “가은 120″이라는 사람이 0원을 낸 것으로 읽고 “보낼 돈이 없습니다”라고 답합니다. 맞는 답은 오른쪽처럼 나래와 다온이 가은에게 40,000원씩 보내는 것입니다.
직접 눌러 보기: Spec Kit 1회차 · Spec Kit 2회차 · Spec Kit 없음. Claude가 만든 파일 그대로입니다. 자세한 요구사항 파일로 만든 결과물은 4편 데모에 있습니다.
직접 실행 확인한 날짜 2026-10-14
- 실행 환경
- macOS 26.1 · Claude Code 2.1.299 · Opus 5.5 · 생각 깊이 중간 · Spec Kit 1.2.0(uvx로 설치 없이 실행). 비교한 4편 결과는 2.1.292~2.1.299, 같은 모델·생각 깊이
- 비용
- Spec Kit은 무료. 클로드 사용량은 정산기 하나에 API 단가로 7~10달러어치(Spec Kit 없이 0.5~0.9달러)
- 필요한 것
- Python 3.11 이상, uv, 지원하는 코딩 에이전트(클로드 코드·코파일럿·코덱스·제미나이 CLI 등)
- 라이선스
- MIT. GitHub 별 약 14.1만(확인한 날짜 기준)
따라 해 보기: 명령 일곱 줄과 실습 재료
실습 재료(zip)에는 이 글의 요청문, 단계별 명령, 까다로운 입력 두 묶음, 2회차가 만든 명세 문서 여섯 개가 들어 있습니다. 아래 설치를 마친 폴더에서 Claude Code를 열고 한 줄씩 보내세요. 한 단계가 끝나면 생긴 문서를 읽어 본 뒤 다음 줄로 넘어갑니다. Claude Code가 처음이라면 클로드 코드 설치 방법부터 보세요.
/speckit-constitution 코드 품질, 테스트, 유지보수에 초점을 맞춘 원칙을 만들어 줘.
/speckit-specify 모임 회비 정산기를 index.html 파일 하나로 만들어 줘. 참석자들이 각자 먼저 낸 돈을 적으면 똑같이 나눠서 누가 누구에게 얼마를 보내면 되는지 알려 주는 거야. 입력은 카톡에 붙여 넣기 좋게 한 줄에 한 사람씩 "이름 금액"으로 받고, 금액에 쉼표나 "원"이 붙어 있어도 되게 해 줘. 빠진 사람은 줄 끝에 "불참"을 붙이면 나누기에서 빼 줘. 송금액은 10원 단위로 반올림하고, 송금 횟수는 최대한 적게. 휴대폰에서 잘 보여야 해. 결과는 한 줄에 "보내는 사람 → 받는 사람 12,340원" 형식으로 보여 주고, 입력 칸은 id="members", 계산 버튼은 id="calc", 결과 칸은 id="result"로 해 줘.
/speckit-clarify
/speckit-plan index.html 파일 하나로 만들어 줘. 따로 설치 없이 HTML·CSS·자바스크립트만 써.
/speckit-tasks
/speckit-implement
/speckit-converge좋은 답이라면 specs/001-…/ 폴더에 spec.md·plan.md·tasks.md가 차례로 생기고, 마지막에 index.html과 tests/ 폴더가 생깁니다. converge가 “수렴 완료(Converged)”라고 하면 끝이고, 남은 작업을 덧붙였다고 하면 implement와 converge를 한 번 더 보냅니다. 결과 페이지에 나래 만원을 넣으면 그 줄을 읽을 수 없다고 나와야 합니다.
Spec Kit이란? 명세를 먼저 쓰게 하는 단계별 스킬 묶음
스펙 주도 개발(Spec-Driven Development, SDD)은 “어떻게 만들지”보다 “무엇을, 왜 만드는지”를 먼저 문서로 정하는 방식입니다. Spec Kit은 이 순서를 코딩 에이전트용 스킬(/speckit-… 명령)과 문서 틀로 묶은 것입니다. 공식 한국어 README도 있습니다.
터미널에서 쓰는 specify 명령은 프로젝트에 이 스킬과 틀을 깔아 주는 일만 합니다. 실제 일은 클로드 코드 대화창에서 /speckit-specify 같은 명령으로 합니다. 버그 고치기(bug), 아이디어 평가(assess) 과정은 따로 더하는 확장입니다(공식 문서 기준).
설치: 클로드 코드용으로 프로젝트에 깔기 (약 1분)
uv(파이썬 도구 관리 프로그램)가 있어야 합니다. 터미널에서 uv --version이 안 나오면 uv 공식 설치 안내부터 따릅니다.
Spec Kit을 쓸 빈 폴더를 만들고, 그 폴더에서 터미널로 실행합니다. 공식 문서의 “한 번만 쓰기” 방식이라 컴퓨터에 specify를 설치하지 않습니다.
uvx --from git+https://github.com/github/spec-kit.git@v1.2.0 specify init --here --integration claude
이렇게 나오면 성공 Project ready.(프로젝트 준비 완료), 그리고 .claude/skills/ 아래에 speckit-로 시작하는 폴더 10개
@v1.2.0은 이 글에서 쓴 버전입니다. 빼면 그날의 최신 코드를 받습니다.- 자주 쓸 거라면 공식 문서가 권하는 영구 설치
uv tool install specify-cli뒤에specify init --here --integration claude로 씁니다. - 이미 코드가 있는 폴더라면 공식 문서의 기존 프로젝트 안내를 먼저 읽고 백업한 뒤
--force를 붙입니다(공식 문서 기준). command not found: uvx가 나오면: uv가 깔리지 않은 것입니다. uv를 설치하고 터미널을 다시 엽니다.
필요 없어지면 같은 폴더에서 아래 명령으로 스킬을 지웁니다. 남은 .specify/ 폴더는 직접 지웁니다.
uvx --from git+https://github.com/github/spec-kit.git@v1.2.0 specify integration uninstall claude이렇게 나오면 성공 ✓ Integration 'Claude Code' uninstalled(클로드 코드 연결 제거됨) Removed 10 file(s)
다른 에이전트에서 쓰기 (공식 문서 기준)
--integration 뒤 이름만 바꾸면 됩니다. 지원 목록에 40개가 넘는 에이전트가 있고, 부르는 모양이 조금씩 다릅니다.
| 쓰는 곳 | 설치 이름 | 대화창에서 부르는 법 |
|---|---|---|
| 클로드 코드 | claude | /speckit-specify |
| GitHub 코파일럿 | copilot | /speckit-specify |
| 코덱스 CLI | codex | $speckit-specify |
| 제미나이 CLI | gemini | 명령 파일로 깔림(.gemini/commands) |
단계별로 무엇이 생기나
같은 대화창에서 명령을 하나씩 보냈습니다. 시간과 사용량은 두 번 돌린 값의 범위입니다.
| 명령 | 하는 일 | 생긴 것 | 걸린 시간 · 사용량 |
|---|---|---|---|
/speckit-constitution | 프로젝트 원칙(헌법)을 정함 | .specify/memory/constitution.md. 테스트 먼저 쓰기를 “꼭 지킬 것”으로 넣음 | 1분 안팎 · 0.4달러 |
/speckit-specify | 요청을 명세로 바꾸고 스스로 점검 | spec.md(사용 시나리오·요구사항·경계 사례·성공 기준·가정, 약 220~240줄), 점검표 16항목 | 1분 반 · 0.4달러 |
/speckit-clarify | 애매한 곳을 한 번에 하나씩 질문(최대 5개)하고 답을 명세에 기록 | spec.md에 “확인 사항” 절 | 2분 안팎 · 0.5~0.7달러 |
/speckit-plan | 기술 계획 | plan.md, research.md, data-model.md, quickstart.md, contracts/ 3개 | 3분 반~4분 남짓 · 0.9~1.3달러 |
/speckit-tasks | 계획을 작업 목록으로 쪼갬 | tasks.md(작업 35개 안팎, 약 340~365줄) | 2분 남짓~2분 반 · 0.7달러 |
/speckit-implement | 작업 목록대로 테스트와 코드를 씀 | index.html, tests/(테스트 56~83개, 모두 통과) | 8분 반~11분 · 3.5~4.9달러 |
/speckit-converge | 코드를 명세·계획과 대조해 빠진 작업을 덧붙임 | tasks.md 끝에 남은 작업(없으면 “수렴 완료”) | 1분 안팎 · 0.4~0.6달러 |
clarify의 첫 질문은 1회차가 “10원 반올림에서 남는 몇십 원은 누가 떠안나”, 2회차가 “불참자가 미리 낸 돈은 정산에 넣나”였습니다. 정산 결과가 달라지는 질문이었습니다. 4편과 같은 조건이 되도록 쓰는 상황(친구 7~8명이 1차·2차를 하고 카톡방에 올림)만 알려 주고 “나머지는 네가 합리적으로 정해 줘”라고 답했습니다. 그러자 Claude가 남은 질문을 스스로 정해 명세에 적었습니다.
converge는 2회차에서 한 번에 “수렴 완료”를 냈습니다. 1회차는 휴대폰 복사 버튼 문제 등 4건을 덧붙였고, 한 번 더 고친 뒤에도 테스트 대기 시간 1건이 남았습니다. 저는 거기서 멈췄습니다.
$ claude -p "/speckit-specify <요청문>" --model claude-opus-5-5 --effort medium --setting-sources project,local --permission-mode acceptEdits ... < /dev/null
# 다음 단계부터는 같은 대화에 이어서: claude -p "/speckit-plan ..." --resume <세션>
$ node --test tests/*.test.mjs
ℹ tests 83
ℹ pass 83
ℹ fail 0Spec Kit 없이 만든 결과와 비교
| 조건 | 걸린 시간 | 사용량(API 단가) | 숨은 검사 20개 | “만원” | “120 000” | 남은 파일 |
|---|---|---|---|---|---|---|
| 짧은 요청 · Spec Kit 없음(4편 2번 + 오늘 1번) | 2분~3분 반 | 0.53~0.85달러 | 18 · 18 · 18 | 3번 다 놓침 | 3번 다 틀림 | index.html 하나 |
| 짧은 요청 · Spec Kit 흐름(오늘 2번) | 20분 반~25분 | 7.20~9.89달러 | 19 · 18 | 2번 다 잡음 | 2번 다 틀림 | 명세 문서 10개 안팎 + index.html + 테스트 |
| 자세한 요구사항 파일 · Spec Kit 없음(4편 2번) | 2분 남짓 | 0.62~0.65달러 | 20 · 20 | 2번 다 잡음 | 2번 다 맞음 | index.html 하나 |
같은 날 Spec Kit 없이 한 번 더 돌린 결과도 4편과 똑같이 두 사례를 놓쳐, 클로드 코드 버전 차이로는 설명되지 않습니다. 2회차가 1회차보다 하나 더 놓친 것은 억 단위 금액입니다. plan 단계에서 “한 줄 금액은 1억 원 이하”라는 제한을 스스로 정해, 1,234,567,890을 오류로 막았습니다.
정확도만 보면 요구사항 파일 한 장이 더 나았습니다. 4편의 요구사항 파일에는 “금액에 쉼표, 공백, 원이 섞여도 된다”는 한 줄이 있었고, 그 결과물은 120 000을 맞혔습니다. Spec Kit 명세는 같은 빈칸을 “이름에 띄어쓰기 허용”으로 채웠습니다. 둘 다 그럴듯한 결정이지만, 제가 원한 쪽은 앞의 것이었습니다.
Spec Kit이 확실히 낫던 점은 남는 것입니다. 4편의 결과물은 모두 index.html 하나였고, 테스트를 쓴 경우에도 Claude의 임시 폴더에만 있었습니다. Spec Kit 두 번은 테스트 파일을 프로젝트 안 tests/에 남겼고, 왜 그렇게 정했는지가 spec.md·research.md에 적혀 있습니다. 다음에 고칠 사람이 “120 000은 왜 안 되지?”를 찾으면 명세의 ①번 줄이 답입니다.
한계와 주의할 점
- 빈 폴더에서 파일 하나짜리 도구를 두 번 만든 결과입니다. Spec Kit이 원래 겨냥하는 여러 화면·여러 기능의 프로젝트에서는 다르게 나올 수 있습니다.
- 명세를 읽지 않으면 효과가 없습니다. 이번에는 clarify 질문에 “알아서 정해 줘”라고 답해 Claude가 명세를 혼자 정했습니다. 사람이 명세의 경계 사례를 읽고 ①번 줄을 고쳤다면 120 000도 맞았을 가능성이 큽니다. 공식 README도 단계마다 결과를 검토하라고 안내합니다.
- 답 한 문장이 범위를 바꿉니다. 1회차는 제 답의 “1차·2차”를 보고 차수 구분 줄 기능을 명세에 넣었습니다. 2회차는 같은 답을 보고 범위 밖으로 뒀습니다.
- 2회차는 clarify에 두 번째로 “그대로 진행해 줘”라고 답하자 plan 단계를 스스로 시작했습니다. 단계 사이에 다른 말을 할 때는 다음 명령을 직접 보내는 편이 안전합니다.
- 사용량 숫자는 클로드 코드가 기록한 API 단가 환산값입니다. 구독 요금제에서는 이 돈이 따로 나가지 않고 사용 한도에서 빠집니다.
- 명령은
claude -p로 한 단계씩 보냈습니다. 대화창에서 직접 치면 허락을 묻는 창이 더 뜰 수 있습니다.
대안
| 이름 | 다른 점 | 이럴 때 고르세요 |
|---|---|---|
| 요구사항 파일 한 장 | 설치 없음. 입력 모양·예외를 직접 적음. 이번 비교에서 정확도가 가장 높고 비용은 1/10(CLAUDE.md 작성법과 같은 원리) | 규칙이 분명한 작은 도구 |
| Superpowers(슈퍼파워스) 브레인스토밍 | 질문 1개로 빠진 조건을 짚고 테스트부터 씀. 문서는 거의 안 남김(4편) | 무엇을 만들지 막연할 때, 가볍게 |
| Spec Kit | 명세·계획·작업 목록·테스트가 파일로 남음. 시간·사용량 약 10배 | 여러 사람이 이어서 고치거나, 결정 근거를 남겨야 할 때 |
자주 묻는 질문
Spec Kit은 무료인가요?
Spec Kit 자체는 MIT 라이선스 무료입니다. 다만 단계마다 코딩 에이전트가 일을 하므로 그 에이전트의 사용량이 듭니다.
/speckit.specify를 쳤는데 명령이 없다고 나와요
공식 문서에는 /speckit.specify(점) 표기와 /speckit-specify(하이픈) 표기가 섞여 있습니다. 클로드 코드에 깔면 스킬 폴더 이름이 speckit-specify라서 하이픈으로 불러야 합니다.
윈도우에서도 되나요?
공식 문서 기준으로 됩니다. 윈도우에서는 PowerShell 스크립트가 기본으로 깔립니다. 이 글은 맥에서만 확인했습니다.
코덱스에서도 쓸 수 있나요?
공식 문서 기준으로 --integration codex로 깔고 $speckit-specify처럼 부릅니다. 이 글에서는 시험하지 않았습니다.
git이 꼭 있어야 하나요?
아닙니다. 이번 작업 폴더는 git 저장소가 아니었고, Spec Kit은 브랜치를 만들지 않고 specs/001-… 폴더에만 문서를 썼습니다. 브랜치를 자동으로 만들려면 git 확장을 따로 켭니다(공식 문서 기준).
출처
github/spec-kit 저장소·README, 한국어 README, 설치 문서, 한 번만 쓰기(uvx), SDD 명령 설명, 지원 에이전트 목록 (모두 2026-10-14 확인)