구현 전에 스펙을 세웠다: spec-kit으로 SDD 시작하기

AI Workflow

2026.02.23

요약

이번에는 "화면부터"가 아니라, 초기세팅 -> 테스트 게이트 -> 스펙 기반 개발 순서로 진행했다.
출발점은 vibe coding을 더 효율적으로 만들려는 고민이었다.
핵심은 spec-kit을 도입해 constitution -> spec -> plan -> tasks -> implement 흐름을 실제 산출물로 고정한 것.

이번 글은 spec-kit 자체를 완전히 해설하는 글이라기보다, 새 프로젝트를 시작하면서 SDD를 어떤 기준선으로 붙였는지를 정리한 기록에 가깝다. 특히 에이전트와 함께 구현할 때 내가 중간중간 맥락을 다시 설명하거나 코드를 손으로 덧대기보다, 한 번 잡은 흐름을 계속 이어가게 만드는 방식이 더 효율적이라고 느꼈다. 그래서 개념 소개보다는 "왜 이 순서로 시작했는지"와 "무엇을 먼저 고정했는지"에 초점을 맞췄다.

SDD란 무엇인가

공식 문서에서는 Spec-Driven Development라는 용어를 사용하고, 맥락에 따라 Specification-Driven Development라고도 부른다.

내가 이해한 SDD는 아래와 같다.

코드보다 먼저 스펙을 정한다.
구현은 스펙을 입력값으로 진행한다.
완료 판단은 "스펙 충족 여부"로 한다.
변경은 코드만이 아니라 스펙/계획/태스크를 함께 갱신한다.

즉, 문서를 많이 쓰는 방식이 아니라 스펙을 실행 가능한 기준선으로 쓰는 방식이다.

왜 구현 전에 초기세팅부터 했는가

기능부터 붙이면 초반에는 빠르게 전진하는 느낌이 든다. 하지만 에이전트와 함께 빠르게 구현을 밀어붙이다 보면, 초반 속도와 별개로 아래 문제가 금방 드러난다.

작업 맥락이 문서보다 채팅 기록에만 남아 휘발됨
중간 수정이 많아질수록 에이전트의 구현 흐름이 자주 끊김
로컬/운영 환경 차이 때문에 같은 지시가 다르게 동작함
회귀를 잡아줄 테스트가 없어 "지금 맞는지"를 계속 사람 손으로 확인하게 됨

그래서 이번에는 화면보다 먼저 아래 기준선을 고정했다.

모노레포 구조
Supabase 로컬 루프
최소 테스트 게이트
기획/정책/스코어링 문서

이번에 고정한 개발 기준선

1) 모노레포 구조

apps/
  web/      # Next.js
  mobile/   # Expo React Native
  worker/   # Node 수집 배치
packages/
  shared-types/
supabase/

핵심은 shared-types를 두고 웹/모바일/워커가 같은 도메인 타입을 바라보게 만드는 것이었다.

2) 로컬 데이터 스택

Supabase local(Docker)를 기준으로 로컬 데이터 루프를 맞췄다. 우선은 아래 네 개 스크립트만 팀의 기본 동작처럼 고정했다.

pnpm supabase:up
pnpm supabase:status
pnpm supabase:down
pnpm supabase:clean

3) 최소 테스트 게이트

Web unit: Vitest
Web e2e: Playwright
Mobile unit: Jest
Mobile e2e: Maestro
Worker unit: Vitest
DB test: pgTAP
pre-commit/pre-push: lefthook

검증 포인트를 화려하게 늘리기보다, 로컬에서 반복 가능한 최소 게이트를 먼저 세우는 것에 집중했다.

spec-kit으로 실제로 만든 SDD 산출물

Constitution

프로젝트 원칙은 아래 다섯 줄로 정리했다. 표현은 영어로 적었지만, 실제로는 "어떤 판단을 우선할 것인가"를 못 박아두는 용도였다.

evidence-first transparency: 근거를 먼저 보여주는 투명성
policy-safe ingestion: 정책 위반을 피하는 수집 설계
mobile-first consistency: 모바일을 기준으로 한 일관성
deterministic scoring & versioned rules: 재현 가능한 스코어링과 버전 관리되는 규칙
test-gated incremental delivery: 테스트 게이트를 통과하며 점진적으로 전달

Baseline Feature (specs/001-ac-mvp-gates)

좋았던 점은 산출물이 각각 따로 노는 문서가 아니라, 에이전트가 다음 구현 단계로 자연스럽게 이어받을 수 있는 입력값이 된다는 점이었다.

spec.md: 사용자 스토리, 요구사항, 성공 기준
plan.md: 기술 맥락, constitution gate
research.md: 의사결정 근거
data-model.md: 엔티티/관계
contracts/public-api.yaml: API 계약
quickstart.md: 검증 시나리오
tasks.md: 구현 순서(P1 -> P2)

이 단계까지 정리하고 나면 구현은 "무엇을 만들지 고민하는 일"보다 "어떤 순서로 검증하며 만들지 결정하는 일"에 가까워진다.

도입하면서 헷갈렸던 점

specify CLI와 슬래시 명령은 같은 것이 아니다. specify init, specify check는 터미널 명령이고, /speckit.* 또는 /specify 계열은 에이전트 워크플로에 가깝다.
슬래시 명령 이름은 에이전트 템플릿에 따라 다를 수 있다. 어떤 문서는 /speckit.constitution, 어떤 문서는 /constitution처럼 더 짧은 형태를 쓴다.
내가 이해한 핵심 흐름은 constitution -> specify -> plan -> tasks -> implement였고, clarify, analyze, checklist는 선택 단계로 보는 편이 이해하기 쉬웠다.
Git 없는 환경에서는 SPECIFY_FEATURE를 명시해야 후속 스크립트가 기대한 경로를 정확히 잡는다.

내가 얻은 결론

초기세팅은 개발을 늦추는 게 아니라 중반 재작업 비용을 줄인다.
SDD는 특히 에이전트와 함께 작업할 때 맥락을 덜 잃고 일관성을 유지하는 데 유리했다.
중요한 건 도구 이름보다 원칙 -> 스펙 -> 태스크 -> 검증 루프를 끊지 않는 것.
반대로 하루짜리 스파이크나 방향 탐색 단계에서는 다소 무겁게 느껴질 수 있다. 그래서 모든 작업에 동일한 강도로 적용하기보다, 기준선이 필요한 기능부터 붙이는 편이 현실적이었다.

참고 자료

Ranohub