구현 스킬 (Implementation Skill)

개요

이 스킬은 작업 계획서를 기반으로 TDD(Test-Driven Development) 방식으로 구현을 진행합니다. 구현과 테스트는 항상 동시에 작성하며, GitHub Actions의 결과를 기준으로 테스트 통과 여부를 판단합니다.

실행 조건

다음과 같은 요청 시 이 스킬이 활성화됩니다:

• "구현 시작해줘"
• "개발 진행해줘"
• "코드 작성해줘"
• "작업 시작"
• "다음 작업 진행"

사전 조건

• docs/tasks/TASK-{번호}-{작업명}.md 작업 계획서가 존재해야 합니다
• 작업 계획서의 상태가 "계획됨" 또는 "진행중"이어야 합니다
• GitHub Actions CI 파이프라인이 설정되어 있어야 합니다

작업 흐름

Phase 1: 작업 계획서 확인

1. 현재 작업 확인

   docs/tasks/ 디렉토리에서 상태가 "계획됨" 또는 "진행중"인 작업 찾기
   

2. 작업 상세 분석

   - 구현 목표 (통과해야 할 인수 테스트)
   - 구현 범위
   - 기술적 접근 방법
   - 테스트 전략
   

3. 관련 문서 로드

   - 명세서: docs/specs/SPEC-{번호}.md
   - 사용자 스토리: docs/user-stories/US-{번호}.md
   - 아키텍처: docs/architecture/ARCHITECTURE.md
   

Phase 2: TDD 구현 사이클

Red-Green-Refactor 사이클을 따릅니다:

┌─────────────────────────────────────────────────────────┐
│                    TDD 구현 사이클                        │
├─────────────────────────────────────────────────────────┤
│                                                         │
│   ┌─────────┐    ┌─────────┐    ┌─────────────┐        │
│   │  RED    │ -> │  GREEN  │ -> │  REFACTOR   │        │
│   │테스트작성│    │구현작성 │    │ 코드개선    │         │
│   └────┬────┘    └────┬────┘    └──────┬──────┘        │
│        │              │                │               │
│        v              v                v               │
│   테스트 실패     테스트 통과      테스트 유지          │
│                                                         │
└─────────────────────────────────────────────────────────┘

Step 1: RED - 테스트 먼저 작성

1. 인수 테스트(AT)를 기반으로 테스트 코드 작성
2. 테스트가 실패하는 것을 확인 (아직 구현이 없으므로)
3. 테스트 코드가 올바른지 검증

테스트 작성 원칙:

• 인수 조건(AC)의 Given-When-Then을 테스트로 변환
• 한 번에 하나의 테스트만 작성
• 테스트 이름은 의도를 명확히 표현

Step 2: GREEN - 최소한의 구현

1. 테스트를 통과시키기 위한 최소한의 코드 작성
2. 완벽한 코드가 아니어도 됨 - 테스트 통과가 목표
3. 로컬에서 테스트 통과 확인

Step 3: REFACTOR - 코드 개선

1. 중복 제거
2. 코드 정리 및 개선
3. 테스트가 여전히 통과하는지 확인

Phase 3: 테스트 실패 처리

테스트 실패 시 처리 흐름:

테스트 실패 발생
       │
       v
명세서와 비교하여 분석
       │
       ├─── 명세에 논리적 오류 있음
       │           │
       │           v
       │    명세 수정 검토 요청
       │    (사용자 확인 필요)
       │
       └─── 명세에 오류 없음
                   │
                   v
            구현 코드 수정
            (테스트는 유지)

핵심 원칙: 테스트보다 구현을 수정

❌ 잘못된 접근:
   테스트가 실패하면 테스트를 수정

✅ 올바른 접근:
   1. 명세 확인
   2. 명세가 맞다면 구현 수정
   3. 명세에 오류가 있다면 사용자에게 알림

Phase 4: GitHub Actions 기반 검증

중요: 테스트 통과 여부는 GitHub Actions 결과를 기준으로 판단합니다.

구현 완료 후 검증 절차

# 1. 변경사항 커밋
git add .
git commit -m "feat: {기능 설명}"

# 2. 푸시
git push origin {브랜치명}

# 3. GitHub Actions 결과 확인
# check-ci.sh 스크립트 또는 GitHub API 사용

CI 결과 확인 방법

check-ci.sh 스크립트 사용 (권장):

이 스킬에는 CI 상태를 자동으로 확인하는 스크립트가 포함되어 있습니다.

스크립트 위치: skills/implementation/scripts/check-ci.sh

# 스크립트 실행 (푸시 후)
./scripts/check-ci.sh

