SpecKit - 대부분 개발자들이 원하지만 존재 자체를 잘 모르는 툴

개요

AI 코딩을 하면서 어려운 점은 프로그램이 제대로 작동하도록 하기 위해 자세한 사양 파일을 직접 작성해야 하고 세세한 컨트롤을 위해 작은 작업단위로 나누어 프롬프트를 매번 만들어야 했다.

이는 개발자들이 고전적인 개발방법론 중 BDD (Behavior-Driven Development) 나 TDD(Test-Driven Development) 등을 혼용하여 사용하고, 디버깅하면서 확인해야 하기 때문이다.

그런데 SDD (Spec-Driven Development) 관점에서 개발할 내용을 정리해 주면 빠르게 해당 프로그램을 만들어 줄 수 있는 Framework이 바로 SpecKit 이다. 이는 AWS의 Kiro도 SDD 방법론을 기본으로 하고 있다. 점점 요구 사양이 다양해지고 복잡해 지는 것을 대응하는 측면에서 상세 코드 보다는 요구 사항에 따른 코드를 생성해 준다는 개념에서 기존 개발자의 방법과는 많이 상이하지만 AI의 발전으로 이젠 이 부분이 쉽게 가능해 지는 것 같다.

주요 개발 방법론 비교

구분 (Dimension)	TDD (Test-Driven Development)	BDD (Behavior-Driven Development)	SDD (Spec-Driven Development)
핵심 철학	실패하는 테스트를 먼저 작성하고, 이를 통과하는 코드를 구현한 후 리팩토링한다.	이해관계자 모두가 이해할 수 있는 자연어로 시스템의 '행위'를 정의하고 이를 기반으로 개발을 진행한다.	코드가 아닌, 시스템의 '명세(Specification)'를 개발의 중심에 두고, 명세를 통해 코드를 생성하고 검증한다.
주요 관점	개발자 관점 (내부 구현)	사용자/이해관계자 관점 (외부 행위)	시스템/제품 관점 (전체 요구사항 및 아키텍처)
개발 시작점	단위 테스트 코드 (Unit Test Code)	사용자 스토리/시나리오 (User Story/Scenario)	제품 요구사항 명세서 (PRD), 기술 명세서 (Spec)
주요 산출물	단위 테스트 코드, 프로덕션 코드	행위 시나리오 (예: Gherkin feature 파일), 인수 테스트 코드	실행 가능한 명세서 (Executable Spec), 기술 계획서, 작업 목록, 생성된 코드
주요 참여자	개발자	개발자, QA, 기획자, 비즈니스 분석가	제품 관리자, 아키텍트, 개발자, AI 코딩 에이전트
검증 단위	코드 단위 (함수, 클래스)	기능/피처 단위 (Feature Behavior)	시스템 전체 또는 주요 기능의 명세
언어/형식	프로그래밍 언어 (예: JUnit, RSpec)	구조화된 자연어 (예: Gherkin Given-When-Then)	정형화된 문서 (Markdown), API 정의 언어 (OpenAPI), 데이터 스키마 (JSON Schema)
주요 장점	높은 코드 커버리지, 견고한 단위 모듈, 안전한 리팩토링	팀원 간의 명확한 소통, 사용자 요구사항 충족, 살아있는 문서	요구사항과 구현의 불일치 최소화, 개발 프로세스 자동화, 단일 진실 공급원(SSoT) 확보, 병렬 개발 촉진
주요 단점	개발 초기 속도 저하, 테스트 코드 유지보수 비용, 전체 시스템 동작 검증의 어려움	테스트 작성의 복잡성 증가, 잘못된 시나리오 정의 시 개발 방향 오류 가능성	초기 명세 작성에 많은 시간과 노력 필요, 요구사항 변경 시 명세 업데이트 부담, 과도한 명세화(Over-specification) 위험
통합 관계	BDD의 구현 단계에서 각 행위를 만족시키기 위한 하위 단위 테스트에 활용될 수 있다.	SDD의 명세로부터 도출된 사용자 스토리를 BDD 시나리오로 구체화할 수 있다.	최상위 프레임워크로서 BDD와 TDD를 포괄하는 워크플로우를 구성할 수 있다. 명세(SDD)로부터 행위(BDD)를 정의하고, 행위를 만족시키기 위해 테스트(TDD)를 작성한다.

Spec Kit이란?

