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

ALT

사양 키트

📝 한줄 요약

GitHub의 Spec Kit을 처음 써봤습니다. “코드부터 짜지 말고 먼저 무엇을 만들지 정의하세요”는 원칙으로, 프로젝트를 Constitution → Specify → Plan → Tasks → Analyze 다섯 단계로 체계적으로 설계했습니다.

Before: 요구사항이 자꾸만 바뀌고, 기획 중간에 기술 문제가 발견돼서 다시 설계
After: 단계별로 검증하면서 진행해서, 이견 없는 완성도 높은 설계 완성

👥 이런 분께 추천

• 프로젝트를 시작하기 전에 체계적으로 기획하고 싶은 분

• AI와 함께 개발할 때 명확한 방향 지침을 먼저 만들고 싶은 분

• 기획 중에 “이건 어떻게 할 거지?” 같은 질문이 자주 생기는 분

• 요구사항이 자꾸 바뀌어서 헷갈리는 상황을 줄이고 싶은 분

🙋 내 스펙 & 환경

진행 방법

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개 페이즈로 나뉘었어요. 각 페이즈는:

1. Setup (프로젝트 초기화)

2. 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차가 명확해졌습니다.

🔜 다음에 적용할 것

1. 새 프로젝트를 시작할 때 항상 Constitution부터 — 원칙 정하고 요구사항 정하고 설계하고 검증하는 흐름

2. 기획 중간에 비용·기술 검증 끼워넣기 — “요구사항은 좋은데 기술로 안 된다”는 발견을 미리 하기

3. Analyze 단계의 일관성 검사 리포트를 구현 전에 꼭 읽기 — 누락을 놓치지 않기

솔직한 소감

처음엔 “명세서 때문에 오히려 느리면 어쩌지?” 싶었어요. 그런데 하루 동안 명세 다섯 단계를 모두 끝내고, 코드 한 줄도 안 짜고도 “이제 시작해도 된다”는 확신이 생긴 게 신기했습니다.

비개발자로 AI와 함께 처음 프로젝트를 하는 입장에서, 이렇게 체계적인 방법론이 있다는 걸 알게 돼서 좋았어요. 요구사항이 자꾸 바뀌고 막힌다고 느꼈던 부분들이, 사실은 처음부터 명확하게 정하지 않아서였다는 걸 깨달았습니다.