Spec Kit - 개요

#1 명세 주도 개발(Spec-Driven Development)

Specification-Driven Development

= Spec-Driven Development

= SDD

= 명세 주도 개발

= 명세 기반 개발

 

#1-1 명세란 무엇인가

다시 말해, 영미권 개발자들이 말하는 Spec이란 무엇인가?

명세 = Spec = 대상이 충족해야 할 것을 정의한 문서 ⊃ API 규칙, 요구사항(requirements), 인터페이스의 제약, 함수의 기능, ...

'충족'이라 함은, WhatㆍWhyㆍHow를 포괄한다. 다시 말해, 무엇을ㆍ왜ㆍ어떻게 충족할지를 정의한 문서가 바로 '명세'다.

 

#1-2 명세 주도 개발의 올바른 정의

'명세'의 정의를 알았으니, 이제 '명세 주도 개발'의 개념도 누워서 떡 먹듯 습득한 것일까?

구현 전에 Spec(의도, 제약, ...)을 명시적 산출물로 만들고, 이 산출물에 의해 이후의 결과가 도출ㆍ통제되도록 만드는 개발 방식

'명세'의 개념만 익히고 '명세 주도 개발'이라는 단어를 보면, 자칫 "Spec을 꼼꼼하게 미리 기록(Spec-first)해 놓자는 개발론이구나"라고 생각하기 십상이다. "잠깐... Spec-first는 새로운 패러다임이 아니라, 원래부터 개발에서의 진리ㆍ정석이잖아?" 이 지점에서 혼돈이 생긴다.

Spec-first가 아니라 Spec-driven이다. 모든 Spec-driven은 Spec-first지만, 반대로 모든 Spec-first가 Spec-driven인 것은 아니다. 코드가 아니라 명세가 원본이고, 코드는 그 명세의 구현물이라는 관점으로 다시 보아야 한다. 구현의 결과가 잘못되었을 때, 코드보다 명세를 기준으로 판단하게끔 만드는 게 명세 주도 개발이다. 명세가 구현을 안내하는 것이 아니라, (에이전틱 프로그래밍 덕에) 구현을 직접 생성하기 때문이다.

 

#2 Spec Kit

#2-1 What

Spec Kit = AI 코딩 에이전트가 요구사항 정리, 기술 설계, 작업 분해, 구현 순서로 개발하도록 만든 작업 절차와 지침의 묶음 (Spec의 묶음)

(사실 당연한 것이지만) 짚고 넘어가야 하는 게 있다. Spec Kit은 명세 주도 개발이지만, 반대로 명세 주도 개발이 Spec Kit은 아니라는 것이다. 마치, Git이 버전 관리 그 자체는 아니며 버전 관리를 구현한 도구인 것과 비슷한 관계다.

• 명세 주도 개발 그 자체가 아님
• GPT, Claude, Gemini 같은 언어 모델이 아님
• Claude Code, Codex, GitHub Copilot 같은 AI 코딩 에이전트도 아님
• JavaScript, Kotlin 같은 언어도 아니고, React나 Spring 같은 코드 라이브러리도 아님

 

막말로, '문서 덩어리'라고 해도 큰 과장은 아니다. '프로그램'이라고는 부를 수 있겠다. 왜냐하면 '문서 덩어리' 파일 생성을 해주는 Specify CLI라는 전용 프로그램까지 포함해서 Spec Kit이라고 부르기 때문이다.

 

#2-2 How

설치

# PowerShell에 전부 입력
winget install --id=astral-sh.uv -e # uv
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@v0.12.17 # Specify CLI

uv는 Specify CLI 설치를 위해 필요하다. 2026년 7월 17일 기준 최신 버전은 v0.12.17이며, 새 버전이 나온다면 그 버전을 사용하도록 하자 (새 버전 확인하기: Spec Kit의 Release 페이지).

 

사용
Spec Kit은 앞서 말한 대로 문서 덩어리에 불과하다. 이제 Specify CLI로 Spec Kit을 불러오기만 하면 된다.

