본문으로 건너뛰기

스펙킷(Spec Kit) 사용법: 미니 PRD로 웹앱 만들기

스펙킷(Spec Kit)은 AI 코딩 도구가 명세, 계획, 작업 목록 순서로 개발하게 해 주는 GitHub 오픈소스 도구예요. 미니 PRD 한 장으로 208명이 쓴 투표 웹앱을 34시간 만에 만들었고, 그사이 명세 13개를 쌓았어요.

스펙킷과 미니 PRD로 무엇을 만들었나

2026년 10월 3일 AI스터디 24기 온오프모임에서 20팀 208명이 함께 쓴 게임 웹앱 「뽀짝이 멀티버스」를 만들었어요. 팀이 운영비서 고양이 뽀짝이를 엉뚱한 세계로 보내는 프롬프트를 내면, 운영진이 이미지를 만들고 모두가 최고의 이미지에 익명으로 투표하는 게임이에요.

  • 팀장이 팀 프롬프트를 한 번만 제출해요

  • 운영진이 뽀짝이 캐릭터 시트를 붙여 이미지를 생성해요

  • 20개 작품을 팀 번호 없이 A부터 T까지 익명으로 전시해요

  • 1인 1표, 자기 팀에는 투표할 수 없어요

코드는 코덱스(Codex)로 짜고 ChatGPT Sites로 배포했어요. 저는 지피터스에서 커뮤니티와 AI스터디 운영을 맡고 있는 커뮤니티 리드 진저예요. 이번 24기는 올해의 마지막 스터디라서 네트워킹에 힘을 줬고, 행사를 기획하면서 앱도 직접 만들었어요.

운영진 화면의 팀별 제출 현황. 참가 팀 20팀, 프롬프트 도착 20/20, 이미지 준비 완료 20/20, 일반 참가자 208명
참가자가 보는 익명 전시 화면. 작품 A부터 T까지 20개가 팀 번호 없이 놓여 있고 접속용 QR 코드가 있다

왼쪽은 운영진이 보는 팀별 제출 현황, 오른쪽은 참가자가 보는 익명 전시 화면이에요.

스펙킷은 처음부터 쓴 게 아니에요: 1시간 38분 뒤에 붙였어요

처음엔 그냥 만들었어요. 첫 커밋이 10월 2일 0시 26분이고, 스펙킷을 넣은 커밋이 같은 날 2시 4분이에요. 1시간 38분 동안은 "이거 만들어줘"로 짰어요.

막힌 지점은 기능을 못 만드는 게 아니었어요. 고칠 때마다 앞 기능이 조용히 깨지는 것이었어요. 운영진 피드백이 밤새 들어오는데, 하나 고치면 다른 데가 틀어지는지 제가 알 방법이 없었어요. 게다가 밤새 만든 앱을 다음 날 타타님이 이 앱을 이어받아야 진행해야 했어요.

그래서 아루나님이 공유해 주신 가이드 「만들긴 했는데, 그다음은? 유지보수까지 이어지는 위임의 최소 단위, 스펙킷」을 그대로 따라 해 봤어요.

스펙킷을 꺼낼 시점은 두 번째 수정 요청이 들어온 순간이었어요. 한 번 만들고 끝낼 거면 처음부터 필요하지 않아요.

미니 PRD는 개발 범위를 정하는 문서 한 장이에요

PRD(Product Requirements Document)는 원래 제품 전체의 요구사항을 담는 긴 문서인데, 미니 PRD는 그걸 "이번에 고칠 한 가지"로 좁혀 한 장에 담은 것이라 미니예요. 문제 장면, 이번 결과, 이번 범위, 제외할 것, 완료 확인 칸만 적어요. 제품을 설명하는 문서가 아니라 AI에게 이번 작업의 경계와 끝나는 기준을 넘기는 문서라서, 제품이 아니라 작업 한 건 단위로 매번 새로 써요.

문제 장면: 운영진이 어느 팀 자료가 빠졌는지 다시 찾느라 진행이 끊긴다

  • 이번 결과: 한 화면에서 빠진 준비물을 보고, 다 갖춰지면 투표를 시작한다

  • 이번 범위: 팀별 누락 목록, 준비가 덜 되면 시작 버튼 잠금

  • 제외할 것: 이미지 자동 생성, 문자 인증, 투표 자격 변경, 실데이터 테스트

  • 완료 확인: 서버에 직접 요청해도 준비가 덜 됐으면 거절된다

