Claude Code에 ‘75일 운동 챌린지 기록 앱을 만들어 줘’ 한 줄만 넣어도 몇 초 만에 돌아가는 앱이 나옵니다. 그사이 AI는 하루를 빠뜨리면 어떻게 할지, 데이터를 어디에 둘지 같은 수십 가지 결정을 묻지 않고 내렸고, 사람은 앱이 완성된 뒤에야 그 결정을 알게 됩니다. spec-driven development(SDD, 명세 주도 개발)는 이 순서를 뒤집어, 무엇을 왜 만들지 먼저 문서로 정해 사람이 승인하고 AI는 그 문서대로 코드를 씁니다. 코드를 쓰는 쪽은 여전히 AI이고, 달라지는 것은 누가 언제 결정하느냐입니다. 빈 폴더에서 기능을 하나씩 쌓는 예제로 Claude Code에서 쓰는 순서와 요령을 정리합니다.
한 줄 prompt가 남긴 숨은 결정
한 예제에서 Claude Desktop 앱의 Claude Code를 Auto mode(도구 실행을 하나하나 승인받지 않는 설정)로 두고 빈 폴더에 이 한 줄 prompt(AI에게 주는 지시문)를 넣었습니다. 원하는 것을 말로 던지고 AI가 짐작해 만든 결과를 대화로 고쳐 가는 vibe coding 방식입니다.
Claude는 묻지 않고 화면 설계용 skill(특정 작업 지침을 묶은 확장 기능)인 frontend-design부터 불러 화면이 필요하다고 스스로 정했고, index.html 파일 하나짜리 웹앱을 만들었습니다. 막연한 요청은 널리 알려진 운동 챌린지 75 Hard로 해석해 운동 두 번, 식단 지키기, 물 1갤런, 10쪽 읽기, 진행 사진을 매일 할 일로 넣었습니다. 시작일을 과거로 바꾸면 뜨는 ‘Restart today’ 버튼은 눌러도 반응하지 않았습니다.
엄격 모드가 켜져 있고 데이터는 브라우저에만 저장된다는 가정은 작업이 끝난 뒤 ‘Things to know’ 요약으로 알려 줬습니다. 이미 코드가 다 만들어진 뒤입니다. 실제로 쓰다 보면 이런 가정은 13일째에 연속 기록이 예고 없이 초기화되는 식으로 늦게 드러나기도 합니다.
vibe coding이 흔들리는 다섯 지점
AI가 먼저 정하고 사람이 뒤따라 반응하는 구조에서는 다섯 가지 문제가 생깁니다.
| 문제 | 결과 |
|---|---|
| 말하지 않은 가정 | ‘하루 빠지면 무조건 재시작’ 같은 규칙이 그대로 코드로 굳음 |
| 실행마다 다른 결과 | 같은 prompt가 다음 세션에서 전혀 다른 규칙을 만들 수 있음 |
| 사라지는 대화 수정 | 대화로 고친 내용이 새 세션에 남지 않아 옛 버그가 돌아옴 |
| context window 소진 | 긴 대화가 context window(모델이 한 번에 다루는 대화 분량)를 채워 hallucination(사실이 아닌 내용을 지어내는 현상)과 회귀가 생김 |
| 팀의 엇갈림 | 개발자 다섯 명이 각자 AI agent(스스로 판단해 작업하는 AI)를 쓰면 같은 기능이 서로 다르게 구현됨 |
뿌리는 하나, 중요한 요구 사항과 설계 결정이 어디에도 적혀 있지 않다는 점입니다. prompt를 길게 써도 빠뜨린 부분은 여전히 AI가 채웁니다. 다만 빠른 개념 검증, boilerplate(프로젝트마다 들어가는 기본 뼈대 코드) 준비, 혼자 쓰는 간단한 사이트처럼 버려도 되는 작업에는 vibe coding이 여전히 알맞습니다.
spec은 AI에게 건네는 작업 지시서
spec은 specification(명세)의 줄임말로, 사람과 AI가 무엇을, 왜 만드는지 글로 맺는 약속입니다. 시공업자에게 건네는 서명된 작업 지시서처럼, 적지 않은 것은 작업자인 AI가 알아서 정합니다. spec에는 사용자, 핵심 목표, 앱의 한계, 만들지 않을 것을 적고, 파일 이름이나 데이터 구조 같은 ’어떻게’는 AI에 맡깁니다. AI가 spec으로 번호 붙은 실행 계획을 내면 사람이 코드 전에 검토합니다. 이 단계의 잘못은 답장 한 번으로 바로잡지만, 코드가 나온 뒤에는 코드를 크게 뜯어고쳐야 합니다.
흔히 나오는 의문 두 가지에는 이렇게 답할 수 있습니다.
- waterfall 아닌가: waterfall(전체를 미리 설계하고 차례로 진행하는 개발 방식)처럼 몇 달씩 계획하지 않고 기능 하나 크기의 짧은 루프를 돕니다.
- AI는 어차피 매번 다르지 않나: 차이를 없앨 수는 없지만 spec이 선택의 폭을 좁혀 짐작을 크게 줄입니다.
specs 폴더 하나로 묶는 문서 구조
문서는 최상위 specs 폴더에 모읍니다. 기초 문서 세 개는 처음에 한 번 쓰고, 기능마다 features 폴더 아래 번호 붙은 폴더에 세 파일이 생깁니다.
| 파일 | 내용 |
|---|---|
| vision.md | 무엇을, 왜, 누구를 위해 만드는지, 하지 않을 일 |
| tech-stack.md | 언어와 도구, 데이터 저장, 테스트 방법 |
| roadmap.md | 만들 기능의 순서와 완료 여부, 범위 밖의 일 |
| requirements.md | 기능이 해야 할 일, 성공 기준, 범위 밖의 일 |
| plan.md | AI의 구현 단계 |
| validation.md | 통과를 확인할 테스트 |
validation.md의 조건은 ’입력란을 비운 채 시작을 누르면 아무것도 저장되지 않는다’처럼 관찰해 확인할 수 있어야 합니다. 이후로는 다음 기능 고르기, spec 쓰기, 승인, AI 구현, 검증, 로드맵에 완료 표시를 되풀이합니다. 이 루프는 Cursor나 Codex에서도 통합니다.
▲ 기초 문서와 기능별 spec 폴더
빈 폴더에서 인터뷰로 기초 문서 만들기
코드도 commit(변경 내용을 저장소 이력에 기록하는 일) 기록도 없는 빈 폴더에서 시작하는 프로젝트를 greenfield라고 합니다. 예제에서는 빈 폴더에 git init으로 Git(코드 변경 이력을 관리하는 도구) 저장소를 만든 뒤, 아직 코드를 쓰지 말고 비전, 기술 스택, 로드맵을 한 번에 한 질문씩 물어 인터뷰하라고 지시했습니다. 로드맵은 기능 6개까지, 기능마다 한자리에서 브라우저로 시험할 수 있게 하라는 조건도 붙였습니다. 질문은 AskUserQuestion 도구를 써서 추천 답이 붙은 객관식으로 받았습니다.
| 질문 | 고른 답 |
|---|---|
| 챌린지 종류 | 규칙이 고정된 75 Hard |
| 사용자와 목적 | 나 혼자, 빠른 하루 체크인 |
| 할 일이 남은 채 하루가 끝나면 | 재시작을 제안하고 사용자가 확인 |
| 데이터 저장 | 외부 데이터베이스 없이 브라우저의 localStorage(웹 페이지가 브라우저에 데이터를 저장하는 공간) |
| 테스트 | Playwright(브라우저 동작을 자동으로 시험하는 도구)와 로직 단위 테스트 |
로드맵 여섯 자리 가운데 세 자리는 Claude가 필수 기능으로 정했습니다. 오늘의 할 일 체크인, ‘75일 중 N일째’ 카운터, 빠뜨린 날의 재시작 처리입니다. 나머지는 75일 진행 격자, 완료 화면과 지난 기록, 백업 내보내기·가져오기로 채웠는데, 데이터가 브라우저에만 남으니 백업은 빼놓을 수 없었습니다. vibe coding으로 만든 앱은 지난 날을 아무 때나 체크할 수 있었지만, 이번에는 챌린지 규칙을 지키려고 어제만 고칠 수 있게 했습니다. 코드 한 줄 없이 이런 선택을 검토하고 바꿀 수 있다는 것이 핵심입니다. 예제에서는 시간을 아끼려고 추천 답을 그대로 골랐지만, 실제 프로젝트라면 질문 하나하나를 따져 봐야 합니다.
기능 하나를 끝내는 두 prompt
기초 문서를 commit하면 기능마다 계획 prompt와 구현 prompt를 되풀이합니다. 계획 prompt로 spec 파일 세 개를 만들어 검토하고 commit합니다. 이어 대화를 비우고 구현 prompt로 기능을 만들게 한 뒤, 자동 테스트와 직접 확인을 모두 통과하면 병합합니다.
계획: 인터뷰하고 세 파일 쓰기
계획 prompt는 roadmap.md에서 다음 기능을 골라 feature/1-todays-check-in 같은 이름의 Git branch(본 코드와 나눠 작업하는 갈래)를 만들고, 인터뷰한 뒤 코드 없이 세 파일만 쓰라고 지시합니다. 첫 기능 ’오늘의 체크인’에서는 체크한 항목을 제자리에서 흐리게, 자정이 지나면 새 날로, 테스트는 Chromium과 WebKit의 모바일 프로필(Pixel 7, iPhone 15)로 돌리게 정했습니다.
requirements.md에는 R1부터 R12까지의 요구 사항과 제외 목록이, validation.md에는 자동 테스트 시나리오 16개와 8단계 수동 확인 목록이 담겼습니다. plan.md는 첫 기능이 프로젝트 설정까지 떠안아 가장 크다며, 길어지면 4단계에서 멈추고 나머지는 다음에 이어 가라고 권했습니다. 기초 문서의 빈틈은 기능 spec까지 번지니 기초 문서부터 확정해야 합니다.
구현: 대화를 비우고 spec만 보고 만들기
spec을 commit한 뒤 /clear 명령으로 대화 기록을 비웁니다. 프로젝트 상태가 대화가 아니라 문서에 남아 있으니 새 세션이나 다른 팀원도 이어받을 수 있습니다. 구현 prompt는 plan.md를 단계별로 따르고, requirements.md에 적힌 것만 만들고, validation.md의 테스트를 모두 돌린 뒤 사람이 확인할 항목을 알리라고 요청합니다.
Claude Code는 Playwright 테스트 38개를 모두 통과시키고도 로드맵의 완료 표시는 사람의 확인을 위해 남겨 두었습니다. 로컬 서버에서 할 일 여섯 개를 차례로 체크해 ’Day complete’가 뜨는 것을 확인한 뒤에야 commit, main branch 병합, 로드맵 갱신을 맡겼습니다. 두 번째 기능도 같은 두 prompt로 진행해 테스트 118개가 통과했습니다. 자동 테스트만 믿지 말고 화면을 직접 확인한 뒤 완료 처리해야 합니다.
▲ 자동 테스트 뒤 사람의 확인
되풀이하는 prompt는 skill로 묶기
기능마다 같은 prompt를 붙여 넣는 수고는 skill로 없앱니다. 계획 prompt를 feature-spec이라는 프로젝트 skill로 만들게 하자 Claude가 .claude/skills/feature-spec 폴더에 SKILL.md를 썼고, Claude Desktop 앱을 다시 시작한 뒤에는 /feature-spec 명령 하나로 다음 기능의 spec 작업이 시작됐습니다. skill은 CLAUDE.md·AGENTS.md 같은 상시 규칙, 별도 context window에서 일하는 전용 agent, 외부 맥락을 잇는 MCP(AI를 외부 도구·데이터와 연결하는 표준 규격) 서버와 함께 프로젝트를 AI agent에게 가르치는 네 가지 방법 중 하나입니다.
이미 있는 코드에 spec 입히기
실제 개발은 대부분 spec 없이 코드가 이미 있는 brownfield 프로젝트에서 이뤄집니다. FastAPI 백엔드와 자동 테스트를 갖춘 75일 운동 기록 PWA(설치형 앱처럼 쓰는 웹앱)에 적용한 순서는 이렇습니다.
- 코드는 고치지 말고 저장소 전체와 테스트를 분석해 거꾸로 기초 문서 세 개를 만들라고 지시합니다.
- 문서와 코드가 어긋난 곳을 확인합니다. README는 연속 기록 지표 4개를 설명했지만 실제 백엔드는 지표 하나로 합쳐져 있었고, README에 적힌 배포 스크립트, 서버 설정 파일, MCP 관련 파일도 실제 저장소에는 없었습니다. spec의 근거는 문서가 아니라 동작하는 코드여야 합니다.
- 기초 문서와 skill을 commit하고
/feature-spec으로 ‘쉬는 날’ 기능을 시작합니다. Claude는 쉬는 날을 며칠로 할지 물으며 5일을 추천했습니다. - 연속 기록을 끊지 않고 쉬는 날을 5일까지 미리 잡는 기능을 구현합니다. 테스트가 통과한 뒤 휴대폰 화면에서 직접 확인합니다.
Plan Mode부터 BMAD까지, 도구 고르기
spec 프레임워크들은 같은 루프를 명령, 규칙, agent 역할로 포장한 것입니다. 2026년 10월 13일 기준으로 가벼운 것부터 정리하면 다음과 같습니다.
| 도구 | 특징 | 어울리는 곳 |
|---|---|---|
| Claude Code Plan Mode | 계획만 세우고 승인 전에는 파일을 고치지 않음 | 작은 작업 |
| OpenSpec | 변경마다 spec 파일을 두는 명령줄 도구 | 기존 코드 |
| GitHub Spec Kit | 원칙에서 코드까지 정해진 경로를 따름 | 여러 코딩 agent를 쓰는 팀 |
| Superpowers | 구상, 계획, 테스트, 코드 검토 순서를 강제하는 plugin skill 묶음 | 혼자 개발하는 사람 |
| BMAD | 전문 agent 역할 5개가 협업하는 가장 무거운 방식 | 기업 규모의 spec |
같은 조건에서 비교한 결과는 아니니 우열보다 무게의 차이로 보면 됩니다. 큰 기능에는 BMAD 같은 무거운 프레임워크를, 작은 작업에는 Plan Mode를 쓰는 두 단계 운영을 권할 만합니다. 한 저장소에 프레임워크 두 개를 두면 spec 파일이 엇갈려 기준이 무너지지만, 파일을 남기지 않는 Plan Mode는 프레임워크 하나와 함께 써도 괜찮습니다.
정리: 다음 기능 하나부터 spec으로
사람이 결정을 적어 두지 않으면 AI가 기술 스택과 디자인까지 정합니다. 결정은 사람이 먼저 내리고, 큰 기능은 계획과 spec을 거쳐 구현합니다. 바로 해 볼 일은 다음과 같습니다.
- 프로젝트에 specs 폴더를 만들고 AI 인터뷰로 기초 문서 세 개를 씁니다. 기존 코드라면 코드에서 뽑게 합니다.
- 다음 기능 하나를 ’아직 코드를 쓰지 말라’는 계획 prompt로 시작해, 나온 세 파일을 검토하고 commit합니다.
- 대화를 비우고 구현을 맡긴 뒤 자동 테스트와 직접 확인을 모두 통과하면 병합합니다.
- 두 번 이상 쓴 prompt는 skill로 묶습니다.
- 파일 3개 미만을 고치거나 설계 결정이 없는 일, 버튼 여백이나 색을 눈으로 다듬는 일은 spec 없이 vibe coding으로 처리합니다.