PR Preflight — 변경 패키지 범위 3-레이어 테스트 게이트#

한마디로 (비개발자용)#

코드를 팀에 합치기 전, 이번에 바뀐 부분만 골라서 자동으로 검사해 주는 "출고 전 품질 검사대"입니다. 비행기가 이륙 전에 점검 목록(pre-flight check)을 확인하듯, 문제가 발견되면 합치는 작업 자체를 막아 줍니다. 검사를 통과해야만 다음 단계로 넘어갈 수 있어, 망가진 코드가 슬쩍 들어가는 것을 사전에 차단합니다.

무엇을·언제 (비개발자용)#

• 무엇을 해 주나요
  • 이번에 변경된 부분만 똑똑하게 골라 검사합니다. 바뀌지 않은 곳까지 전부 돌리지 않아 시간을 아낍니다.
  • 세 단계 검사(작은 단위 → 화면 → 실제 동작)를 순서대로 돌리고, 하나라도 실패하면 즉시 멈추고 보고서를 보여 줍니다.
  • 검사를 건너뛰려면 반드시 명시적으로 사유를 남겨야 하며, 기록이 남아 나중에 확인할 수 있습니다.
• 언제 작동하나요
  • 변경 사항을 팀에 합치자고 요청(PR)하기 직전에 자동으로 켜집니다.
  • "PR 올리기 전에 테스트", "pre-flight check", "변경 패키지 테스트" 같은 요청을 할 때.
  • 자동 개발 흐름(/dev:run)의 마지막 점검 단계에서도 자동으로 불려 옵니다.

핵심 용어 (비개발자용)#

모든 PR 은 본 스킬 PASS 없이 생성 금지 입니다. /pr:preflight 커맨드 또는 /dev:run Step 8 자동 호출로 트리거됩니다.

왜 필요한가#

1. 전체 레포 테스트는 느리다 — 변경 없는 패키지까지 돌리면 수 분 낭비
2. Regression 의 즉시 발견 — PR 올린 뒤 CI 에서 발견하면 feedback loop 이 길어짐
3. 3 레이어 일관 보장 — unit 만 돌리고 widget 을 건너뛰는 개발자 습관 차단
4. 선언적 정책 — 스킵 조건이 명시적(--skip-tests, --skip-integration)이어야 감사 가능

트리거#

• /pr:preflight 커맨드
• /dev:run Step 8 자동 호출
• /e2e:kick-off 완료 후 다음 단계 제안
• 사용자 요청: "PR 올리기 전에 테스트", "pre-flight check", "변경 패키지 테스트"

전제#

• 프로젝트가 melos 모노레포 (kobic/good-teacher 표준)
• 각 패키지에 pubspec.yaml + (해당되면) test/ 디렉토리
• flutter_test, bloc_test, mocktail 등 의존성 설정
• BDD dual 사용 시 bdd_test_gen 생성물이 최신 상태 (dart run build_runner build)

동작#

1. Base 브랜치 결정#

우선순위:

1. --base 옵션 명시 값
2. 현재 브랜치의 upstream (git rev-parse --abbrev-ref '@{u}')
3. development (조직 기본 base)
4. main (fallback)

2. 변경 패키지 자동 감지#

# 1) 변경 파일 목록
git diff --name-only  " $BASE " ..HEAD

# 2) 각 파일 경로를 위로 올라가며 pubspec.yaml 을 만나는 첫 디렉토리 = 패키지 루트
# 3) pubspec.yaml 의 name 필드 → melos scope 이름

조직 모노레포 경로 매칭 힌트:

변경 없음 → 조기 종료 (PR 에 코드 변경이 없다는 뜻, 게이트 skip).

3. 레이어별 실행 매트릭스#

Integration 조건부 실행 규칙:

• --with-integration 플래그 → 변경 패키지의 모든 integration 실행
• --with-integration=smoke (기본) → @smoke 태그 시나리오만 실행
• 변경 패키지에 integration_test 또는 *.patrol_test.dart 가 없음 → integration skip
• 디바이스 없음 (flutter devices 결과 0) → integration skip + 경고
• 전량 integration 은 CI 책임 (PR 머지 전 CI 가 실행)

4. 실행 순서#

1. Unit (빠른 실패 탐지)
   ├─ FAIL → 즉시 중단, 레이어 결과 리포트, PR 차단
   └─ PASS → 다음

2. Widget (BDD widget_test 포함)
   ├─ FAIL → 중단, 리포트, PR 차단
   └─ PASS → 다음

3. Integration (조건부)
   ├─ SKIP (조건 미충족) → 다음
   ├─ FAIL → 중단, 리포트, PR 차단
   └─ PASS → 다음

4. 집계 + 리포트 + PR 진행 허용

5. 실행 세부 명령 예시#

# 변경 패키지 scope 문자열 빌드
SCOPES= " feature_sign_in,feature_store,kobic " 

 # Unit + Widget (동일 명령으로 커버)