다섯 칸 중 제일 많이 쓴 건 완료 확인이었어요. "화면에서 버튼이 비활성화된다"가 아니라 "서버에 직접 요청해도 거절된다"로 적어 둔 덕분에, 나중에 화면만 가리고 끝나는 수정이 걸러졌어요.

스펙킷(Spec Kit) 공식 순서와 제가 더한 두 단계

스펙킷(Spec Kit)은 GitHub이 공개한 오픈소스 도구로, 미니 PRD 한 장을 받아 명세 → 계획 → 작업 목록 → 구현 순서로 AI를 몰고 가면서 단계마다 마크다운 파일을 하나씩 남겨요. 핵심은 "어떻게 만들지" 전에 "무엇을, 왜"를 파일로 고정한다는 것이고, 그래서 다음 수정은 머릿속이 아니라 그 파일을 입력으로 삼아 시작돼요. 설치는 uv tool install specify-cli 한 줄이고, 코덱스·클로드 코드·코파일럿 등 38개 도구에 붙여 쓸 수 있어요.

공식 흐름은 Specify, Plan, Tasks, Implement, Converge 다섯 단계예요. 각 단계가 마크다운 파일 하나를 만들고, 그 파일이 다음 단계의 입력이 돼요. 통합 가능한 AI 도구는 38개라고 공식 사이트에 적혀 있어요(2026년 10월 16일 확인).

저는 여기에 두 단계를 더 썼어요.

  1. constitution으로 프로젝트 원칙을 먼저 정한다

  2. specify, plan, tasks로 명세와 계획, 작업 목록을 만든다

  3. analyze로 요구사항과 작업이 빠짐없이 연결됐는지 대조한다

  4. implement로 구현하고, converge로 빠진 작업을 붙인다

analyze가 제일 체감이 컸어요. 첫 명세에서 요구사항과 성공 기준 11개를 작업 12개에 하나씩 연결했고, 연결률 100%에 미해결 모호성과 중복, 누락이 0으로 나왔어요. 작업 목록을 사람이 눈으로 훑어서는 못 잡는 종류예요.

명세 13개 중 3개가 비밀번호였어요

여기서 제일 배운 게 나왔어요. 명세 13개를 주제별로 세어 보니 비밀번호 하나로 3개를 썼어요.

  • 005: 팀마다 외우기 쉬운 비밀번호를 따로 만든다

  • 006: 운영진 입장을 ChatGPT 로그인 대신 운영진 비밀번호 하나로 받는다

  • 013: 현장 진행 편의로 비밀번호 형식을 더 단순하게 바꾼다

013은 행사 당일 오전 10시 32분 커밋이에요. 형식을 바꾼 이유는 보안이 아니라, 운영진이 20팀에게 비밀번호를 소리로 불러줘야 했기 때문이에요. 숫자가 섞인 비밀번호는 시끄러운 행사장에서 안 들려요.

같은 주제로 명세가 세 번 나오면 설계가 틀린 게 아니라, 책상에서는 알 수 없는 조건이 있다는 뜻이에요. 그래서 미리 다 맞히는 것보다 열세 번 싸게 고칠 수 있는 상태가 중요했어요.

로컬 검사는 다 통과했는데 배포본은 버튼이 안 눌렸어요

행사 전날, 배포 주소에서 모든 버튼이 안 눌린다는 보고를 받았어요. 재현해 보니 TypeError: e is not a function이었고, 빌드된 화면 이동 코드가 함수로 안 잡히는 문제였어요. 주소를 직접 입력하면 그 화면과 내부 버튼은 멀쩡했어요.

로컬 검사는 전부 통과한 상태였어요. 배포본은 다른 코드라서, AI가 통과시킨 검사가 사용자가 쓰는 화면을 보장하지 않아요.

고친 방법은 두 가지예요. 페이지 간 이동을 브라우저 기본 링크로 바꿨고, 출시 검사 항목에 실제 배포 주소를 브라우저로 읽기만 하는 검사를 넣었어요. 제출이나 투표처럼 상태를 바꾸는 동작은 넣지 않았어요.

