# CI Workflow Fix

> CI 실패 로그를 분석하고, 원인 식별 및 수정안을 제시한다. 캐시·병렬 실행·권한 문제에 대응한다.

- Skill: `gaebalai-claude-code-kit-ko/ci-workflow-fix` (Agent Skill)
- Install (CLI): `npx skillmds@latest add gaebalai-claude-code-kit-ko/ci-workflow-fix`
- Raw SKILL.md: https://api.skillmd.com/api/skills/gaebalai-claude-code-kit-ko/ci-workflow-fix/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- 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-workflow-fix

---


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

## 목적

CI 파이프라인의 실패 로그를 체계적으로 분석해 **근본 원인(root cause)** 을 식별한다.  

캐시 손상, 병렬 실행 충돌, 권한 부족, 의존성 불일치, 환경 차이 등  
CI에서 자주 발생하는 장애 패턴을 기준으로 원인을 분류하고,  
구체적인 수정안을 제시한다.

## 입력

- CI 실패 로그 파일 경로, 워크플로 URL, 또는 에러 메시지 (필수)
- 선택: 실패한 Job 또는 Step 이름
- 선택: 최근 변경한 파일 또는 설정 정보
- 선택: “가끔 실패한다”, “특정 브랜치에서만 실패한다” 등 재현 조건
- 정보가 부족하면 사용자에게 질문할 것

## 절차

1. **로그 분석 및 구조화**
   - 지정된 로그 파일 또는 에러 메시지를 Read로 읽는다
   - 로그에서 에러 라인, 경고 라인, 실패한 Step 이름을 추출한다
   - 타임스탬프가 있다면 각 Step의 소요 시간과 실패 시점을 분석한다
   - 종료 코드, 에러 코드, 예외 메시지를 유형별로 정리한다

2. **장애 패턴 대조**
   - 추출한 에러 정보를 아래 주요 패턴과 비교한다:
     - **캐시 문제**: 캐시 키 불일치, 캐시 손상, lock 파일 불일치
     - **병렬 실행 충돌**: 포트 충돌, 파일 락, DB 동시 접근 문제
     - **권한 문제**: `GITHUB_TOKEN` 권한 부족, 파일 권한 오류, 컨테이너 내부 권한 이슈
     - **의존성 문제**: 버전 해결 실패, 비호환 버전, 레지스트리 장애
     - **환경 차이**: Node/Python 버전 불일치, OS 차이, 경로 구분자 문제
     - **타임아웃**: 테스트 지연, 외부 서비스 응답 지연, 리소스 부족

3. **워크플로 파일과 대조**
   - `.github/workflows/` 디렉토리를 Glob으로 검색하고 Read로 내용을 확인한다
   - 실패한 Step의 설정(캐시 키, 환경 변수, 조건문 등)을 점검한다
   - 최근 `git log`를 확인해 워크플로 변경 이력과 장애 발생 시점을 비교한다

4. **관련 코드 변경 확인**
   - `git diff`로 최근 변경 사항을 확인하고 CI 실패와의 인과관계를 분석한다
   - lock 파일(`package-lock.json`, `poetry.lock` 등) 변경 여부를 확인한다
   - 테스트 설정 파일 및 CI 관련 설정 변경 여부를 점검한다

5. **원인 특정 및 수정안 제시**
   - 가장 가능성 높은 원인을 근거와 함께 명확히 제시한다
   - 워크플로 수정이 필요하다면 수정 전/후 diff 형태로 제안한다
   - **영구적 해결책(재발 방지)** 과 **임시 대응책(긴급 우회)** 을 구분해 제시한다

6. **재실행 전략 제안**
   - 수정 후 검증 방법을 제안한다
   - 동일 장애를 조기 탐지하기 위한 모니터링 방안을 제시한다

## 출력 형식

```markdown
## 장애 개요

- **실패한 워크플로**: [워크플로 이름]
- **실패 Job/Step**: [Job 이름 > Step 이름]
- **주요 에러 메시지**: [핵심 에러 메시지]
- **장애 유형**: [캐시/병렬 실행/권한/의존성/환경 차이/타임아웃]

## 원인 분석

### 근본 원인

[원인 설명 및 판단 근거]

### 관련 변경 사항

| 파일 | 변경 내용 | 장애와의 연관성 |
|------|-----------|----------------|
| [파일 경로] | [변경 요약] | [연관 설명] |

## 수정안

### 영구적 해결책 (권장)

[워크플로 수정 diff 또는 설정 변경 내용]

### 임시 대응책 (긴급 대응용)

[단기 우회 방안]

## 재발 방지

- [ ] [재발 방지 방안 1]
- [ ] [재발 방지 방안 2]

## 검증 절차

1. [수정 적용 후 확인 방법]
2. [CI 재실행 및 결과 확인 방법]
```

## 안전 주의사항

- 로그에 포함된 토큰, 시크릿, 인증 정보는 반드시 마스킹 처리할 것
- 워크플로 파일을 직접 수정하지 말고 수정안만 제시할 것
- `git push`, `git reset` 등 파괴적인 git 명령은 실행하지 말 것
- 프로덕션 배포 워크플로 수정 제안 시에는 리스크를 명확히 명시할 것
- 로그에 개인정보가 포함되어 있다면 마스킹 처리 후 출력할 것

## 종료 조건

위 출력 형식에 맞는 장애 분석 리포트를 작성하면 종료한다.
근본 원인이 근거와 함께 명확히 제시되어야 하며,
영구적 해결책과 임시 대응책, 검증 절차가 반드시 포함되어야 한다.

워크플로 파일 적용은 사용자의 추가 지시를 기다린다.