github Spec Kit 란?

 

 

 

1. Spec Kit이란?

• Spec Kit은 Spec-Driven Development (사양 중심 개발) 방식을 돕기 위한 툴킷입니다. 전통적인 방식에서 “먼저 코드를 짜고 나중에 문서를 작성”하던 흐름 대신, 사양(specification, 스펙)을 먼저 정의하고 이 스펙을 실행 가능한 중심(“source of truth”)으로 삼아 개발 과정을 진행하는 접근을 채택합니다. (GitHub)
• 특히 GitHub Copilot, Claude Code, Gemini CLI 같은 AI 코드 생성 도구(coding agent)와 함께 사용하면서, AI가 더 명확한 사양을 바탕으로 코드를 생성하도록 유도하는 구조입니다. (GitHub)
• 이렇게 사양 중심으로 개발을 시작하면, 요구사항의 애매함을 줄이고 AI가 잘못된 가정을 하지 않게 하며 반복 수정, 리팩토링 비용을 줄이는 데 도움을 준다고 합니다. (The GitHub Blog)

---

2. 환경 설정 및 설치

Spec Kit을 쓰기 위한 기본 조건과 설치 방법은 아래와 같습니다:

항목 설명

운영체제	Linux 또는 macOS 권장. Windows 환경에서는 WSL2를 사용하는 것이 좋습니다. (GitHub)
Python	Python 3.11 이상이 필요합니다. (GitHub)
패키지 매니저	uvx라는 툴을 사용하여 Spec Kit을 설치합니다. (GitHub)
Git	Git 리포지토리 환경이 필요하며, CLI 초기화 시 기본적으로 사용됩니다. Spec Kit CLI에서 --no-git 옵션을 통해 Git 초기화를 건너뛸 수도 있습니다. (GitHub)
AI 코딩 에이전트	아래 중 하나가 필요합니다: Claude Code, GitHub Copilot, Gemini CLI, Cursor, opencode, Qwen CLI 등. (GitHub)
선택 옵션	CLI 초기화 시 다음 옵션들을 같이 사용할 수 있습니다: • --here (현재 디렉토리에서 초기화) • --ai <agent> (예: --ai claude) • --script (bash/zsh 또는 PowerShell) • --ignore-agent-tools (AI 도구 체크를 건너뜀) • --no-git (Git 초기화 건너뜀) (GitHub)

설치/초기화 예시

# 새 프로젝트 디렉토리에서 초기화
uvx --from git+https://github.com/github/spec-kit.git specify init my-project

# 현재 디렉토리에 바로 초기화
uvx --from git+https://github.com/github/spec-kit.git specify init --here

# “Claude Code” AI 에이전트를 지정하고, Git 초기화는 건너뜀
uvx --from git+https://github.com/github/spec-kit.git specify init my-project --ai claude --no-git

# 디버그 로깅 켜기
uvx --from git+https://github.com/github/spec-kit.git specify init my-project --ai claude --debug

초기화가 완료되면, 프로젝트 디렉토리에 Spec Kit이 요구하는 기본 파일 구조와 디렉토리 (specs/, scripts/, memory/ 등)가 생성됩니다. (GitHub)

---

3. 기본 워크플로우: /specify → /plan → /tasks → 구현

Spec Kit은 사양 → 계획 → 작업 단위 → 구현의 4단계 흐름을 중심으로 진행됩니다. 각 단계는 AI 코딩 에이전트가 생성한 결과물을 개발자가 검토하고 피드백하는 방식으로 순환됩니다. (GitHub)

1. /specify — 사양(specification) 정의

• 먼저 /specify 명령을 사용해서, 무엇을 만들고 싶은지(what) 그리고 왜 만드는지(why) 에 대한 설명을 자연어로 입력합니다. 기술 스택, UI 구현 방법 등은 아직 고려하지 않고, 기능의 목적, 사용자 흐름, 요구사항 중심으로 설명합니다. (GitHub)
• 예시:
• /specify Build an application that can help me organize my photos in separate photo albums. Albums are grouped by date…
• AI는 이 설명을 바탕으로 구체적인 사양 문서(spec.md)를 생성하고, 사용자 스토리, 기능 요구사항, 제약조건 등을 포함한 구조화된 문서를 만들어 냅니다. (GitHub)