Spec Kit은 GitHub에서 공식적으로 제작·관리하는 오픈소스 AI 프레임워크이다. 기존 커뮤니티가 만든 도구들과 달리, 높은 완성도와 엄격한 관리가 특징이다. 스펙 기반 개발(명확한 요구사항 작성 후 자동화된 구현)을 AI와 결합해, 반복 작업을 확 줄이고 효율적인 개발 환경을 제공한다. GitHub의 개발 철학과 노하우가 스며들어 있어, 실전에서 빠르게 적용할 수 있다는 장점이 크다.

사용법이 간단하다! 명령어 세 가지면 끝

Spec Kit은 세 단계 커맨드로 프로젝트를 셋업한다.

• 스페시파이(specify): 어떤 기능을 만들지 자연어로 입력(what, why)
• 플랜(plan): 기술 스택/아키텍처 등 상세 계획 작성
• 테스크(tasks): 단계별 작업 목록을 자동 생성, 체크박스로 관리

복잡한 명령어나 설치 과정 없이 손쉽게 시작할 수 있다. 예를 들어 "홈페이지와 상세페이지가 있는 한국어 블로그 사이트를 만들겠다"라고 입력만 하면, 알아서 폴더와 파일을 구성해 준다.

---

Spec-Driven Development 워크플로우 재정리 (사용방법)

🎯 핵심 개념

Spec-Driven Development는 전통적인 개발 방식을 뒤집는 접근법이다. 코드 중심이 아닌 사양(Specification) 중심으로 개발하며, 사양이 직접 실행 가능한 구현체를 생성한다.

📊 워크플로우 단계

1단계: 프로젝트 초기화

# 기본 프로젝트 생성
specify init <프로젝트명> --ai <AI도구>

# 현재 디렉토리에서 초기화
specify init --here --ai claude

지원 AI 도구:

• Claude Code
• GitHub Copilot
• Gemini CLI
• Cursor

2단계: 사양 정의 (/specify)

• 목적: "무엇을" 만들지와 "왜" 필요한지 정의
• 특징: 기술 스택은 언급하지 않음
• 결과물: specs/001-기능명/spec.md 파일 생성

/specify 사진을 앨범으로 정리할 수 있는 애플리케이션 구축. 
앨범은 날짜별로 그룹화되고 드래그앤드롭으로 재정리 가능. 
앨범 내 사진은 타일 인터페이스로 미리보기.

3단계: 기술 계획 수립 (/plan)

• 목적: 기술 스택과 아키텍처 선택
• 결과물:
  • plan.md - 구현 계획
  • data-model.md - 데이터 모델
  • api-spec.json - API 명세
  • research.md - 기술 조사
  • quickstart.md - 시작 가이드

/plan Vite 사용, 최소한의 라이브러리만 활용. 
바닐라 HTML, CSS, JavaScript 위주. 
로컬 SQLite 데이터베이스에 메타데이터 저장.

4단계: 작업 목록 생성 (/tasks)

• 목적: 실행 가능한 작업 목록 생성
• 결과물: 구체적인 구현 태스크 리스트

5단계: 구현 및 반복

• AI 에이전트가 실제 코드 구현
• 빌드 오류 해결
• 런타임 오류 수정
• 기능 검증 및 개선

🔄 개발 단계별 접근법

단계 포커스 주요 활동

0-to-1 개발 (Greenfield)	처음부터 생성	초기 사양 작성<br>• 기술 스택 선택<br>• 프로토타입 구축
창의적 탐색	병렬 구현	여러 기술 스택 실험<br>• 대안 탐색<br>• 최적 솔루션 선택
반복적 개선 (Brownfield)	기존 코드 현대화	기능 추가/수정<br>• 리팩토링<br>• 업그레이드

📁 프로젝트 구조

프로젝트/
├── memory/
│   ├── constitution.md          # 프로젝트 원칙
│   └── constitution_update_checklist.md
├── scripts/
│   ├── create-new-feature.sh   # 새 기능 생성
│   ├── setup-plan.sh           # 계획 설정
│   └── update-claude-md.sh     # 문서 업데이트
├── specs/
│   └── 001-기능명/
│       ├── spec.md             # 사양 문서
│       ├── plan.md             # 구현 계획
│       ├── data-model.md       # 데이터 모델
│       ├── contracts/          # API 계약
│       └── research.md         # 기술 조사
└── templates/                  # 템플릿 파일들

✅ 모범 사례

1. 사양 작성 시

