사양이 원본이고 코드는 사양에서 나오는 결과물이라는 생각(SDD), 그리고 요구사항을 Given/When/Then 장면으로 적어 그대로 시험으로 옮기는 습관(BDD)을 짧게 정리합니다. 마지막에 Spec Kit과 AI-DLC가 같은 생각을 어느 수준까지 적용하는지 비교합니다.
사양이 원본이 된다#
AI에게 "주차장 예약 앱 만들어 줘"라고 하면 코드가 나옵니다. 문제는 그다음입니다. 무엇을 만들기로 했는지는 대화 속에만 남고, 코드를 고칠 때마다 그 약속이 조금씩 흐려집니다.
스펙 주도 개발(Spec-Driven Development, SDD)은 순서를 뒤집습니다. 무엇을 왜 만드는지를 먼저 사양 문서로 쓰고, 그 사양에서 계획과 작업, 코드를 차례로 도출합니다. 코드가 사양과 어긋나면 고칠 대상은 코드입니다. 요구가 바뀌면 사양을 먼저 고치고 다음 단계를 다시 진행합니다.
이 방식이 지금 주목받는 이유는 코드를 쓰는 비용이 크게 줄었기 때문입니다. 어셈블리에서 C로 넘어갈 때 사람의 일이 레지스터 관리에서 알고리즘 설계로 옮겨 갔듯이, 지금은 코드 작성에서 사양 정의와 검증 설계로 옮겨 가고 있습니다. 이 비유는 AI-DLC 핸즈온 2장에서 자세히 다룹니다.
| 바이브 코딩 | 스펙 주도 개발 |
|---|---|
| 대화가 곧 요구사항 | 요구사항은 spec.md에 남습니다 |
| 빠진 결정은 AI가 알아서 정합니다 | 빠진 결정은 표시하고 묻습니다([NEEDS CLARIFICATION], /speckit-clarify) |
| 다 만든 뒤에 확인합니다 | 인수 시나리오를 먼저 정하고, 그 시나리오가 곧 시험이 됩니다 |
| 다음 대화에서는 맥락이 사라집니다 | 사양·계획·작업 문서가 다음 작업의 입력이 됩니다 |
BDD: 요구사항을 장면으로 쓴다#
행동 주도 개발(Behavior-Driven Development, BDD)은 요구사항을 사용자가 겪는 장면으로 씁니다. 장면은 세 부분입니다.
| 부분 | 뜻 | 이 교재의 예 |
|---|---|---|
| Given (전제) | 어떤 상황에서 | 샘플 데이터에 강남역 인근 주차장이 3곳 이상 있다 |
| When (행동) | 누가 무엇을 하면 | 운전자가 "강남역 근처 2시간 주차"를 입력한다 |
| Then (결과) | 무엇이 보여야 하나 | 추천 1곳과 비교 후보 2곳이 가격·거리·요금·선정 이유와 함께 표시된다 |
이렇게 쓰면 기획자와 개발자, 시험 담당자가 같은 문장을 읽습니다. 그리고 문장이 그대로 자동 시험의 이름과 구조가 됩니다. 이 실습의 헌법은 "인수 시나리오마다 자동 시험을 먼저 쓰고 실패를 확인한 뒤 구현한다"를 첫 원칙으로 두었습니다. 그래서 tasks.md의 모든 사용자 이야기는 시험 작성 → 실패 확인 → 구현 → 통과 확인 순서로 짜였습니다.
Spec Kit의 사양 틀은 두 가지 방식으로 BDD를 반영합니다.
- 사용자 이야기에 우선순위(P1, P2, P3)를 붙이고, 이야기마다 독립 시험(Independent Test)을 적습니다. P1만 만들어도 쓸 만한 결과물(MVP)이 되도록 나눕니다.
- 이야기마다 Given/When/Then 인수 시나리오에 번호를 붙입니다. 나중에 작업과 시험이 이 번호(
US2-3등)를 가리킵니다.
성공 기준은 기술과 무관하게 잰다#
사양에는 기능 요구사항(FR-001…)과 별도로 성공 기준(SC-001…)이 있습니다. 성공 기준은 측정할 수 있어야 하고, 특정 기술을 명시하지 않아야 합니다. "API 응답 200ms 이내"가 아니라 "운전자는 문장 입력부터 추천 결과 확인까지 10초 안에 도달한다"처럼 씁니다. 기술은 계획 단계에서 정하기 때문입니다.
Spec Kit의 흐름#
| 단계 | 명령 | 남는 문서 | 한 번만 / 기능마다 |
|---|---|---|---|
| 헌법 | /speckit-constitution |
.specify/memory/constitution.md |
프로젝트에 한 번 |
| 명세 | /speckit-specify |
specs/<번호-이름>/spec.md, checklists/requirements.md |
기능마다 |
| 명확화 (선택) | /speckit-clarify |
spec.md의 ## Clarifications |
계획 전에 |
| 계획 | /speckit-plan |
plan.md, research.md, data-model.md, contracts/, quickstart.md |
기능마다 |
| 품질 점검 (선택) | /speckit-checklist |
checklists/<주제>.md |
계획 뒤에 |
| 작업 목록 | /speckit-tasks |
tasks.md |
기능마다 |
| 일관성 분석 (선택) | /speckit-analyze |
없음(보고만) | 구현 전에 |
| 구현 | /speckit-implement |
코드, tasks.md의 [X] |
기능마다 |
| 수렴 | /speckit-converge |
tasks.md 끝에 Phase N: Convergence |
구현 뒤에, 다 될 때까지 |
명령은 터미널이 아니라 에이전트(이 교재에서는 Claude Code)의 입력창에서 하나씩 실행하고, 결과를 읽은 뒤 다음으로 넘어갑니다.
Spec Kit과 AI-DLC#
두 도구는 같은 생각에서 출발하지만, 사람이 개입하는 지점과 문서의 양이 다릅니다.
| 항목 | Spec Kit 1.4 | AI-DLC 2.11 |
|---|---|---|
| 규칙 | 헌법 한 장 | 조직·팀·프로젝트·단계·스테이지 다섯 층의 조향 규칙 |
| 요구사항 묻기 | /speckit-clarify가 최대 5개를 하나씩 |
스테이지마다 질문지와 후속 질문 |
| 승인 | 구현 직전 체크리스트 관문 하나 | 스테이지마다 승인 게이트, 감사 기록 |
| 검토 | 사람이 체크리스트와 분석 보고서를 읽음 | 검토 에이전트가 판정(READY·NOT-READY) |
| 작업 나누기 | 사용자 이야기별 단계와 [P] 표시 |
유닛과 볼트, 의존 그래프 |
| 끝났는지 확인 | /speckit-converge가 남은 일을 작업으로 덧붙임 |
볼트 완료 기준과 빌드·테스트 판정표 |
Spec Kit으로 사양 → 계획 → 작업 → 구현의 뼈대를 익히고, 팀 규칙과 승인, 작업 단위 관리가 필요해지면 AI-DLC로 넘어가는 순서를 권합니다.
확인 문제#
스펙 주도 개발에서 구현 중에 사양에 없는 기능이 필요해지면 어떻게 하나요?
코드에 먼저 넣지 않고 사양을 먼저 고칩니다. 이 실습의 헌법 III 「사양이 기준」은 "spec.md 에 없는 기능은 만들지 않는다. 구현 중 필요한 기능이 발견되면 먼저 spec.md 를 갱신한다"고 정했습니다. 실제로 계획 단계에서 「결제 중 만차」 처리가 사양 없이 들어갔다가, 체크리스트가 이를 찾아내 사양에 FR-017로 추가했습니다(7장).
성공 기준에 "API 응답 200ms 이내"라고 쓰면 무엇이 문제인가요?
API라는 구현 방식을 미리 정해 버립니다. 성공 기준은 기술과 무관하게 사용자 관점에서 측정할 수 있어야 하므로 "문장 입력부터 추천 결과 확인까지 10초 안"처럼 씁니다. 어떤 기술로 목표를 달성할지는 계획(plan.md)에서 정합니다.
Given/When/Then으로 쓴 인수 시나리오는 나중에 어디에 쓰이나요?
자동 시험이 됩니다. 이 실습의 tasks.md는 이야기마다 시나리오별 시험 작업을 먼저 두고, 시험 이름도 시나리오 문장(한국어 @DisplayName)으로 붙이게 했습니다. /speckit-converge도 US1/AC2 같은 시나리오 번호를 기준으로 구현이 사양을 충족했는지 확인합니다.
참고 자료#
- GitHub Spec Kit — https://github.com/github/spec-kit
- Spec Kit 문서 — https://github.github.io/spec-kit/
- Dan North, "Introducing BDD" (2006) — https://dannorth.net/introducing-bdd/