Conventional Commits
구조화된 커밋 히스토리, 자동 체인지로그 생성, 시맨틱 버전 관리를 위해 Conventional Commits v1.0.0 사양을 따르는 커밋 메시지를 작성합니다.
이 스킬을 사용해야 하는 경우
다음과 같은 경우 이 스킬을 사용하세요:
- 구조화된 프로젝트에 git 커밋 메시지를 생성할 때
- Conventional Commits 사양에 따라 커밋 메시지 형식을 검증할 때
- commitlint를 사용한 커밋 메시지 검증을 설정할 때
- 커밋 히스토리로부터 체인지로그 생성을 구성할 때
- 시맨틱 버전 관리 자동화를 구현할 때
- 사양 준수 여부를 위해 커밋 메시지를 검토할 때
- 팀에 커밋 메시지 표준을 교육할 때
- semantic-release, commitizen, git-cliff와 같은 도구와 통합할 때
메시지 구조
<type>[optional scope]: <description>
[optional body]
[optional footer(s)]
구성 요소
| 구성 요소 | 필수 여부 | 설명 | 예시 |
|---|---|---|---|
| type | 필수 | 커밋 분류 | feat, fix, docs |
| scope | 선택 | 영향을 받는 코드베이스 영역 | (auth), (parser) |
| description | 필수 | 변경 사항에 대한 간략한 요약 | add user authentication |
| body | 선택 | 상세 설명 | 컨텍스트가 포함된 여러 단락 |
| footer | 선택 | 주요 변경 사항, 이슈 참조 | BREAKING CHANGE:, Refs: #123 |
커밋 유형
필수 유형 (SemVer 영향)
다음 유형은 Conventional Commits 사양에 의해 요구되며 시맨틱 버전 관리에 직접적인 영향을 미칩니다:
flowchart LR
Fix[fix: 버그 수정<br/>사용자 대상] --> PatchVer[PATCH<br/>0.0.X]
Feat[feat: 새로운 기능<br/>사용자 대상] --> MinorVer[MINOR<br/>0.X.0]
Breaking[모든 유형에<br/>BREAKING CHANGE 또는 !] --> MajorVer[MAJOR<br/>X.0.0]
style PatchVer fill:#e1f5ff
style MinorVer fill:#fff4e1
style MajorVer fill:#ffe1e1
| 유형 | 설명 | SemVer | 예시 |
|---|---|---|---|
feat | 사용자 대상 새로운 기능 | MINOR (0.X.0) | feat: add user authentication |
fix | 사용자 대상 버그 수정 | PATCH (0.0.X) | fix: prevent crash on empty input |
권장 유형 (Angular Convention)
다음 유형은 Angular 커밋 가이드라인을 기반으로 한 @commitlint/config-conventional에서 가져왔습니다. BREAKING CHANGE를 포함하지 않는 한 암시적인 SemVer 효과는 없습니다.
| 유형 | 설명 | 예시 |
|---|---|---|
build | 빌드 시스템 또는 외부 종속성 변경 | build: update webpack to v5 |
ci | CI 구성 변경 | ci: add Node 18 to test matrix |
docs | 문서만 변경 | docs: update API reference |
perf | 성능 개선 | perf: reduce bundle size by 20% |
refactor | 버그 수정이나 기능 추가 없는 코드 변경 | refactor: extract validation logic |
style | 코드 스타일 변경 (공백, 서식) | style: fix indentation |
test | 테스트 추가 또는 수정 | test: add unit tests for parser |
추가 일반 유형
| 유형 | 설명 | 예시 |
|---|---|---|
chore | src나 test 파일을 수정하지 않는 변경 | chore: update .gitignore |
revert | 이전 커밋을 되돌림 | revert: feat: add user auth |
참고: 팀은 feat과 fix 외에도 사용자 정의 유형을 정의할 수 있지만, Angular 컨벤션 유형은 도구에서 널리 지원됩니다.
사양 규칙
다음 규칙은 RFC 2119에 따른 공식 Conventional Commits 1.0.0 사양을 구성합니다.
유형 및 범위
-
커밋 반드시 명사(
feat,fix등)로 구성된 유형으로 접두사를 붙여야 하며, 그 뒤에 선택적 범위, 선택적!, 필수 콜론과 공백이 와야 합니다. -
feat유형은 커밋이 새로운 기능을 추가할 때 반드시 사용해야 합니다. -
fix유형은 커밋이 버그 수정을 나타낼 때 반드시 사용해야 합니다. -
유형 뒤에 범위를 제공할 수 있습니다. 범위는 코드베이스 영역을 설명하는 명사로 괄호로 묶여야 합니다. 예:
fix(parser): -
설명은 유형/범위 접두사 뒤의 콜론과 공백 바로 다음에 와야 합니다. 설명은 코드 변경 사항에 대한 간략한 요약입니다. 예:
fix: array parsing issue when multiple spaces were contained in string
본문
-
간략한 설명 뒤에 더 긴 커밋 본문을 제공할 수 있으며, 추가 컨텍스트 정보를 제공합니다. 본문은 설명 뒤에 한 줄의 빈 줄로 시작해야 합니다.
-
커밋 본문은 자유 형식이며, 줄바꿈으로 구분된 여러 단락으로 구성될 수 있습니다.
꼬리말
-
본문 뒤에 빈 줄 하나를 두고 하나 이상의 꼬리말을 제공할 수 있습니다. 각 꼬리말은 단어 토큰으로 구성되고 그 뒤에
:<space>또는<space>#구분자와 문자열 값이 와야 합니다 (git trailer convention에서 영감을 받음). -
꼬리말 토큰은 공백 문자 대신
-를 반드시 사용해야 합니다. 예:Acked-by(이것은 꼬리말 섹션을 여러 단락 본문과 구분하는 데 도움이 됩니다). 예외:BREAKING CHANGE는 토큰으로 사용될 수 있습니다. -
꼬리말 값은 공백과 줄바꿈을 포함할 수 있습니다. 다음 유효한 꼬리말 토큰/구분자 쌍이 관찰될 때 구문 분석이 종료되어야 합니다.
주요 변경 사항
-
주요 변경 사항은 커밋의 유형/범위 접두사 또는 꼬리말 항목으로 반드시 표시되어야 합니다.
-
꼬리말에 포함된 경우, 주요 변경 사항은 대문자 텍스트
BREAKING CHANGE로 구성되고 그 뒤에 콜론, 공백 및 설명이 와야 합니다. 예:BREAKING CHANGE: environment variables now take precedence over config files -
유형/범위 접두사에 포함된 경우, 주요 변경 사항은
:바로 앞에!로 반드시 표시되어야 합니다.!가 사용된 경우 꼬리말에서BREAKING CHANGE:를 생략할 수 있으며, 커밋 설명을 사용하여 주요 변경 사항을 설명해야 합니다.
추가 규칙
-
feat및fix이외의 유형도 커밋 메시지에서 사용될 수 있습니다. 예:docs: update ref docs -
Conventional Commits를 구성하는 정보 단위는 구현자에 의해 대소문자를 구분하지 않고 처리되어야 하지만,
BREAKING CHANGE는 대문자여야 합니다. -
BREAKING-CHANGE는 꼬리말 토큰으로 사용될 때BREAKING CHANGE와 동의어여야 합니다.
설명 모범 사례
요약/설명 가이드라인
- 명령형 현재 시제 사용: "changed"나 "changes"가 아닌 "change"
- 첫 글자는 소문자로
- 끝에 마침표(.) 없음
- 전체 헤더(type + scope + description)를 72자 미만으로 유지
좋은 예시
feat: add validation for email input
fix: handle null pointer in user service
docs: update installation instructions
refactor: simplify authentication flow
잘못된 예시 (피해야 할 것)
feat: Added validation for email input # 과거 시제
fix: Handles null pointer in user service # 3인칭
docs: Update installation instructions. # 마침표와 대문자로 시작
FEAT: add validation # 대문자 유형 (일관성 없음)
본문 가이드라인
- 명령형 현재 시제 사용 (요약과 동일)
- 변경 동기에 대해 설명
- 이전 동작과 새 동작을 비교하는 것이 도움이 될 때 포함
- 본문은 설명 뒤에 한 줄의 빈 줄로 시작해야 함
- 권장 최소: 본문이 있는 경우 20자 이상
주요 변경 사항
주요 변경 사항 표시 방법
세 가지 동등한 접근 방식:
-
꼬리말 표기법:
feat: allow provided config object to extend other configs BREAKING CHANGE: `extends` key in config file is now used for extending other config files -
!를 사용한 유형 접미사:feat!: remove support for Node 6 -
!를 사용한 유형+범위 접미사:feat(api)!: send an email to the customer when a product is shipped
규칙
BREAKING CHANGE반드시 대문자여야 함BREAKING-CHANGE는 꼬리말 토큰으로 사용될 때 동의어- 주요 변경 사항은 SemVer의 MAJOR 버전 증가와 상관관계가 있어야 함
시맨틱 버전 관리 상관 관계
flowchart TD
Start([커밋 분석]) --> CheckBreaking{커밋 중에<br/>BREAKING CHANGE<br/>또는 !가 있나?}
CheckBreaking -->|예| Major[MAJOR 증가<br/>X.0.0]
CheckBreaking -->|아니오| CheckFeat{커밋 중에<br/>feat가 있나?}
CheckFeat -->|예| Minor[MINOR 증가<br/>0.X.0]
CheckFeat -->|아니오| CheckFix{커밋 중에<br/>fix가 있나?}
CheckFix -->|예| Patch[PATCH 증가<br/>0.0.X]
CheckFix -->|아니오| NoChange[버전 변경 없음]
Major --> End([릴리즈])
Minor --> End
Patch --> End
NoChange --> End
커밋 유형별 버전 매핑
| 커밋 유형 | 버전 증가 |
|---|---|
fix | PATCH (0.0.X) |
feat | MINOR (0.X.0) |
BREAKING CHANGE 또는 ! | MAJOR (X.0.0) |
이유: 커밋 히스토리를 기반으로 자동 시맨틱 버전 관리를 가능하게 합니다.
검증 패턴
헤더 검증 정규식
^(feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert)(\(.+\))?!?:\s.+$
Python 검증 예제
import re
CONVENTIONAL_COMMIT_PATTERN = re.compile(
r"^(?P<type>feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert)"
r"(?:\((?P<scope>[^)]+)\))?"
r"(?P<breaking>!)?"
r":\s"
r"(?P<description>.+)$"
)
def validate_header(header: str) -> bool:
"""커밋 헤더가 Conventional Commits를 따르는지 검증합니다."""
return bool(CONVENTIONAL_COMMIT_PATTERN.match(header))
def parse_header(header: str) -> dict | None:
"""커밋 헤더를 구성 요소로 파싱합니다."""
match = CONVENTIONAL_COMMIT_PATTERN.match(header)
if not match:
return None
return {
"type": match.group("type"),
"scope": match.group("scope"),
"breaking": bool(match.group("breaking")),
"description": match.group("description"),
}
완전한 예제
간단한 커밋
feat: add user authentication
fix: prevent crash on empty input
docs: correct spelling of CHANGELOG
범위가 있는 커밋
feat(lang): add Polish language
feat(parser): add ability to parse arrays
fix(auth): handle token expiration correctly
주요 변경 사항
feat: allow provided config object to extend other configs
BREAKING CHANGE: `extends` key in config file is now used for extending other config files
feat!: send an email to the customer when a product is shipped
feat(api)!: send an email to the customer when a product is shipped
chore!: drop support for Node 6
BREAKING CHANGE: use JavaScript features not available in Node 6.
여러 단락 본문과 꼬리말
fix: prevent racing of requests
Introduce a request id and a reference to latest request. Dismiss
incoming responses other than from latest request.
Remove timeouts which were used to mitigate the racing issue but are
obsolete now.
Reviewed-by: Z
Refs: #123
되돌리기 커밋
revert: let us never again speak of the noodle incident
Refs: 676104e, a215868
성능 개선
perf: reduce memory allocation in parser by 40%
Replace string concatenation with StringBuilder pattern.
Benchmark results show 40% reduction in heap allocations.
Refs: #456
리팩토링
refactor: extract authentication logic into separate module
Move auth-related functions from utils.py to auth.py.
No functional changes.
빌드/CI 변경
ci: add Node 18 to test matrix
build: upgrade webpack from v4 to v5
- Update webpack.config.js for v5 compatibility
- Replace deprecated plugins
- Update all loader dependencies
Refs: #789
테스트 및 스타일 변경
test: add unit tests for user validation
Cover edge cases for email validation and password strength.
style: format code according to prettier config
chore: update .gitignore to exclude IDE files
검증 도구와 통합
commitlint 구성
Angular 구성을 사용하여 commitlint로 커밋을 검증:
# Install commitlint
npm install --save-dev @commitlint/cli @commitlint/config-conventional
# Create configuration
echo "module.exports = {extends: ['@commitlint/config-conventional']}" > commitlint.config.js
# Test commit message
echo 'feat(api): add new endpoint' | npx commitlint
포괄적인 commitlint 구성 안내는 이 문서의 지침을 사용하십시오. 워크스페이스에 설치된 commitlint 플러그인이 있는 경우, 프로젝트별 규칙과 예제에 대해 해당 플러그인을 참조할 수 있습니다.
Pre-commit 훅
pre-commit 훅을 사용하여 커밋 메시지 형식을 강제합니다. 워크스페이스에 설치된 pre-commit 플러그인이 있는 경우, 훅 설정 안내에 사용할 수 있습니다. 그렇지 않으면 훅을 직접 구성하십시오.
체인지로그 생성
semantic-release를 사용하여 Conventional Commits에서 체인지로그 생성:
// release.config.js
module.exports = {
branches: ['main'],
plugins: [
'@semantic-release/commit-analyzer',
'@semantic-release/release-notes-generator',
'@semantic-release/changelog',
'@semantic-release/git',
],
};
위 구성은 릴리즈 노트와 체인지로그를 자동으로 생성합니다.
GitHub Actions 자동화
name: Semantic Release
on:
push:
branches: [main]
permissions:
contents: write
issues: write
pull-requests: write
jobs:
release:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: '20'
- run: npm ci
- run: npx semantic-release
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
스킬 동작
구성 요소 흐름
다음 순서도는 이 스킬의 작동 방식을 보여줍니다:
flowchart TD
A[사용자 입력 또는 코드 변경] --> B{작업 유형 식별}
B --> C[적절한 유형 선택]
C --> D{주요 변경 사항?}
D -->|예| E[! 또는 BREAKING CHANGE 추가]
D -->|아니오| F[유형 접두사 생성]
E --> F
F --> G[범위 식별]
G --> H[설명 작성]
H --> I{본문 필요?}
I -->|예| J[동기 부여 및 컨텍스트 제공]
I -->|아니오| K[꼬리말 추가]
J --> K
K --> L[커밋 메시지 출력]
환경 변수 종속성
GITHUB_TOKEN: GitHub Actions에서 릴리즈 자동화에 필요합니다.NODE_AUTH_TOKEN: npm 패키지 게시에 필요할 수 있습니다.
지원되는 플랫폼
- Claude Code: Claude Code는 이 스킬을 사용하여 Git 워크플로우에서 구조화된 커밋 메시지를 생성하고 검증합니다.
- Cursor: Cursor 커밋 대화 상자에서 실시간으로 이 가이드를 활용합니다.
- Codex: Codex는 변경 사항을 커밋할 때 자동으로 이 규칙을 따릅니다.
- 기타 AI: 모든 일반적인 AI 코딩 어시스턴트가 이 스킬을 사용할 수 있습니다.
문맥 및 동기
Conventional Commits 사양은 체인지로그 생성, 시맨틱 버전 관리, 팀 협업과 같은 프로세스를 자동화하는 일관된 커밋 히스토리를 제공합니다. 이 구조를 따르면 개발자는:
- 수동 개입 없이 자동 체인지로그 생성
- 커밋 히스토리를 기반으로 시맨틱 버전 자동 계산
- 표준화된 메시지로 코드베이스 변경 사항을 쉽게 이해
- CI/CD 파이프라인과 커밋 유효성 검사 도구와의 통합
키워드: structured commits, semantic versioning, automated changelog, commitlint, git workflow, version management, team standards