Git 커밋 메시지 규칙¶

상태: 채택 · 적용 범위: 직접 작성하는 커밋 메시지 · 형식 기준: Conventional Commits 1.0.0

변경의 목적과 영향을 이력만으로 이해할 수 있도록 작성한다. 사용자가 제공한 기존 형식을 바탕으로 모순을 해소한 규칙이다. 설명 문서는 한국어로, 커밋 메시지는 기본적으로 영어로 작성한다.

형식과 길이¶

<type>(<scope>): <subject>

- <body>

<footer>

요소	기준	강도
제목	type, 선택적 scope, `:`, subject	필수
제목 길이	접두어·공백을 포함해 50자 권장, 72자 이내	필수 상한
scope	영향 영역이 명확할 때 영어 소문자·kebab-case	선택
subject	영어는 소문자 동사 원형으로 시작, 끝 마침표 생략	필수
body	제목으로 설명되지 않는 이유·제약·동작 차이	선택
footer	호환성 변경 설명·실제 관련 이슈 등	조건부
구분	제목과 다음 내용 사이, 본문과 footer 사이 빈 줄 1개	필수
본문·footer 길이	한 줄 72자 이내로 직접 개행	필수, 아래 예외 허용

본문과 footer가 모두 없으면 제목 한 줄만 작성한다. 본문 없이 footer만 있으면 제목 다음에 빈 줄 하나를 둔다. 빈 본문이나 형식만 채우는 항목은 만들지 않는다.

길이는 바이트나 화면의 열 너비가 아닌 문자 수로 센다. 한글도 한 글자를 1자로 계산하며 공백과 구두점을 포함한다. 본문·footer의 URL, 해시, 긴 식별자는 분할하면 복사·참조가 깨질 때만 72자 예외를 허용한다. 제목의 긴 식별자는 본문으로 옮긴다. 이 길이 제한은 Git의 저장 제한이 아닌 개인 규칙이다.

type 선택¶

type	용도	경계와 예시
`feat`	기능 추가·확장	플레이어 대시 기능
`fix`	잘못된 동작 수정	아이템 제거 중 null 접근 수정
`refactor`	관찰 가능한 동작을 유지하는 구조 변경	클래스 분리·식별자 변경
`perf`	성능 개선 목적의 변경	할당 감소·캐시 적용
`docs`	문서·설명 주석 변경	설치 안내·API 설명
`test`	테스트 코드·데이터 변경	회귀 테스트 추가
`build`	빌드·패키지·의존성 변경	컴파일 옵션·라이브러리 버전
`ci`	CI 실행 설정 변경	GitHub Actions 워크플로
`style`	동작에 영향 없는 포맷 변경	들여쓰기·공백 정리
`chore`	위 분류에 속하지 않는 유지보수	`.gitignore` 정리

권장: 한 커밋은 하나의 논리적 목적을 갖는다. 독립적인 기능 추가와 포맷 정리는 분리한다. 기능과 그 테스트처럼 같은 목적의 변경은 함께 둘 수 있다.
파일을 추가했다고 무조건 feat로 정하지 않는다. 테스트 파일은 test, 문서 파일은 docs다.
수정 파일 수보다 변경 목적을 기준으로 선택한다. 버그 수정에 필요한 구조 변경은 fix로 표현할 수 있다.
style은 UI 디자인 변경이나 이름 변경을 뜻하지 않는다. 세미콜론 변경도 동작이 달라진다면 style이 아니다.
perf라는 분류만으로 성능 향상이 입증되지는 않는다. 수치·측정 결과는 실제 확인한 경우에만 본문에 적는다.
기존 [Init], [Update], [Remove]는 작업 목적에 따라 위 type으로 분류한다. 공개 기능 제거 등 호환성 변경은 아래 표기까지 적용한다.

scope와 subject¶

scope는 player, ui, save, asset-loader처럼 변경 영역을 식별한다. 같은 영역은 같은 이름을 유지한다. 여러 영역을 억지로 나열하거나 misc로 채우지 않고, 공통 영역이 없으면 생략한다. scope는 브랜치 이름이나 이슈 번호를 넣는 자리가 아니다.

영어 subject는 add, fix, prevent, remove처럼 동사 원형으로 시작한다. added, fixes와 모호한 update code를 피한다. 무엇이 달라지는지 제목에 쓰고, 이유와 세부 조건은 본문에 보충한다. API 이름과 약어의 원래 대소문자는 보존한다.

한국어를 요청받으면 subject·body·설명용 footer 값을 한국어로 작성한다. type, scope, BREAKING CHANGE 같은 형식 토큰은 영어를 유지한다. 한국어에는 영어의 동사 원형·첫 글자 대소문자 규칙을 적용하지 않는다.

fix(inventory): prevent null access on item removal

