코드보다 명세서먼저, AI가그대로 만들게

프로용© AIKOREACLUB

github/spec-kit

코드보다 명세서 먼저, AI가 그대로 만들게

만들 기능을 먼저 글(명세서)로 정해 두고, 계획, 할 일 목록, 구현, 빠진 곳 점검까지 코딩 AI가 한 단계씩 밟게 해 주는 깃허브의 오픈소스 도구예요

★ 146,261터미널 도구 + 에이전트 스킬 · MIT확인 2026-11-03

코딩 AI에게 "사진 정리 앱 만들어 줘" 한 줄을 주면 금방 뭔가 나와요. 그런데 앨범을 날짜로 묶을지, 사진을 어디에 둘지 같은 걸 AI가 알아서 정해 버려요. 그러면 고치다 고치다 결국 처음부터 다시 설명하게 되죠.스펙 킷(Spec Kit)은 깃허브가 공개한 도구예요. 무엇을 왜 만드는지부터 명세서로 쓰게 하고, 그 명세서를 계획, 할 일 목록, 코드로 차례차례 옮기게 해요. 별 14만 개를 넘겼고, 2026-11-02에 1.2.6판이 나왔을 만큼 지금도 자주 고쳐지는 저장소예요.

한 줄로 시키면 AI가 대신 정해 버리는 것들

내가 AI에게 준 것

0AI가 정함

0내가 정함

무엇(명세 단계에서 정함)어떻게(계획 단계에서 정함)

스펙 킷 공식 문서의 사진 정리 앱 예시(명세와 계획 문장)를 질문으로 나눠 저희가 그린 예시예요. 한 줄로 시켰을 때 AI가 실제로 무엇을 고르는지는 모델과 상황에 따라 달라져요.

한눈에

무엇인가요

스펙 킷은 코딩 AI에게 정해진 작업 순서와 문서 틀을 붙여 주는 도구예요. 터미널에서 specify 명령으로 프로젝트에 설치하고, 그다음부터는 AI 대화창에서 /speckit- 으로 시작하는 스킬을 하나씩 불러요.중심은 스펙 주도 개발(SDD)이에요. 프로젝트 원칙(constitution), 명세(specify), 계획(plan), 할 일(tasks), 구현(implement), 점검(converge)을 차례로 밟아요. 단계마다 spec.md, plan.md, tasks.md 같은 파일이 남아서, 나중에 왜 이렇게 만들었는지 다시 볼 수 있어요.버그 고치기와 아이디어 평가도 있어요. 둘 다 필요할 때 따로 설치하는 확장이에요. 버그는 원인 평가, 고치기, 확인 순서로 가고 마지막에 verified, partial, failed 중 하나로 판정해요. 아이디어 평가는 근거를 모아 go(진행), needs-clarification(더 확인), kill(중단) 중 하나로 결론을 내요.명세 단계에서는 무엇을 왜 만드는지만 쓰고, 어떤 기술로 만들지는 계획 단계로 미루는 게 이 방식의 규칙이에요.

함께 쓰는 도구 · 깃허브 코파일럿 · 클로드 코드 · 코덱스 · 커서 · 제미나이 CLI · 오픈코드

이런 분께

코딩 AI에게 큰 기능을 맡겼다가 엉뚱한 결과를 받아 본 분
만든 이유와 결정 사항을 문서로 남기며 AI와 개발하고 싶은 팀
코드를 짜기 전에 아이디어가 해 볼 만한지부터 따져 보고 싶은 분

어떻게 작동하나요

1. 터미널에서는 설치와 프로젝트 만들기만 해요. uv tool install specify-cli 로 설치하고 specify init 에 쓰는 코딩 AI 이름(copilot, claude 등)을 붙이면, 그 AI가 부를 수 있는 스킬 파일과 .specify 폴더가 생겨요.2. 나머지는 AI 대화창에서 한 단계씩 불러요. README는 스킬을 한 번에 하나씩 부르고, 결과를 읽어 본 뒤 다음으로 넘어가라고 적어요. 명령은 AI마다 모양이 조금 달라요. 코파일럿과 클로드 코드는 /speckit-specify, 코덱스는 $speckit-specify 처럼 써요.3. 파일이 다음 단계의 재료가 돼요. specify 가 쓴 spec.md 를 plan 이 읽고, plan.md 를 tasks 가 읽고, tasks.md 를 implement 가 실행해요. analyze 는 세 파일이 서로 어긋나는 곳을 찾기만 하고 고치지는 않아요.4. 다 됐는지는 converge 가 판정해요. 빠진 곳이 있으면 할 일을 덧붙이고, implement 와 converge 를 다시 돌려 Converged 가 나올 때까지 반복해요.핵심은 한 번에 다 만들게 하지 않고, 사람이 단계마다 문서를 확인하며 넘어간다는 거예요.