# PowerShell에 셋 중 하나만 입력
specify init 프로젝트-루트-폴더-경로 --integration claude
specify init . --integration claude # 프로젝트 루트 폴더에서 PowerShell을 실행시켰을 때 비교적 간단한 명령어를 쓸 수 있다.
specify init 프로젝트-루트-폴더-경로 --integration codex # Claude Code 대신 Codex를 쓴다면

 

#3 분석 - 디렉토리

# .specify/memory/...

프로젝트가 반드시 따라야 하는 원칙을 담는다. 헌법 같은 개념이라고 보면 된다.

 

#3-1 .specify/templates/...

plan-template.md
spec-template.md
tasks-template.md
checklist-template.md
...

Spec을 담을 문서들의 템플릿이다. Spec Kit을 만든 제작자가 보기에, 가장 범용적이며 깔끔한 목차만 있는 템플릿일 테다. AI 에이전트는 이 템플릿에 기반해 실제 프로젝트의 명세를 만들어 나갈 것이다.

 

#3-2 .claude/commands/...

AI에게 내릴 수 있는 명령 목록이 들어있다. Skill이랑 비슷하다. Spec Kit 측에서 처음 만들어준 명령어 목록을 그대로 사용하면 되고, 우리가 추가로 커스텀해서 사용할 일은 거의 없다고 보면 된다. 사용할 AI 에이전트가 Claude Code가 아니라 Codex라면, .codex/prompts/... 디렉토리가 대신한다.

 

#3-3 .specify/scripts/...

.claude/commands/...에서 수행할 명령을 잘 수행하기 위해, 서브 명령을 정의해 놓은 곳이다. Tool에 가까운 역할이다. 가령 AI 에이전트가 사용자가 내린 어떤 명령을 수행하면서, 참고할 파일 위치나 특정 커밋이 담긴 브랜치 이름 등을 제멋대로 판단하지 않도록 강제해 주는 식이다. 이 디렉토리는 .claude/commands/... 보다 더더욱 우리가 건들 일이 없다.

 

#3-4 specs/...

specs/001-user-login/...
specs/002-database-migration/...
specs/003-cache-refactoring/...
specs/004-security-hardening/...
specs/005-api-rate-limit/...
...

Spec Kit의 꽃이라고 할 수 있다. 이름 그대로 명세(Spec)를 담는다. 명세는 feature 별로 구분된다. Spec Kit에서 feature는 작업 단위, 한 단위의 개발로 변경할 범위 따위를 의미하는 추상적 용어다. 어디까지가 feature인가가 정해진 것은 아니다. 다만 아주 자잘한 수정은 (실무적으로) feature라 할 수 없다. '본격적인 구현에 앞서 명세를 해야 할 정도의 범위' 이상이어야 feature라 할 수 있을 것이다.

 

#3-5 specs/example_feature_name/...

spec.md
plan.md
tasks.md
...

여러 명세 파일이 담기지만 가장 핵심이 되는 3가지는 spec.mdㆍplan.mdㆍtasks.md다.

• spec.md
  • 이 작업 단위에서 무엇을 만족해야 하는지 명시한다.
  • "사용자는 이메일과 비밀번호로 로그인할 수 있다.", "잘못된 비밀번호를 입력하면 오류 메시지가 표시된다.", "로그인에 성공하면 대시보드로 이동한다.", ...
• plan.md
  • spec.md를 진행하기 위한 구조, 구현 방식, 도구(기술)를 명시한다.
  • "Spring Boot와 Spring Security를 사용한다.", "사용자 정보는 PostgreSQL에 저장한다.", "JWT 기반 인증을 사용한다.", "통합 테스트는 Testcontainers로 작성한다.", ...
• tasks.md
  • 전체 프로그래밍을, 진행 순서를 지켜 잘게 분해한다.
  • [ ] T001 User 엔티티 추가
    [ ] T002 UserRepository 구현
    [ ] T003 로그인 요청 DTO 작성
    [ ] T004 인증 서비스 구현
    [ ] T005 로그인 API 통합 테스트 작성
    ...

 

