이 기사는

GitHub가 개발하고 있는 사양 주도 개발(Spec-Driven Development) 도구인 「Spec Kit」의 설치 방법과 사용법을 소개합니다.

Spec Kit이란

Spec Kit은 GitHub가 개발하고 있는 사양 주도 개발 (Spec-Driven Development)을 위한 도구입니다. AWS의 Kiro 등과 유사한 컨셉의 것으로, AI 코딩 에이전트에게 「사양 → 계획 → 태스크 → 구현」이라는 흐름을 엄격하게 지키게 하면서 개발을 진행할 수 있습니다.

저는 Spec Kit을 사용한 지 반년 이상 되었습니다. 사용하기 전에는 제가 직접 AI에게 「사양서를 써줘」, 「사양서를 바탕으로 실행 계획을 써줘」, 「실행 계획을 바탕으로 구현해줘」와 같은 지시를 매번 내렸습니다. 이렇게 해도 나름대로 개발은 진행되지만, AI가 도중에 멋대로 사양을 다시 해석하여 구현해 버리거나, 계획과 구현이 어긋나는 등의 문제가 종종 발생하곤 했습니다.

Spec Kit을 사용하면 이러한 공정들을 슬래시 커맨드(slash command)화된 일련의 플로우로 실행하고, 미리 정의된 결과물을 베이스로 엄격한 규칙에 따라 개발할 수 있기 때문에, 더욱 확실하게 사양 주도 개발을 진행할 수 있게 되었다고 느끼고 있습니다.

신규 개발에도 기존 프로젝트에도 적용 가능

제가 개발하고 있는 Redmine AI Helper 플러그인은 원래 Spec Kit 없이 개발을 시작했지만, 중간부터 Spec Kit을 도입하여 개발을 진행하고 있습니다.

또한, Sealion이라는 프로젝트는 처음부터 Spec Kit을 사용하여 개발을 진행하고 있으며, 100% Spec Kit에 의해 작성된 코드입니다.

설치

Spec Kit의 CLI인 specify는 uv로 설치합니다.

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

설치가 완료되면 다음 명령어로 도움말이 표시되면 성공입니다.

specify --help

첫 세팅

Spec Kit을 사용하고 싶은 워크스페이스(리포지토리의 루트 등)로 이동하여 specify init을 실행합니다.

specify init .

실행하면 대화 형식으로 다음 두 가지를 묻습니다.

• 사용할 코딩 에이전트 (Claude Code, GitHub Copilot, OpenCode 등)
• 사용할 스크립트 종류 (sh인지 powershell인지. 실행 환경에 맞춰 선택)

참고로, 코딩 에이전트는 여러 개를 동시에 선택할 수 없습니다. 여러 코딩 에이전트를 병용하고 있는 경우에는 사용 중인 에이전트의 수만큼 specify init .을 실행합니다. 저는 GitHub Copilot, Claude Code, OpenCode 3개를 사용하고 있어서 3번 실행했습니다.

실행이 완료되면 워크스페이스 직하에 .specify 디렉토리와, 선택한 에이전트용 설정 파일(예: .claude/commands/ 하위의 슬래시 커맨드 정의 등)이 생성됩니다.

개발 규칙 (헌법) 정의

처음 한 번만 수행하는 작업입니다. Spec Kit이 엄수해야 할 규칙 («헌법»이라고 불립니다)을 정의합니다.

코딩 에이전트를 기동하여 다음 슬래시 커맨드를 실행합니다.

/speckit.constitution

파라미터로 직접 규칙을 지정해도 되고, 아무것도 지정하지 않아도 AGENTS.md나 기존 문서를 읽어 들여 규칙을 작성해 줍니다.

또한, 나중에 다음과 같이 규칙을 추가하는 것도 가능합니다.

/speckit.constitution 구현 후에 반드시 lint를 실행하는 규칙을 추가해줘

규칙은 .specify/memory/constitution.md에 저장됩니다.

여기까지 생성된 파일들을 일단 커밋해 둡니다. 팀에서 사용할 때는 멤버 전원이 uv로 specify 명령어를 설치하지 않더라도, 여기까지 생성된 파일들을 공유하면 Spec Kit으로 개발을 시작할 수 있습니다.

개발 규칙에 추가하면 좋은 항목

저는 항상 constitution에 다음과 같은 규칙을 추가하고 있습니다. 참고 삼아 소개합니다.

