2026년 Claude Code에서 Spec Kit 설정하기: 프롬프트 대신 명세

2026년 5월, 바이브 코딩에는 무슨 일이 있었을까요?#

1년 뒤인 2026년 2월 4일, 그는 회고 스레드를 게시했습니다.

Sequoia Ascent 2026 강연에서 그는 이를 더 정확하게 표현했습니다. “바이브 코딩은 모두가 소프트웨어에서 할 수 있는 일을 늘려 하한선을 높입니다. 에이전틱 엔지니어링은 전문 개발의 품질 기준인 상한선을 지켜 줍니다.” 같은 무대에서 그는 업계의 어휘에 들어간 한마디도 남겼습니다. “바이브 코딩을 이유로 취약점을 도입해도 되는 건 아닙니다. 이전과 마찬가지로 소프트웨어에 대한 책임은 여전히 여러분에게 있습니다.”

두 가지 일이 동시에 일어났습니다. 2025년 9월, GitHub는 Spec Kit 도구를 공개했고, 8개월 만에 별 107,000개를 모았습니다. 2026년 2월, AWS는 “명세에서 비즈니스 로직의 95%를 생성해 80시간 이상을 절약했다”고 보고한 상세한 신약 발굴 사례 연구를 발표했습니다.

2026년 5월 말에는 영어권 정보 공간에서 공감대가 형성되었습니다. 작업 방식으로서 바이브 코딩은 초보자 수준이며, 그다음 단계는 Spec-Driven Development라는 것입니다. 이 가이드에서는 이 접근법을 설치하고 적용하는 방법을 설명합니다.

Spec Kit과 Spec-Driven Development란 무엇인가요?#

이 방법론의 핵심 아이디어는 GitHub 공식 문서의 한 문장에 담겨 있습니다.

실제로는 다음 4단계로 진행됩니다(Spec Kit은 여기에 0단계인 constitution을 하나 더 추가하며, 아래에서 설명합니다).

1. Specify - 원하는 것을 자연어로 명세합니다. 무엇을 할지(WHAT), 왜 하는지(WHY)를 적습니다. 어떻게 할지는 적지 않습니다.
2. Plan - 에이전트가 명세를 받아 기술 계획을 세웁니다. 사용할 기술, 아키텍처, 구성 요소를 정합니다.
3. Tasks - 에이전트가 계획을 구체적이고 검증 가능한 작업으로 나누고 의존성을 표시합니다.
4. Implement - 에이전트(또는 하위 에이전트)가 작업을 수행하고 코드를 작성합니다.

Implement 이후, 현재 Spec Kit에는 Converge라는 검증 단계가 있습니다. 에이전트는 완성된 코드를 명세, 계획, 작업과 대조한 다음 빠진 항목을 tasks.md에 추가합니다. Converge가 “Converged”라고 응답할 때까지 Implement와 Converge를 반복합니다.

각 단계는 저장소의 별도 markdown 파일에 담깁니다. Claude Code에서는 각 단계가 별도의 슬래시 명령입니다. /speckit-specify, /speckit-plan, /speckit-tasks, /speckit-implement을 사용하고, 점검에는 /speckit-converge를 사용합니다. Spec Kit 문서에서는 같은 명령을 점(.)으로 표기하지만(/speckit.specify), Claude Code에서는 Spec Kit이 이를 스킬로 설치하고 하이픈으로 호출합니다. 어느 단계에서든 문제가 생기면 markdown 파일을 수정한 뒤 다음 단계를 다시 실행하세요.

Spec Kit은 SDD를 구체적으로 구현한 도구입니다. 2026년 5월에는 이미 다양한 AI 에이전트와 30개가 넘는 통합을 지원했습니다. 하나의 저장소 안에서 Spec Kit은 Claude Code, Cursor, GitHub Copilot, Codex CLI, Windsurf, Qwen, Tabnine, Amazon Q, Gemini, Goose 등 십여 개의 다른 도구와 동일하게 작동합니다.

