GitHub Spec Kit 심층 분석 — Spec-Driven Development, Constitution, /speckit.* 슬래시

AI 코딩 에이전트(AI coding agents)가 일상이 되면서, 가장 흔한 실패 유형은 _바이브 코딩 (vibe coding)_입니다. 즉, 한 줄짜리 프롬프트로 시작하고 코드 자체가 조용히 명세(spec)가 되어버리는 현상입니다. 코드는 본질적으로 **구속력이 있는 산출물 (binding artifact)**입니다. 일단 구현이 확정되면, 변화하는 모든 요구사항은 비용이 많이 드는 재작업을 유발합니다. GitHub Spec Kit은 이 상황을 완전히 뒤집습니다. 명세를

측면 (Aspect)	전통적 방식 / 바이브 코딩 (Vibe Coding)	명세 기반 개발 (Spec-Driven Development)
주요 산출물 (Primary artifact)	코드 (명세는 뼈대일 뿐이며 폐기됨)	명세 (실행 가능하며, 코드를 생성함)
...	...	...

2. Specify CLI — 설치 및 부트스트랩 (bootstrap)

Spec Kit은 두 가지 기둥으로 구성됩니다: (1) SDD를 위해 프로젝트의 뼈대를 만드는 Specify CLI (Python 기반, MIT 라이선스, 패키지명 specify-cli), 그리고 (2) 명세(spec), 계획(plan), 작업 목록(task list)이 어떤 모습이어야 하는지를 정의하는 템플릿 및 헬퍼 스크립트 (templates and helper scripts) 번들입니다. 이 두 부분 외에 다른 마법 같은 기능은 없습니다. 사전 요구 사항은 다음과 같습니다:

• Linux / macOS / Windows (네이티브 또는 WSL)
• 지원되는 AI 코딩 에이전트 (Copilot, Claude, Gemini, Codex, Cursor, Windsurf 및 30개 이상의 기타 에이전트)
• 영구 설치를 위한 uv (권장) 또는 pipx · Python 3.11+ · Git

# 영구 설치 (권장) — vX.Y.Z를 최신 Releases 태그로 교체하세요
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@vX.Y.Z

...

초기화(Initialization)를 수행하면 .specify/ 폴더와 에이전트 전용 폴더(예: Copilot의 경우 .github/)가 생성됩니다. .specify에는 명세/계획/작업 템플릿과 사용자의 플랫폼에 맞는 스크립트(POSIX용 bash, 네이티브 Windows용 PowerShell)가 들어 있습니다. 그리고 여러분이 이전에 본 적이 없을 수도 있는 파일인 memory/constitution.md가 핵심(keystone) 역할을 합니다.

# `specify init` 실행 후 생성되는 구조 (요약)
my-project/
├── .github/                      # 에이전트 전용: 슬래시 명령어(slash-command) 프롬프트 정의
...

초기화 시, Specify는 사용자가 Git 저장소 내에 있는지 확인하며(필요한 경우 생성함), 헬퍼 스크립트는 모든 작업이 **동일한 기능 브랜치 (same feature branch)**에서 이루어지도록 강제하고, 이후의 프롬프트들이 이전에 생성된 명세, 계획 및 데이터 계약(data contracts)을 올바르게 참조하도록 유지합니다.

3. 헌법 (The Constitution) — 코드가 작성되기 전 협상 불가능한 사항들을 확정하기

SDD에서 **헌법 (Constitution)**은 프로젝트의 *협상 불가능한 원칙 (non-negotiable principles)*을 포착합니다. 예를 들어 "웹 앱은 항상 이 테스트 방식을 따른다", "이 팀이 구축하는 모든 앱은 CLI-first 방식이다"와 같은 원칙들이 어떠한 SDD 반복 (iteration)이 시작되기 전에 확정됩니다. 이를 통해 조직은 모든 신규 및 기존 프로젝트를 안내하는 **의견이 반영된 스택 (opinionated stack)**을 구축할 수 있습니다.

# 프로젝트 디렉토리에서 에이전트를 실행한 후, 가장 먼저 다음을 수행합니다:
/speckit.constitution 코드 품질, 테스트 표준, 사용자 경험 일관성 및 성능 요구 사항에 중점을 둔 원칙을 생성하십시오

이 명령은 .specify/memory/constitution.md 파일을 생성하거나 업데이트하며, 에이전트는 specify, plan, implement 단계 동안 이 파일을 참조합니다. 헌법은 단순한 문서가 아닙니다. 이는 **이후의 모든 단계를 구속하는 가드레일 (guardrail)**입니다. /speckit.plan에 의해 생성된 계획은 헌법을 근거로 삼으며, 여러분의 컨벤션 (convention)을 위반하는 결정들을 억제합니다.

