jaysnote

03. GitHub SpecKit — SDD를 도구로 굳히기

#agentic-engineering #speckit #sdd

SpecKit은 GitHub이 만든 오픈소스 SDD 툴킷이다. SDD의 추상적 흐름(Spec→Plan→Tasks→Implement)을 슬래시 명령어로 박제해, Claude Code 같은 30종 이상의 coding agent 위에서 돌린다.

이 문서의 명령어/경로는 spec-kit 저장소 기준이다. 버전에 따라 바뀔 수 있으니 실제 사용 시 specify integration list와 저장소 README로 최신 내용을 확인하라.

설치

uv(Python 패키지 매니저)와 Python 3.11+ 가 필요하다.

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

# 프로젝트 초기화 (Claude Code 연동)
specify init my-project --integration claude

# 사용 가능한 연동 목록
specify integration list

초기화하면 다음 구조가 생긴다:

.specify/
├── memory/
│   └── constitution.md        # 프로젝트 헌법(불변 원칙)
├── scripts/bash/              # 단계 진행용 스크립트
└── templates/                 # spec/plan/tasks 템플릿
specs/
└── [feature-name]/
    ├── spec.md                # 무엇을·왜
    ├── plan.md                # 어떻게(기술 스택, 아키텍처)
    ├── tasks.md               # 의존성 순서가 반영된 작업 목록
    ├── research.md            # 조사 메모
    ├── data-model.md          # 데이터 모델
    └── contracts/             # API 계약(json 등)

.specify/와 specs/는 저장소에 커밋한다. 명세가 코드와 함께 버전 관리되는 것이 SDD의 핵심.

명령어 워크플로

Claude Code 안에서 슬래시 명령으로 호출한다. 표준 순서는 다음과 같다:

순서명령어하는 일산출물
0/speckit.constitution프로젝트의 불변 원칙·가이드라인 작성.specify/memory/constitution.md
1/speckit.specify무엇을 만들지(요구사항·사용자 스토리) 정의specs/[feature]/spec.md
2/speckit.clarify덜 정의된 부분을 구조화된 질문으로 보완spec.md에 Clarifications 섹션 추가
3/speckit.plan기술 스택을 정해 구현 계획 작성plan.md + research/data-model/contracts
4/speckit.tasks계획을 실행 가능한 작업 목록으로 분해tasks.md
5/speckit.analyze산출물 간 일관성·커버리지 교차 검증분석 리포트
6/speckit.implement모든 작업을 계획대로 실행해 구현소스 코드

보조 명령:

  • /speckit.checklist — 맞춤 품질 체크리스트 생성
  • /speckit.taskstoissues — 작업을 GitHub 이슈로 변환

헌법(constitution)이 가장 중요하다

constitution.md는 모든 SDD 반복 이전에 정하는 협상 불가 원칙 모음이다. “테스트 없는 코드 머지 금지”, “공개 API는 하위 호환 유지”, “외부 호출은 반드시 타임아웃” 같은 규칙. agent는 plan을 세울 때 이 헌법을 반드시 따라야 한다.

→ 헌법은 04. 사람 vs agent 경계에서 말하는 “사람이 정하고 agent가 절대 못 넘는 가드레일” 의 구체적 구현이다. 템플릿: templates/00-constitution.md.

SpecKit 단계 ↔ 사람/agent 분담

단계사람agent
constitution결정 (원칙은 가치 판단)초안 제안
specify주도 (요구사항은 의도)초안 작성, 누락 지적
clarify답한다 (모호함 해소)질문을 던진다
plan승인/거부 (아키텍처 결정)옵션·트레이드오프 제시
tasks검토주도 (기계적 분해)
analyze리포트 읽고 판단주도 (일관성 검사)
implementdiff 리뷰·게이트주도 (코드 생성)

이 표의 원리(왜 이렇게 나뉘는가)가 다음 문서의 주제다.

SpecKit을 꼭 써야 하나?

아니다. SpecKit은 SDD를 편하게 해주는 도구일 뿐, SDD 자체는 마크다운 파일과 규율만으로도 가능하다. 작은 팀·개인이라면:

  • SpecKit 없이: docs/에 spec → plan → tasks를 직접 쓰고, Claude의 plan mode로 계획을 검토받는다. → 06-claude-workflow.md
  • SpecKit 사용: 위 흐름을 명령어로 표준화하고 팀 전체에 강제하고 싶을 때.

도구보다 “명세를 먼저, 코드와 함께 버전 관리” 라는 원칙이 본질이다.

← 목록으로