# Release Tag Plan

> 릴리스 태그·시맨틱 버저닝·CHANGELOG 전략을 수립한다.

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

---


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

## 목적

프로젝트의 기존 버전 관리 체계와 릴리스 이력을 분석하고,  
시맨틱 버저닝(SemVer)에 기반한 태그 전략·CHANGELOG 자동 생성·릴리스 워크플로를 설계한다.  

기존 관행을 존중하면서도 일관성과 자동화 가능성을 높인다.

## 입력

- 프로젝트 디렉터리 (필수)
- 선택: 다음 릴리스 유형 (major / minor / patch)
- 선택: 릴리스 주기 (주간, 격주, 스프린트 단위 등)
- 선택: 모노레포인지 단일 레포인지 여부
- 정보가 부족하면 사용자에게 질문한다

## 절차

1. **현재 버저닝 방식 분석**
   - `git tag --list`로 기존 태그 목록을 확인하고 네이밍 패턴 분석
   - `git log --oneline`으로 최근 커밋 이력 확인 및 커밋 메시지 규칙 파악
   - `package.json`, `pyproject.toml`, `go.mod` 등의 버전 필드 확인
   - `CHANGELOG.md`가 있다면 구조와 형식 분석
   - 릴리스 브랜치 존재 여부 확인 (`release/*`, `main`, `develop` 등)

2. **커밋 분류**
   - 최신 태그부터 HEAD까지의 커밋을 `git log`로 수집
   - Conventional Commits 기준으로 분류:
     - **feat**: 기능 추가 → minor 증가
     - **fix**: 버그 수정 → patch 증가
     - **BREAKING CHANGE**: 호환성 깨짐 → major 증가
     - **docs / chore / refactor / test**: 버전 영향 없음
   - 규칙이 없다면 커밋 내용 기반으로 추정 분류

3. **다음 버전 제안**
   - 분류 결과에 따라 SemVer 기준 다음 버전 제안
   - BREAKING CHANGE가 있으면 명확히 경고 및 마이그레이션 가이드 필요성 명시
   - 프리릴리스(alpha, beta, rc) 필요 여부 검토
   - 0.x.y 초기 개발 단계의 SemVer 차이 설명

4. **CHANGELOG 전략 설계**
   - Keep a Changelog 형식 기반 구조 설계
   - 자동 생성 도구 제안:
     - conventional-changelog / standard-version / release-please
     - semantic-release / goreleaser
   - CHANGELOG 포함·제외 기준 정의
   - 수동 작성 필요 항목(마이그레이션 안내, 중요 공지) 가이드 정의

5. **태그 및 릴리스 워크플로 설계**
   - 태그 네이밍 규칙 정의 (`v1.2.3` 권장)
   - 릴리스 흐름 설계:
     - main 머지 → 자동 태그 생성
     - GitHub Releases 자동 릴리스 노트 생성
     - NPM / PyPI / Docker Hub 배포 자동화
   - 모노레포일 경우 패키지별 독립 버저닝 전략 정의

6. **Conventional Commits 도입 지원**
   - 현재 사용하지 않는 경우 도입 계획 제안
   - commitlint 설정 템플릿 제공
   - husky / pre-commit 기반 커밋 메시지 검증 설정 제안

## 출력 형식

```markdown
## 현재 상태 분석

- **기존 태그**: [태그 수 및 네이밍 패턴]
- **최신 태그**: [태그명 및 날짜]
- **커밋 규칙**: [Conventional Commits 준수 여부]
- **기존 CHANGELOG**: [있음/없음 및 형식 요약]
- **버전 관리 파일**: [package.json 등 버전 값]

## 커밋 분류 (최신 태그 이후)

| 유형 | 건수 | 대표 커밋 |
|------|------|-----------|
| feat | [N] | [예시] |
| fix | [N] | [예시] |
| BREAKING | [N] | [예시] |
| 기타 | [N] | [docs/chore/refactor 등] |

## 다음 버전 제안

- **권장 버전**: [X.Y.Z]
- **근거**: [판단 이유]
- **호환성 깨짐 여부**: [있음/없음]

## CHANGELOG 초안

[다음 릴리스용 CHANGELOG 초안]

## 태그 전략

- **네이밍 규칙**: v{major}.{minor}.{patch}
- **프리릴리스 규칙**: {version}-beta.{N}
- **태그 생성 방식**: 수동 / CI 자동 / release-please

## 릴리스 워크플로

1. [릴리스 단계1]
2. [릴리스 단계2]
3. [릴리스 단계3]

## 자동화 설정

### 권장 도구

- **CHANGELOG 생성**: [도구명 및 이유]
- **커밋 검증**: [commitlint 설정 예시]
- **릴리스 자동화**: [GitHub Actions 구성 개요]

### 설정 파일 예시

[필요 설정 파일 내용]

## 도입 단계

| 단계 | 내용 | 우선순위 |
|------|------|-----------|
| 1 | [가장 먼저 수행] | 필수 |
| 2 | [다음 단계] | 권장 |
| 3 | [선택 사항] | 선택 |
```

## 유의사항

- `git tag` 생성·삭제·push는 수행하지 않는다.
- 기존 태그 및 릴리스 기록은 변경하지 않는다.
- 읽기 전용 git 명령(`git log`, `git tag`)만 사용한다.
- 보안 수정 사항은 CHANGELOG에 기록하되, 상세 취약점 정보는 포함하지 않는다.
- 실제 배포 단계에는 명확한 승인 절차를 포함한다.

## 종료 조건

위 형식에 맞춘 릴리스 전략 문서를 출력하면 종료한다.
현재 상태 분석, 다음 버전 제안, CHANGELOG 초안, 태그 전략, 릴리스 워크플로, 자동화 설정이 모두 포함되어야 한다.
태그 생성 및 실제 릴리스는 사용자의 추가 지시를 기다린다.

## 이 스킬이 적합하지 않은 경우

- **모노레포에서 다수 패키지 동시 릴리스**: 패키지 간 의존성과 릴리스 순서 조정은 별도 설계 필요
- **이미 semantic-release 등 자동화 체계가 완성된 프로젝트**: 기존 자동화와 충돌 가능