본문으로 건너뛰기
중급

Spec Kit을 활용한 명세 주도 개발

바이브 코딩 — "대시보드 만들어줘"라고 하고 돌아오는 결과를 그냥 받아들이는 방식 — 은 기능이 작을 때는 아주 잘 작동합니다. 그러나 기능이 커지면 에이전트가 표류하기 시작합니다. 이전 결정을 잊거나, 함수를 다시 발명하거나, 기술적으로는 실행되지만 의도한 것이 아닌 결과를 내놓습니다. 명세 주도 개발(SDD, Spec-Driven Development) 은 2026년 에이전트 코딩 커뮤니티 전반에서 자리 잡은 해결책입니다. 프롬프트를 일회용으로 취급하는 대신, 글로 작성되고 검토 가능한 명세를 단일 진실 공급원으로 삼고 에이전트가 그것을 바탕으로 코드를 생성하게 합니다.

GitHub의 오픈소스 Spec Kit 은 그 아이디어를 오늘 바로 Claude Code 안에서 실행할 수 있는 구체적인 워크플로로 바꿔줍니다.

What you'll learn
  • 명세 주도 개발이 무엇인지, 그리고 어떤 문제를 해결하는지 이해하기
  • Spec Kit의 단계들 살펴보기: constitution → specify → plan → tasks → implement
  • Specify CLI 설치하고 Claude Code와 연결하기
  • 선택적 품질 게이트(clarify, analyze, checklist) 알아두기
  • SDD가 그 오버헤드를 감수할 가치가 있을 때와 건너뛰어야 할 때 판단하기

왜 프롬프트만이 아니라 명세인가​

프롬프트는 턴이 끝나는 순간 사라집니다. 반면 명세는 산출물(artifact) 입니다. 읽을 수 있고, PR에서 검토할 수 있으며, 수정하고 다시 실행할 수 있습니다. 이 단 하나의 전환이 큰 에이전트 빌드가 잘못되는 세 가지 방식을 모두 바로잡습니다.

  • 표류(Drift) — 아무것도 기록되지 않았기 때문에 에이전트가 이전 결정과 모순됩니다. 명세가 곧 기억입니다.
  • 모호성(Ambiguity) — "멋지게 만들어줘"는 열 가지 다른 의미가 될 수 있습니다. 요구사항을 산문으로 강제로 풀어내면 코드가 존재하기 전에 빈틈이 드러나고, 그때가 수정 비용이 가장 쌉니다.
  • 검토 불가능한 디프(Unreviewable diffs) — 2,000줄짜리 생성된 PR은 판단하기 어렵습니다. 검토된 명세 + 계획이 있으면 디프가 놀라움이 아니라 예상된 것이 됩니다.

핵심 사고 모델은 이렇습니다. 의도(intent)는 가치가 높고 지속되는 것이며, 코드는 그 하류에 있는 재생성 가능한 산출물이다. SDD는 Claude Code 자체의 Plan Mode의 규율 잡힌 사촌입니다 — 먼저 계획하고 그다음에 빌드한다 — 이를 기능 전체 규모로 확장하고 저장소의 파일로 영속화한 것입니다.

Spec Kit 워크플로​

Spec Kit은 하나의 기능을 슬래시 명령어로 이루어진 짧은 파이프라인으로 구조화합니다. 각 명령어는 Markdown 산출물을 저장소(.specify/ 아래)에 기록하므로, 모든 단계가 검사 가능하고 버전 관리됩니다.

Guided walkthrough1 of 5
  1. 프로젝트당 한 번 /speckit.constitution을 실행합니다. 이 명령어는 지배 원칙 — 코드 스타일, 테스트 기준, 협상 불가능한 아키텍처 원칙 — 을 .specify/memory/constitution.md에 기록합니다. 이후의 모든 단계가 이를 기준으로 검증되므로, 이것이 지속되는 가드레일입니다(원칙에 집중한 CLAUDE.md라고 생각하세요).

선택적 품질 게이트​

기능이 중요도가 높을 때 루프를 더 조여주는 세 가지 명령어가 더 있습니다.

  • /speckit.clarify — 명세에서 충분히 명시되지 않은 영역을 캐묻고, 계획을 세우기 전에 타깃 질문을 합니다. specify 직후에 실행하는 것이 가장 좋습니다.
  • /speckit.analyze — 명세, 계획, 작업을 일관성과 누락된 범위에 대해 교차 점검합니다.
  • /speckit.checklist — 검증 체크리스트를 생성하여 "완료"가 정의되고 테스트 가능하도록 만듭니다.
