# CI Coverage Gate

> 테스트 커버리지 임계값과 예외 규칙을 설계한다. CI 게이트로 운영 가능한 설정을 생성한다.

- Skill: `gaebalai-claude-code-kit-ko/ci-coverage-gate` (Agent Skill)
- Install (CLI): `npx skillmds@latest add gaebalai-claude-code-kit-ko/ci-coverage-gate`
- Raw SKILL.md: https://api.skillmd.com/api/skills/gaebalai-claude-code-kit-ko/ci-coverage-gate/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-coverage-gate

---


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

## 목적

프로젝트의 코드 구조와 테스트 현황을 분석하여, CI에서 운영할 수 있는 커버리지 임계값과 예외 규칙을 설계한다.  
획일적인 단일 임계값이 아니라, 디렉터리·파일 유형별로 적절한 기준을 설정하고 단계적으로 커버리지를 개선할 수 있는 현실적인 계획을 수립한다.

## 입력

- 프로젝트 디렉터리 또는 커버리지 설정 파일 경로 (필수)
- 선택: 목표 커버리지 비율 (예: 80%)
- 선택: 기존 커버리지 리포트 (lcov, coverage.xml 등)
- 선택: 커버리지 측정 대상에서 제외하고 싶은 디렉터리 (예: 테스트, 마이그레이션 등)
- 정보가 부족할 경우 사용자에게 질문할 것

## 절차

1. **프로젝트 구조 분석**
   - Glob으로 소스 코드의 디렉터리 구조를 파악한다.
   - 다음 파일 유형을 분류한다:
     - **비즈니스 로직**: 서비스 레이어, 도메인 모델, 유틸리티
     - **엔트리 포인트**: 컨트롤러, 라우터, 핸들러
     - **설정·인프라**: 설정 파일, 마이그레이션, 시드 데이터
     - **타입 정의·인터페이스**: 타입 파일, 프로토콜 정의
     - **자동 생성 코드**: ORM 모델, GraphQL 타입, API 클라이언트
   - 테스트 파일의 위치를 확인하고, 사용 중인 테스트 프레임워크를 식별한다.

2. **기존 커버리지 현황 파악**
   - 커버리지 설정 파일을 검색하고 내용을 확인한다:
     - Jest: `jest.config.*`의 `coverageThreshold`, `collectCoverageFrom`
     - pytest: `pyproject.toml`의 `[tool.coverage]`, `.coveragerc`
     - Go: 커버리지 관련 Makefile 타겟
   - 기존 커버리지 리포트가 있다면 현재 커버리지 비율을 파악한다.
   - 기존 제외 설정(`coveragePathIgnorePatterns` 등)을 확인한다.

3. **임계값 설계**
   - 파일 유형별로 적절한 커버리지 임계값을 설계한다:
     - **비즈니스 로직**: 높은 임계값 (80~90%) — 결함 영향도가 높음
     - **엔트리 포인트**: 중간 임계값 (60~75%) — 통합 테스트로 보완 가능
     - **유틸리티**: 높은 임계값 (85~95%) — 재사용 빈도 높음
     - **설정·인프라**: 낮은 임계값 또는 제외 — 테스트 비용 대비 효과 낮음
     - **자동 생성 코드**: 제외 — 수동 테스트 가치 낮음
   - 전체 임계값과 디렉터리별 임계값을 모두 설정하고, 단계적 상향 계획을 포함한다.

4. **예외 규칙 수립**
   - 커버리지 측정 대상에서 제외해야 할 파일·디렉터리를 명확히 정의한다:
     - 테스트 파일 자체
     - 설정 파일, 마이그레이션 파일
     - 자동 생성 코드
     - 타입 정의 전용 파일
   - 각 제외 항목에 대해 제외 사유를 명시한다.
   - 예외 규칙 남용을 방지하기 위한 가이드라인을 설정한다.