실행을 마치면 저장소에는 코드뿐 아니라 코드의 명세, 계획, 작업도 남습니다. 한 달 뒤 프로젝트로 돌아와 spec.md를 읽으면 무엇을 왜 했는지 이해할 수 있습니다. 이제 “바이브 코딩은 코드가 존재한다는 사실을 잊었다”는 상황이 아니라 프로젝트의 작업 메모리가 되는 것입니다.

코드를 쓰지 않는 바이브 코더에게 왜 필요할까요?#

Spec Kit은 수동으로 여러 채팅에서 진행하던 작업을 4개의 슬래시 명령으로 공식화합니다. 논리는 같습니다. “충분히 생각하기”와 “구현하기”를 분리해 서로 다른 컨텍스트 창에서 진행합니다. 각 단계는 이전 단계의 복잡성에 영향을 받지 않는 깨끗한 컨텍스트에서 시작합니다.

바이브 코더가 얻을 수 있는 구체적인 이점은 세 가지입니다.

• 예측 가능성. 에이전트에게 “이메일 확인 기능이 있는 가입 양식을 만들어 줘”라고 말하면, 에이전트는 세부 사항 10개를 스스로 추측하고 그중 세 가지는 여러분의 생각과 다르게 처리합니다. 불확실한 지점마다 User Stories, Acceptance Scenarios, [NEEDS CLARIFICATION] 표시가 있는 spec.md를 작성하면 추측할 것이 없습니다.
• 프로젝트 메모리. 한 달 후에는 채팅에서 에이전트와 논의했던 내용을 기억하지 못할 수 있습니다. 하지만 spec.md, plan.md, tasks.md는 코드 옆 specs/###-feature/ 폴더에 저장됩니다. 무엇을 했는지만 아니라 왜 했는지도 보여 줍니다.
• 확장성. 파일 1-2개를 다루는 기능에서는 차이가 거의 느껴지지 않습니다. 파일 20개와 데이터 엔터티 5개가 관련된 기능에서는 “4시간 뒤 모든 것을 다시 작성”하는 것과 “4시간 뒤 모든 작업이 메인 브랜치에 반영”되는 것의 차이가 생깁니다. AWS Kiro는 TargetID 프로젝트에서 명세를 바탕으로 비즈니스 로직을 95% 자동화했습니다.

바이브 코딩의 가장 큰 착각은 처음에는 더 빨라 보인다는 점입니다. 30분이면 프로토타입이 나옵니다. 하지만 일주일쯤 지나면 프로토타입이 깨지고, 버리는 편이 더 쉬워집니다. Spec-Driven Development는 초반에 시간이 조금 더 걸리지만(30분 대신 1시간), 일주일 뒤에도 같은 저장소에서 계속 작업할 수 있습니다.

Claude Code에 Spec Kit 설치하기 (4단계)#

1단계. uv 설치. 한 번만 설치하면 시스템에 계속 남습니다.

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

uv가 설치되었는지 확인합니다.

uv --version

2단계. Spec Kit 설치. 명령 하나면 됩니다.

uv tool install specify-cli --from git+https://github.com/github/spec-kit.git

확인합니다.

specify --version

3단계. 저장소 초기화. 프로젝트 폴더로 이동하거나 새 폴더를 만든 다음 실행합니다.

specify init --here --integration claude

--integration claude 플래그는 Claude Code를 바로 선택합니다. 이 플래그가 없으면 Spec Kit이 대화형 목록에서 에이전트를 선택하라고 묻고, 스크립트 유형도 물어볼 수 있습니다(macOS와 Linux에서는 sh를 선택하세요). 폴더가 비어 있지 않으면 Spec Kit이 기존 파일과 자신의 파일을 병합한다고 경고합니다. 먼저 작업을 커밋한 다음 --force 플래그를 붙여 명령을 다시 실행하세요.

그러면 저장소에 다음 항목이 생깁니다.

