specify CLI가 프로젝트를 부트스트랩하면 AI 코딩 에이전트가 /speckit.* 슬래시 명령을 따라 어떻게를 만들어낸다. GitHub가 공식으로 내놓은 이 툰킷은 이제 단순 템플릿 생성기를 넘어 워크플로 엔진·확장·프리셋·번들·34종 에이전트 통합을 갖춘 플랫폼으로 자랐다. (저장소: github/spec-kit · Python 3.11+ · TrendShift Daily 18위 · MIT · v0.12.13, 2026-07-13 릴리스)이 레포가 무엇을 하는 물건인가.
건물을 지을 때 설계 도면을 그린 뒤 그걸 보고 짓지만, 다 지으면 도면은 서랍에 처박힌다. Spec Kit의 발상은 "도면을 살아있게" 두는 것 — 도면(명세)을 고치면 건물(코드)이 다시 지어지도록.
Spec Kit은 SDD(명세 주도 개발)라는 개발 방식을 실제로 굴러가게 해주는 도구 모음(toolkit)이다. 핵심 실체는 specify라는 파이썬 CLI (Command-Line Interface, 명령줄 도구) 하나와, 그것이 프로젝트에 심어주는 한 묶음의 슬래시 명령 프롬프트다. 사용자가 직접 코드를 짜는 게 아니라, Claude Code·Copilot·Gemini 같은 AI 에이전트에게 "무엇을 만들지"를 단계적으로 설명하면, 에이전트가 명세→계획→작업목록→구현 순서로 코드를 생성한다.
흐름은 정해진 순서를 따른다. /speckit.constitution(원칙 세우기) → /speckit.specify(무엇을 만들지) → /speckit.plan(어떤 기술로) → /speckit.tasks(작업 쪼개기) → /speckit.implement(실제 구현). 각 단계가 .specify/ 폴더 안에 문서(아티팩트)를 남기고, 다음 단계는 그 문서를 입력으로 받는다. 즉 프롬프트 한 방으로 앱을 뽑는 게 아니라, 검토 가능한 문서를 계단처럼 쌓아 올린다.
specify init이 .claude/commands/ 같은 폴더에 이 프롬프트들을 깔아두면, 에이전트 채팅창에서 /speckit.plan처럼 호출할 수 있다. (스킬 모드를 지원하는 에이전트는 speckit-plan 형태의 에이전트 스킬로 설치된다.)트렌딩 이유 · 경쟁 대비 장점.
첫째, GitHub 공식 프로젝트다(라이선스 저작권자 = GitHub, Inc.). "바이브 코딩(vibe coding)"이 유행하며 품질·재현성 문제가 불거지자, GitHub이 그 반대편의 규율 잡힌 방법론을 도구로 제시한 셈이라 주목도가 높다. 둘째, 에이전트 중립성 — 특정 AI에 묶이지 않고 34종의 코딩 에이전트(Claude·Copilot·Gemini·Codex·Cursor·opencode·Hermes 등)를 지원한다. 셋째, 쉬지 않고 출시한다 — v0.12.13이 2026-07-13에 나왔고 며칠 간격으로 릴리스가 이어져, TrendShift에 반복적으로 재등장(re-trending)한다.
| 비교 축 | 바이브 코딩 (즉흥) | 전통 개발 | Spec Kit의 SDD |
|---|---|---|---|
| 출발점 | "이런 거 만들어줘" 한 방 프롬프트 | 사람이 손으로 코딩 | 명세·원칙 문서를 먼저 확정 |
| 명세의 지위 | 거의 없음 | 짜고 나면 버려지는 발판 | 실행 가능한 1급 자산 |
| AI 역할 | 한 번에 코드 생성 | 보조 자동완성 | 다단계 정제(명세→계획→작업→구현) |
| 재현성/검토 | 낮음(왜 이렇게 됐는지 불명) | 수동 리뷰 | 단계별 아티팩트로 추적·검토 가능 |
큰 기능을 프롬프트 하나로 뽑으면, 에이전트가 요구사항을 자기 마음대로 해석하고 중간 결정이 블랙박스로 묻힌다. 결과가 틀려도 "어느 가정에서 어긋났는지" 되짚기 어렵고, 팀이 같은 결과를 재현하기도 힘들다.
명세·계획·작업목록을 사람이 검토 가능한 문서로 분리해 각 단계에서 가정을 드러낸다. /speckit.clarify로 애매한 부분을 먼저 질문받고, /speckit.analyze로 문서 간 모순을 잡은 뒤에야 구현으로 넘어가므로, 오해가 코드로 굳기 전에 걸러진다.
넷째, 기업 친화성이 크게 강화됐다. 설치 자산을 휠(wheel) 안에 core_pack으로 번들해 네트워크 없이(air-gapped)도 specify init이 동작하고, 서브프로세스의 shell=True를 린트로 봉쇄(S602/S604/S605)하는 등 보안 자세를 코드로 못박았다. 개인 실험 도구를 넘어 조직에 배포하기 좋게 다듬은 것이 최근 트렌딩의 배경이다.
이 레포는 "웹앱"이 아니라 파이썬 CLI + 마크다운 프롬프트 팩이다.
Spec Kit에는 프론트엔드·서버·DB가 없다. 실체는 터미널에서 도는 파이썬 CLI와, 그 CLI가 흩뿌리는 마크다운 프롬프트/템플릿 파일들이다. 그래서 "스택"은 CLI를 이루는 라이브러리와 배포·스크립트 계층으로 읽어야 한다. (파이썬 소스만 약 95,000줄, 그중 src/specify_cli/ 코어가 약 35,700줄.)
| 레이어 | 기술 / 버전 | 역할 |
|---|---|---|
| CLI 프레임워크 | Typer ≥0.24 + Click ≥8.2.1 | specify의 서브명령 트리(init·workflow·extension…) 정의. |
| 터미널 UI | Rich + readchar | 컬러 출력·표·진행바, 화살표 키로 에이전트 고르는 대화식 프롬프트. |
| 설정/파싱 | PyYAML ≥6.0 · json5 ≥0.13 · pathspec · packaging | 워크플로 .yml·카탈로그 .json·버전 비교·경로 매칭. |
| 경로/저장 | platformdirs | OS별 사용자 설정 폴더(카탈로그 캐시 등) 위치 해석. |
| 빌드/배포 | hatchling (빌드 백엔드) · uv/pipx (설치) | 휠 패키징 + uv tool install로 전역 설치. |
| 크로스플랫폼 스크립트 | bash(.sh) + PowerShell(.ps1) + python 3중 패리티 | 전제조건 확인·기능 브랜치 생성 등을 어느 OS에서도 동일 동작. |
| 테스트 | pytest (test_*.py 113개) | contract·unit·integration·hooks·extensions 계약 검증. |
uv tool install specify-cli --from git+…@vX.Y.Z인데, 이렇게 하면 특정 릴리스 태그를 콕 집어 전역 명령으로 깐다. (릴리스 태그는 앞의 v를 유지 — 예: v0.12.11.)--옵션·서브명령·도움말을 자동 생성해주는 라이브러리(Click 위에 얹힘). Spec Kit은 이걸로 specify init/self/workflow/extension/preset/bundle/integration/step/catalog이라는 서브명령 트리를 만든다.명령이 어떤 순서로 흐르고, 커스터마이즈가 어떻게 겹쳐 쌓이는가.
Spec Kit을 이해하는 열쇠는 세 가지다. ① SDD 명령 파이프라인(문서가 계단처럼 쌓임), ② 4단 커스터마이즈 오버레이(코어를 안 건드리고 덮어쓰기), ③ 워크플로 엔진(그 명령들을 자동으로 이어 돌리고 사람 승인 게이트에서 멈췄다 재개). 하나씩 보자.
각 슬래시 명령은 .specify/ 아래에 아티팩트를 남기고, 다음 명령이 그 파일을 읽는다. 앞 단계 산출물이 뒤 단계 입력이 되는 단방향 계단 구조다.
.specify/memory/constitution.md에 저장되는 최상위 원칙 문서(코드 품질·테스트 기준·UX 일관성·성능 등). 이후 모든 단계가 이 "헌법"을 참조해 의사결정을 일관되게 유지한다 — 프로젝트 전체에 걸리는 가드레일.Spec Kit의 템플릿은 런타임에 위→아래로 훑어 첫 매치를 쓴다. 그래서 코어를 포크하지 않고도 스펙 양식·용어·명령을 갈아끼울 수 있다. 위층일수록 우선순위가 높다.
여기서 확장·프리셋·번들의 역할 분담이 핵심이다. 헷갈리기 쉬우니 표로 못박자.
| 구분 | 무엇을 하나 | 예시 | 명령 |
|---|---|---|---|
| 확장(Extension) | 새 능력 추가 — 없던 명령·단계를 붙임 | Jira 연동, 코드리뷰 단계, V-Model 추적성 | specify extension add |
| 프리셋(Preset) | 작동 방식 변경 — 코어·확장의 템플릿을 덮어씀 | 규제 양식, 도메인 용어, 애자일/워터폴, 언어 현지화 | specify preset add |
| 번들(Bundle) | 역할 세트 한 방 설치 — 확장+프리셋+워크플로를 묶음 | PM·비즈니스분석가·보안연구원·개발자 페르소나 | specify bundle install |
위 슬래시 명령들을 사람이 하나씩 치는 대신, specify workflow run이 YAML로 선언된 단계들을 순차 실행한다. 압권은 게이트(gate)에서 멈춰 사람 승인을 기다리고, 디스크에 상태를 저장했다가 나중에 재개(resume)하는 것이다. 내장 speckit 워크플로 = "Full SDD Cycle": specify → (스펙 리뷰 게이트) → plan → tasks → implement.
gate 스텝은 사람의 검토·승인을 위해 실행을 멈춘다(CI에선 PAUSED로 대기). 엔진은 매 스텝 후 RunState(현재 스텝 인덱스 + 누적 결과)를 파일로 저장하므로, specify workflow resume <run_id>로 정확히 그 지점부터 이어갈 수 있다. 장시간·사람개입 파이프라인을 안전하게 다루는 정석 패턴.공항 출국 게이트처럼 생각하면 쉽다. 체크인→보안검색→탑승까지 단계가 정해져 있고(스텝), 보안검색대(gate)에서 사람이 통과 도장을 찍어줘야 다음으로 간다. 도중에 비행기가 지연돼 대기실에 앉았다가(PAUSED, 디스크에 상태 저장) 안내방송이 나오면 앉았던 그 자리에서 이어서 탑승(resume)한다.
어떤 폴더가 무슨 일을 하나 (파이썬 코어 + 배포 자산).
| 위치 | 역할 |
|---|---|
src/specify_cli/workflows/ | 엔진의 심장 — engine.py(1,377줄)가 스텝을 디스패치, expressions.py가 {{ }} 치환. |
src/specify_cli/integrations/ | 에이전트마다 명령을 어디에 어떤 형식(Markdown/TOML/Skill)으로 깔지 정의. 새 에이전트는 여기 서브클래스로 추가. |
templates/commands/ | 실제로 배포되는 /speckit.* 프롬프트 원본. 이 마크다운이 곧 "에이전트 지시서". |
scripts/{bash,powershell,python}/ | 같은 기능을 3중으로 — 어떤 OS·셸이든 동일 동작 보장. |
.specify/ (생성물) | specify init이 사용자 프로젝트에 만드는 폴더 — memory(헌법)·templates·specs가 여기 쌓인다. |
이 레포에서 실제로 훔쳐올 만한 설계 아이디어 + 어디를 보면 되는지.
specify 하나 밑에 init·self·workflow·extension·preset·bundle·integration·step·catalog가 트리로 달린다. app.add_typer(sub_app, name="...") 패턴으로 큰 CLI를 모듈별로 쪼개는 법을 src/specify_cli/__init__.py와 commands/에서 배울 수 있다.
YAML로 스텝을 선언하고, 제어흐름 스텝(if/switch/while)이 next_steps를 반환해 재귀 실행되는 구조. 매 스텝 후 상태를 직렬화해 resume하는 체크포인트 설계는 배치·에이전트 파이프라인에 그대로 응용된다. → workflows/engine.py, workflows/ARCHITECTURE.md.
코어를 포크하지 않고 "위층이 아래층을 덮는" 4단 해석으로 확장성을 얻는 설계. 확장·프리셋·번들의 책임 분리(능력 추가 vs 방식 변경 vs 역할 묶음)는 어떤 플러그인 아키텍처에도 참고가 된다. → extensions/__init__.py(3,535줄), presets/__init__.py(3,391줄).
34종 에이전트의 차이를 MarkdownIntegration·TomlIntegration·SkillsIntegration 세 베이스 클래스로 흡수한다. "N종 대상 × 공통 로직"을 어댑터로 접는 법을 integrations/base.py에서 볼 수 있다.
워크플로 스텝은 이렇게 YAML로 선언된다(내장 speckit 워크플로 발췌):
steps:
- id: specify
command: speckit.specify
integration: "{{ inputs.integration }}" # auto = 프로젝트가 init된 에이전트
input: { args: "{{ inputs.spec }}" }
- id: review-spec # ← 사람 승인 게이트
type: gate
message: "Review the generated spec before planning."
options: [approve, reject]
on_reject: abort
- id: plan
command: speckit.plan
integration: "{{ inputs.integration }}"돌리려면 무엇이 필요한가 (순수 SW·터미널 도구).
| 항목 | 요구사항 |
|---|---|
| OS | Linux · macOS · Windows (스크립트가 3중 패리티라 셸 무관) |
| 런타임 | Python 3.11+ |
| 설치 도구 | uv(권장) 또는 pipx — uv tool install specify-cli --from git+…@vX.Y.Z |
| 버전 관리 | Git (기능 브랜치·아티팩트 추적) |
| AI 에이전트 | 지원 목록 중 최소 1종 (Claude Code·Copilot·Gemini·Codex·Cursor·opencode·Hermes 등 34종) |
| 네트워크 | 설치 시 필요하나, init 자체는 core_pack 번들 덕에 오프라인 가능(에어갭 환경 대응) |
v를 떼지 말 것설치 시 @v0.12.11처럼 앞의 v를 유지해야 한다(@0.12.11은 실패). 비대화식 세션(CI·파이프)에서 specify init은 --integration 미지정 시 GitHub Copilot으로 기본 선택되니, 다른 에이전트면 명시하자.
난이도별로 손에 익히는 단계.
specify init photo-albums --integration copilot로 시작해, 에이전트 창에서 /speckit.constitution → /speckit.specify(사진 앨범 앱) → /speckit.plan(Vite+바닐라JS+SQLite) → /speckit.tasks → /speckit.implement 순서로 실행. 각 단계가 .specify/·specs/에 어떤 문서를 남기는지 열어보는 게 핵심.
.specify/templates/overrides/에 스펙 템플릿을 하나 두고, 섹션(예: "보안 고려사항")을 강제로 추가해본다. 런타임 오버레이라 코어를 안 건드리고도 다음 /speckit.specify 결과가 바뀌는 것을 확인.
specify workflow run speckit으로 Full SDD Cycle을 실행 → review-spec 게이트에서 멈추는 것을 확인하고, 승인/거부에 따라 흐름이 달라지는지 본다. 중단 후 specify workflow resume으로 이어지는지도 테스트.
presets/lean을 참고해 나만의 프리셋을 작성 — 예: 스펙 용어를 우리 팀 표준으로 바꾸거나 test-first 순서를 강제. specify preset add로 설치하고 우선순위 스택에서 코어를 덮는지 확인.
integrations/CONTRIBUTING.md 체크리스트대로 src/specify_cli/integrations/<agent>/에 MarkdownIntegration 서브클래스를 만들고, integrations/catalog.json에 등록 + 테스트 추가. 어댑터 패턴을 직접 확장해보는 과제.
한 주씩 따라가는 계획.
| 주차 | 주제 | 학습 자료 |
|---|---|---|
| 1주차 | SDD 개념 + 한 바퀴 실행 | README · spec-driven.md · 실습 1 |
| 2주차 | 슬래시 명령 프롬프트 해부 | templates/commands/*.md 정독 (specify·plan·analyze) |
| 3주차 | Typer CLI 구조 + 서브명령 트리 | src/specify_cli/__init__.py · commands/ |
| 4주차 | 워크플로 엔진 + 상태 재개 | workflows/ARCHITECTURE.md · engine.py |
| 5주차 | 확장·프리셋·번들 오버레이 설계 | extensions/·presets/ 가이드 · 예시 번들 매니페스트 |
본문에 나온 용어 빠른 참조.
| 용어 | 의미 |
|---|---|
| SDD | Spec-Driven Development. 명세를 실행 가능한 1급 자산으로 삼아 구현을 파생시키는 개발 방식. |
| specify CLI | Spec Kit의 실체가 되는 파이썬 명령줄 도구. 프로젝트를 부트스트랩하고 명령·워크플로를 관리. |
| constitution | 프로젝트 최상위 원칙 문서(.specify/memory/). 모든 단계가 참조하는 가드레일. |
| slash command | /speckit.* — 에이전트에게 정의된 프롬프트를 부르는 단축키. 스킬 모드는 speckit-*. |
| clarify / analyze | 구현 전 품질 게이트 — 애매한 요구를 질문(clarify), 문서 간 모순·누락을 교차 점검(analyze). |
| converge | 기존(브라운필드) 코드베이스를 명세·계획과 대조해 남은 작업을 새 태스크로 추가. |
| 워크플로 엔진 | YAML 스텝을 순차 실행. gate에서 멈추고 상태 저장 후 resume 가능. |
| gate 스텝 | 사람 검토·승인을 위해 실행을 멈추는 스텝(CI에선 PAUSED). |
| 확장(Extension) | 없던 명령·단계를 추가하는 애드온(git·bug·agent-context 등). |
| 프리셋(Preset) | 코어·확장의 템플릿/용어를 덮어써 "작동 방식"을 바꾸는 오버레이(lean 등). |
| 번들(Bundle) | 확장+프리셋+워크플로를 묶은 버전 관리 역할 세트(PM·개발자 등). |
| 통합(Integration) | Spec Kit이 지원하는 AI 코딩 에이전트(34종). Markdown/TOML/Skills 베이스로 추상화. |
| core_pack | 설치 자산을 휠에 번들해 init을 오프라인·에어갭에서도 돌게 하는 장치. |
| uv | Rust 기반 초고속 파이썬 패키지·도구 관리자(권장 설치 경로). |