4. 핵심 워크플로 (The core workflow) — /speckit.* 슬래시 명령어

출시 당시 Spec Kit은 세 가지 명령어(/specify, /plan, /tasks)로 시작했습니다. 2026년 현재, 이들은 네임스페이스가 지정된 /speckit.* 체계로 정착되었습니다 (스킬 모드의 Codex CLI는 $speckit-*를 사용합니다). 한 문장으로 요약하자면, 전체 흐름은 Spec → Plan → Tasks → Implement이며, 헌법과 품질 게이트 (quality gates)가 상하로 감싸고 있는 형태입니다.

4.1 핵심 명령어

명령어	에이전트 스킬	역할
/speckit.constitution	speckit-constitution	거버닝 원칙 (governing principles) 및 개발 가이드라인 생성/업데이트
...
/speckit.specify는 기술적 결정을 명시적으로 제외합니다. 즉, 스택을 작성하는 것이 아니라 동기(motivations)와 기능적 요구 사항을 작성합니다. 반대로 /speckit.plan은 "방법 (how)"(프레임워크, 라이브러리, DB, 인프라)을 다루며, 팀원들이 즉시 실험을 시작할 수 있도록 조사(research), 데이터 계약 (data contracts), 퀵스타트 (quickstart)와 같은 추가 메타데이터를 생성합니다.

# 4단계: 무엇을 / 왜 (스택을 지정하지 마세요)
/speckit.specify 날짜별로 그룹화된 앨범으로 사진을 정리하고, 메인 페이지에서 드래그 앤 드롭으로 순서를 변경할 수 있으며, 중첩된 앨범은 없고, 앨범당 타일 스타일의 미리보기를 제공하는 앱을 구축하세요.
...

4.2 선택적 명령어 — 품질 게이트 (quality gates)

명령어	에이전트 기술 (Agent skill)	역할 / 권장 타이밍
/speckit.clarify	speckit-clarify	질문을 통해 명시되지 않은 영역을 해결 — plan 단계 이전 (이전의 /quizme)
...

실제 환경에서 가장 권장되는 엔드 투 엔드 (end-to-end) 흐름은 constitution → specify → clarify → plan → tasks → analyze → implement입니다. 구현하기 전에 clarify를 통해 명세(spec)의 공백을 채우고, analyze를 통해 명세/계획(plan)/작업(tasks)이 서로 모순되지 않는지 확인하는 것이 재작업을 가장 많이 줄여주는 방법입니다.

flowchart TD
  A["/speckit.constitution\n프로젝트 헌법 (constitution) = 협상 불가 사항"] --> B["/speckit.specify\n무엇을 / 왜 (PRD)"]
  B --> C["/speckit.clarify\n모호성 해결"]
...

5. 확장 기능 및 프리셋 — 조직적 커스터마이징 (organizational customization)

Spec Kit은 두 가지 상호 보완적인 시스템인 확장 기능 (Extensions) 및 **프리셋 (Presets)**과 프로젝트 로컬 오버라이드 (project-local overrides)를 통해 맞춤 설정할 수 있습니다. 템플릿은 **런타임 (runtime)**에 결정됩니다. Spec Kit은 우선순위 스택을 상단에서 하단으로 탐색하며 첫 번째로 일치하는 항목을 사용합니다.

우선순위	구성 요소	위치
1 (가장 높음)	프로젝트 로컬 오버라이드	.specify/templates/overrides/
...

기술 (skills) 모드를 지원하는 통합 (integrations)의 경우, --integration <agent> --integration-options="--skills"를 사용하면 슬래시 명령어 프롬프트 파일 대신 에이전트 기술을 설치합니다. 따라서 동일한 SDD 워크플로우를 슬래시 명령어로든 기술 형태로든 배포할 수 있습니다.

6. 한계 및 운영상의 주의 사항 — "명세는 완벽하지만, 코드는 비어 있다"

SDD는 만능 해결책 (silver bullet)이 아닙니다. 공식 블로그 댓글에서 가장 많이 제기되는 문제들은 실제 운영상의 리스크와 직결됩니다.