.specify/
  memory/
    constitution.md        # project rules, filled in by /speckit-constitution
  scripts/
  templates/
    spec-template.md
    plan-template.md
    tasks-template.md
.claude/
  skills/
    speckit-constitution/SKILL.md
    speckit-specify/SKILL.md
    speckit-clarify/SKILL.md
    speckit-plan/SKILL.md
    speckit-checklist/SKILL.md
    speckit-tasks/SKILL.md
    speckit-analyze/SKILL.md
    speckit-implement/SKILL.md
    speckit-converge/SKILL.md
    speckit-taskstoissues/SKILL.md

4단계. Claude Code를 열고 슬래시 명령을 확인합니다. 같은 폴더에서 다음을 실행합니다.

claude

세션에서 /speckit을 입력합니다. 추천 항목에 speckit-* 명령들이 보여야 합니다. 보이지 않으면 Claude Code를 다시 시작해 .claude/skills/를 다시 읽도록 합니다. 프로젝트 루트에 CLAUDE.md가 이미 있어도 Spec Kit은 그대로 둡니다. Spec Kit은 .specify/memory/constitution.md에서 CLAUDE.md와 함께 작동합니다.

Spec Kit은 Claude Code 없이도 작동하며 30개 이상의 에이전트를 지원하지만, 이 가이드는 Claude를 위한 설정을 다룹니다. 두 도구를 바로 설치하려면 CLAUDE.md 설정 가이드와 Claude Code의 Plan Mode 가이드를 참고하세요.

Spec Kit은 “에이전트 고용 계약”의 첫 번째 구성 요소입니다. 완전한 설정에는 세 가지가 모두 포함됩니다. AI 클론(Skills와 하위 에이전트 형태로 담은 여러분의 방법론), Second Brain(에이전트가 매번 돌아오는 business/ 구조), 그리고 컨텍스트 엔지니어링(Spec Kit, Plan Mode, /compact)입니다. AI가 환각을 일으키지 않게 하는 세 가지 기둥입니다.

첫 번째 명세 작성하기 (Specify)#

Claude Code에서 다음을 입력합니다.

/speckit-specify

그러면 에이전트가 기능 설명을 요청합니다. 이 단계에서는 기술 용어 없이 쉬운 말로 설명하세요.

I want a registration form in my app. The user enters an email
and password, receives a confirmation email, and after confirming
대시보드로 이동합니다. 인증은 48시간 후 만료됩니다. 그때도 이메일이
미확인이면 기한 후 5분 이내 계정을 삭제하고 확인된 계정은 삭제하지 마세요.

예시의 삭제 허용 지연은 48시간 기한 후 5분으로 명확히 했습니다. 실제 제품은 Plan 전에 이를 확인하세요. 정확한 48시간이면 더 강한 설계·시험이 필요합니다. 에이전트는 specs/001-registration/spec.md를 작성하며 다음과 같은 구조가 나옵니다.

# Feature Specification: User Registration

**Feature Branch**: `001-registration`
**Created**: 2026-05-31
**Status**: Draft
**Input**: User Description: "I want a registration form..."

## User Scenarios & Testing *(mandatory)*

### Primary User Story
As a new user, I want to register an account with email confirmation,
so that I can access the dashboard with a verified identity.

### Acceptance Scenarios
1. **Given** I am on the registration page,
   **When** I submit valid email and password,
   **Then** I receive a confirmation email within 1 minute.
2. **Given** I clicked the confirmation link within 48 hours,
   **When** I land on the dashboard,
   **Then** I see my email confirmed in profile.
3. **Given** 48시간 기한에도 미확인 상태,
   **When** 다음 5분 안에 정리 실행,
   **Then** 계정을 삭제하고 이메일 재등록 허용.
4. **Given** 48시간 직전이거나 이미 확인된 계정,
   **When** 정리 실행,
   **Then** 계정을 삭제하지 않음.

## Requirements *(mandatory)*

