AI 스터디 · 7주차

Spec Kit
명세가 코드를 만든다 — 스펙 주도 개발(SDD)

"떠오르는 대로 프롬프트"의 답답함을 구조로 푸는 방법 · GitHub Spec Kit으로 Claude Code 활용하기

왜 이 주제? 오늘 바로 설치해서 써볼 수 있는 구체적 도구. 에이전트를 "어떻게 굴릴까"가 아니라 "무엇을 만들지를 어떻게 고정할까"에 답하는 보완재.

무엇

specify CLI + /speckit.* 슬래시 커맨드 (GitHub 오픈소스)

어디서

Claude Code · Copilot · Gemini CLI · Cursor · Codex 등 여러 에이전트

1 / 10 문제 제기

"AI한테 시켰는데 왜 자꾸 딴 걸 만들지?"

즉흥 프롬프트 → AI가 추측 → 다시 고치기 무한 반복

😵 즉흥 프롬프트

  • 의도가 머릿속에만 있음 → AI가 추측
  • 맥락이 대화에 흩어짐, 재현 불가
  • 코드부터 나오고 설계는 사후에
  • "대충 이런 느낌으로…" → 매번 다른 결과

🧭 스펙 주도

  • 의도를 문서(스펙)로 먼저 고정
  • 스펙 → 계획 → 작업 → 구현, 단계마다 검증
  • 재현성·품질 ↑
  • "코드가 명세를 섬긴다"
근거: METR 무작위대조연구(2025) — 숙련 개발자가 초기-2025 AI 도구를 쓸 때 작업 시간이 오히려 19% 더 길었다. "빨리 짜는 것"이 아니라 "의도를 명확히 하는 것"이 진짜 병목이라는 방증.

출처: METR — Early-2025 AI & experienced OSS dev productivity (arXiv:2507.09089)

2 / 10 개념

SDD = Spec-Driven Development

"명세서가 단순한 문서가 아니라, 코드를 생성하는 실행 가능한 계약이 된다."

전통/즉흥 vs SDD

전통 / 즉흥 프롬프트SDD
출발점코드 / 즉흥 프롬프트명세(spec) 문서
문서의 역할코드를 설명 (사후)코드를 생성 (사전)
진행한 번에 쭉단계별 체크포인트, 검증 후 다음
AI의 역할추측해서 채움명확한 입력으로 실행
핵심 한 줄: "현재 단계가 완전히 검증되기 전엔 다음 단계로 넘어가지 않는다."

출처: GitHub Blog — Spec-driven development with AI

3 / 10 도구 소개

GitHub Spec Kit

SDD를 실제로 굴리는 오픈소스 툴킷. GitHub가 공개.

무엇인가

  • specify CLI + 슬래시 커맨드 세트
  • 프로젝트에 스펙/플랜/태스크 골격을 부트스트랩
  • 에이전트 위에 얹는 워크플로우 프레임워크

어디서 도나

  • 여러 AI 코딩 에이전트 지원
  • Claude Code · Copilot · Gemini CLI · Cursor · Codex …
  • 에이전트 대화창에서 /speckit.* 슬래시 커맨드로 실행
연결: "에이전트를 어떻게 굴릴까"가 하네스/워크플로우 도구였다면, Spec Kit은 "무엇을 만들지를 어떻게 고정할까"에 답한다.

출처: github/spec-kit — 공식 레포 README

4 / 10 핵심 다이어그램

4(+1)단계 워크플로우

이 한 장이 발표의 척추. 각 단계는 산출물(문서)을 만들고, 검증 후 다음으로.

0 · 원칙/speckit.constitution프로젝트 헌법·규칙
→
① 무엇을/speckit.specify요구사항·유저스토리
→ spec.md
→
② 어떻게/speckit.plan기술스택·설계
→ plan.md
③ 쪼개기/speckit.tasks실행 가능한 작업목록
→ tasks.md
→
④ 만들기/speckit.implement작업을 실제 코드로
→ 구현
결과동작하는 기능+ 추적가능한 문서
외울 것: 의도(Spec) → 설계(Plan) → 검증가능 과업(Tasks) → 구현(Implement). 구조화된 입력 → 추측 ↓, 재현성·품질 ↑.

출처: github/spec-kit — README "The workflow"

5 / 10 실습 · 설치

설치 & 초기화

1) CLI 설치 (uv 필요, Python 3.11+)

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

2) 프로젝트 초기화 (Claude Code 연동)

