SDD Workflow Skill

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

워크플로우 개요

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

---

환경 요구사항

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

GitHub CLI (gh) 자동 설정

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

1. 자동 설치: gh 명령어가 없으면 자동으로 설치

   • Linux: apt, yum, pacman 또는 바이너리 직접 설치
   • macOS: brew 또는 바이너리 직접 설치

2. 자동 인증: 다음 환경변수 중 하나를 사용

   • 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. 상태 확인: 각 명세의 상태를 확인
   • ⏳ 대기: 구현 대기 중 (작업 대상)
   • 🚧 진행중: 이미 작업 중
   • ✅ 완료: 완료됨
3. 의존성 확인: 의존성 그래프에서 선행 조건 확인

1.2 다음 작업 선택 기준

1. 의존성이 해결된 명세 중 가장 높은 우선순위
2. ⏳ 대기 상태인 명세
3. 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. 작업을 적절한 크기로 분할 (각 단계는 1-2시간 분량)
3. 예상 변경 파일 목록
4. 검증 방법
5. 롤백 계획

2.2 작업 분할 원칙

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

---

Phase 3: 구현 (Implement)

3.1 구현 순서

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

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

스크립트 동작:

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

수동 확인 (필요시):

# 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 수정 및 재시도

1. 실패 원인 분석
2. 코드 수정
3. 재커밋 및 push
4. CI 재확인

최대 재시도 횟수: 3회

3회 실패 시:

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

---

Phase 6: 완료

6.1 최종 확인

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

6.2 다음 작업 안내

현재 작업 완료 후:

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

---

실행 예시

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

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

---

주의사항

• 명세 없이 구현 금지: 항상 명세가 먼저
• 매트릭스 동기화: 모든 변경은 즉시 매트릭스에 반영
• 점진적 진행: 한 번에 하나의 명세만 구현
• 실패 시 중단: 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