### Functional Requirements
- **FR-001**: System MUST accept registration via [NEEDS CLARIFICATION:
  email/password only, or also SSO/OAuth?]
- **FR-002**: System MUST send confirmation email within 60 seconds
- **FR-003**: 인증은 48시간에 만료되어야 함. 미확인 계정은 그 후
  5분 이내 삭제하고 확인 계정은 삭제하지 않아야 함
- **FR-004**: System MUST log all registration attempts for [NEEDS
  CLARIFICATION: how long do we retain logs - 30 days, 90 days, forever?]

### Key Entities
- User: email, password_hash, email_verified_at, created_at, deleted_at
- ConfirmationToken: token, user_id, expires_at, used_at

## Success Criteria *(mandatory)*
- **SC-001**: 95% of confirmation emails delivered within 60 seconds (p95)
- **SC-002**: 확인된 계정의 우발적 삭제 0
- **SC-004**: 48시간 전 삭제 없음. 시험 부하에서 모든 대상
  미확인 계정은 생성 후 48시간 5분까지 삭제됨
- **SC-003**: Registration completion rate > 60% (from form open to dashboard)

[NEEDS CLARIFICATION: ...] 표시를 유의해서 보세요. Spec Kit은 텍스트만으로 명확한 답을 얻지 못한 곳에 의도적으로 이 표시를 넣습니다. Plan 단계로 넘어가기 전에 spec.md에서 직접 답하거나 /speckit-clarify를 실행해야 합니다. 그러면 에이전트가 불분명한 부분을 하나씩 살펴보며 대화 중에 질문합니다.

Spec Kit에 내장된 /speckit-clarify 명령은 말로 하던 “질문해 줘”를 대신합니다. 효과는 같습니다. spec.md에 [NEEDS CLARIFICATION] 표시가 남아 있지 않을 때까지 Plan으로 넘어가지 않습니다.

spec.md에는 기술 스택이 들어가면 안 됩니다. React, Postgres, Prisma, Redis를 언급하지 마세요. 명세는 사용자와 비즈니스의 관점에서 시스템이 무엇을 하는지를 설명합니다. 기술 스택은 다음 단계에서 정합니다.

Plan 단계에서 Claude는 무엇을 하나요?#

spec.md가 준비되면 실행합니다.

/speckit-plan

원한다면 명령에 기술 힌트를 직접 전달할 수 있습니다.

/speckit-plan Next.js App Router, Prisma, PostgreSQL, Resend for email

Claude는 세 가지 자료를 읽습니다. spec.md, CLAUDE.md(또는 memory/constitution.md), 저장소의 기존 코드입니다. 출력은 대략 다음과 같은 구조의 plan.md입니다.

# Implementation Plan: User Registration

## Technical Context
- Framework: Next.js 14 App Router
- Database: PostgreSQL via Prisma
- Email: Resend (single transport)
- Validation: Zod schema in shared lib
- Auth: NextAuth.js with credentials provider

## Architecture Decisions

### 1. Token storage
Tokens stored in DB (table ConfirmationToken), not in JWT.
Reason: need server-side revoke on email re-register.

### 2. Email delivery
Async via cron `/api/cron/send-confirmation` triggered immediately
after registration. Retries handled by Resend.

### 3. Auto-delete cron
`/api/cron/cleanup-unconfirmed`를 매분 실행하세요. 다음 조건만 삭제합니다.
created_at <= NOW() - INTERVAL '48 hours' AND email_verified_at IS NULL.
예시는 최대 5분 지연을 허용합니다. 스케줄러 지연과 완료 시간을 검증하고
기한 초과는 일일 정리 성공이 아닌 실패로 보고하세요.

## Data Model
See data-model.md

## API Contracts
See contracts/
- POST /api/auth/register
- POST /api/auth/confirm
- GET /api/auth/resend-confirmation

## Implementation Phases
1. Database migration (Prisma schema + migration file)
2. API routes (3 endpoints)
3. UI: registration form + confirmation success page
4. Cron jobs (send + cleanup)
5. Email template
6. Integration tests