#3-6 src/...

domain/User.kt
domain/Category.kt
application/LoginService.kt
infrastructure/JwtTokenProvider.kt
presentation/LoginController.kt
...

프로그램의 소스 코드. task.md의 결과로 만들어진다.

 

#3-7 tests/...

소스 코드를 검증하는 테스트 파일들을 담는다.

 

#4 분석 - 명령어

#4-1 /speckit.constitution

이 명령어가 주로 다루는 파일:
.specify/memory/constitution.md
.specify/templates/*.md

프로젝트 전체가 지켜야 할 개발 원칙을 생성ㆍ수정한다. 프로그램의 핵심 구조(아키텍처), 보안 같은 공통 규칙까지 포함한다. Constitution은 프로그램의 헌법으로 가장 중요한 원칙이다. 따라서 /speckit.constitution 명령으로 원칙을 업데이트했을 때, (AI 에이전트가 변경이 필요하다고 판단한 경우) 명세 템플릿까지도 수정될 수 있다.

 

#4-2 /speckit.specify

이 명령어가 주로 다루는 파일:
specs/example_feature_name/spec.md

새 작업 단위를 신설한다. spec.md에는 기능명, 관련 브랜치, 생성일, 상태, 최초 요청 내용, 기능 요구사항 등의 많은 내용이 들어간다.

 

#4-3 /speckit.clarify

이 명령어가 주로 다루는 파일:
specs/example_feature_name/spec.md

이미 존재하는 작업 단위를 업데이트한다. 모호(underspecified)한 부분을 명료(Clarify)하게 만든다는 뜻이다. /speckit.plan 수행 전 spec.md를 더 다듬기 위해 사용한다.

 

#4-4 /speckit.plan

이 명령어가 주로 다루는 파일:
specs/example_feature_name/plan.md (최종 구조, 구현 방식, 기술 스택)
specs/example_feature_name/research.md (plan.md 속 기술 스택의 선택 이유, 선택을 고려했었던 후보들의 탈락 이유)
specs/example_feature_name/data-model.md (Entity, Field, ...)
specs/example_feature_name/quickstart.md (구현 절차를 추상적으로만 나열)
specs/example_feature_name/contracts/* (프로그램 외부와의 소통을 위한 규칙)

spec.md의 요구사항을 어떤 구조와 도구(기술)로 구현할지 설계한다. 이 명령의 핵심 결과물은 plan.md지만, 실제로는 여러 문서가 생성된다.

• tests/... 디렉토리가 존재하는데, quickstart.md는 왜 존재할까? 중복은 아닐까? tests/... 에는 프로그램이 특정 단위마다 수백수천 번을 알아서 하는 자동화 테스트가 들어가지만, quickstart.md에는 개발할 feature를 사용할 어떤 사용자를 상정하고 그 사용자가 구현 결과물을 사용하는 시나리오가 적힌다. 개발할 기능이 '일단 정상 실행되는 모습'을 가장 짧은 경로로 재현한다.
  • 여담으로, 우리가 전자제품을 사면 동봉되어 오는 '사용 설명서'는 2종류다. 하나는 User Manual이고, 하나는 Quick Start Guide다. 전자는 모든 기능ㆍ설정ㆍ오류 해결까지 자세히 설명하는 반면, 후자는 전원 연결 → 초기 설정 → 핵심 기능 첫 사용까지의 최소 단계만 안내한다.
• plan.md가 최종적으로 채택한 구현 방향의 요약이라면, research.md는 그 결론에 도달하기 전에 해결해야 했던 기술적 의문과 판단 근거를 적는다. research.md는 최종 기술 스택, 구조의 결정에 대한 근거 문서인 것이다.
• .../contracts/ 에는 example-site-rest-api.yaml, user-event-schema.json 따위의 문서가 들어간다.
• /speckit.specify 의 경우에는, /speckit.clarify 라는 업데이트 전용 명령어가 있다. /speckit.plan 도 그럴까? 아니다, 없다. /speckit.plan를 한 번 더 호출해서 고쳐 달라고 하거나, plan.md 문서를 직접 수정해도 된다. 직접 수정하는 경우, 이미 만들어진 tasks.md가 있다면 /speckit.tasks 명령까지 (연쇄적으로) 재실행해 주어야 한다.

 

#4-5 /speckit.checklist

이 명령어가 주로 다루는 파일:
specs/example_feature_name/checklists/requirements.md
specs/example_feature_name/checklists/security.md
specs/example_feature_name/checklists/ux.md
...

요구사항 문서가 아주 명확하고 빠짐없이 작성됐는지 확인할 점검표를 만든다. 구현 완료 여부가 아니라, 명세의 품질을 점검하는 문서다.

 

#4-6 /speckit.tasks

이 명령어가 주로 다루는 파일:
specs/example_feature_name/tasks.md

특정 feature 디렉토리에 있는 여러 문서를 총망라해, 잘게 분해된 프로그래밍 계획을 세운다.

 

#4-7 /speckit.analyze

이 명령어가 주로 다루는 파일:
.specify/memory/constitution.md
specs/example_feature_name/spec.md
specs/example_feature_name/plan.md
specs/example_feature_name/tasks.md

기본적으로 어떤 파일을 만드는 명령은 아니고, AI 에이전트가 대화창에 출력한 채팅으로 명령에 대한 결과를 받는다. AI 에이전트는 아래와 같은 것들을 분석(Analyze)한다.

• 요구사항이 계획에 빠짐없이 반영됐는지
• 계획이 작업 목록으로 충분히 분해됐는지
• 문서끼리 충돌하지 않는지
• Constitution을 위반하지 않는지
• 중복이나 모호함이 없는지
• ...

보통

1. /speckit.tasks
2. /speckit.analyze
3. /speckit.implement

의 순서로 사용한다.

 

#4-8 /speckit.taskstoissues

이 명령어가 주로 다루는 파일:
specs/example_feature_name/tasks.md

tasks.md를 GitHub Issue로 변환한다.

 

#4-9 /speckit.implement

이 명령어가 주로 다루는 파일:
src/...
tests/...
specs/example_feature_name/tasks.md

소스 코드와 테스트 코드를 짜고, tasks.md에서 완료된 항목에 ✓ 표시한다.

 

#4-10 /speckit.converge

이 명령어가 주로 다루는 파일:
.specify/memory/constitution.md
specs/example_feature_name/spec.md
specs/example_feature_name/plan.md
specs/example_feature_name/tasks.md
src/...
tests/...
...

/speckit.converge는 /speckit.implement 후에 수행한다. 구현 결과물과 명세(Spec)와의 차이를 찾아, 빠졌거나 불완전한 구현을 tasks.md 하단에 보완 작업으로 추가한다. 이 명령이 코드(src/*)를 고치는 것은 아니며, tasks.md에 새 작업만을 추가한다.

 

#5 분석 - 의존성 그래프

어떤 feature 하나를 명세부터 구현까지 해내는 데 필요한 명령어 간의 의존성 그래프다. 파란색은 한 단위의 완성된 워크플로를 구현하기 위해 필수적으로 요구되는 명령어고, 주황색은 없어도 되는 명령어다. 물론, 그렇다고 중요도가 떨어지진 않을 것이다. 아쉽게도 현재 블로그에는 Mermaid 그래프 코드를 이미지로 변환하는 기능이 없어서, 이미지 파일로 대체했다. 코드는 아래와 같다.

 

```mermaid
flowchart BT
    subgraph Foundation["기반 명세"]
        direction LR
        Constitution["①
/speckit.constitution
(constitution.md)"]
        Specify["②
/speckit.specify
(spec.md)"]
    end
    subgraph Refinement["명세 보강"]
        direction LR
        Clarify["③
/speckit.clarify
(spec.md)"]
        Checklist["⑤
/speckit.checklist
(checklists/*.md)"]
    end
    subgraph Planning["계획 및 작업화"]
        direction LR
        Plan["④
/speckit.plan
(plan.md + 설계 산출물)"]
        Tasks["⑥
/speckit.tasks
(tasks.md)"]
    end
    subgraph Execution["분석·연동·구현"]
        direction LR
        TasksToIssues["⑦
/speckit.taskstoissues
(tasks.md)"]
        Analyze["⑧
/speckit.analyze
(*)"]
        Implement["⑨
/speckit.implement
(*)"]
        Converge["⑩
/speckit.converge
(*)"]
    end
    Specify --> Constitution
    Clarify --> Specify
    Plan --> Specify
    Plan --> Constitution
    Checklist --> Specify
    Tasks --> Plan
    TasksToIssues --> Tasks
    Analyze --> Tasks
    Implement --> Tasks
    Converge --> Implement
    Legend["※ A → B: A 명령이 B 명령의 산출물 또는 선행 실행에 의존
※ 괄호 안: 해당 명령이 다루는 주요 파일
※ *: 여러 산출물과 코드베이스를 종합적으로 다룸
※ 파란색 노드: 필수(Core) 명령 / 노란색 노드: 선택(Optional) 명령
※ 선택 명령(③⑤⑧)은 품질·명료화를 돕는 보조 단계로, 생략해도 워크플로우는 성립
※ 가독성을 위해 전이 의존성과 선택적 보조 의존성은 생략"]
    Legend ~~~ Constitution

    classDef note fill:none,stroke:none,color:#666,font-size:12px;
    classDef core fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#1e3a5f;
    classDef optional fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#7c4a03;
    class Legend note;
    class Constitution,Specify,Plan,Tasks,TasksToIssues,Implement,Converge core;
    class Clarify,Checklist,Analyze optional;
    style Foundation fill:#fafafa,stroke:#bbb
    style Refinement fill:#fafafa,stroke:#bbb
    style Planning fill:#fafafa,stroke:#bbb
    style Execution fill:#fafafa,stroke:#bbb
```

 

#6 간단히 진행한 실습

#6-1 진행 방식

공식 저장소 README.md의 "Get Started" 섹션에 나온 명령어 순서를 그대로 따라 하되, 명세 내용만 내가 원하는 대로 바꿨다. 아래는 내가 AI 에이전트에게 내린 명령어 모음이다.

• /speckit.constitution 개발의 각 단계의 진행이 일목요연하게 보여야 하며, README.md 파일 등을 아주 친절하게 적어 초보자를 배려해야 함.
• /speckit.specify 사용자가 배우고 싶은 어떤 개념을 말하면, 따라 하기 좋은 Codelab 파일을 반환하는 Agent Harness. 사용자는 막연한 개념을 질문해도 좋고, 어떤 구체적인 웹페이지 링크를 보내도 좋다. 사용자의 질문을 받으면 Agent는 Codelab의 각 단계의 개수와 이름을 어떻게 구성할 것인지를 먼저 생각한다. 그리고 그걸 사용자에게 중간 점검 받은 후 비로소 본격적인 Codelab 파일 제작에 착수한다.
• /speckit.plan 내부적으로 .md 파일을 만든다. 그리고 그걸 claat.exe의 .md → .html 변환 기능으로 Codelab 파일(.html 형태)로 만들어 사용자에게 반환한다. claat를 사용자가 따로 설치하지 않아도 되도록 프로젝트에 구성한다. 지정한 버전의 실행 파일이 없으면 자동으로 다운로드한다.
• /speckit.tasks
• /speckit.implement

 

#6-2 결과

GitHub - Kanmanemone/keenel-codelab at simple-first-practice

위 레포지토리의 README.md 또한 Spec Kit에 의해 자동 생성된 것이다.