fix(inventory): 아이템 제거 시 null 접근 방지

body와 footer¶

본문은 제목을 반복하기보다 변경 이유, 이전 동작과의 차이, 제약을 설명한다. 기존 선호에 따라 - 목록을 기본으로 사용하고 긴 항목의 이어지는 줄은 공백 2칸 들여쓴다. 연결된 설명이 더 자연스러우면 문단도 허용한다.

필수: 실제 변경·사용자 설명에서 확인한 내용만 작성한다. 요청에 없는 캐시 확장, 이벤트 구독, 보간 버퍼 조정, 성능 향상이나 테스트 통과를 추측해서 넣지 않는다. 실제 커밋 대상이 있으면 staged diff를 기준으로 확인하며 다른 변경을 섞지 않는다.

footer는 목록 항목으로 쓰지 않는다. 단순 관련 이슈는 Refs: #23, 실제로 해결하는 이슈는 Closes #23처럼 구분한다. 번호를 모르면 생략한다. 자동 종료 여부는 호스팅 서비스와 병합 조건에 따르므로 문구만으로 종료가 보장된다고 설명하지 않는다.

fix(ui): refresh boss health bar on phase change

- keep the health bar consistent with the active phase

Closes #23

이 예시는 변경 목적과 해결 이슈가 확인된 경우다. 내부 구현 방식은 추가로 추측하지 않았다.

호환성을 깨는 변경¶

저장 형식·공개 API·설정 등 기존 사용 방식이 더 이상 동작하지 않으면 호환성 변경으로 표시한다. 리팩토링도 외부 계약을 깨면 해당하며, 변경 규모가 크다는 이유만으로 표시하지 않는다.

필수: !는 콜론 바로 앞에 둔다. scope가 있으면 feat(save)!:, 없으면 feat!:다. feat!(save):는 잘못된 형식이다.
필수: 호환성 변경에는 !와 BREAKING CHANGE: footer를 함께 작성한다. 제목에서 식별하고 footer에서 영향·필요한 대응을 설명하기 위한 개인 정책이다. 명세 자체는 둘 중 하나만으로도 표시할 수 있다.
footer에 무엇이 호환되지 않는지와 확인된 대응 방법을 적는다. 마이그레이션 도구가 없거나 미확인이라면 있다고 만들어 쓰지 않는다.

feat(save)!: replace JSON saves with binary format

BREAKING CHANGE: existing JSON saves cannot be loaded.
  Users must start a new save with this version.

위 예시는 이전 파일을 읽거나 변환하는 기능이 없는 경우다. 단순 포맷 변경만으로 저장 속도 향상을 주장하지 않는다.

작성 절차와 출력¶

실제 변경 목적과 범위를 확인하고 type·scope를 선택한다.
제목을 작성하고 전체 길이를 확인한다.
필요한 이유·제약만 본문에 추가한다.
호환성 영향·이슈 관계를 확인하고 footer를 추가한다.
문법·길이·사실 일치 여부를 다시 확인한다.

커밋 메시지 작성만 요청받으면 설명 없이 text 코드 블록에 메시지만 출력한다. 브랜치 이름도 요청받으면 Commit:과 Branch:로 구분해 각각 출력한다. 이 출력 규칙은 메시지 생성 요청에 적용하며, 컨벤션 검토·설명 요청에는 적용하지 않는다.

chore: ignore build output directory

메시지나 브랜치 이름 제안은 실제 커밋·브랜치 생성 명령 실행과 구분한다.

범위와 후속 사항¶

팀 프로젝트에서는 명시된 팀 형식을 우선한다. 도구가 생성하는 merge·revert·fixup 메시지의 처리, squash·병합 전략, 자동 릴리스·검증 도구는 후속 주제다. 이 문서만으로 자동 메시지나 과거 이력을 일괄 변경하지 않는다.

근거와 기존 방식의 변경점¶

기존 한글 자료（로컬 참고 자료）와 영문 자료（로컬 참고 자료）의 영어 기본·짧은 제목·목록 본문을 참고했다. 사용자가 새로 제공한 type(scope): subject를 기본으로 삼으며 [Add] 방식과 혼용하지 않는다.

제공안의 제목 대문자·소문자 충돌은 소문자로 통일했다. body의 목록 강제는 기본 목록·필요 시 문단 허용으로 완화했고, 구분용 빈 줄은 후속 내용이 있을 때만 요구한다. 길이·언어·type 목록·호환성 표시의 강화는 개인 정책이며 명세 전체의 요구사항으로 설명하지 않는다.

출처 확인일: 2026-09-12. 본문 문단 허용과 호환성 표시 두 가지의 병용을 포함하여 채택했다.

채택일: 2026-09-12. 명시된 적용 범위 안에서 채택하며, 후속 정리 대상은 제외한다.