data-model.md에는 엔터티와 관계가 설명됩니다. contracts/에는 OpenAPI YAML이나 TypeScript 요청/응답 타입 형태의 API 계약 뼈대가 담깁니다. 코드는 아니며, 나중에 Claude가 실제 경로로 구현할 의도를 표현한 것입니다.

Plan 단계의 가장 큰 장점은 깨끗한 컨텍스트입니다. Claude는 명세와 구현을 동시에 기억하려고 하지 않습니다. 먼저 충분히 검토하고, 결정을 파일에 기록한 뒤 다음 단계로 넘어갑니다.

선택 사항으로 /speckit-analyze 명령도 있습니다. Tasks 단계 이후, Implement 전에 실행합니다. spec.md + plan.md + tasks.md 묶음의 모순을 검토하고, 계획과 작업이 명세의 모든 요구사항을 다루는지 확인합니다. 파일을 수정하지 않고 보고서만 작성합니다. 구현 전에 진행하는 정식 점검이라고 볼 수 있습니다.

작업을 세분화하는 방법 (Tasks)#

spec.md와 plan.md가 준비되면 실행합니다.

/speckit-tasks

Claude는 계획을 확장해 tasks.md를 작성합니다.

# Tasks: User Registration

## Phase 1: Database (no dependencies)
- [ ] T-001: Add User model to prisma/schema.prisma (parallel-safe)
- [ ] T-002: Add ConfirmationToken model to prisma/schema.prisma (after T-001)
- [ ] T-003: Generate migration `add-user-registration` (after T-002)

## Phase 2: API contracts (no dependencies)
- [ ] T-004: Create Zod schemas in shared/validation/auth.ts
- [ ] T-005: Define TypeScript types in shared/types/auth.ts (after T-004)

## Phase 3: Routes (depends on Phase 1+2)
- [ ] T-006: Implement POST /api/auth/register
- [ ] T-007: Implement POST /api/auth/confirm
- [ ] T-008: Implement GET /api/auth/resend-confirmation

## Phase 4: UI (parallel with Phase 3)
- [ ] T-009: Build /register page with form
- [ ] T-010: Build /register/confirm/[token] page
- [ ] T-011: Build /register/success page

## Phase 5: Cron + integration (depends on Phase 3+4)
- [ ] T-012: Cron /api/cron/send-confirmation
- [ ] T-013: Cron /api/cron/cleanup-unconfirmed
- [ ] T-014: Email template registration-confirmation.tsx
- [ ] T-015: 통합 테스트(Playwright). 48h 직전·정확한 48h,
  48h 5m까지 삭제, 지연 작업 실패, 확인 계정 보호 포함

## Notes
- T-001, T-004, T-009-T-011 are parallel-safe (different files)
- T-002 conflicts with T-001 (same file: schema.prisma) - run sequentially
- T-006 needs T-003 (migration applied) and T-005 (types)

parallel-safe와 after T-NNN 표시를 살펴보세요. 이는 이후 여러 단계를 병렬로 실행할 수 있게 해주는 의존성 그래프입니다. Spec Kit의 속도 향상은 전적으로 이 메커니즘에 달려 있습니다. 어떤 작업은 서로 다른 Claude Code 세션 5개에 동시에 맡길 수 있지만, 어떤 작업은 반드시 순차적으로 해야 합니다.

Spec Kit은 명령 하나로 이 작업을 자동으로, 바로 수행합니다.

선택 사항인 /speckit-taskstoissues 명령은 tasks.md를 읽어 목록에서 GitHub Issue를 만들며, 각 이슈에는 spec.md로 돌아가는 링크가 있습니다. 팀으로 일하거나 GitHub Projects에서 진행 상황을 추적하려면 유용합니다.

하위 에이전트로 구현하기 (Implement)#

/speckit-implement