개발자는 이 생성된 스펙을 읽고 “이 사양이 내가 원한 기능을 충분히 담고 있는가?”, “빼먹은 요구사항은 없는가?”, “모호하거나 애매한 부분이 있는가?”를 검토하고 피드백을 줍니다.

2. /plan — 기술 계획(technical implementation plan)

• 사양이 정리되면, /plan 명령을 통해 기술 스택, 아키텍처, 제약 조건, 통합 방식 같은 기술적 제약 및 선택 사항을 AI에게 알려줍니다. 예: 데이터베이스, 프론트엔드 프레임워크, API 설계, 배포 전략, 레거시 시스템 통합 방식 등. (GitHub)
• AI는 이 정보를 바탕으로 “계획 문서(plan.md)”를 만들고, 디렉토리 구조, API 계약, 데이터 모델, 상호작용 흐름, 통합 전략 등 상세한 기술 계획을 제시합니다. 프로젝트 디렉토리 트리가 확장되어 specs/.../plan.md, data-model.md, research.md 등 다양한 계획 관련 문서가 포함됩니다. (GitHub)
• 개발자는 이 계획을 보고 “기술 제약을 제대로 반영했는가?”, “성능, 보안, 확장성, 배포 전략 등의 고려가 충분한가?”, “비즈니스 요구사항과 잘 맞는가?” 등을 검토하고 필요한 수정을 요청할 수 있습니다.

3. /tasks — 구현 작업 단위(Task)로 분해

• 기술 계획이 승인되면 /tasks 명령을 사용해서 Spec + Plan을 바탕으로 작업 단위(task) 목록을 생성합니다. 여기서 AI는 구현 가능한 작은 단위의 작업 항목을 만들어 줍니다. 예: “사용자 등록 API 구현”, “이메일 유효성 검사”, “프론트엔드에서 앨범 목록 UI 구현” 같은 구체적인 단위 작업. (GitHub)
• 각 작업 단위는 독립적으로 검토, 구현, 테스트할 수 있는 수준이어야 하며, 리뷰하기 쉬운 작고 구체적인 덩어리로 나뉘는 것이 중요합니다. 이렇게 분해함으로써 AI가 단계별로 작업을 수행하고, 개발자는 각 작업 결과를 점검하면서 점진적으로 진행할 수 있습니다.

4. 구현 (Implement)

• 마지막으로, AI 코딩 에이전트가 /tasks로 나뉜 작업들을 기반으로 실제 코드를 작성합니다. 예를 들어 implement specs/002-feature/plan.md 같은 명령을 통해 작업 단위를 실행합니다. (GitHub)
• 개발자는 이 코드 변경사항을 리뷰하고, 빌드 오류나 런타임 오류를 확인하고 필요한 수정을 지시합니다. AI는 CLI 빌드 로그나 브라우저 콘솔 오류 등을 기반으로 스스로 오류를 수정하도록 유도할 수 있습니다. (GitHub)

이 과정에서 중요한 점은, AI가 “사양(spec)”, “계획(plan)”, “작업(tasks)”이라는 구조 안에서 점진적으로 코드를 생성하고, 개발자가 각 단계에서 피드백하고 교정하는 반복적인 검토 과정을 거친다는 것입니다. Spec Kit을 통해 AI 기반 개발이 “vibe coding” (즉시 코드 생성 → 반복 수정) 방식보다 더 예측 가능하고 안정적인 워크플로우를 가질 수 있다는 것이 핵심입니다. (The GitHub Blog)

---

4. 실전 팁 & 고려사항

