[SDD Plugin] 개발 과정 — 프로토타입에서 완성까지

개요

SDD(Spec-Driven Development) Plugin은 Claude Code용 플러그인으로, GitHub Issue 기반의 4단계 프로세스(분석→설계→구현→테스트)를 통해 AI와 체계적으로 협업할 수 있도록 도와줍니다. 이번 포스트에서는 이 플러그인이 어떤 과정을 거쳐 만들어졌는지, 각 Phase에서 무엇을 고민하고 어떤 시행착오를 겪었는지 공유합니다.

SDD Plugin의 전체 구조와 사용법은 SDD Plugin의 전체 구조와 사용법에서, 만들게 된 배경은 AI 코딩의 함정과 해결 방향에서, 적용한 엔지니어링 원리는 AI 엔지니어링 4가지 패러다임으로 분석에서 다루고 있습니다.

파일 구조

먼저 완성된 플러그인의 파일 구조를 살펴봅시다. 개발 과정을 따라가면서 이 구조가 어떻게 만들어졌는지 이해하는 데 도움이 됩니다.

sdd-plugin/
├── README.md
├── .claude-plugin/
│   └── marketplace.json               # 마켓플레이스 메타데이터
└── plugins/sdd-plugin/
    ├── .claude-plugin/
    │   └── plugin.json                # 플러그인 메타데이터
    └── skills/sdd/
        ├── SKILL.md                   # 핵심: 명령어 라우팅 + 공통 정의
        ├── commands/                  # 각 명령어의 상세 프로세스
        │   ├── analyze.md
        │   ├── design.md
        │   ├── implement.md
        │   ├── test.md
        │   ├── resume.md
        │   ├── status.md
        │   ├── review.md
        │   ├── ai-review.md
        │   ├── init.md
        │   ├── rollback.md
        │   └── help.md
        └── templates/                 # 언어별 템플릿
            ├── en/                    # 영어
            ├── ko/                    # 한국어
            └── ja/                    # 일본어

가장 중요한 파일은 SKILL.md입니다. 이 파일이 Claude Code가 “어떤 명령어가 들어오면 어떤 파일을 읽고 어떻게 동작해야 하는지”를 정의합니다. 일반적인 프로그래밍 언어로 로직을 작성하는 것이 아니라, Markdown으로 프로세스를 기술하면 AI가 이를 따르는 구조입니다.

Phase 1: 기반 구축

가장 먼저 Claude Code 플러그인의 기본 구조를 만들었습니다.

만든 것들

plugin.json: 플러그인 이름, 버전, 작성자 등 메타데이터
SKILL.md: 명령어 라우팅과 공통 정의 (라벨, 마커, 언어 설정 등)
영어 Issue 템플릿 4종 (버그 수정, 새 기능, 기능 개선, 리팩터링)
분석/설계 산출물 템플릿

이 단계에서 고민한 것

처음에는 모든 프로세스를 SKILL.md 하나에 다 넣었습니다. 하지만 파일이 금방 수백 줄이 되면서, Claude Code가 매번 전체 내용을 컨텍스트에 로드하는 것이 비효율적이라는 것을 깨달았습니다.

그래서 SKILL.md는 라우터 역할만 하도록 바꾸고, 각 명령어의 상세 프로세스는 commands/ 디렉토리의 별도 파일로 분리했습니다. /sdd analyze를 실행하면 SKILL.md가 commands/analyze.md를 읽도록 안내하는 식입니다.

Phase 2: 다국어 지원

글로벌 팀에서 사용할 수 있도록 일본어와 한국어 지원을 추가했습니다.

만든 것들

언어별 Issue 템플릿 (한국어, 일본어)
언어별 산출물 템플릿
언어 설정 저장 (/sdd init ko로 초기화하면 .github/.sdd-lang에 저장)

번역이 아닌 현지화

단순한 번역이 아니라 각 언어권의 개발 문화에 맞게 용어를 선택했습니다. 예를 들어 일본어 Issue 템플릿에서는 バグ修正, 新機能, 機能改善, リファクタリング이라는 용어를 사용합니다.

번역 키를 사용하는 대신 언어별 전체 템플릿을 별도 파일로 관리하기로 했습니다. 파일이 좀 더 많아지지만, 각 언어에 맞는 자연스러운 표현을 사용할 수 있고, 특정 언어에만 필요한 설명을 추가하기도 쉽습니다.

Phase 3: Issue 템플릿 개선

실제로 사용해 보면서 GitHub Issue 템플릿을 개선했습니다.

개선 포인트

처음에는 Issue 템플릿이 너무 자유로웠습니다. 제목과 본문만 있는 단순한 형태였는데, 이러면 사람마다 적는 내용이 달라서 AI가 분석할 때 필요한 정보가 빠지는 경우가 많았습니다.

그래서 요청 배경(Why), 기능 설명(What), **완료 기준(DoD)**을 구조화하여 입력하도록 템플릿을 개선했습니다.

name: '새 기능'
description: '새 기능을 요청합니다'
labels: ['sdd:analyze']
body:
  - type: textarea
    id: background
    attributes:
      label: '요청 배경'
      description: '이 기능이 왜 필요한가요?'
      value: |
        - 문제 / 동기:
        - 사용자 피드백: (있다면)

  - type: textarea
    id: description
    attributes:
      label: '기능 설명'
      description: '무엇을 만들어야 하나요?'
      value: |
        - 한 줄 요약:
        - 상세 설명:
        - 대상 화면:
        - 참고 자료:

  - type: textarea
    id: done
    attributes:
      label: '완료 기준 (Definition of Done)'
      description: '이 기능이 완료된 것으로 간주되는 기준은?'
      value: |
        - [ ] 기준 1:
        - [ ] 기준 2:

이렇게 하면 Issue를 작성하는 시점에 필요한 정보가 빠짐없이 들어가고, AI가 분석할 때도 구조화된 입력을 받을 수 있습니다.

Phase 4: resume 명령어 추가

실제로 사용하다 보니 가장 불편한 점은 대화가 끊겼을 때 이어서 작업하기 어렵다는 것이었습니다. 특히 implement 단계는 여러 PR에 걸쳐 진행되기 때문에, 대화가 끊길 가능성이 높습니다.

해결 방법

이 문제를 해결하기 위해 /sdd resume 명령어를 추가했습니다.

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

resume 명령어는 다음과 같은 로직으로 동작합니다.

Issue 라벨(sdd:analyze, sdd:design 등)로 현재 단계 판단
Issue comment에서 기존 산출물(분석 결과, 설계 결과) 확인
관련 PR 상태 확인
Parent Issue인 경우, Child Issue들의 진행 상태 확인
중단된 지점을 사용자에게 보고 후 확인을 받고 이어서 실행

모든 산출물이 GitHub에 마커와 함께 저장되어 있기 때문에, 대화가 완전히 새로 시작되어도 GitHub에서 맥락을 복원할 수 있습니다. 이것이 “GitHub 네이티브” 설계의 가장 큰 장점이었습니다.

실제로 사용해 보기

간단한 프로젝트를 만들어서 전체 프로세스를 테스트해 보았습니다.

# 1. 초기화
/sdd init ko

# 2. Issue 작성 (GitHub에서 템플릿 사용)

# 3. 분석
/sdd analyze 1

# 4. 설계 (분석 완료 후 이어서 진행)
/sdd design 1

# 5. 구현 (TDD)
/sdd implement 1

# 6. 테스트
/sdd test 1