[SDD Plugin] SDD Plugin의 전체 구조와 사용법

개요

SDD(Spec-Driven Development) Plugin은 Claude Code용 플러그인으로, GitHub Issue 기반의 구조화된 개발 프로세스를 통해 AI와 협업하여 체계적으로 개발할 수 있도록 도와줍니다. 이번 포스트에서는 SDD Plugin의 4단계 프로세스, 명령어, GitHub 연동, 사용법까지 한 번에 살펴봅시다.

이 플러그인을 만들게 된 배경은 AI 코딩의 함정과 해결 방향에서, 개발 과정은 프로토타입에서 완성까지에서, 적용한 엔지니어링 원리는 AI 엔지니어링 4가지 패러다임으로 분석에서 다루고 있습니다.

완성된 플러그인은 GitHub에서 공개되어 있습니다. 관심 있으신 분들은 아래 링크를 참고해 주세요.

GitHub: https://github.com/dev-yakuza/deku-claude-plugins

SDD 프로세스란

SDD(Spec-Driven Development)는 사양(Spec) 중심의 개발 방법론입니다. 코드를 작성하기 전에 충분한 분석과 설계를 거치고, 구현은 TDD(Test-Driven Development) 방식으로 진행하도록 했습니다. 이렇게 하면 AI가 작성한 코드라도 명확한 요구사항과 설계에 기반하기 때문에, 유지보수성과 확장성이 높아집니다.

4단계 프로세스

1. 요구사항 분석 (What/Why) → 2. 설계 (How) → 3. 구현 (TDD) → 4. 테스트 (E2E/QA)

Stage 1: 요구사항 분석 (What / Why)

무엇을 만들 것인지, 왜 필요한지에만 집중합니다. 기술적인 구현 방법(How)은 이 단계에서 논의하지 않습니다.

요청 유형 분류 (새 기능 / 기능 개선 / 버그 수정 / 리팩터링)
기능 목록 도출
우선순위 결정

이 단계의 핵심은 What/Why와 How를 분리하는 것입니다. AI는 How에 대한 답을 빨리 내놓으려는 경향이 있기 때문에, 의도적으로 기술적 논의를 차단합니다.

Stage 2: 설계 (How)

1단계에서 정리한 요구사항을 바탕으로 어떻게 구현할지 설계합니다.

기존 코드베이스 탐색 (전용 탐색 에이전트 활용)
영향 범위 파악
파일 구조 및 데이터 모델 설계
제약사항 및 리스크 식별
PR 단위 분리 (큰 기능은 여러 PR로 나눔)

규모가 큰 기능의 경우, 이 단계에서 자동으로 Child Issue를 생성하여 각 PR을 독립적으로 관리합니다.

Stage 3: 구현 (TDD)

PR 단위로 Red → Green → Refactor 사이클을 반복합니다.

3-0. PR 킥오프: 테스트 계획 + 구현 계획 수립
3-1. Red: 실패하는 테스트 작성
3-2. Green: 테스트를 통과하는 최소 구현
3-3. Refactor: 코드 개선
3-4. PR 생성 및 코드 리뷰
→ 다음 PR로 반복

각 단계에서 AI 자체 리뷰 + 독립 에이전트 리뷰(최대 3라운드) + 사용자 확인의 이중 검증을 거칩니다.

Stage 4: 테스트 (E2E / QA)

3단계에서 Unit/UI 테스트는 이미 완료되었으므로, 이 단계에서는 E2E 테스트와 QA에 집중합니다.

4-0. 테스트 셋업: 기존 테스트 환경 감지 및 설정
4-1. E2E 테스트: AI가 E2E 테스트 코드를 작성하고 실행
4-2. QA 체크리스트: 수동 테스트용 체크리스트 생성
4-3. 수동 QA: 사용자가 체크리스트 기반으로 직접 테스트
4-4. 결과 리뷰: 실패 항목은 Stage 3로 돌아가 TDD 수정

Parent Issue(여러 Child Issue가 있는 경우)에서는 모든 Child Issue가 완료된 후에 전체 기능에 대한 E2E 테스트를 진행합니다.