Claude는 tasks.md의 첫 번째 작업부터 시작합니다. 각 작업은 관련 파일을 읽고, diff를 작성하고, 테스트를 실행하고, [x] 표시를 하는 짧은 주기를 거칩니다. 필요하면 하위 에이전트를 자동으로 호출합니다. 코드 검토용 에이전트, 린터 실행용 에이전트, 회귀 확인용 에이전트를 각각 따로 둡니다.

그리고 규칙에 관해서는 다음과 같이 말합니다.

Spec Kit에서는 이 주기가 정형화되어 있습니다. 진실의 원천인 spec.md, 기술적 결정을 담은 plan.md, 체크리스트인 tasks.md가 있습니다. Claude가 어느 단계에서든 방향을 벗어나면 명세로 돌아가 “이건 FR-003과 맞지 않으니 다시 해”라고 말하면 됩니다. “앞에서 논의한 내용을 기억해...”라고 길게 프롬프트를 작성할 필요가 없습니다. 전체 이력이 파일에 들어 있습니다.

Opus 4.8의 Dynamic Workflows를 연결했다면 Spec Kit을 완전 자동화 모드로 사용할 수 있습니다. /speckit-implement 명령 하나로 Claude가 작업을 병렬화하고, 결과를 통합하고, 점검합니다. 한 번에 실행할 수 있는 하위 에이전트 수는 1000개입니다. 대부분의 기능에는 10-30개면 충분합니다.

모든 [x] 상자를 표시하고 다음 섹션의 점검에서 “Converged”가 반환되면 PR을 검토하고(작업이 많다면 여러 PR을 검토하고) 병합합니다. spec.md, plan.md, tasks.md 산출물은 기능 문서로 저장소에 남습니다. 1년 뒤 코드에서 로직을 역으로 추적할 필요가 없습니다.

에이전트가 빠뜨린 것이 없는지 확인하기 (Converge)#

/speckit-converge

먼저 에이전트는 심각도별로 발견 사항을 요약한 다음 두 가지 결과 중 하나를 제시합니다. “Converged”는 빠진 항목이 없고 tasks.md가 바이트 단위로 그대로 유지되었으므로 검토 단계로 넘어가도 된다는 뜻입니다. “Tasks appended”는 빠진 항목을 찾아 tasks.md의 Convergence 섹션에 추가했다는 뜻이며, 에이전트가 그 수를 알려 줍니다.

Converge는 코드를 수정하거나 삭제하지 않습니다. tasks.md에 새 작업을 추가하는 것이 유일한 쓰기 작업입니다. 따라서 걱정 없이 실행해도 되지만, 먼저 /speckit-implement가 현재 tasks.md의 작업을 처리한 뒤에 실행해야 합니다. 다음 점검에서는 빠진 항목이 줄어듭니다.

Spec Kit은 CLAUDE.md와 Plan Mode와 어떻게 다른가요?#

5가지 특성으로 비교해 보겠습니다.

Spec Kit 용어로 이것은 .specify/memory/constitution.md입니다. 초기화할 때 Spec Kit은 기존 CLAUDE.md를 constitution의 기반으로 사용하거나 그 옆에 별도 파일을 만들 수 있습니다. 저는 보통 CLAUDE.md를 전역 “계약”(스택, 용어집, 배포 프로토콜)으로 두고, Spec Kit constitution에는 이 워크플로에만 적용되는 규칙을 넣습니다. 예를 들면 “모든 양식은 Zod로 검증하고 수동 검사는 하지 않는다”와 같은 규칙입니다.

Plan Mode와의 관계는 더 간단합니다. Plan Mode는 단일 세션에서 코드를 쓰기 전에 빠르게 계획하는 모드입니다. 버그 수정이나 함수 리팩터링처럼 작은 변경에 적합합니다. 큰 기능에서는 한 세션의 컨텍스트 창에 3000줄짜리 계획을 담기 어려워 Plan Mode가 적합하지 않습니다. 라이브 세션에서 제가 직접 설명한 내용입니다.