specify init my-project --ai claude
cd my-project

3) 생성되는 골격

.specify/
  ├── memory/constitution.md   # 프로젝트 원칙
  ├── scripts/                 # 단계 실행 스크립트
  └── templates/               # 스펙/플랜/태스크 템플릿
specs/
  └── 001-feature/
      ├── spec.md   ├── plan.md   └── tasks.md
📷 스크린샷 자리
터미널에서 specify init 실행 → 생성된 디렉터리 트리
(직접 캡처해 img/sk/에 넣고 이 자리를 <img>로 교체)

출처: github/spec-kit — README "Installation / Quickstart"

6 / 10 실습 · 단계 0

① /speckit.constitution — 프로젝트 헌법

AI가 모든 단계에서 지켜야 할 원칙을 먼저 못박는다. (CLAUDE.md 정신의 SDD 버전)

여기서 정하는 것

  • 코딩 규칙·아키텍처 원칙
  • 테스트/품질 기준
  • 쓰면 안 되는 것, 지켜야 할 것

왜 먼저 하나

  • 이후 spec/plan/tasks가 이 헌법을 상속
  • "매번 같은 잔소리" 반복을 제거
📷 스크린샷 자리
Claude Code 대화창에 /speckit.constitution 입력 → 생성된 constitution.md 일부

출처: github/spec-kit — /speckit.constitution 커맨드

7 / 10 실습 · 단계 ①②

/speckit.specify → /speckit.plan

② specify — "무엇을" (한국어로 설명해도 OK)

예: "중고차 상세 페이지에 찜하기 기능을 추가한다. 로그인 사용자만, 찜 목록에서 해제 가능…"

→ AI가 요구사항·유저스토리·엣지케이스를 spec.md로 구조화

③ plan — "어떻게" (기술 결정)

스택·데이터모델·API 계약을 plan.md, data-model.md, contracts/로

📷 spec.md
유저스토리 + 수용기준 부분
📷 plan.md
기술스택 + 데이터모델 부분
데모 포인트: "한국어 한 문단 → 구조화된 스펙 문서" 변환을 보여주면 비개발자도 즉시 이해.

출처: github/spec-kit — /speckit.specify, /speckit.plan

8 / 10 실습 · 단계 ③④

/speckit.tasks → /speckit.implement

④ tasks — 검증 가능한 작업으로 쪼개기

plan을 체크 가능한 할일 목록 tasks.md로. 각 작업은 독립적으로 완료/검증 가능.

⑤ implement — 작업을 실제 코드로

AI가 tasks를 순서대로 구현. 사람은 단계별 검토 포인트에서 확인.

📷 녹화/스크린샷 자리
/speckit.tasks → tasks.md 생성 → /speckit.implement 실행 → 코드 변경 diff
솔직한 한계: 스펙이 부실하면 결과도 부실. AI 공동작성 코드는 리뷰를 없애는 게 아니라 리뷰 지점을 명확히 하는 것 — SDD의 단계별 검증이 바로 그 리뷰 지점을 만든다.

출처: github/spec-kit — /speckit.tasks, /speckit.implement

9 / 10 실전 팁

잘 쓴 스펙 vs 못 쓴 스펙

❌ 못 쓴 스펙

  • "찜 기능 만들어줘" (한 줄, 모호)
  • 수용 기준 없음 → AI가 추측
  • 엣지케이스·실패 케이스 누락
  • 기술 결정을 spec 단계에 섞음

✅ 잘 쓴 스펙

  • 유저스토리 + 명확한 수용 기준
  • "무엇(spec)"과 "어떻게(plan)" 분리
  • 비로그인·중복찜 등 경계 조건 명시
  • 한 기능 = 한 spec 폴더 (작게 쪼갬)
팁: 위 두 입력으로 실제 생성된 spec.md를 나란히 스크린샷 → 차이를 눈으로 보여주기.

출처: github/spec-kit · Microsoft Dev — Diving into Spec Kit

10 / 10 정리

정리 · 우리 스터디에 적용

코드부터 쓰지 말고, 의도부터 고정하라.

스터디 액션: 각자 본인 프로젝트의 작은 기능 1개를 Spec Kit으로 spec→implement까지 돌려보고 다음 모임에서 spec.md 공유하기.

출처: github/spec-kit — 종합

감사합니다 🙏

질문 / 같이 해볼 사람?

참고 자료

1 / 11← / → 넘기기 · a: 스크롤 · n: 노트