Spec-Gatekeeper: Spec 중심 개발 워크플로우
spec-gatekeeper에 의해 소스 코드 작성이 차단되었거나, 새로운 기능, 서비스, 주요 리팩터링을 시작할 때 이 스킬을 사용하세요.
Spec 중심 개발(Spec-Driven Development, SDD)은 구현 전에 합의된 구조화된 아키텍처 계약을 요구하여 명확성을 확보하고 요구사항 변경에 따른 설계 변화(드리프트)를 제거합니다.
워크플로우 단계
1단계: 4가지 질문으로 구성된 개발자 인터뷰 진행
코드를 작성하거나 파일을 스텁하기 전에, 개발자에게 다음 4가지 집중 질문을 하거나(또는 기존 요구사항에서 답변을 추출하여 확인을 요청하세요):
-
범위 및 보안:
- 이 작업의 핵심 목표와 명시적 비목표(Non-goals)는 무엇인가요?
- 관련된 아키텍처 구성 요소 또는 시스템 경계는 무엇인가요?
- 보안, 권한, 인증, 또는 샌드박스 제약 조건은 무엇인가요?
-
데이터 계약:
- 정확한 스키마, API 인터페이스, 타입, 프로토콜 형태는 무엇인가요?
- 정확한 입력 매개변수와 예상 출력 페이로드는 무엇인가요?
-
엣지 케이스 및 복원력:
- 주요 실패 모드, 네트워크/IO 중단, 잘못된 입력은 무엇인가요?
- 어떤 오류 처리, 유효성 검사, 폴백 메커니즘이 마련되어야 하나요?
-
수락 기준:
- '완료'를 정의하는 결정론적 검증 매트릭스와 테스트 케이스는 무엇인가요?
- 각 수락 기준은 어떻게 검증될 것인가요?
2단계: SPEC.md 작성
해결된 프로젝트 루트(<repo_root>/SPEC.md)에 SPEC.md를 생성하거나 업데이트합니다.
필수 구조
명세 파일은 다음 조건을 충족해야 합니다:
- 크기 요구사항: 최소 300 UTF-8 바이트의 실질적인 콘텐츠.
- 표준 섹션 제목: 각 4개 필수 섹션과 일치하는 코드 블록 외부의 1~3단계 마크다운 제목:
- 범위 및 보안:
Scope,Security,Architecture,Overview,Boundaries,Threat Model, 또는Permissions을 포함하는 제목. - 데이터 계약:
Data Contract,Data Contracts,Schema,Schemas,Interface,Interfaces,API,Types,Payload, 또는Protocol을 포함하는 제목. - 엣지 케이스:
Edge Case,Edge Cases,Error Handling,Failure Mode,Failure Modes,Resilience,Constraints, 또는Fallbacks을 포함하는 제목. - 수락 기준:
Acceptance Criteria,Acceptance Test,Test Matrix,Verification,Testing,Definition of Done, 또는Validation을 포함하는 제목.
- 범위 및 보안:
템플릿
# 명세: <기능 또는 서비스 이름>
## 1. 범위 및 보안
### 목표 및 아키텍처 경계
- 상세 범위 설명...
### 보안 및 위협 모델
- 권한 확인 및 보안 경계...
## 2. 데이터 계약
### 스키마 및 인터페이스
- 타입, API 시그니처, 요청/응답 형식...
## 3. 엣지 케이스 및 복원력
### 오류 처리 및 폴백
- 경계 조건, 입력 유효성 검사, 실패 모드...
## 4. 수락 기준
### 검증 및 테스트 매트릭스
- AT-01: ...
- AT-02: ...
3단계: 개발자 승인 및 구현
SPEC.md초안을 개발자에게 검토 및 명시적 승인을 위해 제시합니다.SPEC.md가 커밋되고 유효한 경우(>= 300 바이트, 모든 4개 섹션 포함),spec-gatekeeper훅이 자동으로 구현 소스 파일 작성을 허용합니다.