Spec Kit은 구체적인 컨텍스트 엔지니어링 도구입니다. “아키텍처 판”을 채팅에서 파일로 옮깁니다. Spec.md는 저장소에 남고 새 Claude 세션을 시작할 때마다 다시 읽힙니다. 같은 말을 반복할 필요가 없습니다.

대규모 프로젝트를 위한 구성은 다음과 같습니다.

1. CLAUDE.md - 스택, 용어집, 하지 말아야 할 일. 프로젝트 루트에 둡니다.
2. .specify/memory/constitution.md - Spec Kit을 위한 규칙. 이 워크플로에 적용됩니다.
3. specs/001-feature-A/spec.md, plan.md, tasks.md - 첫 번째 기능.
4. specs/002-feature-B/spec.md, plan.md, tasks.md - 두 번째 기능.
5. 일상 작업에는 준비된 작업을 위한 /speckit-implement이나 변경 전에 빠르게 재확인하는 /plan을 사용합니다.

실제 현장에서 어떤 사례가 효과를 내고 있나요?#

구체적인 사례는 다음과 같습니다.

• AWS Kiro - 신약 발굴 에이전트. 2026년 2월 18일 자 AWS Industries 블로그 게시물에서 팀은 TargetID 프로젝트를 설명합니다. 개발자 3명, 3주, 신약 발굴 에이전트. 게시물에 따르면 Kiro는 비즈니스 로직 코드의 95% 이상을 생성해 개발 시간을 80시간 넘게 절약했습니다. 또한 “Kiro가 작성한 README 문서로 약 8시간을 절약했다”, “프롬프트 수정 반복 주기가 40% 줄었다”고 합니다.
• Rackspace Technology. 같은 AWS 블로그에서 Rackspace는 “추정 작업량 52주를 단 3주 만에 완료”하고 “효율을 90% 높였다”고 보고했습니다. 이는 작은 기능이 아니라 기업 전체를 위한 프로젝트입니다.
• GitHub Spec Kit의 성장. 2026년 5월 31일 기준 저장소의 별은 107,000개였습니다. 3주 동안 별이 14,000개 늘었습니다.

독자에게 이는 이 접근법이 이론이 아니라는 뜻입니다. 진지한 팀들이 이미 프로덕션에서 사용하고 있습니다.

Spec Kit이 적합하지 않은 경우는 언제인가요?#

적합하지 않은 경우 1 - 작은 수정. 작업이 “변수 이름 바꾸기”, “문구의 오타 수정”, “로그 추가”라면 Specify → Plan → Tasks를 거치는 데 수정 자체보다 시간이 더 걸립니다. 작은 수정이라면 Plan Mode나 Claude Code에 바로 프롬프트를 입력하는 편이 빠릅니다.

적합하지 않은 경우 2 - 실시간 실험. 원하는 것이 아직 무엇인지 몰라 인터페이스를 “이것저것 만져 보거나”, 프로토타입을 빠르게 만들어 “먹히는지” 확인해야 한다면 명세는 쓸모가 없습니다. 가치가 있는 부분은 바로 즉흥적으로 시도하는 데 있습니다. 아이디어를 “가지고 놀 때”는 명세보다 바이브 코딩이 효과적입니다.

적합하지 않은 경우 3 - 복잡한 상태를 가진 레거시 코드. 강한 반론이 있습니다. “현실은 명세보다 빠르게 변합니다.” 구독 결제를 예로 들면, 팀이 결제 주기와 세금 규칙을 설명했지만 일주일 뒤 재무 부서가 유럽 VAT를 요청할 수 있습니다. 출시 전에 명세가 이미 구식이 될 수 있습니다. 비즈니스 로직이 빠르게 바뀌면 명세 유지가 부담이 됩니다.