바로 쓸 수 있나요

개발자 필요

필요한 것파이썬 3.11 이상과 uv, 터미널, 그리고 깃허브 코파일럿이나 클로드 코드 같은 코딩 AI. 만든 코드를 읽고 판단할 수 있어야 단계마다 확인이 의미가 있어요

비용저장소는 무료(MIT). 함께 쓰는 코딩 AI 요금은 따로예요

시작하기

준비물
파이썬 3.11 이상, 파이썬 도구 관리자 uv, 그리고 지원하는 코딩 AI가 필요해요. 리눅스, 맥, 윈도우 모두 돼요.
스펙 킷 설치
터미널에서 실행해요.
```
uv tool install specify-cli
```
프로젝트 만들기
README 예시는 코파일럿이에요. 클로드 코드라면 copilot 자리에 claude 를 넣어요. 이미 코드가 있는 프로젝트라면 공식 문서의 '기존 프로젝트' 안내를 먼저 따르라고 해요.
```
specify init my-project --integration copilot
cd my-project
```
코딩 AI를 그 폴더에서 열기
여기서부터는 터미널이 아니라 AI 대화창에서 스킬을 하나씩 불러요.
원칙부터 한 번
README 예시 그대로예요. 결과 파일(.specify/memory/constitution.md)을 읽어 보고 다음 단계로 가요.
```
/speckit-constitution Create principles focused on code quality, testing, and maintainability.
```

처음 해 볼 한마디

/speckit-specify Build a photo organizer with albums grouped by date and a tile preview of each album.

README의 첫 명세 예시예요. 날짜별로 묶인 앨범과 앨범마다 사진 타일 미리 보기가 있는 사진 정리 앱이라는 뜻이에요. 설명을 우리말로 써도 되는지는 README에 따로 적혀 있지 않아요.

처음 쓰는 순서

/speckit-constitution품질, 테스트, 유지 보수 같은 원칙을 한 번 써 두기
/speckit-specify기술 이야기 없이 무엇을 왜 만드는지만 설명하기
/speckit-clarifyAI가 묻는 질문에 답해 빈칸 채우기
/speckit-plan이때 처음으로 쓸 기술과 저장 방식을 말하기
/speckit-tasks할 일 목록을 읽어 보고 순서 확인하기
/speckit-implement 와 /speckit-convergeConverged 가 나올 때까지 번갈아 돌리기

빠른 문서(Quickstart)는 작은 기능이면 clarify 없이 specify, plan, tasks, implement, converge 다섯 단계만 써도 된다고 적어요. 실제로 내보낼 기능이면 clarify, checklist, analyze 를 사이사이 넣는 긴 순서를 권해요.

명세가 코드가 되기까지, 단계마다 남는 파일

코딩 AI 대화창에 입력

프로젝트 폴더

스펙 킷 공식 문서의 사진 앨범 예시와 명령 설명, 문서 틀(spec, plan, tasks)의 모양을 따라 저희가 그린 예시예요. 명령 뒤 설명은 우리말로 옮겨 적었고, 실제 문서 내용과 할 일 개수는 쓰는 코딩 AI와 프로젝트에 따라 달라져요.

명령어 전체 18개, 언제 쓰나

터미널에서

uv tool install specify-cli: 스펙 킷 명령(specify) 설치
specify init my-project --integration claude: 새 프로젝트 만들기, 쓰는 AI 이름을 붙여요
specify integration install claude: 이미 있는 스펙 킷 프로젝트에 다른 AI 연결
specify extension add bug: 버그 고치기 확장 설치
specify extension add assess: 아이디어 평가 확장 설치

