ci-flaky-triage

name	ci-flaky-triage
description	불안정한 테스트(Flaky Test)를 탐지·분류하고, 격리 전략과 재시도 정책을 수립한다.
argument-hint	[test-dir|workflow-file|test-log] (선택: 의심되는 테스트 이름)
user-invocable	true
disable-model-invocation	true
allowed-tools	Read, Grep, Glob, Bash(git log *)

당신은 신중한 시니어 엔지니어다. $ARGUMENTS 를 대상으로 아래 작업을 수행하라.

목적

CI에서 간헐적으로 실패하는 테스트(Flaky Test)를 체계적으로 탐지하고, 불안정성의 원인을 분류한다.
테스트 격리 전략, 재시도(리트라이) 정책, 근본 개선의 우선순위를 수립하여 CI 신뢰도를 회복하는 실행 계획을 수립한다.

입력

• 테스트 디렉토리, 워크플로우 파일, 또는 테스트 실행 로그 경로 (필수)
• 선택: 불안정하다고 의심되는 테스트 이름 또는 파일명
• 선택: “3번 중 1번 실패”, “특정 시간대에만 실패” 등 발생 패턴
• 선택: 최근 CI 실행 결과 링크
• 정보가 부족한 경우 사용자에게 질문할 것

절차

1. 불안정 테스트 탐지

   • Read로 테스트 로그 또는 테스트 디렉토리를 확인한다
   • Grep으로 아래 패턴을 검색하여 불안정성 징후를 수집한다:
     • 타임아웃 설정 (setTimeout, time.sleep, waitFor 등)
     • 날짜/시간 의존 처리 (Date.now(), time.time(), 타임존 참조)
     • 랜덤성 (Math.random(), random.choice, 시드 미고정)
     • 외부 서비스 의존 (HTTP 요청, DB 연결, 파일 시스템 접근)
     • 공유 상태 (전역 변수, 공유 파일, 공용 DB 테이블)
     • 실행 순서 의존 (테스트 간 암묵적 의존 관계)
   • git log로 과거 테스트 관련 수정 이력을 확인하고, 반복적으로 수정된 테스트를 식별한다

2. 불안정 원인 분류

   • 탐지된 각 테스트를 아래 카테고리로 분류한다:
     • 타이밍 의존: 고정 sleep, 타임아웃 부족, 비동기 완료 대기 미흡
     • 환경 의존: OS별 동작 차이, 타임존, 로케일, 파일 경로 차이
     • 외부 의존: 네트워크, 외부 API, DB 연결, 파일 시스템
     • 상태 오염: 테스트 간 공유 상태, 정리(clean-up) 누락, 실행 순서 의존
     • 리소스 충돌: 포트, 파일 락, 병렬 테스트 간 자원 경쟁
     • 데이터 의존: 테스트 데이터 불일치, 랜덤 생성 데이터, 날짜 의존 데이터

3. 영향도 평가

   • 각 테스트에 대해 아래 항목을 평가한다:
     • 실패 빈도 (높음: 3회 중 1회 이상 / 중간: 10회 중 1회 / 낮음: 드물게 발생)
     • 차단 영향 (CI 전체를 중단시키는지 / 특정 Job만 영향 있는지)
     • 수정 비용 (테스트 재작성 / 설정 변경 / 아키텍처 수정 필요 여부)
   • 실패 빈도와 차단 영향을 기준으로 대응 우선순위를 결정한다

4. 격리 전략 수립

   • 즉시 개선이 어려운 테스트의 격리 방안을 제안한다:
     • 태그 기반 분리 실행 (@flaky, @unstable 태그)
     • 불안정 테스트 전용 Job으로 분리
     • fail-fast: false 설정으로 다른 테스트 영향 최소화
   • 격리된 테스트의 모니터링 방식과 격리 해제 조건을 정의한다

5. 재시도(리트라이) 정책 설계

   • 사용 중인 테스트 프레임워크에 맞는 재시도 설정을 제안한다:
     • Jest: jest.retryTimes()
     • pytest: pytest-rerunfailures
     • Go: t.Run + 커스텀 재시도 로직
   • 재시도 횟수 상한과 적용 조건을 설정한다
   • 재시도로 통과한 테스트의 로그 출력 방식을 제안한다

6. 근본 개선 계획 수립

   • 각 테스트의 근본 개선 방안을 구체적으로 기술한다
   • 우선순위는 “영향도 × 수정 난이도” 기준으로 결정한다
   • 개선 후 검증 방법(연속 다회 실행, 다양한 환경에서 실행 등)을 제안한다

출력 형식

## 탐지 요약

- **조사 대상**: [테스트 디렉토리 또는 파일]
- **총 테스트 수**: [확인한 테스트 수]
- **불안정 테스트 후보 수**: [탐지된 후보 수]
- **원인 카테고리 분포**: 타이밍: X / 환경: X / 외부 의존: X / 상태 오염: X

## 불안정 테스트 목록

| # | 테스트명 | 파일 | 원인 카테고리 | 실패 빈도 | 차단 영향 | 우선순위 |
|---|----------|------|--------------|----------|-----------|---------|
| 1 | [테스트명] | [파일:라인] | [카테고리] | 높음/중간/낮음 | 높음/낮음 | P1/P2/P3 |

## 원인 상세

### [테스트명1]

- **원인**: [불안정성의 구체적 원인]
- **근거**: [로그 해당 구문, 코드 위치]
- **근본 개선안**: [구체적인 개선 방법]

## 격리 전략

- **즉시 격리 대상**: [격리할 테스트와 방법]
- **격리 방법**: [태그 분리/Job 분리/조건부 실행]
- **격리 해제 조건**: [근본 개선 완료 + 연속 N회 성공]

## 재시도 정책

- **프레임워크**: [사용할 재시도 메커니즘]
- **재시도 횟수**: [상한과 설정 이유]
- **적용 조건**: [어떤 테스트에 적용할지]
- **설정 예시**: [구체적 설정 코드]

## 개선 로드맵

| 우선순위 | 테스트 | 개선 방향 | 예상 공수 |
|----------|--------|-----------|-----------|
| P1 | [테스트명] | [개선 방안] | [예상 기간] |
| P2 | [테스트명] | [개선 방안] | [예상 기간] |

안전 주의사항

• 테스트 코드 수정·삭제는 수행하지 말고, 분석과 제안만 진행할 것
• 테스트 비활성화(skip, disable)는 최후의 수단이며 권장하지 않음
• 재시도 5회 이상 설정은 근본 원인을 가릴 수 있으므로 경고할 것
• 테스트 로그에 포함된 인증 정보나 개인정보는 결과에 포함하지 말 것
• git log 외 다른 git 명령은 실행하지 말 것

종료 조건

위 출력 형식에 맞춘 Flaky Test 트리아지 보고서를 작성한 뒤 종료한다. 불안정 테스트가 원인 분류 및 우선순위와 함께 정리되어 있고, 격리 전략·재시도 정책·개선 로드맵이 포함되어 있어야 한다. 테스트 수정은 사용자의 추가 지시를 기다린다.