각 단계의 공통 패턴

모든 단계는 동일한 패턴을 따릅니다.

① 입력 → ② AI 작업 → ③ AI 자체 리뷰 → ④ 독립 에이전트 리뷰 → ⑤ 사용자 확인 → 다음 단계

명령어 목록

SDD Plugin은 /sdd 뒤에 명령어를 붙여서 사용합니다. 4단계 프로세스를 실행하는 핵심 명령어와, 작업을 보조하는 유틸리티 명령어로 나뉩니다.

명령어	설명
`/sdd init [lang]`	저장소 초기화 (Issue 템플릿, 라벨 생성)
`/sdd analyze <issue>`	Stage 1: 요구사항 분석 (What/Why)
`/sdd design <issue>`	Stage 2: 설계 (How)
`/sdd implement <issue>`	Stage 3: TDD 구현 (Red → Green → Refactor)
`/sdd test <issue>`	Stage 4: E2E/QA 테스트
`/sdd resume <issue>`	현재 단계를 자동 감지하고 이어서 진행
`/sdd status <issue>`	진행 상태 확인
`/sdd review <issue>`	현재 단계 산출물에 대한 AI 리뷰
`/sdd rollback <issue>`	이전 단계로 되돌리기
`/sdd help`	사용법 안내

사용법

실제로 SDD Plugin을 사용하는 흐름을 순서대로 살펴봅시다.

1. 설치

먼저 Claude Code에서 플러그인을 설치합니다.

claude plugin add dev-yakuza/deku-claude-plugins

2. 저장소 초기화

설치가 완료되면 프로젝트 저장소에서 초기화를 실행합니다. 언어를 지정하면 해당 언어의 Issue 템플릿이 설정됩니다.

/sdd init ko        # 한국어 템플릿으로 초기화

이 명령어를 실행하면 다음이 설정됩니다.

.github/ISSUE_TEMPLATE/에 한국어 Issue 템플릿 복사
.github/.sdd-lang에 언어 설정 저장
GitHub 라벨 생성 (sdd:analyze, sdd:design, sdd:implement, sdd:test, sdd:done)

3. Issue 생성

GitHub에서 SDD 템플릿을 사용하여 Issue를 생성합니다. 4가지 템플릿 중 적절한 것을 선택합니다.

새 기능
기능 개선
버그 수정
리팩터링

템플릿에는 요청 배경(Why), 기능 설명(What), **완료 기준(DoD)**이 구조화되어 있어서, AI가 분석에 필요한 정보를 빠짐없이 받을 수 있습니다.

4. 개발 프로세스 실행

Issue가 준비되면, 각 단계를 순서대로 실행합니다. Issue 번호만 넘기면 됩니다.

# Stage 1: 요구사항 분석
/sdd analyze 123

# Stage 2: 설계
/sdd design 123

# Stage 3: 구현 (TDD)
/sdd implement 123

# Stage 4: 테스트
/sdd test 123

각 단계에서 AI가 작업을 수행하고, 자체 리뷰 후 사용자에게 확인을 요청합니다. 사용자가 승인하면 산출물이 Issue comment에 저장되고 다음 단계로 넘어갑니다.

5. 작업 이어서 하기

Claude Code의 대화가 끊기거나 새 세션을 시작한 경우, resume 명령어를 사용하면 Issue의 라벨과 산출물을 확인하여 중단된 지점부터 이어서 작업할 수 있습니다.

/sdd resume 123     # 자동으로 현재 단계를 감지하고 이어서 진행

6. 진행 상태 확인

현재 Issue가 어느 단계까지 진행되었는지 확인하고 싶을 때 사용합니다.

/sdd status 123

다음과 같은 형식으로 각 단계의 완료 여부와 현재 진행 상황을 보여줍니다.

Issue #123: 사용자 프로필 페이지 개발
Stage: implement
- [x] Analyze: 완료
- [x] Design: 완료
- [ ] Implement: PR #1 진행 중
- [ ] Test: 미시작

GitHub 연동

SDD Plugin의 모든 데이터는 GitHub에 저장됩니다. 별도의 데이터베이스나 파일 관리가 필요 없습니다.