기본 흐름(대화창)

/speckit-constitution: 프로젝트 원칙 정하기, 처음 한 번
/speckit-specify: 무엇을 왜 만드는지 명세서로
/speckit-plan: 기술 선택과 설계
/speckit-tasks: 순서가 정해진 할 일 목록
/speckit-implement: 할 일 순서대로 만들기
/speckit-converge: 명세와 코드를 맞춰 보고 빠진 일 덧붙이기

품질 점검(골라 쓰기)

/speckit-clarify: 애매한 곳을 하나씩 묻고 명세에 반영
/speckit-checklist: 요구 사항이 빠짐없고 분명한지 확인 목록
/speckit-analyze: 명세, 계획, 할 일끼리 어긋나는 곳 보고(읽기만)

버그·아이디어(확장)

/speckit-bug-assess: 증상을 주면 원인 평가
/speckit-bug-fix: 범위를 좁혀 고치기
/speckit-bug-test: 원래 증상이 사라졌는지 확인, verified 만 성공
/speckit-assess-intake: 아이디어 받아 적기, 이어서 research, define, shape, decide

명령 이름은 README가 예로 든 깃허브 코파일럿 기본 모양이에요. 클로드 코드도 /speckit-specify 처럼 쓰고, 코덱스는 $speckit-specify, Kimi는 /skill:speckit-specify 처럼 앞부분이 달라요. 명령 뒤에 하고 싶은 걸 말로 붙여요.

비슷한 도구

셋 다 코딩 AI가 바로 코드부터 짜지 않게 하는 도구예요. 스펙 킷은 명세, 계획, 할 일을 파일로 남기는 데 가장 무게를 둬요(각 README 기준).

코딩 AI, 왜 엉뚱한 걸 만들어 올까묻기, 계획, 테스트 먼저 순서를 스킬이 알아서 켜서 지키게 함. 스펙 킷은 단계마다 내가 명령을 부르고 문서를 남기는 쪽obra/superpowers

코딩 AI 여럿을 한 화면에서 굴리려면프로젝트 설명서(SPEC.md)를 AI가 계속 고쳐 가는 실험 단계 데스크톱 앱JetBrains/thinkrail

주의할 점

기본 흐름은 꽤 길어요. 단계마다 문서를 읽고 넘어가야 해서, 작은 수정 하나에 다 쓰면 오히려 느릴 수 있어요. 공식 문서도 작은 기능은 짧은 순서를 쓰라고 해요.
커뮤니티 확장과 묶음 목록은 검사나 보증이 아니라고 README가 밝혀요. 남이 만든 확장은 설치하거나 실행하기 전에 코드를 직접 보라고 해요.
클로드 코드에 설치하면 스펙 킷 스킬 설명이 늘 클로드에게 보이는 상태라, 스킬이 많은 프로젝트에서는 다른 스킬이 목록에서 밀릴 수 있어요. 설치할 때 --integration-options="--no-model-invocation" 을 붙이면 내가 부를 때만 켜져요.
구현은 결국 코딩 AI가 해요. converge 가 Converged 라고 해도 명세와 맞는지를 본 것이지, 코드 검토나 테스트를 대신하는 건 아니에요.

낯선 말

명세서(스펙) · 무엇을, 누구를 위해, 왜 만드는지와 다 됐다고 볼 조건을 적은 문서예요
스펙 주도 개발(SDD) · 코드보다 명세서를 먼저 쓰고, 명세서에서 계획과 코드를 끌어내는 개발 방식이에요
constitution · 프로젝트의 기본 원칙 문서예요. 스펙 킷은 뒤 단계를 모두 이 원칙에 비춰 봐요
인수 조건 · '이런 상황에서 이렇게 하면 이렇게 돼야 한다'처럼, 기능이 다 됐는지 판정하는 기준이에요
uv · 파이썬 프로그램을 설치하고 관리하는 도구예요
확장 · 기본에 없는 명령이나 점검 단계를 나중에 더해 넣는 묶음이에요

AI 답은 참고 자료예요. 법·세금·돈·건강처럼 삶에 큰 영향을 주는 일에서는 AI 답이 정답이 될 수 없어요. 최종 판단은 전문가나 공식 기관에서 확인하세요.