스크립트 기능:

• 현재 커밋에 대한 모든 워크플로우 상태 조회
• 모든 워크플로우가 완료될 때까지 대기 (최대 10분)
• 실패한 워크플로우의 상세 정보 (jobs, steps) 출력
• 성공/실패 결과 반환

필요 환경:

• GITHUB_TOKEN 또는 GH_TOKEN 환경 변수 설정
• GitHub CLI (자동 설치됨)

출력 예시 (성공):

[INFO] Checking CI status...
[INFO] GitHub repository: owner/repo
[INFO] Commit SHA: abc1234
[INFO] Found 2 workflow(s) for commit abc1234
[INFO] Progress: 2 completed, 0 pending (elapsed: 60s)
[INFO] All workflows completed successfully!

출력 예시 (실패):

[ERROR] One or more workflows failed!
[ERROR] Failed workflow: CI Pipeline (#12345)
━━━ Job: test [❌ failure] ━━━
  ✅ Checkout code
  ✅ Install dependencies
  ❌ Run unit tests
[ERROR] Full logs: https://github.com/owner/repo/actions/runs/12345

대안: GitHub CLI 직접 사용:

gh run list --limit 1
gh run view {run-id}

CI 결과에 따른 처리

CI 결과 확인
     │
     ├─── 모든 Job 성공 ✅
     │         │
     │         v
     │    Phase 5로 진행
     │    (작업 완료 처리)
     │
     └─── 실패한 Job 있음 ❌
               │
               v
          실패 원인 분석
               │
               ├─── 테스트 실패
               │         │
               │         v
               │    Phase 3로 돌아가서
               │    테스트 실패 처리
               │
               ├─── 빌드 실패
               │         │
               │         v
               │    빌드 오류 수정
               │
               └─── 린트 실패
                         │
                         v
                    코드 스타일 수정

Phase 5: 작업 완료 처리

5.1 작업 계획서 상태 업데이트

# TASK-{번호} 상태 변경
상태: 계획됨 → 완료

## 완료 조건 체크
1. [x] 구현 코드 작성 완료
2. [x] 단위 테스트 작성 및 통과
3. [x] 통합 테스트 작성 및 통과
4. [x] GitHub Actions CI 통과
5. [x] 인수 테스트 통과 (AT-{번호}.x)
6. [x] 추적성 매트릭스 업데이트

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

| US ID | AT ID | TASK ID | 구현 상태 | CI 상태 | 완료일 |
|-------|-------|---------|---------|--------|-------|
| US-001 | AT-001.1 | TASK-001 | ✅ | ✅ | 2024-01-15 |

5.3 커밋 메시지 규칙

feat: {기능 설명}

- {변경 사항 1}
- {변경 사항 2}

Closes: TASK-{번호}
Related: US-{번호}, AT-{번호}.x

반복 사이클

테스트가 모두 통과할 때까지 반복합니다:

┌────────────────────────────────────────────────────────────┐
│                       구현 반복 사이클                       │
├────────────────────────────────────────────────────────────┤
│                                                            │
│   코드 작성 → 로컬 테스트 → 커밋 → 푸시 → CI 확인          │
│       ↑                                         │          │
│       │                                         │          │
│       │         실패 시                         │          │
│       └─────────────────────────────────────────┘          │
│                                                            │
│                     성공 시                                 │
│                        ↓                                   │
│                   작업 완료                                 │
│                                                            │
└────────────────────────────────────────────────────────────┘

산출물

이 스킬 실행 후:

코드

1. 기능 구현 코드
2. 테스트 코드 (단위/통합/E2E)

문서 업데이트

3. docs/tasks/TASK-{번호}.md 상태 업데이트
4. docs/traceability-matrix.md 업데이트

Git

5. 기능 구현 커밋
6. GitHub Actions CI 통과

주의사항

1. 테스트와 구현 동시 작성: 절대로 테스트 없이 구현만 작성하지 않습니다.

2. CI 기준 판단: 로컬 테스트가 아닌 GitHub Actions 결과로 최종 판단합니다.

3. 테스트 수정 금지: 테스트 실패 시 테스트를 수정하지 않고, 명세 확인 후 구현을 수정합니다.

4. 반복 필수: CI가 통과할 때까지 수정-커밋-푸시-확인을 반복합니다.

5. 작은 커밋: 작은 단위로 자주 커밋하여 문제 발생 시 롤백을 용이하게 합니다.

다음 단계

작업이 완료되면:

• task-planning 스킬로 다음 작업 확인
• 모든 작업이 완료되었다면 릴리스 준비