• 거짓 완료 (False done): 명세(spec)/계획(plan)/작업(tasks) 문서가 매우 훌륭하게 작성되었고, 에이전트가 "구현 완료"라고 보고하지만, 실제로는 기능의 상당 부분이 누락되어 있고 테스트가 전혀 없는 상태입니다. → /speckit.implement를 신뢰할 수 있는 결승선으로 취급하지 마세요. "모든 기능은 테스트와 함께 배포된다"는 원칙을 헌법(constitution)에 고정하고, checklist와 실제 테스트 실행을 통해 구현 내용을 명세와 비교하세요.
• 명세에 무엇을 담을 것인가: 근본적인 질문입니다 — "사용자 스토리(user stories)를 넣을 것인가, 아니면 다른 형태를 넣을 것인가?" 더 상세한 첫 번째 프롬프트(first prompt)는 명세의 품질을 극적으로 향상시키므로, 성공에 결정적인 경험이 무엇인지, 그리고 명시적으로 원하지 않는 것이 무엇인지 구체적으로 작성하세요.
• 멀티 에이전트, 멀티 개발자 (Multi-agent, multi-developer): Cursor, Claude Code, Gemini CLI를 사용하는 개발자들이 모인 하나의 모노레포(monorepo)에서 어떻게 단일 명세를 유지할 수 있을까요? → 명세를 IDE 외부로 분리하여 레포지토리와 함께 버전 관리하세요. 그러면 도구를 교체하더라도 동일한 계약(contract)에 따라 구현할 수 있으며, 속도 향상은 정렬(alignment)에서 비롯됩니다.

요약하자면, SDD(Spec-Driven Development)의 속도는 "더 빠른 타이핑"이 아니라 **정렬 (alignment)**에서 나옵니다. 그리고 이 정렬은 인간이 헌법(constitution)과 명세(spec)를 끝까지 검토하고 승인할 때만 유지됩니다.

7. ManoIT 내부 배포 체크리스트 (internal rollout checklist)

#	작업 (Task)	담당자 (Owner)	완료 기준 (Done criteria)
1	필수 요구사항 준비 — uv, Python 3.11+, Git; 표준 에이전트 선정	Platform	specify integration list 작동 확인
...

8. 결론 — "코드 이전에 의도, 에이전트보다 상위에 있는 헌법"

한 줄로 요약하자면, GitHub Spec Kit은 AI 에이전트의 출력물을 제어하기 위해, 코드 작성 _전(before)_에 의도(intent), 계획(plan), 원칙(principles)을 실행 가능한 명세(spec)로 고정하는 툴킷입니다. Constitution(헌법)은 조직의 타협할 수 없는 원칙들을 모든 단계에 걸친 가드레일(guardrail)로 전환하며, 단계별 /speckit.specify → clarify → plan → tasks → analyze → implement 흐름은 "무엇을/왜(what/why)"와 "어떻게(how)"를 분리하여 각 결정이 검토 가능하도록 만듭니다. Specify CLI는 거의 제로에 가까운 설정으로 30개 이상의 에이전트에 걸쳐 이 모든 것을 부트스트랩(bootstrap)합니다. 하지만 도구 그 자체는 "마법이 아니라, 단지 템플릿과 스크립트의 조합"일 뿐이라는 점을 기억하세요.

마무리하며 세 가지 운영 권장 사항을 제안합니다: (1) 헌법(constitution)부터 시작하세요 — 테스트, 보안, 아키텍처 컨벤션(convention)을 constitution.md에 먼저 고정해두지 않으면, 잘 작성된 명세(spec) 뒤에 내용 없는 빈 구현체만 남게 될 것입니다. (2) 명확화(clarify)와 분석(analyze) 단계를 건너뛰지 마세요 — 모호함을 해결하고 산출물(artifact)의 일관성을 확인하는 것이 구현 재작업을 가장 많이 줄여줍니다. (3) 명세를 코드처럼 버전 관리하세요 — 도구가 바뀌더라도 동일한 계약(contract)을 바탕으로 협업할 수 있도록, 명세는 IDE 외부의 저장소(repo)에 존재해야 합니다. 가장 짧은 조언을 드리자면, 이번 스프린트 중에 하나의 PoC 저장소에서 specify init을 실행하고, 내부 헌법을 작성한 뒤, 대표적인 기능 하나에 대해 전체 프로세스를 한 번 완료해 보세요.

이 기사는 GitHub Spec Kit 공식 문서(github.github.com/spec-kit, 2026-05-27 업데이트), github/spec-kit 저장소 README(슬래시 명령어 및 CLI 참조), Microsoft 개발자 블로그(Den Delimarsky, 2025-09-15) 및 커뮤니티 토론, 그리고 SDD 도입 보고서를 주요 출처로 사용하여 ManoIT의 자동화된 블로깅 파이프라인(Claude Opus 4.6 + Cowork Agent)에 의해 조사 및 작성되었습니다. 명령어 이름, CLI 옵션, 디렉토리 구조 및 통계는 2026-05-31 기준 공식 문서를 반영합니다. Spec Kit은 명시적으로 실험적인 프로젝트이며 변경될 수 있습니다. 운영 환경에 도입하기 전에 github.com/github/spec-kit Releases에서 최신 명령어와 통합 상태를 확인하십시오.

원문은 ManoIT Tech Blog에 게시되었습니다.