TDD(Test-Driven Development)로 개발할 것- 먼저 코드를 작성하게 한 뒤 나중에 테스트 코드를 작성하게 하면, AI는 코드를 정답으로 간주하고 테스트 코드를 작성하는 경우가 많습니다. 이럴 경우 코드가 틀렸더라도 테스트에서 발견할 수 없습니다. TDD라면 사양을 충족하기 위한 테스트 코드를 작성하는 것부터 시작하므로, 올바른 테스트를 수행할 수 있습니다. 이와 함께 커버리지(Coverage) 목표치도 설정해 두는 것이 좋습니다.

KISS, YAGNI 원칙을 지킬 것- AI는 무심코 다양한 기능을 포함시키려 하지만, 이러한 원칙을 지킴으로써 필요 최소한의 심플한 구현에 머무를 수 있습니다.

DRY 원칙을 지킬 것- 동일한 코드를 반복해서 쓰지 않도록 하는 규칙입니다. 이 또한 AI가 무심코 비슷한 코드를 반복해서 작성하는 경우가 있으므로, DRY 원칙을 지키는 규칙을 추가하는 것이 좋습니다.

안이하게 에러 폴백(Fallback) 처리를 하지 말 것- 안이한 폴백 처리는 에러를 숨겨버려 버그 발견을 늦춥니다. 에러는 에러로서 확실하게 다루어야 합니다.

정적 분석 실행- 구현 후에는 반드시 정적 분석을 실행하여 코드 품질을 유지할 것. 포맷팅, TSDoc 등의 문서 추가, 순환 복잡도(Cyclomatic Complexity) 등 사용하는 언어에 따른 체크 도구를 실행하는 규칙을 추가합니다.

ADR 기록- 중요한 설계 결정을 내렸을 때는 반드시 ADR(Architecture Decision Record)을 기록하는 규칙을 추가합니다. 이를 통해 왜 해당 설계 결정이 내려졌는지 나중에 되돌아볼 수 있습니다. 또한, AI가 다른 기능을 구현할 때 과거의 설계 결정을 참조하여 일관성 있는 설계를 할 수 있습니다.

보안을 최우선 사항으로 다룰 것- AI는 편의성이나 구현의 용이성을 우선시하여 인증·인가, 입력값 검증, 기밀 정보 취급 등에서 안이한 구현을 해버릴 때가 있습니다. 보안을 최우선 사항으로 다루는 규칙을 추가함으로써 이러한 문제를 방지합니다.

이것들을 공통 규칙으로 삼고, 나머지는 프로젝트나 언어, 프레임워크 등의 특성에 따라 적절히 규칙을 추가해 나가고 있습니다.

사용법

Spec Kit에서는 다음과 같은 6가지 슬래시 명령어를 구분하여 사용하며 개발을 진행합니다.

명령어	용도	필수 여부
/speckit.specify	사양서 작성 (외부 사양·요구사항 정의)	필수
/speckit.clarify	사양서의 모호한 점을 명확히 함	선택
/speckit.plan	내부 사양을 포함한 실행 계획 작성	필수
/speckit.tasks	계획을 태스크로 분해	필수
/speckit.analyze	사양·계획·태스크의 모순 확인	선택
/speckit.implement	태스크를 바탕으로 구현	필수

각 명령어를 차례대로 살펴보겠습니다.

1. /speckit.specify (사양서 작성)

가장 먼저 실행하는 명령어입니다. 구현하고 싶은 기능을 자연어로 전달하면, 외부 사양 및 요구사항 정의를 포함한 사양서를 생성해 줍니다.

/speckit.specify 사용자가 로그인하여 TODO를 관리할 수 있는 Web 앱을 만들고 싶어. 인증은 이메일 주소와 비밀번호로 진행하고, TODO는 사용자별로 독립적으로 관리해.

파일 생성 위치

사양서는 specs 디렉토리 하위에 기능별로 폴더가 일련번호 순으로 생성되며, 그 아래에 spec.md라는 파일명으로 저장됩니다. 예를 들어, 첫 번째 기능 추가가 TODO 화면 생성이라면 specs/001-create-todo-window/spec.md와 같은 파일이 생성됩니다.

이후 이 기능과 관련하여 Spec Kit이 생성하는 모든 문서은 이 폴더 안에 저장됩니다. 또한, 이 폴더와 동일한 이름으로 git 브랜치도 생성됩니다 (예: 001-create-todo-window). 이 브랜치에서 개발을 완료한 후 main 브랜치로 머지(Merge)하는 흐름이 됩니다.

spec.md는 Spec Kit으로 개발하는 데 있어 가장 중요한 파일입니다. 이 부분은 사람이 직접 철저하게 리뷰를 수행합니다.

Issue 관리 도구와 연동하기

GitHub, Jira, Redmine과 같은 Issue 관리 도구에서 개발 항목이 관리되고 있다면, 다음과 같이 Issue 번호를 지정하여 사양서를 작성할 수도 있습니다.

