커밋 스킬은(는) 무엇을 하나요?
관례적 커밋 스타일과 원자적 커밋 원칙에 따라 변경 사항을 스테이징하고 커밋합니다.
커밋 메시지 형식
<타입>(<선택적 범위>): <짧은 요약>
- 소문자로만 작성 — 타입, 범위, 요약 모두
- 요약 끝에 마침표 없음
- 명령형 사용 — "added feature"나 "adds feature" 대신 "add feature"
- 요약 줄은 최대 50자 (권장 한도, hard limit 72자)
- 요약은 무엇이 아닌 왜를 설명 (diff가 무엇을 보여줌)
타입
| 타입 | 사용 시기 | 예시 |
|---|---|---|
feat | 새로운 기능이나 능력 | feat: add user authentication flow |
fix | 버그 수정 | fix: resolve null pointer on empty input |
refactor | 버그 수정이나 기능 추가 없는 코드 변경 | refactor: extract parser into standalone module |
style | 포맷팅, 공백, 세미콜론 — 로직 변경 없음 | style: apply formatter to config files |
docs | 문서만 변경 | docs: add API usage examples to readme |
test | 테스트 추가나 업데이트 | test: add edge case coverage for validator |
chore | 빌드 프로세스, 도구, 의존성, 설정 | chore: update dependency lockfile |
perf | 성능 개선 | perf: cache repeated database lookups |
ci | CI/CD 파이프라인 변경 | ci: add lint step to PR workflow |
범위 (선택 사항)
타입만으로는 모호할 때 범위를 사용해 컨텍스트를 좁힙니다. 프로젝트의 디렉토리 구조나 도메인 영역에서 범위를 도출하세요:
feat(auth): add OAuth2 token refresh
fix(api): handle timeout on large payloads
docs(contributing): add setup instructions
워크플로우
- 변경 사항 검토 —
git status와git diff(스테이징 + 언스테이징)를 실행하여 무엇이 변경되었는지 확인 - 최근 히스토리 확인 —
git log --oneline -10을 실행하여 프로젝트의 기존 커밋 스타일과 일치하는지 확인 - 의도 확인 — 변경 사항이 하나의 논리적 단위인지 확인; 그렇지 않으면 여러 커밋으로 나누도록 제안
- CI 검사 실행 — 스테이징 전에 프로젝트의 linter, formatter, 테스트 스위트를 실행하여 문제를 조기에 발견.
package.json스크립트,Makefile, 또는 CI 설정에서 사용 가능한 명령어 확인. 실패 시 수정 후 진행. - 파일 스테이징 — 특정 파일을 이름으로 추가 (
git add file1 file2), 절대git add -A나git add .사용 금지 - 메시지 작성 — 올바른 타입 선택, 필요시 범위 추가, 명령형 요약 작성
- 커밋 — 메시지에 heredoc을 사용하여 깔끔한 서식 유지
- 확인 — 커밋 후
git status실행하여 성공 여부 확인
멀티라인 커밋
본문이 필요한 커밋의 경우 (드물게 — 간결한 한 줄 메시지 선호):
<타입>(<범위>): <요약>
<본문: 무엇이 아닌 왜를 설명>
- 요약과 본문 사이에 빈 줄
- 본문은 72자에서 줄바꿈
- 요약만으로 이유를 전달할 수 없을 때만 본문 사용
규칙
- 원자적 커밋 — 커밋당 하나의 논리적 변경. 기능과 그 테스트는 하나의 커밋이 될 수 있음. 관련 없는 서식 수정은 별도 커밋으로.
- 비밀 정보 금지 — 절대
.env, 자격 증명, API 키, 토큰을 커밋하지 않음. 이러한 파일이 스테이징되면 사용자에게 경고. - 생성된 산출물 금지 — 빌드 출력, 의존성 디렉토리, 컴파일된 파일을 커밋하지 않음. 스테이징 전에
.gitignore적용 범위 확인. - 새 커밋만 생성 — 항상 새 커밋 생성. 사용자가 명시적으로 요청하지 않는 한 절대 amend하지 않음.
- 훅 건너뛰기 금지 — 절대
--no-verify사용 금지. 훅이 실패하면 근본 문제 해결. - 공동 작성자 줄 — Claude가 변경 사항을 작성하거나 공동 작성한 경우 공동 작성자 트레일러 추가:
Co-Authored-By: Claude <[email protected]>
예시
# Feature — 새로운 기능
feat: add webhook notification system
# Feature with scope
feat(api): add rate limiting middleware
# Fix — 버그 수정
fix: prevent crash on malformed JSON input
# Style — 서식만
style: apply consistent indentation across modules
# Docs — 문서
docs: add architecture decision records
# Chore — 도구/설정
chore: broaden gitignore to cover build artifacts
# Test with scope
test(auth): add integration tests for token refresh
# Refactor with scope
refactor(db): replace raw queries with query builder
참조 문서
- conventional-commits.md — 타입 선택 가이드, breaking changes, 범위 전략, 멀티 파일 커밋 결정, 본문 서식, 트레일러, 일반적인 실수