GitHub의 ‘Spec Kit’을 사용해 보기ー사양 주도 개발로 시작하는 새로운 개발 흐름ー
-
2025년 11월 13일
안녕하세요.
Cocone Engineering Web Development Unit 소속 프론트 엔지니어 사루타입니다.
이번에는 GitHub에서 2025년 9월에 공개한 스펙 기반 개발을 위한 툴킷 ‘Spec Kit’에 대해 실제로 사용해 본 소감을 정리하여 소개하고자 합니다.
많은 관심 부탁드립니다.
‘Spec Kit’란?
https://github.com/github/spec-kit
Spec Kit은 GitHub가 OSS로 2025년 9월에 공개한 스펙 기반 개발(Spec-Driven Development, SDD)을 지원하는 도구입니다.
최근 AI를 통한 자동 코드 생성의 정확도가 높아지는 반면, 스펙의 모호함으로 인한 문제도 증가하고 있는데, Spec Kit은 그 근본을 바로잡는 ‘스펙부터 시작하는 개발’을 GitHub 공식으로 체계화한 것입니다.
설계서를 기반으로 개발함으로써 AI의 ‘추측’을 방지하고 코드와 의도의 무결성을 확보하며, 각 단계별 검증 기능을 통해 ‘과도한 코드 생성’과 ‘요구사항 누락’을 방지하여 견고한 개발 플로우를 구현합니다.
핵심 개념
스펙 기반 개발(Spec-Driven Development, SDD)에서는 다음 사항을 중요시 합니다 :
・의도 중심의 개발：어떻게 만들 것인가보다 ‘무엇을 만들 것인가’를 먼저 명확히 한다
・충실한 사양 작성：가이드라인과 조직의 원칙을 활용하여 제대로된 사양을 마련한다.
・한 번에 완성하지 않고 단계적으로 보완해 나간다.
・AI의 높은 이해력을 활용하여 사양을 해석한다.
경쟁 상대인 스펙 기반 개발 도구와 비교
2025년 10월 기준, Spec Kit과 경쟁하는 스 기반 개발 도구는 다음과 같습니다.
・Kiro
각각의 툴을 비교해 보았습니다.
| 項目 | ⭐SpecKit | Kiro | spec-workflow-mcp | cc-sdd | Claude Code Spec Workflow |
|---|---|---|---|---|---|
| 제공 | GitHub（2025/9 공개） | AWS계열 스타트업 | 커뮤니티 구현 | 일본 개발 OSS | Anthropic 주변 커뮤니티 |
| 라이센스 | 클로즈드（GitHub 공식） | 클로즈드 | OSS와 같은 워크 플로우 구현 | OSS | OSS와 같은 워크 플로우 |
| 사양기술형식 | 전용 포맷（YAML/Markdown 연계 상정） | 고유 형식／IDE 연계 | Markdown/DSL | 일본어 대응 DSL | Markdown 베이스 |
| AI연계 | GitHub Copilot, OpenAI 계열과 연계 전제 | AWS계열 모델에 최적화 | Claude / GPT 양쪽 대응 | 임의 LLM 접속 가능 | Claude 특화 |
| 점 | GitHub 공식の안심、CI/CD 통합이 강력 | 엔터프라이즈 지향、IDE통합 | 승인 플로우 중시、품질 관리 | 일본어 대응、가볍게 학습하기 좋음 | Claude 와 스펙 기반의 표준화된 실험적 접근 방식 |
| 과제 | 클로즈드로 확장성 제한 있음 | 클로즈드＆이용 실적에 제한 됨 | 성숙도가 낮음、구현 례가 적음 | 대규모 안건에 대한 실적 부족 | 기능이 제한적、Claude 의존 |
| 대상 유저 | GitHub 유저 전반, SDD 초급자 ~ 실무 | 대규모 조직、AWS유저 | 품질 관리를 중시하는 팀 | OSS 지향、일본어 이용자 | Claude 를 이용중인 팀 |
| 성숙도 | 높음（공식 서포트 ＋문서 정비） | 중간（클로즈드β와 같은 단계） | 저 〜 중（한정 이용） | 저（커뮤니티 성장 단계） | 저（실험적） |
보충 설명
Spec Kit 자체는 사양 수립에 특화된 프롬프트 모음과 같은 도구이며, GitHub Copilot이나 Claude 등 다른 AI 어시스턴트와 함께 사용합니다.
도입 방법（Getting Started）
uv 설치
Spec Kit의 CLI를 사용하기 위해서는 Python 패키지 관리자 uv가 필요하며, uv를 설치하려면 아래 명령어를 실행합니다.
curl -LsSf <https://astral.sh/uv/install.sh> | shSpecify CLI 설치
아래 명령어로 설치합니다.
specify-cli는 Spec Kit의 CLI 프론트엔드로 제공되며, Spec Kit 리포지토리 내에 포함되어 있습니다.
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git개발 흐름
개발 과정은 총 7단계로 구성되어 있다.
・‘공정 1: 프로젝트 원칙 작성 /constitution‘은 원칙적으로 한 번만 수행합니다.
‘공정 3: 기술적 구현 계획 작성’, ‘공정 6: 무결성 검사’의 실행은 2025년 10월 현재 선택 사항입니다.
각 공정을 명령어로 실행합니다.
| 공정 | 작업 내용 | 명령 |
|---|---|---|
| 1 | 프로젝트 원칙 작성 | /constitution |
| 2 | 사양 작성 | /specify |
| 3 | 사양 명확화 | /clarify |
| 4 | 기술적 구현 계획 작성 | /plan |
| 5 | 작업 관리 | /tasks |
| 6 | 무결 검사 | /analyze |
| 7 | 구현 | /implement |
실제 작업
실시간 채팅 구축을 예로 들어 설명하겠습니다.
（준비）프로젝트 초기화
아래 명령어로 최신 템플릿에서 새로운 Specify 프로젝트를 초기화합니다.
# 신규 작성
specify init <PROJECT_NAME>
# 기존 프로젝트에서 작성
$ specify init --here
# 자동으로 설정되는 git의 설정을 무시하고 싶은 경우
$ specify init <project-name> --no-git
AI 어시스턴트를 선택합니다. 이번에는 copilot (GitHub Copilot) 을 선택하였다.
스크립트를 선택합니다. 이번에는 sh 를 선택하였습니다.
-- 보안 --
프로젝트가 준비되었습니다. 일부 에이전트는 프로젝트내 에이전트 폴더에 인증 정보, 인증 토큰, 그외의 식별 정보나 비밀의 성과물을 보존하는 경우가 있습니다.
인증 정보의 누출을 방지하기 위해, .github/（또는 그일부）를 .gitignore 에 추가할 것을 검토해주세요.
--- 다음 단계 --
1. 프로젝트 폴드에 이동: cd speckit-project │
2. AI 에이전트에 슬래쉬 명령어를 사용해 보아요: │
2.1 /constitution - 프로젝트 원칙 확립 │
2.2 /specify - 베이스 라인 사양 작성 │
2.3 /plan - 구현 계획 작성 │
2.4 /tasks - 실행 가능한 작업 작성 │
2.5 /implement - 구현 실행 │
--- 확장 명령어 --
○ /clarify（임의） - 애매한 부분을 리스크 회피를 하기 위해 구조화된 질문을 합니다.（사용할 경우 /plan 전에 실행）
○ /analyze（임의） - 성과물 간의 일관성과 무결성의 레포트 작성（/tasks 후、/implement 전에 실행）※ Specify-cli를 설치하지 않고 직접 실행하는 방법도 존재하지만, 2025년 10월 현재로서는 명령어 설치를 권장하고 있습니다.
uvx --from git+https://github.com/github/spec-kit.git specify init <PROJECT_NAME>프로젝트 디렉토리 구조
다음과 같은 디렉토리 구성으로 프로젝트가 설정됩니다.
tree -a -I '.git|node_modules' -L 4
.
├── .github
│ └── prompts # 프롬프트
│ ├── analyze.prompt.md
│ ├── clarify.prompt.md
│ ├── constitution.prompt.md
│ ├── implement.prompt.md
│ ├── plan.prompt.md
│ ├── specify.prompt.md
│ └── tasks.prompt.md
└── .specify
├── memory # AI의 행동 범위를 정의
│ └── constitution.md
├── scripts
│ └── bash # 프로텍트 운영의 자동화 스크립트
│ ├── check-prerequisites.sh
│ ├── common.sh
│ ├── create-new-feature.sh
│ ├── setup-plan.sh
│ └── update-agent-context.sh
└── templates # 사양・계획・작업을 문서화하기 위한 템플릿
├── agent-file-template.md
├── plan-template.md
├── spec-template.md
└── tasks-template.md1. 프로젝트 원칙 확립：/constitution
・작성은「 /constitution 」명령어로 시작합니다.
・개발 도구, 개발 스타일, 코딩 규약을 지정합니다.
・기본 처음 한 번만 실행합니다. 수정이 필요한 경우 다시 실행합니다.
・실행 후, .specify/memory/constitution.md 가 생성/업데이트됩니다.
・이후, 기반 파일로 활용됩니다.
👨💻 실행 예시：
/constitution 코드 품질, 테스트 기준, UX, 퍼포먼스 요건, 보안, 문서 정비의 원칙 작성
1. 코드 품질
- 모든 코드는 정해진 스타일 가이드와 린팅 룰에 따를 것.
- 모든 풀 리퀘스트는 코드 리뷰를 반드시 실할 것.
- 가동석과 확장성을 유지하기 위해 필요에 따라 리펙토링을 우선시할 것.
2. 테스트 기준
- 각 기능에는 에지 케이스(edge case)를 포함하는 유닛 테스트를 반드시 구현할 것.
- 중요한 처리 플로우에는 통합 테스트를 실시할 것.
- 코어 모듈의 테스트 관리는 항상 85% 이상을 유지 할 것.
3. UX의 일관성
- UI는 공통 디자인 시스템에 준비 할 것.
- 접근성 기준 (WCAG 2.1 AA 이상)을 반드시 충족할 것.
- 릴리스 전에 크로스 디바이스・크로스 브라우저의 동작 검증을 실행할 것.
4. 퍼포먼스 요건
- 페이지 읽기 시간은 표준 디바이스에 2초 이내를 목표로할 것.
- API응답 시간은 평상시 부하 상태에서 300ms이내를 목표로할 것.
- 각 스프린트마다 퍼포먼스 검사를 실시 할 것.
5. 보안
- 모든 의존 라이브러리는 정기적으로 업데이트하고, 취약점을 검사할 것.
- 기밀 정보（API 키、패스워드 등）은 코드 베이스에 포함하지말 것.
- OWASP Top 10을 기준으로 보안 검사를 할 것.
6. 문서 정비
- 한국어로 기재 할 것.
- 신기능이나 중요한 변경점에는 반드시 개발자용 문서를 업데이트할 것.
- README・설정 순서・API 사양은 항상 최신 상태를 유지할 것.
- 유저용 가이드나 튜토리얼은 릴리스와 동시에 공개・업데이트할 것.2. 사양 작성：/specify
・작성은「 /specify 」명령어로 시작합니다.
・프로젝트의 사양을 지정합니다.
・대상은 개발자가 아닌 비즈니스 관계자입니다.
・프로젝트의 의도인 ‘사용자가 무엇을 필요로 하는지’, ‘왜 필요한지’를 지정합니다.
・이 과정에서는 기술 스택, API, 코드 구조 등 구현 방법에 대해서는 언급해서는 안됩니다.
・기술 스택은 다음 /plan 으로 지정하고, 대상은 개발자가 됩니다.
・사양이 모호한 경우, [NEEDS CLARIFICATION] 마크가 부여됩니다. 이 부분은 AI와 상의하면서 명확히 해 나갑니다.
・실행 후, .specs/ 아래에 브런치(예: 001-1-google-2） specs/001-1-google-2 디렉토리가 생성됩니다.
・위 디렉토리 아래에 spec.md 가 생성됩니다.
👨💻실행 예시：
/specify 심플한 리얼 타임 챗팅 작성
1. 인증 시스템
- Google 계정 로그인
- 자동 유저 정보 동기
- 세션 관리
2. 리얼 타임 챗팅
- 즉시 메세지 송수신
- WebSocket 를 사용한 쌍방향 통신
- 30분간의 메세지 이력
- 자동 메세지 클린 업（30분 경과 후）
3. 유저빌리티 기능
- PC、스마트폰 댕응
- 입력 중 표시（타이핑 인디케이터）
- 온라인 참가자 리스트（아이콘 표시）
- 문자는 100자 제한＋문자수 카운터
- Enter 키로 송신, Shift+Enter 로 개행
- 색상은 모노톤(흑백)으로, 대비를 높게
- 텍스트는 모든 환경에서 보기 좋은 크기로
- 반응형 웹 디자인
4. 퍼포먼스＆보수성
- Error Boundary 를 사용한 에러 처리spec.md 생성 후, AI가 미확정 사항에 대한 질문을 하여 답변하였습니다.
미확정사항（Clarification 필수）
- 타이핑 인디케이터 삭제까지의 X 초（제안: 3 초 유지 후 페이드 아웃）
- 타이핑 이벤트 송신 스로틀 간격（제안: 500ms）
- 재접속시 일괄 동기의 최대 메세지 건수（제안: 200 건）
- 중복 메세지（내용・타임스탬프 근접）의 제어 필요/불필요（현재는 허용 설계）
- 여러 탭/여러 디바이스 동시 접속 처리（PresenceSession 모델 1:1 제약을 완화할지）
- 오프라인에서 돌아올때의 배치사이즈 상한선（제안: 200 건 or 30 분 기간내 전건）3. 사양 명확화： /clarify
・작성은「 /clarify 」명령어로 시작합니다.
・작성한 사양에서 AI가 보기에 부족한 부분을 명확히 합니다.
・/plan 앞에 실행해야 합니다.
・명확화를 진행하면 앞서 설명한 spec.md 가 업데이트됩니다.
👨💻실행 예시：
/clarify 사양 부족, 불명확한 사양 확인AI의 질문이 있으면 답변합니다.
🤖질문 예시：
Presence（접속 상태）판별을 위한 하트비트 간격과 타임아웃 임계값을 선택해 주십시오.
(정의: 클라이언트는 일정 간격으로 heartbeat 를 송신. 서버는 최종 송신 시각과의 차분이 임계치를 넘으면'이탈'로 봅니다.)
Option Description
A 10s 간격 / 25s で이탈 (2회 연속 결손 + 유예)
B 15s 간격 / 45s で이탈 (3회 연속 결손)
C 5s 간격 / 15s で이탈 (3회 연속 결손) / 반응성 우선
D 8s 간격 / 24s で이탈 (3회 연속 결손, 중용)
E Short답변을 계속하면 종료 취지의 답변을 얻을 수 있습니다.
이걸로 Clarification 는 상한선 도달로 인해 종료합니다.
다음 단계로 /plan 실행을 추천합니다. 진행해도 된다면 '/plan 실행'이나 'plan' 이라고 답변해 주세요.4. 기술적 구현 계획 작성：/plan
・작성은「 /plan 」명령어로 시작합니다.
・구현 기술, 구현 정책 등 사용할 기술 스택을 구체화합니다.
👨💻실행 예시：
/plan 기술 스택은 밑에와 같이 채용
- 프론트엔드：Next.js 15 (App Router)
- 스타일링：TailwindCSS
- 상태관리：Zustand
- 인증：Clerk (Google OAuth)
- 백엔드、데이터 베이스：Convex (리얼 타임 데이터 베이스)
- Type세이프티: TypeScript
- 단위 테스트: Vitest
- UI 테스트: React Testing Library실행 후, /specify 로 생성된 디렉토리 아래에 다음과 같은 파일이 생성됩니다.
.
├── contracts # 각 모듈・에이전트간의 통신 사양을 저장
│ ├── heartbeat.json # 시스템의 생존확인이나 헬스 체크용 통신사양. 에이전트가 동작하고 있는지 확인
│ ├── message.json # 일반적인 메세지 송수신 사양. 송신자・수신자・본문・타임스탭프등을 정의
│ ├── presence.json # 에이전트의 '온라인／오프라인'상태등 현재 상태를 다루는 계약
│ └── typing.json # '입력중（typing）'등 리얼 타임 상태를 통지하는 계약. 챗팅이나 공동 편집계열에서 이용
├── data-model.md # 데이터 구조・스키마 정의
├── plan.md # 구현 계획・진행 방침
├── quickstart.md # 초기 셋업 가이드
├── research.md # 조사・검토 기록
└── spec.md # 2. 사양 작성：`/specify` 에서 생성5. 작업 정리：/tasks
・작성은「 /tasks 」명령어로 시작합니다.
・기술 계획에서 실행 가능한 작업 목록을 작성합니다.
・실행 후, /specify 로 생성된 디렉토리 아래에, tasks.md 가 생성됩니다.
👨💻실행 예시：
/taskstasks.md 의 예시：
## Phase 3.1: Setup
- [ ] T001 Initialize project manifest & tooling (Node 22.16.0 via .nvmrc, package.json with Next.js 15.5.4, React 19, TypeScript, Tailwind, shadcn/ui, Zustand, Convex, Clerk, ESLint, Prettier, Vitest, React Testing Library). Files: `.nvmrc`, `package.json`, `.eslintrc.cjs`, `tsconfig.json`, `vitest.config.ts`, `.prettierrc`.
- [ ] T002 Configure Tailwind & shadcn/ui (generate config, add base styles). Files: `tailwind.config.ts`, `postcss.config.js`, `app/globals.css`.・작업는 ‘작업(T)’로 나열됩니다(예: T008).
・작업 묶음은 ‘Phase’로 분류됩니다.
6. 整合性のチェック：/analyze
・작성은「 /analyze 」명령어로 시작합니다.
・사양・계획・작업의 일관성을 확인합니다.
👨💻실행 예시：
/analyze실행 후, 분석 결과와 AI에서 수정 여부를 묻습니다.
A) 지금 바로 수정 작업을 적용합니다（추천：코딩 전）
B) 현재 작업 그대로 진행합니다（리스크：'모든 기능 테스트'게이트를 충족하지 못할 가능성 있음）실행 후, /specify 로 생성된 디렉터리 아래 파일이 업데이트됩니다.
예시：
logging.md # 신규 추가
spec.md # 업데이트
tasks.md # 업데이트7. 구현：/implement
・계획에 따라 작업을 소화하고 구현을 진행합니다.
👨💻실행 예시：
/implement위의 경우, 모든 페이즈를 실행하게 되므로 버그 발생 시 대응, 코드 검토가 어려워집니다.
기본은 페이즈별로, AI의 제안을 참고하여 작업별로 실행 + 그때그때 검토하면서 진행하였습니다.
👨💻실행 예시：
/implement Phase 3.1: Setup
/implement contract 의 확장 (T064, T069)
/implement T012 → (병행) T013, T014, T015, T016, T017, T018 순서로 추가
/implement T060 군 추가
/implement 잔여 복구 시스템 통합 테스트 프레임워크 추가 (T060–T068) 도 먼저 failing 으로 준비실행 후, tasks.md 의 작업 목록에서 완료된 작업에 체크가 들어갑니다.
예시：
## Phase 3.1: Setup
- [x] T001 Initialize project manifest & tooling (Node 22.16.0 via .nvmrc, package.json with Next.js 15.5.4, React 19, TypeScript, Tailwind, shadcn/ui, Zustand, Convex, Clerk, ESLint, Prettier, Vitest, React Testing Library). Files: `.nvmrc`, `package.json`, `.eslintrc.cjs`, `tsconfig.json`, `vitest.config.ts`, `.prettierrc`.
- [x] T002 Configure Tailwind & shadcn/ui (generate config, add base styles). Files: `tailwind.config.ts`, `postcss.config.js`, `app/globals.css`.사용해 본 소감
※좋았던 점
・명령줄 인터페이스(CLI), 프롬프트 등이 미리 정비되어 있어 도입 장벽이 낮게 느껴졌습니다.
・사양 기반으로 구축하기 때문에 프로젝트 목적에 어긋나지 않고, 품질이 높은 코드가 생성되었습니다. 마찬가지로 자동 테스트 생성, 문서 자동 생성도 원활하게 이루어졌다.
・구현 명령어「 /implement 」에 대해 세밀하게 지정하여 요청하여 진행했기 때문에 검증 및 수정이 무리 없이 진행되어 문제를 조기에 발견하고 수정할 수 있었습니다.
※아쉬웠던 점
・개발 전 세부 사양을 정리하는 작업에 시간이 많이 소요됩니다. 속도를 중시하는 프로젝트에서는 부담이 될 것 같습니다.
・기술 스택의 버전을 명시하는 것이 좋을 것 같습니다. 예를 들어 Next.js에 대해 처음에 ’15’로 의뢰했는데, 오래된 버전이었습니다. ‘v15.5.4’라고 명확하게 지시하는 것이 좋을 것 같습니다.
※기타
・앞서 언급했듯이 Spec Kit 자체는 프롬프트 모음집과 같아서 코드의 품질을 보장하지 않으므로 AI 모델 선택은 신중하게 진행하는 것이 좋을 것 같습니다(이번엔 ‘Agent + GTP-5’로 진행했습니다).
・사양을 명확히 하는 명령어「 /clarify 」를 사용하면 사양의 정확도가 높아진다는 인상을 받았습니다. 현재 임의 명령어로 제공되고 있지만, 실행하는 것이 좋을 것 같습니다.
마지막으로
Spec Kit은 ‘스펙 기반 개발’을 촉진하는 강력한 도구이며, 설계의 정확성을 높이고 싶은 페이즈에서 매우 효과적이라고 느꼈습니다.
아마도 ‘요건이 복잡하여 팀 간 인식을 일치시켜야 하는 개발 프로젝트’에 적합할 것 같습니다.
반면, ‘프로토 타이핑, 속도 중점을 둔 프로젝트’에는 오버헤드가 발생하기 쉬워 적합하지 않은 것 같다는 인상을 받았습니다.
본 기사로 관심을 가져주셨다면 좋겠습니다.
