name	sdd-workflow
description	SDD(Spec Driven Development) 자동화 워크플로우를 실행합니다. 사용자가 "다음 작업 진행해줘", "구현 시작해줘", "SDD 워크플로우 실행" 등을 요청할 때 활성화됩니다. 작업 분할, 계획서 작성, 구현, CI 검증까지 자동으로 진행합니다.

SDD Workflow Skill

이 스킬은 Spec Driven Development 워크플로우를 자동으로 실행합니다.

워크플로우 개요

1. 분석 → 2. 계획 → 3. 구현 → 4. Push → 5. CI 확인 → 6. 수정(필요시)

환경 요구사항

이 워크플로우는 사용자 개입 없이 자동으로 실행됩니다.

GitHub CLI (gh) 자동 설정

CI 상태 확인을 위해 GitHub CLI가 필요합니다. 스크립트가 자동으로 처리합니다:

자동 설치: gh 명령어가 없으면 자동으로 설치
- Linux: apt, yum, pacman 또는 바이너리 직접 설치
- macOS: brew 또는 바이너리 직접 설치
자동 인증: 다음 환경변수 중 하나를 사용
- GITHUB_TOKEN: GitHub Personal Access Token
- GH_TOKEN: gh CLI 기본 환경변수

필수 환경변수

# 다음 중 하나 설정 (repo, workflow 권한 필요)
export GITHUB_TOKEN="ghp_xxxxxxxxxxxx"
# 또는
export GH_TOKEN="ghp_xxxxxxxxxxxx"

권한 요구사항

토큰에 필요한 권한:

repo: 저장소 접근
workflow: 워크플로우 실행 조회

Phase 1: 분석 (Analyze)

1.1 추적성 매트릭스 분석

specs/TRACEABILITY.md 파일을 읽어서 현재 상태를 파악합니다:

우선순위 확인: 구현 우선순위 섹션에서 다음 작업 식별
상태 확인: 각 명세의 상태를 확인
- ⏳ 대기: 구현 대기 중 (작업 대상)
- 🚧 진행중: 이미 작업 중
- ✅ 완료: 완료됨
의존성 확인: 의존성 그래프에서 선행 조건 확인

1.2 다음 작업 선택 기준

의존성이 해결된 명세 중 가장 높은 우선순위
⏳ 대기 상태인 명세
Phase 순서 준수 (Phase 1 → Phase 2 → Phase 3)

Phase 2: 계획 (Plan)

2.1 계획서 작성

선택한 명세에 대해 specs/plans/PLAN-XXX.md 파일을 생성합니다.

계획서 ID 규칙:

관련 명세 ID를 기반으로 생성
예: FEAT-001 구현 → PLAN-001

계획서 포함 내용:

목표 정의
작업을 적절한 크기로 분할 (각 단계는 1-2시간 분량)
예상 변경 파일 목록
검증 방법
롤백 계획

2.2 작업 분할 원칙

단일 책임: 각 단계는 하나의 명확한 목표
테스트 가능: 각 단계 완료 후 검증 가능
되돌림 가능: 문제 시 이전 단계로 롤백 가능
적정 크기: 너무 크지도, 너무 작지도 않게

Phase 3: 구현 (Implement)

3.1 구현 순서

계획서의 각 단계를 순서대로 실행
각 단계 완료 시 체크박스 업데이트
관련 테스트가 있다면 함께 작성
추적성 매트릭스 상태 업데이트 (⏳ 대기 → 🚧 진행중)

3.2 코드 작성 규칙

명세 ID를 주석으로 포함: @spec FEAT-001
기존 패턴과 일관성 유지
에러 처리 포함
필요한 경우 타입 정의 추가

3.3 추적성 매트릭스 업데이트

구현 완료 후 specs/TRACEABILITY.md 업데이트:

구현 파일 경로 추가
테스트 파일 경로 추가
상태를 🧪 테스트중 또는 ✅ 완료로 변경

Phase 4: Push 및 CI 확인

4.1 Git 커밋

git add .
git commit -m "feat(SPEC-ID): 구현 설명"

커밋 메시지 형식:

feat(FEAT-001): Add user authentication
fix(API-002): Fix response format
docs(PLAN-001): Add implementation plan

4.2 Push

git push -u origin <current-branch>

4.3 CI 상태 확인

Push 후 GitHub Actions CI 완료를 자동으로 대기합니다.

자동화 스크립트 사용:

# 스크립트가 gh CLI 설치/인증/모니터링을 모두 처리
.claude/skills/sdd-workflow/scripts/check-ci.sh

스크립트 동작:

gh CLI 설치 확인 (없으면 자동 설치)
GITHUB_TOKEN/GH_TOKEN으로 자동 인증
Push 후 10초 대기 (워크플로우 시작 대기)
30초 간격으로 상태 확인 (최대 10분)
완료 시 결과 반환

수동 확인 (필요시):

# CI 실행 상태 확인
gh run list --limit 1

# CI 완료 대기
gh run watch

Phase 5: CI 실패 시 수정

5.1 실패 분석

# 실패한 run의 로그 확인
gh run view <run-id> --log-failed

5.2 수정 및 재시도

실패 원인 분석
코드 수정
재커밋 및 push
CI 재확인

최대 재시도 횟수: 3회

3회 실패 시:

현재까지의 시도 내용 요약
사용자에게 도움 요청
추적성 매트릭스 상태를 ❌ 실패로 변경

Phase 6: 완료

6.1 최종 확인

CI 통과
추적성 매트릭스 업데이트
계획서 체크박스 모두 완료

6.2 다음 작업 안내

현재 작업 완료 후:

완료된 작업 요약 출력
다음 우선순위 작업 안내
사용자에게 계속 진행할지 확인

실행 예시

사용자가 "다음 작업 진행해줘"라고 요청하면:

specs/TRACEABILITY.md 분석
다음 작업 식별 (예: FEAT-001)
specs/features/FEAT-001.md 명세 읽기
specs/plans/PLAN-001.md 계획서 작성
계획대로 구현
추적성 매트릭스 업데이트
Git commit & push
CI 완료 대기
결과 보고

주의사항

명세 없이 구현 금지: 항상 명세가 먼저
매트릭스 동기화: 모든 변경은 즉시 매트릭스에 반영
점진적 진행: 한 번에 하나의 명세만 구현
실패 시 중단: 3회 실패 시 사용자 개입 요청

참고 파일

계획서 템플릿: .claude/skills/sdd-workflow/plan-template.md
추적성 매트릭스: specs/TRACEABILITY.md
CI 워크플로우: .github/workflows/ci.yml
CI 상태 확인 스크립트: .claude/skills/sdd-workflow/scripts/check-ci.sh

sdd-workflow

Install Skill

SKILL.md