Spec Kit 5단계로 프로젝트 설계하기
2026.08.12

📝 한줄 요약
GitHub의 Spec Kit을 처음 써봤습니다. “코드부터 짜지 말고 먼저 무엇을 만들지 정의하세요”는 원칙으로, 프로젝트를 Constitution → Specify → Plan → Tasks → Analyze 다섯 단계로 체계적으로 설계했습니다.
Before: 요구사항이 자꾸만 바뀌고, 기획 중간에 기술 문제가 발견돼서 다시 설계
After: 단계별로 검증하면서 진행해서, 이견 없는 완성도 높은 설계 완성
👥 이런 분께 추천
프로젝트를 시작하기 전에 체계적으로 기획하고 싶은 분
AI와 함께 개발할 때 명확한 방향 지침을 먼저 만들고 싶은 분
기획 중에 “이건 어떻게 할 거지?” 같은 질문이 자주 생기는 분
요구사항이 자꾸 바뀌어서 헷갈리는 상황을 줄이고 싶은 분
🙋 내 스펙 & 환경
항목 | 내용 |
|---|---|
직업 | 일정관리 사이트 개발 |
코딩 경험 | 비개발자. 이번 프로젝트가 첫 개발 경험 |
AI 도구 | Claude Code |
환경 | 윈도우 11 |
기존 자산 | 사이트 샘플 HTML (6월 데이터) |
진행 방법
1. 왜 처음부터 설계 문서가 필요했나
기존 샘플 HTML은 localStorage에 갇혀 있어서 폰에서 못 보고, 월마다 새로 파일을 만들어야 했습니다. 이번 프로젝트는 “한 사람을 여러 번 만날 때도 같은 카드에 기록이 쌓여야 한다”는 요구사항이 처음부터 구조를 크게 바꾸는 일이었거든요.
“코드부터 짜면 중간에 다시 설계해야 할 것 같으니, 먼저 명세를 완벽하게 정한 뒤 시작하자”고 생각했어요.
2. Spec Kit을 알게 된 계기
스터디장 아루나님이 추천해주셨어요. “GitHub에서 만든 오픈소스인데, AI와 함께 명세 기반 개발을 할 수 있다”고.
처음엔 “또 다른 프레임워크가 나왔나” 싶었는데, 설명을 읽어보니 달랐습니다. 단계별로 멈추고 검토하는 구조가 있어서, AI가 자꾸 방향을 잃는 문제를 방지할 수 있겠다는 생각이 들었어요.
3. Constitution — 프로젝트 원칙 정하기 (1단계)
가장 먼저 한 일은 “이 프로젝트의 헌법”을 정하는 것입니다. 무엇이 가장 중요한가.
저한테는 “데이터 유실이 최대 리스크” 였어요. 코드는 다시 짜면 되지만, 축적된 인물 기록과 대화 내용은 복구 불가능하니까요.
그래서 원칙에는 이런 것들을 넣었습니다:
모든 스키마 변경은 마이그레이션 파일로만
사용자가 입력한 원문은 요약본과 별개로 항상 보존
전체 데이터를 언제든 내보낼 수 있어야 함
자동 백업은 운영 DB와 다른 곳에 보관
백업은 실제로 한 번 복구해봐야 검증됨
이 원칙이 나중에 모든 기술 결정을 가이드했습니다.
4. Specify — 요구사항 정의하기 (2단계)
다음은 “무엇을 만드는가”를 명확히 하는 단계입니다. 기술은 아직 언급 금지.
처음에는 요구사항이 44개였어요. 그런데 기획하면서 “CEO 개인 비서 입장에서 필요한 게 뭔가”를 계속 물었고, 요구사항이 늘어났습니다.
최종적으로 98개 요구사항까지 늘어났어요. 중간에 “이건 너무 크다.
1차와 2차로 나누자”는 결정도 했고요.
5. Plan — 기술 결정하기 (3단계)
여기서 처음 기술 스택이 나옵니다. 요구사항을 어떤 기술로 구현할 건가.
처음 계획에서 놓친 부분이 있었어요. “리마인더를 Vercel의 크론 기능으로”라고 잡았는데, Vercel 무료 플랜은 하루에 1회 정도만 지원한다는 걸 발견했거든요.
그래서 다시 설계해서 Supabase의 pg_cron을 쓰기로 바꿨습니다. 비용도 안 늘어나고, 이미 쓸 기술이라 추가 학습도 없었어요.
6. Tasks — 작업 분해하기 (4단계)
이제 구현할 작업들을 분해합니다. 계획을 “누가” “뭘” 할지 구체적으로.
83개 작업이 13개 페이즈로 나뉘었어요. 각 페이즈는:
Setup (프로젝트 초기화)
Foundational (인증, DB 마이그레이션 같은 기초) 3-11. 사용자 스토리별 (인물 카드, 캘린더, 리마인더 등) 12-13. Polish (마무리, 배포)
작업마다 어느 파일을 수정하는지, 의존성이 뭔지까지 적었습니다.
7. Analyze — 일관성 검사하기 (5단계)
마지막 단계는 자동 검사예요. Spec에 쓴 요구사항이 정말 Plan과 Tasks에 전부 포함됐는지 확인합니다.
검사 결과:
98개 요구사항 중 심각한 누락: 0건
기술 결정과의 충돌: 0건
작업 분해의 누락: 0건
그 시점에서 “이제 구현해도 된다”는 확신이 생겼어요.
배운 점
💡 핵심 교훈
1. 원칙을 먼저 정하면 나머지는 흔들리지 않는다
중간에 “대표님도 이 사이트를 봐야 하지 않을까?”라는 요구사항이 생겼어요. 그럼 인증 구조가 완전히 달라져야 합니다. 하지만 “단독 사용자만 가능”이라는 원칙이 있었으니, “원칙을 바꾸려면 먼저 합의가 필요하다”고 판단할 수 있었어요.
2. 단계별 검증이 나중의 수정을 줄인다
기획이 거의 끝났을 때 비용 문제를 발견했지만, 아직 코드를 안 짜서 2시간 만에 수정했어요. 만약 구현까지 다 했다면 훨씬 컸을 거고요.
3. “너무 크면 나누는 게 맞다”
98개 요구사항을 한 번에 하려니 복잡했어요. “1차: 기본 기능만 / 2차: 폰 입력 폼이나 이미지 편집” 이렇게 나누니까 1차가 명확해졌습니다.
🔜 다음에 적용할 것
새 프로젝트를 시작할 때 항상 Constitution부터 — 원칙 정하고 요구사항 정하고 설계하고 검증하는 흐름
기획 중간에 비용·기술 검증 끼워넣기 — “요구사항은 좋은데 기술로 안 된다”는 발견을 미리 하기
Analyze 단계의 일관성 검사 리포트를 구현 전에 꼭 읽기 — 누락을 놓치지 않기
솔직한 소감
처음엔 “명세서 때문에 오히려 느리면 어쩌지?” 싶었어요. 그런데 하루 동안 명세 다섯 단계를 모두 끝내고, 코드 한 줄도 안 짜고도 “이제 시작해도 된다”는 확신이 생긴 게 신기했습니다.
비개발자로 AI와 함께 처음 프로젝트를 하는 입장에서, 이렇게 체계적인 방법론이 있다는 걸 알게 돼서 좋았어요. 요구사항이 자꾸 바뀌고 막힌다고 느꼈던 부분들이, 사실은 처음부터 명확하게 정하지 않아서였다는 걸 깨달았습니다.
로그인하고 댓글을 남겨 주세요
저도 똑같은 데서 걸린 적이 있어서, 코드 한 줄 안 짜고 하루 안에 5단계를 다 끝내셨다는 대목을 두 번 읽었습니다. 문서에 적힌 '미착수'를 그대로 믿고 이미 있는 기능을 또 만든 적이 있는데, 결국 만들기 전에 열어보지 않은 값이었거든요.
제이리님이 Constitution에 '백업은 실제로 한 번 복구해봐야 검증됨'을 넣으신 지점이 정말 좋은데요, 다음 관건은 그 원칙이 83개 작업 안에 실제 작업 항목으로 들어가 있는지에 있을 것 같습니다. 원칙은 문장으로 남고 작업은 체크박스로 남으니, 둘이 연결돼 있지 않으면 구현 단계에서 조용히 빠지기 쉽거든요.
예를 들어, 98개 요구사항에 FR-01 같은 ID를 붙여두고 Tasks 문서에서 그 ID를 전부 grep해 건수를 대조하면, '누락 0건'이라는 결과 옆에 검사기가 실제로 몇 개를 봤는지가 숫자로 같이 남습니다. 복구 리허설처럼 원칙에서 파생된 작업도 그 대조에 걸리면 놓치지 않게 되고요.
화이팅입니다!!
마지막 검수 단계 converge도 실행해보시길 추천드립니다~~
덕분에 잘 읽었습니다~




요구 사항 자체를 명확하게 해 주고 제대로 스펙을 작성하고 작업을 할 수 있기 때문에 유지 보수 측면에서도 도움이 되고 개발자와의 커뮤니케이션에도 굉장히 도움이 되는 측면이 있어요. 하지만 아무래도 스펙 기반을 개발하기 때문에 명세가 명확해야 되는 부분이 있어서 중간중간에 요구사항이치고 들어온다거나 혹은 크게 뭔가 바뀐다거나 할 때에는 애자일 방식으로 작업을 해야 되는데 이런 애자의 방식과 스펙 명세 기반 방식을 잘 조합해서 하셔야 할 것 같습니다.