Pro tip
  • /speckit.plan 전에 /speckit.clarify를 실행하세요 — 모호성을 고치는 비용은 아키텍처가 확정되기 전이 가장 쌉니다.
  • 생성된 각 산출물을 PR처럼 다루세요: 읽고, 수정하고, 그런 다음에야 다음 단계로 넘어가세요.
  • .specify/ 산출물을 커밋하세요 — 그것들이 코드 뒤에 있는 의도의 검토 가능한 기록입니다.

Claude Code로 실행하기​

Spec Kit은 슬래시 명령어를 프로젝트에 스캐폴딩해주는 CLI인 Specify를 제공합니다. Claude Code를 포함해 30개가 넘는 코딩 에이전트를 지원합니다.

Guided walkthrough1 of 3
  1. uv를 사용해 저장소에서 설치합니다. (Python + uv 필요.)

Install the Specify CLI (uv)

uv tool install specify-cli --from git+https://github.com/github/spec-kit.git

Scaffold spec-driven workflow into a project

# new project
specify init my-feature

# or in the current repo
specify init --here

Then, inside Claude Code, run the pipeline

/speckit.constitution Establish principles: TypeScript strict, tests for every public function, no secrets in code.
/speckit.specify Build a CSV export for the reports page: users pick a date range and download a CSV of matching rows.
/speckit.clarify
/speckit.plan Next.js App Router, server action for the query, stream the CSV; no new dependencies.
/speckit.tasks
/speckit.implement
Watch out
  • specify init의 정확한 에이전트 선택 플래그는 릴리스마다 바뀝니다 — 플래그를 무작정 복사하지 말고 README의 빠른 시작 가이드를 확인하세요.
  • SDD는 검증의 필요성을 없애주지 않습니다: 생성된 코드를 읽고 실행해보세요. 명세는 디프를 검토 가능하게 만들 뿐, 자동으로 올바르게 만들어주지는 않습니다.
  • 명세, 계획, 헌법에 절대 비밀이나 자격 증명을 넣지 마세요 — 다른 파일처럼 커밋됩니다.

언제 사용할 것인가(그리고 언제 하지 말 것인가)​

SDD는 선행 의식을 치르는 대가로 통제력을 얻습니다. 이 거래는 작업이 크거나, 모호하거나, 다른 사람의 검토를 받아야 할 때 가치가 있고 — 그렇지 않을 때는 순전한 오버헤드입니다.

What you'll learn
  • SDD를 선택하세요: 그린필드 기능, 여러 파일에 걸친 빌드, 동료가 검토해야 하는 모든 것, 또는 서브에이전트 군단에 넘길 작업.
  • SDD를 건너뛰세요: 일회성 스크립트, 사소한 수정, 탐색용 일회용 코드 — 평범한 프롬프트나 Plan Mode가 더 빠릅니다.
  • 브라운필드에서도 작동합니다: /speckit.specify를 새 프로젝트뿐 아니라 기존 코드베이스의 개선 작업에도 겨누세요.
SDD at a glance
Enter 또는 스페이스 키를 눌러 카드를 뒤집습니다. 좌우 화살표 키로 카드를 이동할 수 있습니다.용어가 표시되었습니다.
1 / 5

스스로 점검하기​

Check yourself

0/3
  1. 명세 주도 개발의 핵심 아이디어는 무엇인가?
  2. 기술 스택과 아키텍처를 담아야 하는 Spec Kit 단계는 어느 것인가?
  3. 언제 명세 주도 개발이 그 오버헤드를 감수할 가치가 없는가?
Key takeaways
  • 명세 주도 개발은 프롬프트가 아니라 검토 가능한 명세를 단일 진실 공급원으로 삼아, 표류와 모호성, 검토 불가능한 디프를 없앱니다.
  • GitHub의 Spec Kit(Specify CLI)은 SDD를 /speckit.* 슬래시 명령어로서 Claude Code에 들여옵니다.
  • 파이프라인은 constitution → specify → (clarify) → plan → (analyze) → tasks → (checklist) → implement이며, 각 단계가 검사 가능한 산출물을 기록합니다.
  • 무엇을/왜는 명세에, 어떻게는 계획에 두세요; 다음으로 넘어가기 전에 모든 산출물을 PR처럼 검토하세요.
  • 크거나, 모호하거나, 검토받는 기능에는 사용하고; 일회용 작업에는 건너뛰세요 — 그리고 언제나 생성된 코드를 검증하세요.

다음​

  • Plan Mode — 내장된, 더 가벼운 "빌드 전에 계획하기" 루프
  • Slash Commands — /speckit.* 명령어가 Claude Code의 명령어 시스템에 어떻게 들어맞는지
  • CLAUDE.md & Memory Files — 헌법(constitution) 뒤에 있는 원칙-을-기억으로 삼는 아이디어
  • Subagents — 검토된 작업 목록을 에이전트 군단에 넘기기
  • Coding & Software Development — SDD가 의존하는 모든 것을 검증하는 사고방식

출처 및 더 읽을거리​