바로 코딩하기 전에 무엇을 만들고, 어떤 기준으로 완료를 판정할지 먼저 파일로 남깁니다.
이 가이드는 비개발자도 AI 코딩 도구와 Spec Kit을 이용해 작은 웹 프로젝트를 끝까지 실습할 수 있도록 정리한 입문 절차입니다. 예시는 Cursor와 Claude Code를 중심으로 설명하지만, Codex·Antigravity·Gemini 등 지원되는 통합으로 바꿀 수 있습니다.
실습 목표
화면이 한 번 뜨는 것만 성공으로 보지 않습니다. 요구사항과 구현 결과가 연결되고, 실행 명령과 검증 결과를 다시 확인할 수 있어야 완료입니다.
1. 도구를 준비합니다
- Git 2.x 이상
- Python 3.11 이상과
uv - Node.js 20 LTS 권장과 npm·pnpm·bun 중 하나
- 주 구현용 AI 코딩 도구 한 개
- 필요하면 독립 검토용 AI 도구 한 개
여러 도구를 한꺼번에 설치하는 것보다 주 도구 하나로 전체 흐름을 익히는 편이 좋습니다. 두 번째 도구는 같은 결과를 다시 검토하는 역할로 사용합니다.
2. Spec Kit을 설치합니다
재현 가능한 교육이나 팀 프로젝트에서는 설치 버전을 고정할 수 있습니다. 이 문서를 등록한 2026년 9월 28일 기준 공식 최신 릴리스는 1.0.6입니다.
버전은 시간이 지나면 바뀝니다. 새 프로젝트를 시작할 때는 공식 릴리스와 로컬 버전을 다시 확인합니다.
3. 프로젝트를 만들고 통합을 하나 선택합니다
Cursor Agent를 주 도구로 쓰면 통합 키를 해당 도구로 바꿉니다. 한 번의 init에는 주 통합 하나만 지정합니다. 추가 도구가 꼭 필요할 때만 프로젝트를 초기화한 뒤 별도로 통합을 설치합니다.
초기화 후에는 .specify/와 에이전트 명령·스킬 폴더를 확인합니다. 비어 있지 않은 기존 저장소에서 --force를 쓰기 전에는 반드시 변경 파일을 백업하거나 커밋합니다.
4. 작은 PRD를 먼저 작성합니다
처음 실습은 30~60분 안에 확인할 수 있는 범위가 좋습니다. 로그인, 결제, 운영 데이터베이스, 복잡한 외부 연계는 제외합니다.
예: “기존 회사 소개 사이트를 단일 페이지 MVP로 리뉴얼한다. 데이터베이스·로그인·결제는 사용하지 않고, 모바일 화면과 문의 버튼을 포함한다.”
5. 프로젝트 지침 파일을 갱신합니다
PRD와 저장소 구조를 바탕으로 Claude Code는 CLAUDE.md, Codex 계열은 AGENTS.md처럼 실제 도구가 읽는 프로젝트 지침을 작성합니다. 외부 코딩 원칙은 그대로 복사하지 말고 다음 항목으로 번역합니다.
- 먼저 기존 코드와 문서를 읽고 가정을 명시합니다.
- 가장 단순한 해결책을 우선합니다.
- 요청 범위 밖의 파일은 함부로 바꾸지 않습니다.
- 완료 전 빌드와 테스트를 실제로 실행합니다.
- 실패를 숨기거나 테스트를 약화해 통과시키지 않습니다.
- 프로젝트의 설치·실행·검증 명령을 정확히 기록합니다.
전역 지침에는 언어와 일반 작업 원칙만 두고, 프로젝트별 기술·경로·검증 명령은 저장소 안의 지침 파일에 둡니다.
6. Constitution으로 비협상 원칙을 정합니다
PRD를 바탕으로 프로젝트 헌장을 만듭니다. 예를 들어 모바일 우선, 접근성 기본 준수, 비밀정보 커밋 금지, 실제 빌드 성공 필수, 모든 날짜·시간은 KST 기준 같은 원칙을 판정 가능한 문장으로 작성합니다.
7. Specify로 기능 스펙을 만듭니다
구현 방법보다 사용자 문제와 수용 조건에 집중합니다. 생성된 spec.md에서 사용자 시나리오, 예외 상황, 범위 밖 항목, 검증 가능한 성공 기준을 확인합니다.
8. 고위험 불확실성을 먼저 해소합니다
운영 데이터, 인증, 외부 API, 권한, 개인정보, 배포 환경처럼 비용을 크게 바꾸는 질문이 남아 있다면 계획 전에 명확히 합니다. 체크리스트는 요구사항 품질과 누락 여부를 점검하는 별도 게이트입니다.
9. Plan으로 구현 방식을 설계합니다
프레임워크, 디렉터리 구조, 데이터 흐름, 주요 컴포넌트, 테스트 전략, 배포·복구 방법을 정합니다. 작은 실습에서도 “어떤 파일을 왜 만들 것인가”를 설명할 수 있어야 합니다.
10. Tasks로 검증 가능한 작업을 만듭니다
작업은 파일 이름만 나열하지 않고 사용자 가치와 검증 방법이 보이도록 나눕니다.
11. Analyze로 구현 전 정합성을 검사합니다
spec.md, plan.md, tasks.md 사이의 모순과 누락을 찾습니다. 요구사항이 태스크에 연결되지 않았거나 헌장과 계획이 충돌한다면 구현 전에 고칩니다.
12. Implement로 태스크를 실행합니다
태스크 순서대로 구현하되, 중간 변경을 작게 유지하고 각 단계에서 실행 결과를 확인합니다. 권한을 모두 건너뛰는 실행 옵션은 편하지만 파일 삭제·명령 실행·외부 전송 범위까지 넓힐 수 있으므로 격리된 실습 환경이 아니라면 기본값으로 사용하지 않습니다.
13. Converge로 스펙과 코드를 수렴시킵니다
Converge는 “다 끝났다”는 선언이 아닙니다. 현재 코드가 스펙을 충족하는지 확인하고, 빠진 요구를 새 태스크로 돌려보냅니다.
차이가 없어질 때까지 반복한 뒤 실제 개발 서버와 빌드를 실행합니다.
14. 최종 검증합니다
- 주요 사용자 흐름이 작동하는가?
- 모바일과 데스크톱에서 읽을 수 있는가?
- 콘솔·빌드 오류가 없는가?
- 요구사항마다 테스트 또는 확인 증거가 있는가?
- 생성물과 소스코드가 저장소에 남아 있는가?
- 알려진 한계와 다음 작업이 기록되었는가?
실습에서 자주 생기는 오류
- 버전 고정값을 영구 정답처럼 사용: 공식 릴리스와 로컬 버전을 시작할 때 확인합니다.
- 바로 구현부터 시작: 작은 PRD와 수용 조건부터 만듭니다.
- 지침 파일에 외부 문서를 통째로 복사: 프로젝트 명령과 위험에 맞는 규칙만 남깁니다.
- Analyze를 구현 후 실행: 구현 전 문서 정합성 게이트로 사용합니다.
- Converge 한 번으로 종료: 미충족 작업이 있으면 구현과 수렴 검증을 반복합니다.
- 개발 서버 화면만 보고 완료: 빌드, 테스트, 요구사항 연결, 알려진 한계를 함께 확인합니다.
MVP 다음 단계
이 실습은 스펙 주도 개발의 기본 흐름을 익히는 과정입니다. 실제 운영시스템으로 전환하려면 현행 시스템 진단, 데이터 이관, 인증·권한, 보안, 관측성, 백업·복구, 배포·롤백, 운영 책임과 변경 절차를 별도 게이트로 추가해야 합니다.
Spec Kit의 가치는 문서를 많이 만드는 데 있지 않습니다. 사람이 방향을 바꿀 수 있을 때 요구사항을 공유하고, AI가 만든 결과를 검증 가능한 증거로 연결하는 데 있습니다.