데이터 저장 위치

각 단계의 산출물이 어디에 저장되는지 정리하면 다음과 같습니다.

데이터	저장 위치
요구사항 (입력)	Issue body
분석 산출물	Issue comment
설계 산출물	Issue comment
현재 단계	Issue label
구현 결과	Pull Request
테스트 결과	Issue comment

라벨로 진행 상태 추적

Issue에 붙는 라벨로 현재 어느 단계에 있는지 한눈에 파악할 수 있습니다. GitHub의 Issue 목록에서 라벨 필터링만으로 전체 작업 현황을 관리할 수 있어 편합니다.

라벨	단계
`sdd:analyze`	요구사항 분석 중
`sdd:design`	설계 중
`sdd:implement`	구현 중
`sdd:test`	테스트 중
`sdd:done`	완료
`sdd:child`	Child Issue

각 단계가 완료되면 자동으로 이전 라벨을 제거하고 다음 라벨을 추가합니다.

산출물 마커

“다음 단계에서 이전 단계의 결과를 어떻게 찾는가?”가 궁금하실 수 있습니다. Issue comment에 저장되는 산출물에는 HTML 주석 마커가 포함되어 있어서, 이 마커를 통해 필요한 산출물을 정확히 식별합니다.

<!-- sdd:analyze:output -->
분석 결과 내용...
<!-- /sdd:analyze:output -->

이 마커를 통해 다음 단계에서 이전 단계의 산출물을 자동으로 읽어올 수 있고, resume 명령어도 이 마커를 확인하여 진행 상태를 판단합니다.

Multi-PR 워크플로우

규모가 큰 기능은 하나의 PR로 처리하기 어렵습니다. SDD Plugin은 Parent/Child Issue 구조로 이를 해결합니다.

Parent Issue #10: 사용자 프로필 기능
├── Child Issue #11: 프로필 API 연동 (PR #1)
├── Child Issue #12: 프로필 UI 구현 (PR #2)
└── Child Issue #13: 프로필 이미지 업로드 (PR #3)

설계 단계에서 여러 PR이 필요하다고 판단되면, 자동으로 Child Issue를 생성합니다.
구현 단계에서 각 Child Issue를 독립적으로 TDD 사이클을 진행합니다.
테스트 단계에서 모든 Child Issue가 완료된 후, Parent Issue에서 전체 E2E 테스트를 실행합니다.

핵심 설계 결정

이 플러그인을 만들면서 몇 가지 중요한 설계 결정을 내렸습니다.

1. GitHub 네이티브

별도의 데이터베이스 없이 GitHub의 기능만 활용합니다. Issue body에 요구사항, Issue comment에 산출물, Issue label에 진행 상태, PR에 구현 결과를 저장합니다. 이렇게 하면 대화가 끊겨도 GitHub에서 모든 맥락을 복원할 수 있습니다.

2. 선언형 프로세스

코드 로직이 아닌 Markdown으로 프로세스를 기술합니다. SKILL.md 파일 하나가 AI의 행동을 제어합니다. 프로세스를 수정하고 싶으면 Markdown 파일만 편집하면 됩니다.

3. 다국어 지원

번역 키가 아닌 언어별 전체 템플릿을 별도로 관리합니다. 단순 번역이 아니라 각 언어권에 맞는 표현을 사용할 수 있습니다. 현재 한국어, 영어, 일본어를 지원합니다.

완료

이번 포스트에서는 SDD Plugin의 4단계 프로세스, 명령어, GitHub 연동, 사용법을 살펴보았습니다.

핵심은 What/Why를 먼저 정리하고(분석), How를 설계한 다음(설계), TDD로 구현하고(구현), E2E/QA로 검증하는(테스트) 것입니다. 이 모든 과정이 GitHub Issue와 자연스럽게 연결되어, 대화가 끊겨도 언제든지 이어서 작업할 수 있습니다.

이 플러그인이 어떤 과정을 거쳐 만들어졌는지 궁금하시다면 SDD Plugin 개발 과정 — 프로토타입에서 완성까지를 참고해 주세요.