또 다른 위험은 통제하고 있다는 착각입니다. 구조는 우아하지만 에이전트가 지시를 무시하는 경우가 많고, 반대로 템플릿을 지나치게 문자 그대로 따르기도 합니다. 그 결과 구조적으로는 올바르지만 특정 저장소에 맞지 않는 코드가 나올 수 있습니다. 명세가 에이전트의 해석이 의도와 일치한다는 것을 보장하지는 않습니다.

업계 분석가들은 워터폴 방식에 대해 경고했습니다. 코드를 쓰기 전에 긴 명세를 작성하는 길은 이미 200페이지짜리 요구사항이 쓰이던 시절 업계가 한 번 실패했던 방식입니다. 그 이후 엔지니어들은 이 접근법에 신중했고, 그럴 만한 이유가 있습니다.

어떻게 하면 될까요? 저는 기능의 크기와 명세 작성 시간을 비교하는 간단한 기준을 제안합니다. 구현에 2시간 미만이 걸릴 기능이라면 명세를 작성하지 마세요. Plan Mode가 더 빠릅니다. 일주일이 걸릴 기능이라면 Spec Kit을 꼭 사용하세요. 절약한 시간은 한 시간짜리 명세 작성 시간의 다섯 배를 보상할 것입니다. 2시간에서 일주일 사이라면 직접 판단하세요. 개인적으로는 저장소에 산출물이 남는 가치가 30분 절약보다 크기 때문에 반나절짜리 기능에도 명세를 작성합니다.

다음 단계: 프로젝트에 Spec Kit 통합하기#

앞으로 7일 동안 할 수 있는 구체적인 계획입니다.

• 1일 차. uv와 Spec Kit을 설치합니다(5-10분). Claude Code에 /speckit-* 명령이 나타났는지 확인합니다. 기존 프로젝트에 적용하려 하지 말고 새 프로젝트에서 시작하세요.
• 2일 차. 실제로 만들 예정인 기능을 고릅니다. 자유 형식 설명을 사용해 /speckit-specify를 실행합니다. spec.md를 열어 읽고 모든 [NEEDS CLARIFICATION]에 답합니다. Plan 단계로 서두르지 마세요.
• 3일 차. 기술 스택에 관한 힌트를 넣어 /speckit-plan을 실행합니다. 특히 Architecture Decisions 섹션을 살펴보며 plan.md를 읽습니다. 마음에 들지 않는 내용이 있으면 직접 수정합니다.
• 4-5일 차. /speckit-tasks를 실행하고, 이어서 명세·계획·작업 묶음을 재확인하는 /speckit-analyze를 실행한 다음 /speckit-implement를 실행합니다. Claude가 tasks.md에서 [x]를 표시하는 과정을 지켜보세요. 중간에 막힐 수도 있지만 정상입니다. spec.md로 돌아가 요구사항을 명확히 하고 구체적인 작업을 지정해 /speckit-implement를 다시 시작합니다. 작업이 끝나면 /speckit-converge를 실행하고 “Converged”라고 응답할 때까지 Implement와 Converge를 반복합니다.
• 6-7일 차. PR 또는 여러 PR을 검토하고 병합합니다. spec.md와 plan.md를 읽어 보세요. 앞으로 1년간 기능 문서로 사용할 수 있습니다.

다음 자료도 함께 읽어 보세요.

• 2026년에 CLAUDE.md 설정하기 - Spec Kit constitution의 기반입니다.
• Claude Code의 Plan Mode - 작은 작업에 쓸 수 있는 빠른 대안입니다.
• 2026년의 컨텍스트 엔지니어링 - Spec Kit이 왜 효과적인지 설명합니다.
• Skills, Subagents, MCP, 또는 Plugins - 워크플로에 Spec Kit과 함께 무엇을 추가할지 설명합니다.
• Claude Code의 Dynamic Workflows - Implement 단계에서 여러 하위 에이전트를 동시에 시작하는 방법을 설명합니다.

전체 컨텍스트 워크플로: AI 클론 + Second Brain + Context Engineering.

더 많은 자료는 Ailoot에서 볼 수 있습니다.