Community생산성 & 협업github.com

spec-gatekeeper

소스 코드 작성을 시작하기 전에 4가지 질문으로 구성된 개발자 인터뷰를 진행하고, 결정론적인 4개 섹션의 SPEC.md (범위 및 보안, 데이터 계약, 엣지 케이스, 수락 기준)를 작성합니다.

spec-gatekeeper란 무엇인가요?

Spec-Gatekeeper는 Spec 중심 개발(Spec-Driven Development, SDD) 워크플로우를 지원하는 스킬입니다. 이 스킬은 소스 코드 작성이 차단되었거나, 새로운 기능이나 서비스, 주요 리팩터링을 시작할 때 사용됩니다. 주요 기능은 구현 전에 구조화된 아키텍처 계약을 수립하여 명확성을 확보하고 요구사항 변경에 따른 설계 변화(드리프트)를 방지합니다. 작업 흐름은 세 단계로 구성됩니다: 1) 4가지 핵심 질문(범위 및 보안, 데이터 계약, 엣지 케이스 및 복원력, 수락 기준)을 통해 개발자 인터뷰를 진행하고, 2) 인터뷰 결과를 바탕으로 프로젝트 루트에 SPEC.md 파일을 작성하며(최소 300바이트 이상, 4개 필수 섹션 포함), 3) 개발자 승인 후 구현을 허용합니다. 이 스킬은 코드 품질, 보안, 그리고 팀 커뮤니케이션을 향상시키며, Claude Code, Cursor, Codex와 같은 AI 에이전트 플랫폼에서 원활하게 사용할 수 있습니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/dansierrasam79/spec-gatekeeper/tree/main/skills/spec-gatekeeper

Installed? Explore more 생산성 & 협업 skills: steipete/gemini, steipete/gh-issues, steipete/skill-creator · View all 6 →

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

Spec-Gatekeeper: Spec 중심 개발 워크플로우

spec-gatekeeper에 의해 소스 코드 작성이 차단되었거나, 새로운 기능, 서비스, 주요 리팩터링을 시작할 때 이 스킬을 사용하세요.

Spec 중심 개발(Spec-Driven Development, SDD)은 구현 전에 합의된 구조화된 아키텍처 계약을 요구하여 명확성을 확보하고 요구사항 변경에 따른 설계 변화(드리프트)를 제거합니다.


워크플로우 단계

1단계: 4가지 질문으로 구성된 개발자 인터뷰 진행

코드를 작성하거나 파일을 스텁하기 전에, 개발자에게 다음 4가지 집중 질문을 하거나(또는 기존 요구사항에서 답변을 추출하여 확인을 요청하세요):

  1. 범위 및 보안:

    • 이 작업의 핵심 목표와 명시적 비목표(Non-goals)는 무엇인가요?
    • 관련된 아키텍처 구성 요소 또는 시스템 경계는 무엇인가요?
    • 보안, 권한, 인증, 또는 샌드박스 제약 조건은 무엇인가요?
  2. 데이터 계약:

    • 정확한 스키마, API 인터페이스, 타입, 프로토콜 형태는 무엇인가요?
    • 정확한 입력 매개변수와 예상 출력 페이로드는 무엇인가요?
  3. 엣지 케이스 및 복원력:

    • 주요 실패 모드, 네트워크/IO 중단, 잘못된 입력은 무엇인가요?
    • 어떤 오류 처리, 유효성 검사, 폴백 메커니즘이 마련되어야 하나요?
  4. 수락 기준:

    • '완료'를 정의하는 결정론적 검증 매트릭스와 테스트 케이스는 무엇인가요?
    • 각 수락 기준은 어떻게 검증될 것인가요?

2단계: SPEC.md 작성

해결된 프로젝트 루트(<repo_root>/SPEC.md)에 SPEC.md를 생성하거나 업데이트합니다.

필수 구조

명세 파일은 다음 조건을 충족해야 합니다:

  1. 크기 요구사항: 최소 300 UTF-8 바이트의 실질적인 콘텐츠.
  2. 표준 섹션 제목: 각 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단계: 개발자 승인 및 구현

  1. SPEC.md 초안을 개발자에게 검토 및 명시적 승인을 위해 제시합니다.
  2. SPEC.md가 커밋되고 유효한 경우(>= 300 바이트, 모든 4개 섹션 포함), spec-gatekeeper 훅이 자동으로 구현 소스 파일 작성을 허용합니다.

관련 스킬