• 가능한 한 명확하고 구체적으로 작성
• "무엇"과 "왜"에 집중 (기술적 세부사항 X)
• 사용자 관점에서 기능 설명

2. 계획 수립 시

• 조직의 제약사항 고려 (클라우드, 기술 스택)
• 과도한 엔지니어링 방지
• Constitution 원칙 준수

3. 구현 시

• 점진적 개선 접근
• 체크리스트 활용한 검증
• 병렬 연구 작업 활용

4. 반복 개선

• 리뷰 & 승인 체크리스트 검증
• 피드백 즉시 반영
• 지속적인 문서 업데이트

오류가 발생했을 때는 특별한 명령어 없이 그냥 AI 에이전트에게 직접 오류를 보고하고 수정을 요청하면 된다.

📌 명령어별 사용 시점

/specify - 새로운 기능 정의할 때만

# ❌ 잘못된 사용
/specify 드래그앤드롭 오류를 수정해줘

# ✅ 올바른 사용
/specify 사용자 프로필 관리 기능을 추가해줘. 
프로필 사진 업로드와 개인정보 수정이 가능해야 해.

/plan - 기술 계획 수립할 때만

# ❌ 잘못된 사용
/plan API 오류를 고쳐줘

# ✅ 올바른 사용
/plan React에서 Next.js로 마이그레이션하자. 
SSR을 활용하고 Vercel에 배포할 예정이야.

/tasks - 작업 목록 생성할 때만

# ✅ 새로운 기능의 구현 작업 나열
/tasks 프로필 기능 구현을 위한 작업 목록을 만들어줘

🔧 오류 수정 요청 방법

직접 요청 (명령어 없이)

# ✅ 빌드 오류
"npm run build 실행 시 다음 오류 발생:
Module not found: Can't resolve '@/components/TaskCard'
이 문제 해결해줘"

# ✅ 런타임 오류
"드래그앤드롭할 때 카드가 사라져. 
브라우저 콘솔에 이런 오류가 나와:
Uncaught TypeError: Cannot read property 'dragEnd' of undefined
수정해줘"

# ✅ 로직 오류
"댓글을 수정하면 다른 사용자 이름으로 저장돼. 
현재 로그인한 사용자 정보가 제대로 전달되지 않는 것 같아. 
확인하고 수정해줘"

# ✅ UI/UX 문제
"칸반 보드의 칼럼이 화면 밖으로 넘어가서 
가로 스크롤이 생겨. 반응형으로 수정해줘"

💡 효율적인 오류 수정 워크플로우

1. 오류 발견
   "태스크 삭제 버튼이 작동하지 않아"

2. 원인 분석 요청
   "왜 작동하지 않는지 코드를 확인해봐"

3. 수정 요청
   "문제를 수정해줘"

4. 테스트 요청
   "수정한 후 제대로 작동하는지 테스트해봐"

5. 관련 기능 점검
   "삭제 기능과 연관된 다른 부분도 확인해줘"

🎯 요약

상황 사용 방법 예시

새 기능 추가	/specify 사용	/specify 알림 기능 추가
기술 스택 변경	/plan 사용	/plan PostgreSQL을 MySQL로 변경
오류 수정	직접 요청	"로그인 오류 수정해줘"
버그 수정	직접 요청	"이 버그 고쳐줘: [오류 내용]"
코드 개선	직접 요청	"이 함수를 리팩토링해줘"
성능 최적화	직접 요청	"페이지 로딩 속도를 개선해줘"

📝 실제 대화 예시

You: "사용자가 자기 댓글이 아닌데도 수정 버튼이 보여. 
     현재 로그인한 사용자 ID와 댓글 작성자 ID를 
     비교하는 로직을 확인하고 수정해줘"

AI: "네, 확인해보니 TaskCard.js의 85번 줄에서 
    사용자 ID 비교 로직에 문제가 있네요. 
    수정하겠습니다... [코드 수정]"

You: "수정 후 테스트해봐"

AI: "테스트 완료했습니다. 이제 본인 댓글만 
    수정 버튼이 표시됩니다."

 

핵심: /specify, /plan, /tasks는 새로운 것을 만들 때만 사용하고, 기존 코드의 오류나 버그 수정은 평범한 대화로 요청하면 된다.

---

Reference

• https://youtu.be/em3vIT9aUsg
• SpecKit : https://github.com/github/spec-kit

GitHub - github/spec-kit: 💫 Toolkit to help you get started with Spec-Driven Development