2025년 DORA 보고서도 같은 지점을 남은 과제로 꼽았어요. AI 적용은 90%, 생산성이 늘었다는 응답은 80%가 넘는데, 과제는 "사용자에게 가기 전에 의도대로 동작하는지 확인하는 일"이라고 적혀 있어요.

"결과 발표하면 참가자 폰에도 바로 뜨나요?" 한 줄이 권한 설계를 바꿨어요

운영진의 이 질문 한 줄이 가장 큰 구조 변경을 불렀어요. 현장에서 우승을 먼저 발표하고, 참가자 링크에는 운영진이 원하는 시점에 공개해야 했어요.

화면만 가리는 걸로는 안 됐어요. 새로고침하거나 API를 직접 부르면 결과가 샐 수 있으니까요. 그래서 결과 상태를 네 단계로 나눴어요.

  1. locked: 투표 중

  2. revealing: 현장 연출 10초

  3. announced: 운영진과 행사장 화면만 순위를 본다

  4. published: 운영진이 직접 누를 때만 참가자에게 열린다

팀원과 팀장이 부르는 API는 announced까지 득표수와 순위, 닉네임을 아예 안 돌려줘요. 쿼리 인자로 운영진 관점을 요청할 수도 없고, 발표 전에 공개를 요청하면 409로 거절해요.

같은 원칙을 데이터에도 적용했어요. 투표가 시작된 뒤에는 팀 정보 행을 수정하지 못하게 막아 두고, 비밀번호는 따로 만든 표에 저장했어요. 행사 중에 건드리면 안 되는 값은 운영 규칙으로 두면 깨져요. 코드로 막는 게 안전했어요.

운영진 결과 발표 화면. 현장 발표 뒤 참가자에게 결과 공개 버튼을 눌러야 참가자 링크가 열린다

운영진만 보는 결과 발표 화면이에요. 참가자 링크는 이 버튼을 눌러야 열려요.

검사 97개가 112개로 늘면서 13번째 수정을 지켰어요

숫자로 가장 또렷하게 남은 변화예요. 첫 명세의 통합 검사가 97개였는데, 명세가 쌓이면서 112개가 됐어요. 13번째 수정을 할 때도 이 112개가 앞 기능을 지켜 줬어요.

  • 통합 검사: 97개에서 112개로

  • 팀 로그인 확인: 20팀의 팀원과 팀장 40건 통과

  • 인수인계 문서: 작업 23건이 쌓임

인수인계 문서 덕을 실제로 봤어요. 행사 전날 새벽에 다른 운영진이 "투표는 어디에 쌓여?"라고 물었을 때, 저는 자러 가야 했지만 운영비서 뽀짝이가 프로젝트 코드와 문서를 읽고 바로 답했어요!

행사 당일에는 20팀 모두 프롬프트를 제출했고, 투표부터 발표까지 앱 하나로 진행했어요. 총 81표가 모였고 1위는 14팀 17표, 공동 2위는 09팀과 18팀이 각 7표였어요.

최종 결과 화면. 1위 14팀 17표, 공동 2위 09팀과 18팀 각 7표, 팀별 참여 멤버가 함께 표시된다
1위 14팀 작품. 갓과 한복 차림의 고양이들이 서당에서 책을 펴고 공부하는 그림
공동 2위 09팀 작품. 뽀짝이 잠옷을 입은 사람이 소파에 엎드려 있고 옆에 GPTers 모자를 쓴 검은 고양이가 있다
공동 2위 18팀 작품. 24기 온오프모임 현장 사진 위에 뽀짝이 캐릭터를 합성했다

최종 결과 화면과 1위 14팀, 공동 2위 09팀과 18팀의 작품이에요.

못 한 것과, 스펙킷이 줄여주지 않은 것

솔직하게 적어 둘 게 두 가지 있어요.

208명 동시 접속은 검사하지 못한 채 행사에 들어갔어요. 동시 투표 요청 검사는 8건까지만 돌렸고, 그건 부하 테스트가 아니에요. 실제 휴대폰 사파리와 행사장 네트워크도 미확인으로 남겼어요. 다행히 문제는 없었지만 운이 좋았던 쪽이에요.

