Spec-Kit
- GitHub에서 공개한 오픈소스 툴킷
- SDD를 실천할 때에 필요한 것들을 한 상자에 모아놓은 것
구성 요소
-
Specify CLI
프로젝트 초기 세팅 도구
프로젝트 폴더 구조 자동 생성 -
템플릿 모음
명세·계획·작업 표준 양식
명세서는 어떻게 생겨야 하는지, 계획서에는 어떠한 항목들이 들어가야 하는지 -
슬래시 명령어
/speckit.* AI 역할 정의
AI와 대화할 때 특별한 명령어를 쓸 수 있게 해줌
7단계 워크플로 전체 그림
각 단계의 산출물이 다음 단계의 입력이 됨
1. Constitution
.specify/memory/constitution.md
- 프로젝트의 헌법
- AI의 시키지도 않은 일 까지 하려는 경향을 원천 차단
예)
- 모든 코드 테스트를 먼저 작성(TDD)
- 프로젝트는 최대 3개까지만
- 프레임워크는 직접 사용, 래퍼 금지
- API 응답은 500ms 이내
위반 시 ERROR로 중단·모든 단계의 기준점
2. 문서 계층 구조
- 위로 갈수록 '왜'(철학)
- 아래로 갈수록 '어떻게'(실행)
- 변경은 위→아래로만 전파
- 관심사 분리: 각 단계는 자기 차원의 고민만
spec: 요구사항, plan: 기술, Tasks: 순서 - 이러한 구조 덕분에 프로젝트가 커져도 추적이 가능함
3. 자동 검증 장치
-
Constitution Check: Plan 단계
기술 선택이 헌법 위반이 아닌지 확인
위반 시 ERROR로 중단 -
Analyze Cross-Validation: TASKS 후
spec·plan·tasks 모순 검증
CRITICAL / HIGH / MEDIUM 심각도 -
TDD GATE: Implement 단계
테스트 없이 코드 작성 금지
Red→Green 사이클 강제
AI를 자유롭게 풀어주는 것이 아닌, 구조 안에서 자유롭게 움직이게 하는 것
8개 명령어 전체 요약
핵심 명령(5개, 필수)
/speckit.constitution: 헌법 수립
/speckit.specify: 명세 작성
/speckit.plan: 기술 설계
/speckit.tasks: 작업 분해
/speckit.implement: 코드 구현
선택 명령(3개, 품질)
/speckit.clarify: spec 모호할 때
/speckit.checklist: 도메인별 품질
/speckit.analyze: 구현 전 검증
3가지 핵심
1. 말하기 전에 쓰기
- 명세가 먼저, 코드는 그 다음. AI는 우리 머릿속을 보지 못함
2. AI의 자유를 제한하라
- 헌법·게이트·체크리스트가 일관된 결과를 만든다.
3. 문서는 공통 언어다
spec.md는 팀원과도, AI와도, 미래의 나와도 소통하는 매개체
Specify
1) spec.md - user story
- Given, When, Then
2) Functional Requirements(FR-001~)
- 시스템이 반드시 해야할 일
3) Success Criteria(SC-001~)
- 성공 기준
측정 가능한 지표로만 작성
4) Assumptions
- 가정
NEEDS CLARIFICATION
- AI가 확신하지 못한 부분을 명시적으로 남김
다음 단계인clarify단계에서 Q&A로 해결함
Clarify
- NEEDS CLARIFICATION이 있을 때만 실행
Plan
- 기술 스택을 결정하는 단계
- Constitution Check
Plan의 내용이 Constitution에 대해 원칙을 지키는지 점검
하나라도 만족하지 못할 시, 진행 불가
1) research.md
- 기술 선택에 대한 근거
Decision: useReducer
Rationale: 배열 상태 단순
Alternatives:
Redux, Zustand2) data-model.md
- 데이터 구조
interface Todo {
id: string;
date: string;
text: string;
completed: boolean;
}3) contracts/storage.md
// localStorage 스키마
key: "calendar-todos"
value: Todo[]
(JSON 배열)4) quickstart.md
- 앱이 제대로 만들어졌는지 검증할 시나리오
5) plan.md
- 위 모든 문서들을 총괄하는 문서
5개의 문서는 서로 일관되어야 함
데이터 모델의 타입이 컨트랙트에 나타나야 하며,
스펙의 성공 기준이 퀵스타트에서 검증되어야 하는 등
→ analyze 단계에서 체크함
Tasks
- 플랜을 실제 손으로 쓸 수 있는 작업 단위로 쪼갬
- phase로 구분함
- [P]: parallel, 병렬 실행 가능
Analyze
- 지금까지 만든 4개의 문서
spec, plan, taks, constitution이 서로 모순되지 않는지 검사 - 파일을 절대 수정하지 않음, 읽기 전용
CRITICAL, HIGH는 반드시 해결
Implement
- 실제 코드 작성