melos exec --scope= " $SCOPES "   --dir-exists=test -- flutter test \
  --coverage --exclude-tags=integration

# BDD dual 이면 build_runner 가 최신인지 확인
melos exec --scope= " $SCOPES "   --depends-on= " bdd_test_gen "   \
  -- dart run build_runner build --delete-conflicting-outputs

# Integration @smoke (선택)
cd app/kobic
patrol test \
  --target integration_test/features/smoke.feature \
  --flavor staging

6. 집계 리포트 포맷#

🧪 PR Preflight Report (base: development → feature/1234-sign-in)

📦 변경 패키지 (3)
  - feature_common_auth
  - feature_application_store
  - kobic (app)

🔬 Unit
  ✅ 42 passed / 0 failed    feature_common_auth
  ✅ 18 passed / 0 failed    feature_application_store
  ✅  5 passed / 0 failed    kobic

🎨 Widget
  ✅ 12 passed / 0 failed    feature_common_auth (BDD widget_test 포함)
  ✅  8 passed / 0 failed    feature_application_store

📱 Integration (@smoke)
  ✅ 3 passed / 0 failed     kobic / integration_test/features/smoke.feature

───────────────────────────────────────────────
✅ ALL LAYERS PASSED — PR 생성 허용

다음 단계: gh pr create --base development

실패 시:

❌ WIDGET LAYER FAILED

📦 feature_common_auth
  ❌ test/src/bdd/sign_in.widget_test.dart
     -  " Successful login with valid email "   FAILED
       expected: K.storeScreen visible
       actual:   timeout after 5s

🚫 PR 생성 차단. 조치:
  1. 실패 원인 확인: flutter test feature/common/auth/test/src/bdd/sign_in.widget_test.dart --name  " Successful login " 
   2. TestDriver step 검토: feature/common/auth/test/src/bdd/step/*.dart
  3. 수정 후 /pr:preflight 재실행

7. Skip 정책 (사용자 명시 필수)#

--skip-all 허용 조건:

• Urgent hotfix (프로덕션 장애 대응)
• 커밋 메시지에 hotfix: 또는 fix!: 접두사
• 사용자가 프롬프트에 이유 명시

감사 로그 형식:

[2026-04-23T12:34:56Z] user=dongwoo branch=hotfix/payment-crash
reason= " 프로덕션 결제 크래시 응급 패치, CI 에서 전량 검증 "

8. lefthook 통합 (선택)#

프로젝트 lefthook.yml 의 pre-push 에 얇은 wrapper 추가 권장:

pre-push:
  parallel: false
  commands:
    preflight-unit:
      tags: test
      run: |
        # 변경 패키지의 unit/widget 만 빠르게
        # --skip-integration 는 default
        claude-code-cli run /pr:preflight --from-hook || exit 1

주의: integration 은 hook 에 두지 말 것 (push 속도 저하). /pr:preflight 로 개발자가 명시 실행.

9. CI 연계#

CI 는 preflight 와 별도로 전량 테스트 를 실행:

• PR 매트릭스: 변경 패키지의 unit + widget + 전체 integration
• Nightly: 전체 레포 unit + widget + integration
• .claude/preflight-skip.log 감지 시 CI 가 강한 게이트로 동작

출력#

• 실행 리포트 (stdout)
• .claude/preflight-report-{timestamp}.json (선택, --save-report)
• .claude/preflight-skip.log (skip 시만)
• 실패 시 exit code ≠ 0 (자동화 연계용)

금지 사항#

• ❌ --skip-unit / --skip-widget 을 정책 변경 없이 허용
• ❌ base 브랜치 감지 실패 시 로컬 전체 브랜치로 fallback (잘못된 diff)
• ❌ 변경 없는 패키지를 scope 에 포함 (전체 테스트 실행)
• ❌ 디바이스 없음 상태에서 integration 을 강제 실행하여 false positive 생성
• ❌ 자동 생성 파일(.g.dart, .freezed.dart, .widget_test.dart, .patrol_test.dart) 에 의한 변경을 "변경 패키지" 로 오인 — 이들은 source 변경을 따라간 결과이므로 원천 소스 패키지 기준으로 매칭

자동 생성 파일 필터#

변경 파일 목록에서 다음은 패키지 scope 판정 시 부수적으로만 반영:

• **/*.g.dart, **/*.freezed.dart, **/*.gr.dart, **/*.config.dart, **/*.gen.dart, **/*.mocks.dart
• **/*.widget_test.dart, **/*.patrol_test.dart (bdd_test_gen 산출물)

이들이 유일한 변경이면 scope 추가하지 않음 (코드 생성 재실행일 가능성).

다른 스킬/에이전트와의 관계#

실패 케이스#

참고#

• 정책: rules/pr-preflight-policy.md
• 커맨드: commands/pr/preflight.md
• 기존 /dev:run Step 8 의 test-runner-agent 는 본 스킬 내부에서 호출됨