5. **CI 게이트 설정 생성**
   - 사용 중인 테스트 프레임워크에 맞춰 설정을 생성한다:
     - 커버리지 임계값 설정
     - CI 실행 명령어
     - 커버리지 리포트 출력 형식 (lcov, cobertura 등)
     - PR에 커버리지 코멘트 출력 (Codecov, Coveralls 등)
   - 임계값 미달 시 CI 동작(실패 / 경고)을 정의한다.

6. **단계적 도입 계획 수립**
   - 현재 커버리지 비율이 낮거나 불명확한 경우, 초기 임계값을 낮게 설정하고 점진적으로 상향하는 계획을 수립한다.
   - 마일스톤별 목표 임계값과 일정 제안.
   - 커버리지 하락을 감지하기 위한 차등 비교(신규 코드 기준 커버리지) 전략을 제안한다.

## 출력 형식

```markdown
## 프로젝트 분석

- **언어/프레임워크**: [감지된 언어]
- **테스트 프레임워크**: [Jest/pytest/go test 등]
- **소스 디렉터리 수**: [대상 디렉터리 수]
- **추정 소스 파일 수**: [테스트 제외 파일 수]
- **기존 커버리지 설정**: [있음(요약)/없음]

## 커버리지 임계값 설계

### 전체 임계값

| 지표 | 임계값 | 단계 |
|------|--------|------|
| Line Coverage | [X%] | 초기 → [Y%] 목표 |
| Branch Coverage | [X%] | 초기 → [Y%] 목표 |
| Function Coverage | [X%] | 초기 → [Y%] 목표 |

### 디렉터리별 임계값

| 디렉터리 | 유형 | 임계값 | 이유 |
|-----------|------|--------|------|
| [src/services/] | 비즈니스 로직 | [X%] | [이유] |
| [src/controllers/] | 엔트리 포인트 | [X%] | [이유] |
| [src/utils/] | 유틸리티 | [X%] | [이유] |

### 제외 규칙

| 대상 | 패턴 | 제외 사유 |
|-------|--------|------------|
| [테스트 파일] | [패턴] | [사유] |
| [자동 생성 코드] | [패턴] | [사유] |
| [마이그레이션] | [패턴] | [사유] |

## CI 설정

### 커버리지 설정 파일

[테스트 프레임워크에 맞는 설정을 코드 블록으로 출력]

### CI 워크플로 설정

[GitHub Actions 기준 커버리지 실행 스텝을 코드 블록으로 출력]

## 단계적 도입 계획

| 단계 | 기간 | 전체 목표 | 중점 영역 |
|------|------|-----------|-----------|
| Phase 1 | [기간] | [X%] | [대상] |
| Phase 2 | [기간] | [X%] | [대상] |
| Phase 3 | [기간] | [X%] | [대상] |

## 운영 규칙

- **신규 코드**: [신규 코드에 적용할 최소 커버리지 비율]
- **예외 승인 절차**: [임계값 예외를 허용하는 조건과 승인 프로세스]
- **정기 점검**: [임계값 재검토 시점과 기준]
```

## 안전 주의사항

- 커버리지 설정 파일을 직접 수정하지 말고, 설정 템플릿만 출력할 것
- 비현실적인 임계값(초기부터 100%)을 설정하지 말 것 — 팀 사기 저하를 초래할 수 있음
- 커버리지 수치만으로 테스트 품질을 판단하지 않는다는 주석을 포함할 것
- 자동 생성 코드나 서드파티 코드를 측정 대상에 포함하지 말 것
- 테스트 데이터에 운영 데이터나 개인정보를 사용하는 설정을 포함하지 말 것

## 종료 조건

위 출력 형식에 맞는 커버리지 게이트 설계 문서를 작성한 후 종료한다.
전체 및 디렉터리별 임계값, 예외 규칙, CI 설정 템플릿, 단계적 도입 계획이 모두 포함되어야 한다.
실제 설정 적용은 사용자 지시를 기다린다.