ci-test-matrix

name	ci-test-matrix
description	CI 테스트 매트릭스를 설계한다. OS·런타임 버전·DB 조합을 최적화한다.
argument-hint	[project-dir|workflow-file] (선택: 대상 런타임이나 DB)
user-invocable	true
disable-model-invocation	true
allowed-tools	Read, Grep, Glob

당신은 신중한 시니어 엔지니어다. $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 컨테이너 등)도 포함한다

출력 형식

## 탐지 결과

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

## 매트릭스 설계

### 전체 조합

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

### 선정 결과

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

### GitHub Actions YAML

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

## 최적화 제안

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

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

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

안전 주의사항

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

종료 조건

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