배포 동기화는 수동이었어요. 전체 커밋 50개 중 27개가 배포본을 올리는 커밋이에요. 절반 이상이 설계 작업이 아닌, 손으로 올리는 일이었어요. 스펙킷은 무엇을 만들지 정리해 주지만, 올리는 과정을 줄여 주지는 않아요.

스펙킷을 처음 써 보신다면

처음엔 미니 PRD 한 장만 써도 충분해요. 다섯 칸 중 완료 확인부터 적어 보시는 걸 권해요. 아래 문장을 코덱스나 클로드 코드에 그대로 줘도 시작할 수 있어요.

이번에 만들 기능의 미니 PRD를 같이 쓰자.
문제 장면, 이번 결과, 이번 범위, 제외할 것, 완료 확인 다섯 칸으로.
완료 확인은 서버 기준으로 적어 줘.
다 쓰면 스펙킷 specify부터 순서대로 진행해 줘.

다시 한다면 바꿀 세 가지

제가 다시 한다면 세 가지를 바꿀 거예요. 완료 확인을 서버 기준으로 적는 건 그대로 두고, 출시 검사에 배포 주소 확인을 처음부터 넣고, 투표 기록 내보내기를 첫 범위에 넣을 거예요. 투표 결과는 앱 DB에만 쌓여서 나중에 따로 세어야 했어요.

미니 PRD와 스펙킷 흐름은 아루나 스터디장님의 가이드 덕분에 하루 만에 실전에 쓸 수 있었어요. 좋은 자료 공유해 주셔서 정말 감사해요!

확인일 2026년 10월 16일.

공식 흐름 다섯 단계와 통합 38개는 GitHub Spec Kit 공식 사이트와 github/spec-kit 저장소에서 확인했어요.

AI 적용률 90%, 생산성이 늘었다는 응답 80% 이상, 남은 과제는 구글 2025 DORA 보고서 요약이에요. 2025년 9월 23일 공개, 기술 전문가 약 5,000명 조사예요.

명세 13개, 검사 97개에서 112개, 커밋 50개 중 27개, 인수인계 작업 23건은 제가 프로젝트 기록에서 직접 센 값이에요.

글쓴이 진저. 국내 최대 AI 커뮤니티 지피터스(GPTers)에서 커뮤니티와 AI스터디 운영을 맡고 있어요. 이번 행사는 기획부터 앱 제작까지 직접 했어요.

지피터스가 사내 AX를 어떻게 하는지는 지피터스는 사내 AX를 어떻게 할까에 모아 두었어요.

2

함께 이야기해요 2

로그인하고 댓글을 남겨 주세요

아그나르 프로필 이미지
아그나르2026.10.16

스펙킷은... "그저 해줘"와 어떤 점이 다른가요?? 미니 PRD는... 따로 제품이나 스킬이 있는건가요? 아님 PRD를 작게 썼다 해서 미니 PRD인가요??

현장 반응이 좋았을 거 같은데, 좀 더 알려주세요.

지피터스_진저 프로필 이미지

아그나르님 감사합니다! 순서대로 답해볼게요.

그저 해줘와의 차이는 남는 게 있느냐예요. 단계마다 파일이 남아서 다음 수정의 입력이 돼요. 버전 아카이브의 개념이랄까요.

미니 PRD는 제품이 아니에요. 범위를 적는 문서 한 장이고, 아루나님 가이드대로 문제 장면, 이번 결과, 이번 범위, 제외할 것, 완료 확인 다섯 칸을 썼어요. 완료 확인이 제일 셌어요. "버튼이 비활성화된다"가 아니라 "서버에 직접 요청해도 거절된다"로 적으니 화면만 가리는 수정이 걸러졌어요.

현장은, 20팀 전원 제출에 총 81표가 모였고 온오프모임 후기 설문에서도 만족도가 높게 나와서 몹시 뿌듯했습니다.

필요한 AI 정보만
메일함에 쏙쏙 넣어드려요.

지금 핫한 AI 소식부터 직접 해 본 사례까지, 월요일마다 무료로 받아보세요

우리 회사에도 이런 자동화를 도입하고 싶다면

회사 업무에 맞춘 AI 교육을 함께 설계해요.

기업교육 문의하기

함께 읽어보세요

AX 현장 전체 보기