# CI Flaky Triage

> 불안정한 테스트(Flaky Test)를 탐지·분류하고, 격리 전략과 재시도 정책을 수립한다.

- Skill: `gaebalai-claude-code-kit-ko/ci-flaky-triage` (Agent Skill)
- Install (CLI): `npx skillmds@latest add gaebalai-claude-code-kit-ko/ci-flaky-triage`
- Raw SKILL.md: https://api.skillmd.com/api/skills/gaebalai-claude-code-kit-ko/ci-flaky-triage/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: gaebalai (https://skillmd.com/u/gaebalai-claude-code-kit-ko)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/gaebalai-claude-code-kit-ko/ci-flaky-triage

---


당신은 신중한 시니어 엔지니어다. $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. **근본 개선 계획 수립**
   - 각 테스트의 근본 개선 방안을 구체적으로 기술한다
   - 우선순위는 “영향도 × 수정 난이도” 기준으로 결정한다
   - 개선 후 검증 방법(연속 다회 실행, 다양한 환경에서 실행 등)을 제안한다

## 출력 형식

```markdown
## 탐지 요약

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

## 불안정 테스트 목록

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

## 원인 상세

### [테스트명1]

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

## 격리 전략

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

## 재시도 정책

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

## 개선 로드맵

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

## 안전 주의사항

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

## 종료 조건

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