# CI Test Matrix

> CI 테스트 매트릭스를 설계한다. OS·런타임 버전·DB 조합을 최적화한다.

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

---


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

## 목적

프로젝트의 지원 대상 환경(OS, 런타임 버전, 데이터베이스 등)을 분석하고,  
CI에서 실행해야 할 테스트 매트릭스를 설계한다.  

모든 조합을 단순 나열하지 말고, **리스크 기반으로 중요한 조합만 선별**해  
CI 실행 시간과 커버리지의 균형을 최적화한다.

## 입력

- 프로젝트 디렉토리 또는 워크플로우 파일 경로 (필수)
- 선택: 지원 대상 런타임 버전 (예: Node 18, 20, 22)
- 선택: 사용 중인 데이터베이스나 서비스 (예: PostgreSQL, Redis)
- 선택: CI 실행 시간 상한 목표
- 정보가 부족하면 사용자에게 질문할 것

## 절차

1. **지원 대상 환경 탐지**
   - Glob으로 프로젝트 설정 파일을 검색하고, Read로 확인한다:
     - `package.json` 의 `engines` 필드
     - `pyproject.toml` 의 `python_requires`
     - `go.mod` 의 Go 버전
     - `.node-version`, `.python-version`, `.tool-versions`
   - `docker-compose.yml`, `Dockerfile`에서 사용 중인 외부 서비스(DB, 캐시 등)를 탐지한다
   - 기존 워크플로우 파일이 있다면 현재 매트릭스 설정을 확인한다

2. **호환성 요구사항 정리**
   - 탐지한 정보를 바탕으로 지원해야 할 버전 범위를 정리한다:
     - **런타임**: LTS 버전, 현재 안정 버전, 차기 버전(선택)
     - **OS**: Linux(필수), macOS/Windows(크로스플랫폼 요구 시)
     - **DB**: 메이저 버전, 마이너 버전 차이에 따른 리스크 평가
   - EOL(지원 종료) 임박 버전을 식별하고, 제외 또는 경고 대상으로 분류한다

3. **매트릭스 설계**
   - 전체 조합(데카르트 곱)을 계산해 총 테스트 수를 확인한다
   - 리스크 기반으로 아래 원칙에 따라 조합을 선별한다:
     - **필수**: 사용 비율이 가장 높은 플랫폼 + 최신 LTS
     - **권장**: 모든 LTS 버전 + 주요 OS
     - **선택**: 엣지 케이스 조합(최저 지원 버전 + 특수 OS)
   - `include` / `exclude` 규칙으로 미지원 조합을 제외한다
   - `fail-fast: false` 적용 여부와 그 이유를 명시한다

4. **실행 시간 최적화**
   - 각 Job의 예상 실행 시간을 기반으로 전체 매트릭스 실행 시간을 추정한다
   - 아래 최적화 기법을 검토하고 적용을 제안한다:
     - 테스트 분할 실행(sharding)
     - 변경 영향 범위 기반 동적 매트릭스 축소
     - PR 시 경량 매트릭스, main 병합 시 전체 매트릭스 운영
     - 캐시 활용으로 각 Job 실행 속도 개선

5. **매트릭스 YAML 생성**
   - 설계 결과를 GitHub Actions `strategy.matrix` 형식으로 출력한다
   - 각 파라미터 선택 이유를 주석으로 설명한다
   - 필요 시 `services` 블록(DB 컨테이너 등)도 포함한다

## 출력 형식

```markdown
## 탐지 결과

- **언어/런타임**: [탐지된 언어 및 버전 제약]
- **지원 OS**: [탐지 또는 기본 OS 목록]
- **외부 서비스**: [DB, 캐시 등 목록]
- **기존 매트릭스**: [있음(현재 설정 요약) / 없음]

## 매트릭스 설계

### 전체 조합

| 축 | 값 | 선정 이유 |
|----|-----|----------|
| OS | [ubuntu-latest, ...] | [이유] |
| 런타임 | [버전 목록] | [이유] |
| DB | [버전 목록] | [이유] |

### 선정 결과

- **전체 조합 수**: [데카르트 곱 총합]
- **최종 실행 조합 수**: [실행할 조합 수]
- **제외한 조합**: [제외 사유 포함 목록]
- **예상 실행 시간**: [병렬 실행 기준 예상 소요 시간]

### GitHub Actions YAML

[strategy.matrix YAML을 코드 블록으로 출력]

## 최적화 제안

| 기법 | 기대 효과 | 적용 권장도 |
|------|-----------|-------------|
| [최적화 기법] | [예상 시간 절감] | 높음/중간/낮음 |

## 단계별 매트릭스(권장)

- **PR 시(경량)**: [조합 개요]
- **main 병합 시(전체)**: [조합 개요]
- **정기 실행(야간 배치)**: [추가 검증 조합]
```

## 안전 주의사항

- 워크플로우 파일을 직접 수정하지 말고 YAML 템플릿만 출력할 것
- EOL 버전 유지 지원은 보안 리스크로 경고할 것
- 조합 수가 50개를 초과하면 명확히 경고하고 축소안을 제시할 것
- DB 서비스 비밀번호·포트는 기본값 또는 시크릿 참조로 처리할 것
- 운영 환경 정보(실제 접속 정보, 인증 정보)는 매트릭스에 포함하지 말 것

## 종료 조건

위 출력 형식에 맞는 매트릭스 설계 문서를 작성하면 종료한다.
선정 이유가 포함된 조합 목록, YAML 템플릿, 최적화 제안이 반드시 포함되어야 한다.
워크플로우 반영은 사용자의 추가 지시를 기다린다.