/speckit.specify issue #1234의 내용으로부터 사양을 작성해줘

단, 이 경우에는 GitHub, Jira, Redmine 등의 MCP Server가 설정되어 있어야 합니다.

2. /speckit.clarify (모호한 점을 명확히 하기)

임의의 단계이지만, 저는 거의 매번 실행합니다. 사양서 중에서 모호한 부분을 AI가 찾아내어 질문해 주기 때문에, 이에 답변해 나감으로써 사양의 정밀도를 높일 수 있습니다.

/speckit.clarify

3. /speckit.plan (실행 계획)

사양서를 바탕으로 내부 사양을 포함한 실행 계획을 작성합니다. 사용하는 기술 스택(Tech Stack)이나 설계 방침 등은 이 단계에서 결정됩니다.

/speckit.plan Next.js + Prisma + PostgreSQL로 구현한다

실행 계획은 plan.md라는 파일명으로 사양서와 같은 폴더 안에 저장됩니다. plan.md 외에도 data-model.md, research.md 등 여러 파일이 생성됩니다. 이 파일들을 바탕으로 다음 단계인 태스크 분해(Task Decomposition)가 이루어지게 됩니다.

4. /speckit.tasks (태스크 분해)

실행 계획을 바탕으로 구현 가능한 입도의 태스크로 분해합니다.

/speckit.tasks

그러면 tasks.md라는 파일이 생성됩니다. 태스크는 체크리스트 형식으로 생성되기 때문에 진척 관리에도 사용할 수 있습니다.

5. /speckit.analyze (정합성 체크)

사양·계획·태스크 사이에 모순이 없는지 확인하는 커맨드입니다. 임의의 단계이며, 저 자신은 평소에 잘 사용하지 않습니다. 신경 쓰일 때만 실행하는 정도입니다.

/speckit.analyze

6. /speckit.implement (구현)

태스크를 바탕으로 실제 구현을 진행합니다.

/speckit.implement

태스크를 순서대로 구현해 나갑니다. 실제로 코드가 구현되고 테스트가 수행됩니다. 구현이 끝나면 tasks.md의 체크리스트에 완료 표시가 붙습니다.

사용하는 모델

저의 경우, Claude Code로 개발할 때는 spec은 opus를, 그 외에는 sonet을 사용하는 경우가 많습니다. 구현할 기능의 난이도에 따라서는 plan도 opus로 설정하기도 합니다. plan 단계까지 확실하게 되어 있다면, tasks나 implement는 그렇게 고성능 모델이 아니더라도 충분한 경우가 많다는 인상입니다.

Spec Kit 업그레이드

Spec Kit은 빈번하게 업데이트되고 있습니다. 2026년 6월 현재, 주に 2~3회 정도의 속도로 업데이트가 릴리스되고 있는 상황입니다. 새로운 버전이 릴리스되면 다음 커맨드로 업그레이드할 수 있습니다.

specify self upgrade

단, 이 커맨드는 specify CLI 자체를 업그레이드하는 것이며, 프로젝트 내의 설정 파일이나 스크립트 등은 자동으로 업데이트되지 않습니다. specify init .을 재실행함으로써 최신 템플릿에 기반한 파일을 생성할 수 있습니다. 생성되었다면 커밋해 두시기 바랍니다.

사용해 본 소감

반년 정도 사용해 본 소감입니다만, 특히 다음과 같은 상황에서 Spec Kit이 강력하다고 느끼고 있습니다.

어느 정도 규모가 있는 기능 추가: 사양서와 태스크, 그리고 개발 규칙이 명확해짐으로써 AI의 구현이 궤도에서 벗어나기 어려워짐 -
며칠에 걸친 개발: 사양서·계획·태스크가 파일로 남기 때문에, 다음 날 이어서 재개해도 편차가 적음 -
팀 개발: 팀 전체가 규칙에 따른 개발을 강제할 수 있음. 사양서 작성 방식이 통일되어 있어 리뷰하기 쉬움

반면, 몇 줄로 끝나는 간단한 수정에는 이 정도의 엄격한 프로세스는 토큰(Token) 사용량 대비 과잉(Overkill)입니다. 경우에 따라서는 평소처럼 AI에게 직접 요청하는 편이 더 나을 것입니다.

요약

Spec Kit을 사용하면, 지금까지 매번 직접 지시해야 했던 "사양 → 계획 → 태스크 → 구현"의 흐름을 슬래시 커맨드(Slash Command)화된 엄격한 프로세스로 실행할 수 있게 됩니다. AI에게 맡기는 개발의 질을 한 단계 높이고 싶은 분들은 시도해 볼 가치가 있다고 생각합니다.

Discussion