"코드부터 짜지 마세요. 먼저 무엇을 만들지 정의하세요."
spec-kit은 AI 코딩 에이전트와 함께 명세 기반 개발(Spec-Driven Development)을 실현하는 도구입니다.
📌 들어가며
AI 코딩 도구(Claude Code, GitHub Copilot, Cursor 등)를 사용하면서 이런 경험 있으신가요?
- "이거 만들어줘"라고 했더니 내가 원하는 것과 다른 결과물이 나왔다
- 코드는 생성됐는데 전체 구조가 엉망이다
- 기능을 추가할수록 일관성이 깨진다
- AI가 맥락을 자주 잊어버린다
이런 문제의 근본 원인은 "무엇을 만들지"에 대한 명확한 정의 없이 바로 코딩에 들어가기 때문입니다.
spec-kit은 이 문제를 해결합니다. "Vibe Coding"에서 벗어나 체계적이고 예측 가능한 AI 개발을 가능하게 해주는 도구입니다.
🤔 spec-kit이란?
한 줄 정의
spec-kit은 GitHub에서 만든 오픈소스 툴킷으로, AI 코딩 에이전트와 함께 명세(Specification) 기반 개발을 할 수 있게 해주는 도구입니다.
Spec-Driven Development란?
기존 개발 방식과 Spec-Driven Development의 차이를 비교해보겠습니다.
| ❌ 기존 방식 (Vibe Coding) | ✅ Spec-Driven Development |
|---|---|
| "이거 만들어줘" | Constitution (프로젝트 원칙) |
| ↓ | ↓ |
| AI가 코드 생성 | Specify (무엇을 만들지) |
| ↓ | ↓ |
| 원하는 게 아님 | Plan (어떻게 만들지) |
| ↓ | ↓ |
| 다시 요청 → 반복... | Tasks (할 일 목록) |
| ↓ | |
| Implement (구현) |
핵심 차이점:
- 기존: 코드 → (문제 발견) → 수정 → 코드 → 반복...
- Spec-Driven: 원칙 → 명세 → 계획 → 작업 → 구현 (체계적 단계)
왜 spec-kit이 필요한가?
| 문제 | spec-kit의 해결책 |
|---|---|
| AI가 맥락을 잊음 | 명세 문서가 항상 컨텍스트로 유지됨 |
| 결과물이 일관성 없음 | Constitution(원칙)이 모든 결정을 가이드 |
| 무엇을 만들지 불명확 | Specify 단계에서 요구사항 명확화 |
| 기술 스택 결정이 흔들림 | Plan 단계에서 기술적 결정 고정 |
| 큰 기능을 어디서부터 시작할지 모름 | Tasks로 실행 가능한 단위로 분해 |
⚡ 설치하기
사전 요구사항
- Python 3.11+
- Git
- uv (Python 패키지 매니저)
- AI 코딩 에이전트 (Claude Code, GitHub Copilot, Cursor 등)
uv 설치 (없다면)
# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows (PowerShell)
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"spec-kit 설치
# 영구 설치 (권장)
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git
# 설치 확인
specify --version
# 시스템 요구사항 체크
specify check🚀 프로젝트 시작하기
새 프로젝트 초기화
<# 새 프로젝트 생성
specify init my-project --ai claude
# 또는 현재 디렉토리에서 초기화
specify init . --ai claude
specify init --here --ai claude
지원하는 AI 에이전트
| 에이전트 | 옵션 |
|---|---|
| Claude Code | --ai claude |
| GitHub Copilot | --ai copilot |
| Cursor | --ai cursor-agent |
| Gemini CLI | --ai gemini |
| Windsurf | --ai windsurf |
| 기타 | codex, qwen, opencode, amp 등 |
초기화 후 프로젝트 구조
my-project/
├── .claude/
│ └── commands/
│ ├── speckit.analyze.md
│ ├── speckit.checklist.md
│ ├── speckit.clarify.md
│ ├── speckit.constitution.md
│ ├── speckit.implement.md
│ ├── speckit.plan.md
│ ├── speckit.specify.md
│ ├── speckit.tasks.md
│ └── speckit.taskstoissues.md
├── .specify/
│ ├── memory/
│ │ └── constitution.md
│ ├── scripts/bash/
│ │ ├── check-prerequisites.sh
│ │ ├── common.sh
│ │ ├── create-new-feature.sh
│ │ ├── setup-plan.sh
│ │ └── update-agent-context.sh
│ └── templates/
│ ├── agent-file-template.md
│ ├── checklist-template.md
│ ├── plan-template.md
│ ├── spec-template.md
│ └── tasks-template.md
└── LICENSE
📋 핵심 워크플로우: 5단계
spec-kit의 개발 워크플로우는 5가지 슬래시 명령어로 이루어집니다.
💡 중요: 각 단계 사이에 사람의 검토가 들어가고 피드백을 줘야 합니다. 초기 단계에서 잘못된 부분을 잡지 않으면, 나중에 구현할 때 엉뚱한 방향으로 코드가 생성될 위험이 있습니다.
1️⃣ Constitution: 프로젝트 원칙 수립
목적
프로젝트 전반에 걸쳐 AI가 따라야 할 원칙과 가이드라인을 정의합니다. 이는 프로젝트의 "헌법" 같은 역할을 합니다.
사용법
AI 에이전트(예: Claude Code)를 실행한 후:
/speckit.constitution 코드 품질, 테스트 표준, 사용자 경험 일관성, 성능 요구사항에 초점을 맞춘 원칙을 만들어줘
생성되는 파일
.specify/memory/constitution.md
포함되는 내용 예시
- 코드 스타일 가이드
- 테스트 커버리지 기준
- 성능 요구사항
- 보안 원칙
- 의존성 관리 정책
💡 팁
✅ 좋은 Constitution 예시:
- "외부 라이브러리보다 표준 라이브러리 우선 사용"
- "모든 public 함수에 docstring 필수"
- "단위 테스트 커버리지 80% 이상 유지"
❌ 피해야 할 것:
- 너무 일반적인 원칙 ("좋은 코드를 작성한다")
- 기술 스택 명시 (이건 Plan 단계에서)2️⃣ Specify: 요구사항 정의
목적
무엇을 만들지, 왜 필요한지를 정의합니다. 기술 스택은 아직 언급하지 않습니다!
사용법
/speckit.specify 팀 생산성 플랫폼 Taskify를 개발해줘. 사용자가 프로젝트를 생성하고, 팀원을 추가하고, 작업을 할당하고, 칸반 스타일로 보드 간에 작업을 이동할 수 있어야 해. 각 작업 카드에서 상태 변경, 댓글 작성, 담당자 지정이 가능해야 해.생성되는 파일
.specify/specs/001-feature-name/spec.md
포함되는 내용
- 사용자 스토리
- 기능 요구사항
- 수락 기준 (Acceptance Criteria)
- 검토 체크리스트
💡 팁: 명확하게 작성하기
✅ 좋은 Specify 예시:
"사용자는 작업 카드를 드래그 앤 드롭으로 다른 컬럼으로 이동할 수 있다.
이동 시 상태가 자동으로 업데이트된다.
본인이 담당한 카드는 다른 색상으로 표시된다."
❌ 피해야 할 것:
"React로 칸반 보드 만들어줘" (기술 스택 언급)
"좋은 UI로 만들어줘" (모호함)선택: /speckit.clarify
명세가 불명확한 부분이 있다면:
/speckit.clarifyAI가 명확하지 않은 부분에 대해 질문을 던지고, 답변을 기반으로 명세를 보완합니다.
3️⃣ Plan: 기술 계획 수립
목적
어떻게 만들지, 어떤 기술 스택을 사용할지 결정합니다.
사용법
/speckit.plan Vite와 바닐라 JavaScript를 사용하고, 데이터는 로컬 SQLite에 저장해. 최소한의 라이브러리만 사용해줘.
생성되는 파일들
.specify/specs/001-feature-name/
├── spec.md # (이전 단계에서 생성)
├── plan.md # 구현 계획
├── data-model.md # 데이터 모델
├── research.md # 기술 리서치
├── quickstart.md # 빠른 시작 가이드
└── contracts/
├── api-spec.json # API 명세
└── ...💡 팁: 기술 스택 명시하기
✅ 좋은 Plan 프롬프트:
"Next.js 14 App Router 사용, PostgreSQL, Prisma ORM,
TailwindCSS, 인증은 NextAuth.js로"
❌ 피해야 할 것:
"적절한 기술로 만들어줘" (AI가 임의로 결정함)주의: AI의 과잉 엔지니어링
AI가 요청하지 않은 것을 추가할 수 있습니다. 항상 확인하세요!
"plan.md를 검토하고, 내가 요청하지 않은 컴포넌트가 있다면 알려줘.
왜 추가했는지 근거를 설명해줘."4️⃣ Tasks: 작업 분해
목적
구현 계획을 실행 가능한 작업 단위로 분해합니다.
사용법
/speckit.tasks
생성되는 파일
.specify/specs/001-feature-name/tasks.md
포함되는 내용
- 사용자 스토리별 작업 분류
- 작업 간 의존성 표시
- 병렬 실행 가능 작업 표시
[P] - 각 작업의 파일 경로
- 체크포인트 (검증 지점)
tasks.md 예시
## Phase 1: 프로젝트 설정
### Task 1.1: 프로젝트 초기화 [P]
- [ ] Vite 프로젝트 생성
- [ ] 필요한 의존성 설치
- 파일: `package.json`, `vite.config.js`
### Task 1.2: 데이터베이스 설정 [P]
- [ ] SQLite 연결 설정
- [ ] 스키마 정의
- 파일: `src/db/schema.sql`, `src/db/connection.js`
---
**Checkpoint**: 프로젝트 빌드 및 DB 연결 확인5️⃣ Implement: 구현 실행
목적
tasks.md에 정의된 작업들을 순서대로 실행하여 실제 코드를 생성합니다.
사용법
/speckit.implement실행 과정
- 사전 조건 검증 (constitution, spec, plan, tasks 존재 확인)
- tasks.md 파싱
- 의존성 순서에 따라 작업 실행
- 병렬 실행 가능한 작업은 동시 처리
- 각 체크포인트에서 검증
💡 팁
✅ 권장 사항:
- 처음에는 AI의 실행을 지켜보며 검토
- 문제 발생 시 즉시 중단하고 수정
- 브라우저 콘솔 에러도 AI에게 공유
⚠️ 주의:
- AI가 로컬 CLI 명령어(npm, dotnet 등)를 실행함
- 필요한 도구가 설치되어 있는지 확인🔄 전체 워크플로우 요약
📁 생성되는 파일 구조
전체 워크플로우를 거친 후의 프로젝트 구조:
my-project/
├── .specify/
│ ├── memory/
│ │ └── constitution.md # 프로젝트 원칙
│ ├── specs/
│ │ └── 001-my-feature/
│ │ ├── spec.md # 요구사항 명세
│ │ ├── plan.md # 구현 계획
│ │ ├── tasks.md # 작업 목록
│ │ ├── data-model.md # 데이터 모델
│ │ ├── research.md # 기술 리서치
│ │ ├── quickstart.md # 빠른 시작 가이드
│ │ └── contracts/
│ │ └── api-spec.json # API 명세
│ ├── scripts/
│ └── templates/
├── src/ # 생성된 소스 코드
├── tests/ # 생성된 테스트
└── CLAUDE.md # AI 에이전트 설정✅ 명령어 요약
핵심 명령어
| 명령어 | 설명 | 언제 사용? |
|---|---|---|
/speckit.constitution | 프로젝트 원칙 정의 | 프로젝트 시작 시 |
/speckit.specify | 요구사항 정의 | 새 기능 시작 시 |
/speckit.plan | 기술 계획 수립 | 명세 확정 후 |
/speckit.tasks | 작업 분해 | 계획 확정 후 |
/speckit.implement | 구현 실행 | 작업 분해 후 |
보조 명령어
| 명령어 | 설명 |
|---|---|
/speckit.clarify | 불명확한 부분 질문 (specify 후, plan 전) |
/speckit.analyze | 아티팩트 간 일관성 검사 (tasks 후, implement 전) |
/speckit.checklist | 품질 체크리스트 생성 |
💡 실전 팁
1. 각 단계에서 검토하기
AI의 첫 결과물을 그대로 받아들이지 마세요.
"spec.md를 검토하고, 내가 언급하지 않은 요구사항이 있다면 알려줘"
"plan.md에서 과잉 엔지니어링된 부분이 있는지 확인해줘"2. 점진적으로 진행하기
한 번에 모든 것을 하려 하지 마세요.
❌ "전체 앱을 한 번에 만들어줘"
✅ "먼저 사용자 인증 기능부터 시작하자"3. Constitution 활용하기
AI가 이상한 결정을 내리면 Constitution을 참조하게 하세요.
"Constitution의 원칙에 따라 이 결정이 맞는지 검토해줘"4. 리서치 활용하기
빠르게 변하는 기술(예: Next.js, .NET Aspire)은 리서치를 요청하세요.
"Next.js 14의 App Router 관련 최신 패턴을 리서치해서 research.md에 추가해줘"⚠️ 주의사항
토큰 사용량
spec-kit은 많은 컨텍스트를 사용합니다. Anthropic Pro 계정의 경우 1시간 내에 한도에 도달할 수 있습니다.
대응 방법:
- 필요한 명세만 컨텍스트에 포함
- 작은 단위로 나눠서 작업
- 불필요한 재생성 피하기
단순한 작업에는 과한 도구
버그 수정이나 작은 변경에는 spec-kit이 과할 수 있습니다.
✅ spec-kit이 적합한 경우:
- 새로운 기능 개발
- 대규모 리팩토링
- 새 프로젝트 시작
❌ spec-kit이 과한 경우:
- 버그 수정
- 작은 UI 변경
- 단순 설정 변경🎯 사용해보며 느낀 점
💭 총평
Claude AI를 처음 사용할 때는 별도의 문서화 없이, 요구사항을 프롬프트로 전달하며 개발을 진행했습니다. 이후에는 PRD.md를 작성하고 tasks.md에서 Phase–Epic–Task 단위로 요구사항을 쪼개 보면서, 작업 범위와 우선순위를 더 명확히 정리할 수 있었습니다. 그다음으로 spec-kit이라는 툴킷을 접하면서 단계별 문서화를 훨씬 수월하게 진행할 수 있다는 점을 체감했습니다.
AI Agent 개발을 하며 가장 크게 느낀 점은 문서화의 중요성입니다. 초기 설계 단계에서 방향과 기준이 문서로 정리되어 있어야 AI가 맥락을 유지하며 일관된 방향으로 작업을 이어갈 수 있습니다. 반대로 문서화 없이 프롬프트만으로 개발을 계속하다 보면, 컨텍스트가 흔들리면서 AI가 방향을 잃는 상황을 종종 겪었습니다. 앞으로 AI Agent 개발자로서 문서화에 더 신경 쓰고, 설계와 기록을 습관화해야겠다고 느꼈습니다.
📚 참고 자료