• 사양을 명확히 작성하는 것부터 시작: /specify 단계에서 가능한 한 구체적이고 명확하게 요구사항을 기술하는 것이 중요합니다. “무엇을 왜 만드는가”에 대한 설명을 충분히 포함하고, 엣지 케이스나 예외 상황도 같이 언급하면 AI가 더 좋은 사양 문서를 생성하는 데 도움이 됩니다. (GitHub)
• 사양과 계획은 살아있는 문서(living document): 처음 작성한 사양이나 계획이 끝이 아니며, 개발 도중에 사용자 요구사항이 바뀌거나 기술적 제약이 발견되면 이를 반영해 사양과 계획을 업데이트하고 다시 태스크를 재생성할 필요가 있습니다. Spec Kit은 이런 반복적인 업데이트를 염두에 둔 워크플로우를 지원합니다. (The GitHub Blog)
• 작은 수정 또는 버그 해결에는 과할 수 있음: 일부 사용자들은 Spec Kit 워크플로우가 간단한 버그 수정이나 작은 기능 변경엔 다소 “무겁다(overkill)”는 의견을 제시하기도 합니다. ﹘ 즉, Spec Kit은 새 기능 개발이나 복잡한 시스템 개선에 더 적합하며, 아주 단순한 작업에는 적절하지 않을 수 있습니다. (Reddit)
• UI 중심의 복잡한 기능(예: 드래그 앤 드롭 UI, 복잡한 그래픽 인터랙션 등)은 AI가 자동으로 구현하기 어려우므로, 사양 단계에서 UI 흐름, 상태 전환, 인터랙션에 대한 설명과 제약을 명확히 해야 합니다. Spec Kit 자체가 비주얼 디자인 또는 UI 레이아웃을 자동으로 처리해 주는 툴은 아니기 때문입니다. (The GitHub Blog)
• AI 에이전트의 선택: 사용하는 AI 코딩 에이전트(예: Claude Code, Copilot, Gemini CLI 등)에 따라 결과물이 다르게 나오기 때문에, 어떤 AI를 사용할지 미리 정하고 specify init 명령어에서 --ai 옵션으로 지정하는 것이 추천됩니다. (GitHub)

---

5. 예시: 간단한 프로젝트 워크플로우

아래는 “사진 앨범 정리 앱(photo album organizer)”이라는 간단한 예제를 가지고 Spec Kit 워크플로우를 따라가는 흐름을 정리해본 예시입니다.

1. 초기화
2. uvx --from git+https://github.com/github/spec-kit.git specify init photo-album-organizer --ai claude cd photo-album-organizer
3. 사양 정의 (/specify)→ 이 명령어를 통해 specs/001-.../spec.md 같은 사양 문서가 생성됩니다.
   → 생성된 사양을 검토하면서, 예: “앨범은 날짜 순으로 자동 정렬되는가?”, “사진 메타데이터는 어떻게 저장되는가?”, “앨범 이름 변경 기능이 필요한가?” 등의 질문을 추가로 피드백할 수 있습니다.
4. /specify Build an application that helps me organize my photos into albums by date. Albums should not be nested inside other albums. Users should be able to drag and drop photos to rearrange them in an album. Photos are displayed with previews in a grid within the album view.
5. 기술 계획 생성 (/plan)→ AI가 plan.md, data-model.md, research.md 등 기술 계획 문서를 생성합니다.
   → 개발자는 이 플랜을 보고 “사진 파일은 클라이언트 파일 시스템에 저장하나요?”, “메타데이터는 어떻게 관리하나요?”, “앱을 배포할 때 파일 접근 권한은 어떻게 처리하나요?” 등을 확인하고 피드백합니다.
6. /plan Use a static single‐page app built with Vite + vanilla JavaScript, storing metadata in a local SQLite database. No image uploading to remote servers. Use drag-and-drop with HTML5 native APIs. No user authentication; all data is local.
7. 작업 단위 분해 (/tasks)
   → AI는 위의 사양과 계획을 기반으로 구체적인 작업 리스트를 생성합니다. 예:
   • Task 1: Set up project scaffold and folder structure
   • Task 2: Build photo metadata model and SQLite schema
   • Task 3: Render album list view grouped by date
   • Task 4: Implement drag-and-drop UI within albums
   • Task 5: Save rearranged photo order into metadata
   • Task 6: Generate preview grid UI for photos in album
   • Task 7: Write simple tests for metadata ordering logic
8. 구현 실행 (implement)
   → 예:→ AI가 Task별로 코드를 작성하기 시작합니다.
   → 개발자는 각 Task 결과를 리뷰하고, 빌드 오류 또는 실행 오류가 발생하면 AI에게 수정 요청을 합니다.
9. implement specs/001-photo-album-organizer/plan.md
10. 반복 및 개선
    → 만약 앱에 새로운 요구사항이 생기거나 동작 방식이 변경된다면, /specify 또는 /plan 문서를 갱신하고 다시 /tasks를 통해 작업을 재구성할 수 있습니다.