SDD 경험 끄적끄적고
GitHub Copilot, Cursor, Claude 같은 AI 도구들이 일상적인 개발 도구로 자리잡으면서, 코딩의 주체가 서서히 달라지고 있습니다. 예전에는 개발자가 한 줄 한 줄 직접 작성했다면, 이제는 구현하고 싶은 내용을 설명하면 AI가 코드를 만들어줍니다. 이런 방식을 요즘 바이브 코딩(Vibe Coding) 이라고 부릅니다.
바이브 코딩의 가장 큰 변화는 속도와 범위입니다. 반복적으로 작성하던 코드들을 AI가 대신 처리해주면서, 아이디어가 실제로 동작하는 코드가 되기까지의 시간이 훨씬 짧아졌습니다. 혼자서도 더 넓은 범위를 다룰 수 있게 됐고, 개발자는 세세한 구현보다 전체적인 방향과 구조를 잡는 역할에 더 집중할 수 있게 됐습니다.
그렇다고 바이브 코딩이 모든 걸 해결해주는 건 아닙니다. 현재 LLM 기반 도구에는 몇 가지 구조적인 한계가 있고, 이 부분을 이해하지 못하면 AI를 잘 활용하기가 어렵습니다.
AI 도구의 세 가지 구조적 한계
첫 번째는 할루시네이션(Hallucination)입니다.
AI가 존재하지 않는 함수나 라이브러리를 마치 있는 것처럼 코드를 작성하는 현상입니다. 결과물이 그럴듯하게 보여서 그냥 넘어가기 쉬운데, 실제로 실행해보면 에러가 나거나 아예 동작하지 않는 경우가 생깁니다. AI가 자신 있게 틀린다는 게 이 문제의 가장 까다로운 점입니다.
두 번째는 Lost in the Middle 현상입니다.
대화나 컨텍스트가 길어질수록 AI가 중간에 있는 내용을 사실상 무시하는 경향이 생깁니다. 앞부분과 뒷부분은 잘 참고하지만, 중간에 넣어둔 중요한 조건이나 요구사항이 슬그머니 빠지는 것입니다. 프로젝트가 복잡해질수록 이 문제가 더 두드러집니다.
세 번째는 컨텍스트 한계입니다.
AI는 대화가 누적될수록 앞선 내용을 잊거나 품질이 떨어지기 시작합니다. 새 채팅을 열면 이전 맥락이 모두 사라지고, 그렇다고 한 채팅을 계속 이어가면 응답 품질이 흔들립니다. 장기 프로젝트를 AI와 함께 진행할 때 가장 자주 부딪히는 문제이기도 합니다.
한계를 완화하는 방법: SDD
그렇다면 이 한계들을 어느 정도 완화할 수 있는 방법이 없을까요? 여기서 주목할 개념이 바로 SDD, Spec Driven Development(명세 기반 개발) 입니다.
SDD는 말 그대로 AI에게 코드를 맡기기 전에, 먼저 명세를 충분히 작성해두는 방식입니다. 어떤 기능을 만들 건지, 어떤 구조로 설계할 건지, 어떤 조건을 지켜야 하는지를 문서로 정리한 뒤 AI에게 그 명세를 기반으로 작업을 시키는 것입니다.
이게 앞서 말한 세 가지 문제와 어떻게 연결되냐면,
AI는 맥락이 명확할수록 할루시네이션이 줄어듭니다. 모호한 요청일수록 AI가 스스로 빈칸을 채우다가 없는 것을 만들어내는데, 명세가 구체적으로 잡혀 있으면 그 여지 자체가 줄어듭니다.
Lost in the Middle 문제도 마찬가지입니다. 중요한 조건들이 명세 문서에 정리되어 있으면, 대화가 길어져도 해당 문서를 다시 참조시키는 방식으로 컨텍스트를 보완할 수 있습니다.
결국 SDD는 AI를 더 잘 부리기 위한 설계도를 미리 그리는 작업입니다. AI가 코드를 짜는 시대일수록, 오히려 개발자가 명세를 잘 쓰는 능력이 더 중요해진다는 뜻이기도 합니다.
Spec Kit: 명세 작성을 도와주는 도구
그런데 이 명세 작성 자체도 막상 해보면 어디서부터 시작해야 할지 막막한 경우가 많습니다. 그래서 찾아보다가 발견한 게 바로 Spec Kit입니다. GitHub가 2025년 9월에 오픈소스로 공개한 SDD 지원 도구로, 명세 작성부터 구현까지의 전체 개발 흐름을 체계적으로 잡아주는 CLI 툴킷입니다.
Spec Kit의 개발 흐름은 총 8단계로 구성됩니다.
핵심은 각 단계마다 개발자가 직접 검토하고 승인한다는 점입니다. 수천 줄짜리 코드를 한꺼번에 받아보는 게 아니라, 작은 단위로 쪼개진 결과물을 그때그때 확인하면서 진행하기 때문에 문제를 조기에 발견하고 방향을 바로잡을 수 있습니다.
직접 해보고 깨지기
SDD를 학습해보기 위해 SDD 학습을 도와주는 Speckit을 적용해 프로그램을 만들어보며 느꼈던 점을 적어봤습니다.
/constitution — 프로젝트의 헌법 만들기
speckit을 처음 시작하면 가장 먼저 치는 명령어가 /constitution입니다. 이름 그대로 프로젝트의 헌법, 즉 모든 개발 결정의 기준이 되는 원칙 문서를 만드는 단계입니다.
결과물은 이렇게 생겼습니다.
# 은하계 게시판 Constitution
### I. 3D 성능 우선
- 30fps 이상 유지
- 페이지당 행성 50개, 행성당 별 100개 상한
### VI. 테스트 우선 (TDD) — NON-NEGOTIABLE
- 모든 기능 구현 전 테스트를 먼저 작성
- Red-Green-Refactor 사이클 엄격 준수
...프로젝트에서 지켜야 할 원칙들을 항목별로 정리한 문서입니다. 기술 제약(어떤 라이브러리를 써야 하는지), 개발 워크플로우(커밋 단위, 브랜치 규칙), 거버넌스(이 문서 자체를 어떻게 수정하는지)까지 담겨 있습니다. 이후 모든 단계에서 AI는 이 문서를 기준으로 판단합니다.
사용법은 간단합니다. 지켜야 할 규칙들을 AI한테 넘겨주면 됩니다. 저는 이렇게 요청했습니다.
"이 프로젝트에서 지켜야 할 규칙들이야. (규칙을 나열) 이걸 기반으로 constitution 만들어줘."
그랬더니 첫 결과물로 바로 저 문서가 나왔습니다.
흥미로운 건 이게 살아있는 문서라는 점입니다. 개발하다가 "Storybook 스토리는 무조건 써야겠다" 싶으면 /constitution 다시 호출해서 원칙을 추가합니다. 그러면 버전이 올라가고, 어떤 템플릿에 영향이 가는지까지 자동으로 정리해줍니다.
Version change: 1.1.0 → 1.2.0 (MINOR - 원칙 1개 추가)
Added principles:
- VIII. 컴포넌트 스토리 필수이를 바탕으로 개발 프로젝트의 헌법을 만들어 AI의 이상행동을 방지하는 점은 매우 흥미로웠습니다.
/specify — 뭘 만들 건지 정리하기
constitution이 "어떻게 만들 건지"의 원칙이라면, /specify는 "뭘 만들 건지"를 정리하는 단계입니다.
저는 한 번에 전체 프로젝트를 다 넣지 않고, 기능 단위로 쪼개서 진행했습니다. 프로젝트 세팅 명세를 먼저 만들고, 구현이 끝나면 다음 기능 명세를 만드는 식으로요.
사용법은 이렇습니다. /specify 명령어를 치고, 스프린트 티켓처럼 기능 목록을 넣어줍니다.
“은하계 행성 게시판을 만들거”
- 게시글은 은하고 좋아요는 별 댓글은 위성
여기서 한 가지 편한 점이 있었습니다. /specify를 치면 speckit이 자동으로 브랜치를 만들고, 해당 폴더 안에 spec.md를 저장해줍니다. 파일을 직접 만들거나 관리할 필요가 없습니다.
specs/001-galaxy-board/
└── spec.md ← 자동 생성중요한 건 이 단계에서 "어떻게 구현할지"는 적지 않는다는 점입니다. specify는 무엇(WHAT) 과 왜(WHY) 에만 집중합니다. 구현 방법은 다음 단계인 /plan에서 결정합니다.
/clarify — 내가 미처 생각 못한 걸 물어보다
spec.md가 나오면 바로 /plan으로 넘어가고 싶지만, 그 전에 /clarify를 거치는 게 좋습니다. spec을 읽고 애매모호한 부분을 AI가 스스로 찾아서 질문해주는 단계입니다.
저는 이 단계에서 내가 생각하지 못했던 부분들이 꽤 나왔습니다.
• 게시글(행성)은 한 화면에 몇 개까지 보여줄 건가요? • 행성 커스텀은 어디까지 가능한가요? 색상만인가요, 형태도 변경 가능한가요?
사실 당연한 것들인데, 명세를 쓸 때는 그냥 넘어가게 되는 부분들입니다. 이걸 /clarify가 짚어주니까 "아, 이거 결정하고 넘어가야 했구나" 하게 됩니다.
여기서 답을 해주면 spec.md에 반영되고, 그게 이후 단계의 기준이 됩니다. 이 단계를 건너뛰면 나중에 /plan이나 구현 단계에서 AI가 알아서 판단해버리는데, 그게 내 의도랑 다를 수 있습니다.
/plan — AI가 알아서 설계해오다
/plan은 specify와 clarify에서 정리한 내용을 바탕으로 실제 구현 방법을 설계하는 단계입니다.
따로 파일을 넘기거나 경로를 알려줄 필요가 없습니다. /plan을 치면 speckit이 알아서 해당 폴더의 spec.md를 읽고, 리서치를 한 뒤 plan.md를 만들어줍니다.
결과물은 이렇게 생겼습니다.
# Implementation Plan: 은하계 게시판
**Branch**: `001-galaxy-board` | **Date**: 2026-03-25 | **Spec**: [spec.md](./spec.md)
**Input**: Feature specification from `/specs/001-galaxy-board/spec.md`
## Summary
Three.js 기반 3D 우주 공간에서 은하계(주제), 행성(게시글), 별(좋아요) 시스템을 구현하는 인터랙티브 게시판. NestJS 백엔드(헥사고날 아키텍처)와 Next.js 프론트엔드(FSD 구조)로 구성된 모노레포 프로젝트.
## Technical Context
**Language/Version**: TypeScript 5.7+, Node.js 22 LTS
**Primary Dependencies**:
- **Frontend**: Next.js 15.x, React 19, Three.js 0.183.x, @react-three/fiber 9.x, @react-three/drei 10.x, Zustand 5.x, TanStack Query 5.x, react-hook-form 7.x, Zod 3.x, shadcn/ui, Tailwind CSS 4.x
- **Backend**: NestJS 11.x, Prisma 6.x, class-validator 0.15.x, class-transformer 0.5.x
**Storage**: PostgreSQL 16 (Docker), Prisma ORM
**Testing**: Jest 29 + @testing-library/react (프론트엔드), Jest 29 + Supertest (백엔드 E2E), SWC 기반 트랜스파일
**Target Platform**: WebGL 지원 모던 브라우저 (Chrome, Firefox, Safari, Edge 최신 2개 버전), 데스크톱 우선
**Project Type**: Web application (모노레포: apps/api + apps/web + packages/*)
**Performance Goals**: 30fps 이상 (행성 50개 + 별 500개 장면), 초기 로딩 3초 이내, 전환 1초 이내
**Constraints**: 게시글당 별 최대 100개, 페이지당 행성 50개, WebGL 미지원 시 폴백
**Scale/Scope**: 데스크톱 브라우저 사용자, 다수 은하계/게시글 지원
## Constitution Check
*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
| 원칙 | 상태 | 비고 |
|------|------|------|
| I. 3D 성능 우선 | ✅ PASS | 행성 50개/페이지, 별 100개/행성 상한 설정. 페이지네이션 적용 |
| II. 사용자 경험 중심 | ✅ PASS | 카메라 애니메이션 전환, 오버레이 패널 UI, 직관적 인터랙션 |
| III. 단순성 (YAGNI) | ✅ PASS | 현재 필요한 CRUD + 3D 시각화만 구현. 인증/수정/삭제 제외 |특히 흥미로웠던 건 AI가 자기만의 체크리스트를 만들어왔다는 점입니다. constitution에 선언한 원칙들을 하나씩 꺼내서 "이 설계가 원칙을 지키고 있는지" 스스로 검증하고, 통과 여부를 표로 정리해왔습니다.
저는 이 결과물을 보면서 수정이 필요한 부분을 대화로 조율했습니다. 처음부터 완벽하진 않았지만, 기준이 되는 문서(constitution, spec)가 있으니 엉뚱한 방향으로 튀는 일은 없었습니다.
/tasks — 할 일을 쪼개오다
/plan이 끝나면 /tasks를 칩니다. plan.md를 비롯한 모든 설계 문서를 읽고, 구현 가능한 최소 단위로 작업을 쪼개서 tasks.md를 만들어줍니다. 따로 넘겨줄 것 없이 명령어만 치면 됩니다.
결과물은 이렇게 생겼습니다.
## Phase 1: Setup (프로젝트 초기화)
- [ ] T001 Prisma 스키마에 Galaxy, Planet, Star 모델 정의
- [ ] T002 Prisma 마이그레이션 생성 및 적용
- [ ] T003 [P] 공유 타입 정의 (Galaxy, Planet, Star)
...
## Phase 3: User Story 1 — 은하계(주제) 탐색
- [ ] T026 [P] [US1] GalaxyService 단위 테스트 작성
- [ ] T027 [P] [US1] PlanetService.findByGalaxy 단위 테스트 작성
...Phase별로 나뉘고, 각 태스크마다 정확한 파일 경로까지 붙어 있습니다. [P] 표시가 붙은 태스크는 병렬로 처리 가능하다는 뜻이고, 어떤 태스크가 어떤 태스크를 기다려야 하는지 의존성도 정리되어 있습니다. constitution에서 TDD를 NON-NEGOTIABLE로 선언해뒀더니, 모든 구현 태스크 앞에 테스트 작성 태스크가 먼저 붙어서 나왔습니다.
/implement — AI가 테스트 체크해가며 개발하다
/implement를 치면 tasks.md를 보고 테스트를 먼저 작성하고, 통과시키면서 구현해나갑니다. Red-Green-Refactor 사이클을 직접 돌리면서요.
여기서 한 가지 한계를 몸으로 배웠습니다.
테스트 코드는 프로그램의 동작을 보장하지, 내 의도를 설명하지 않습니다.
아무리 명세를 꼼꼼하게 잡아도, 여러 기능이 붙다 보면 이전 기획이랑 상충되는 부분이 생깁니다. 그런데 AI는 그걸 모릅니다. 테스트만 통과하면 되니까요. 기능적으로는 동작하는데 기획 의도랑 다른 구현이 나오거나, 개발자가 미처 생각하지 못한 케이스가 슬쩍 빠지는 일이 생깁니다.
결국 /implement 단계에서도 개발자가 결과물을 직접 보고 판단해야 합니다. AI가 테스트를 통과시켰다고 해서 끝난 게 아니라, "이게 내가 원하던 거 맞나?"를 매번 확인해야 하는 것입니다.
회고
- 이전에도 GPT나 Cursor 같은 AI 도구를 써본 적이 있지만, Claude Code의 속도와 범용성은 확실히 달랐습니다. 손으로 코드를 치는 비중이 앞으로 계속 줄어들겠다는 걸 몸으로 느꼈습니다. 다만 AI가 만들어준 코드의 검토를 소홀히 하면 안 된다는 것도 분명히 느꼈습니다. AI가 테스트를 통과시켰다고 해서 끝이 아니라, "이게 내가 원하던 거 맞나?"를 매번 확인과 책임은 결국 개발자의 몫이었습니다.
- Spec Kit 자체는 훌륭한 도구입니다. 특히 SDD가 익숙하지 않은 사람에게 강제성을 부여해준다는 점이 좋았습니다. 마치 React처럼, 방법을 어느 정도 강제함으로써 일정 수준 이상의 결과물을 보장해주는 느낌이랄까요. 다만 모든 앱에 React가 필요하지 않듯, 프로젝트의 규모와 목적에 맞게 선택하면 될 것 같습니다. 간단한 계산기 앱에 React를 쓸 필요가 없는 것처럼요.
- 한 가지 실용적인 교훈도 있었는데, Spec Kit과 다른 플러그인이 충돌하면서 이상한 폴더가 생성되는 문제가 있었습니다. 팀에서 어떤 도구를 쓸지 미리 통일해두는 게 생각보다 중요하다는 걸 새삼 느꼈습니다.