Unity Commit Message

Unity 게임 프로젝트를 위한, Conventional Commits 표준을 기반으로 한 커밋 메시지 작성 스킬입니다.

언제 사용하는가

• 사용자가 명시적으로 커밋 메시지 작성을 요청할 때
• 대화 세션에서 하나의 기능/수정/리팩토링 작업이 마무리되는 시점에 사용자가 다음 단계로 넘어가려 할 때 (먼저 "커밋 메시지 만들어드릴까요?" 라고 제안해도 좋음)

입력은 git diff가 아니라 대화 맥락이다. 이 스킬은 git diff를 파싱하는 도구가 아니다. 해당 세션에서 실제로 어떤 작업을 했는지 — 어떤 클래스/함수를 추가했는지, 어떤 버그를 왜 고쳤는지, 어떤 에셋을 왜 만들었는지 — 를 대화 내용에서 추론해서 커밋 메시지를 구성한다. 애매하면 추측해서 채우지 말고 사용자에게 확인한다.

작업 순서

1. 세션 내용 정리: 이번 세션에서 실제로 이루어진 변경사항을 목록화한다. 코드 변경(C# 스크립트 로직)과 콘텐츠/에셋 변경(씬, 프리팹, ScriptableObject, 머티리얼, 메시, 애니메이션 클립 등)을 구분한다.
2. 관심사(concern) 단위로 묶기: 목록화된 변경사항을 관심사 단위로 그룹핑한다. "기능 추가"와 "무관한 리팩토링"처럼 성격이 다른 변경이 섞여 있으면 하나의 커밋으로 뭉치지 않는다.
3. 커밋 분리 여부 판단: 관심사가 2개 이상이면, 여러 개의 원자적(atomic) 커밋으로 나눌 것을 제안한다. 각 커밋을 순서대로 제시하고, 왜 나누었는지 한 줄로 설명한다. 사용자가 "하나로 합쳐줘" 등으로 요청하면 그에 따른다.
4. 각 커밋에 대해 type/scope/subject/body/footer 구성 (아래 규칙 참고).
5. 최종 결과를 코드 블록으로 제시하여 그대로 복사해 git commit 에 쓸 수 있게 한다. 여러 커밋이면 각각 별도 코드 블록으로 분리한다.

커밋 메시지 형식

Conventional Commits 표준을 기반으로 하되, 아래처럼 구성합니다.

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

<body>

<footer>

• type, scope, subject는 영어로 작성한다.
• body는 한국어로 작성 가능하다 (변경 이유·맥락을 정확히 전달하는 것이 우선이므로).
• subject는 명령형(imperative mood)으로, 마침표 없이, 50~72자 이내로 간결하게.
• body/footer가 필요 없는 단순한 변경이면 subject 한 줄만 작성해도 된다. 억지로 body를 채우지 않는다.

type

Conventional Commits 표준 type을 기본으로 사용한다.

type	의미
feat	새로운 기능 추가
fix	버그 수정
refactor	동작 변화 없는 코드 구조 개선
perf	성능 개선
style	포맷팅, 네이밍 등 로직에 영향 없는 변경
docs	문서, 주석
test	테스트 코드 추가/수정
build	빌드 설정, ProjectSettings/, Packages/manifest.json, .asmdef, 플러그인/모듈 설정
ci	CI/CD 파이프라인
chore	그 외 잡무성 변경
revert	이전 커밋 되돌리기

Unity 프로젝트 확장 type (표준에는 없지만 이 프로젝트에서 사용):

type	의미
assets	코드 변경 없이 순수하게 씬/프리팹/ScriptableObject/머티리얼/메시/사운드 등 에셋만 추가·수정한 경우

코드와 함께 에셋도 바뀌었다면 굳이 assets를 쓰지 않고, 변경의 본질(feat/fix 등)을 type으로 삼는다. assets는 에셋만 단독으로 변경됐을 때만 쓴다.

scope

unity-issue-message 스킬과 동일한 scope 목록을 사용합니다. 프로젝트 구조가 다르면 사용자에게 맞춰 조정하세요.

scope	의미
movement	캐릭터 이동 로직
camera	카메라 추적/줌/흔들림
skill-block	스킬 블록 낙하, 체이닝(드래그), 슬롯 조작 로직
skill	개별 스킬 데이터, 모션, 이펙트
resource	자원(마나) 생성·누적·소모, 특수 스킬 생성
hit	피격 판정, 기준 프레임 처리
ui	전투 UI의 시각적 표현/레이아웃 (skill-block과 달리 로직이 아닌 뷰)
core	여러 시스템에 걸친 아키텍처성 작업
network	멀티플레이(NGO) 관련 — 실제 멀티 개발 착수 전에는 사용하지 않음

• 변경이 여러 scope에 걸치면 가장 핵심적인 scope 하나만 고른다. 억지로 여러 개를 나열하지 않는다 (feat(skill,ui): ... 같은 표기 금지).
• 목록에 맞는 scope가 없으면 프로젝트에 맞게 새 scope를 제안하고, 어떤 걸 새로 만들었는지 짚어준다.

body

• 무엇을(what) 보다 왜(why) 바꿨는지를 우선적으로 설명한다. "무엇을 했는지"는 diff/코드로 보이지만 "왜"는 커밋 메시지에만 남는다.
• 씬·프리팹·ScriptableObject·머티리얼·메시 같은 에셋 변경은 body 설명이 특히 중요하다. 이런 파일은 바이너리이거나(메시, 텍스처, 오디오) YAML로 직렬화되어 있어도 git diff로 실질적인 변경 내용을 읽기 어려우므로, body에 "무엇을 추가/변경했는지"를 구체적으로 기록해서 커밋 메시지가 사실상의 diff 역할을 하게 한다. (예: 추가된 에셋 이름, 변경된 Inspector 파라미터, 교체된 레퍼런스 등)
• 여러 항목이면 - 불릿으로 나열해도 된다.

footer

• Breaking Change: 다른 스크립트나 프리팹에서 참조하는 public 메서드/필드 시그니처 변경, NetworkVariable 구조 변경, 세이브 데이터 포맷 변경 등 기존 프리팹/씬/세이브와 호환이 깨지는 변경이면 반드시 명시한다.

  BREAKING CHANGE: <영향과 필요한 후속 조치>
  

• 이슈 참조: 사용자가 이슈/티켓 번호를 언급한 경우에만 Refs #12 또는 Closes #12 형태로 적는다. 번호를 추측해서 지어내지 않는다.

• 둘 다 해당 없으면 footer는 생략한다.

예시

일반 기능 추가 (코드)

feat(skill): 스킬 블록 3연쇄 콤보 발동 로직 추가

플레이어가 슬롯 내 인접한 동일 종류 블록을 연속 선택해 3연쇄 콤보를
발동할 수 있도록 SkillComboHandler를 추가함. 각 타격 시 콤보 타이머가
초기화되고, 제한 시간 내 후속 입력이 없으면 콤보가 리셋됨.

버그 수정

fix(movement): 대시 중 이동 입력에 넉백이 씹히는 현상 수정

대시 애니메이션 재생 중 이동 입력이 들어오면 Rigidbody 이동 처리가
대시 이동과 동시에 적용되어 제자리에서 미끄러지던 문제를 수정.
대시 상태에서는 이동 입력을 일시적으로 락하도록 변경.

에셋 단독 변경

assets(skill): 화염 스킬 파티클 및 임팩트 스프라이트 추가

- FireSkill_Particle(Particle System) 프리팹 추가
- Impact_Fire 스프라이트 시트 3종 추가
- 바이너리/직렬화 에셋이라 diff로 확인이 불가능하여 추가 내역을 본문에 기록

Breaking Change가 있는 리팩토링

refactor(core): DamageCalculator.Calculate 파라미터 정리

Calculate 메서드에서 불필요한 파라미터를 제거하고 순서를 정리함.

BREAKING CHANGE: DamageCalculator.Calculate 파라미터 순서가 변경되어,
이 메서드를 참조하는 다른 스크립트와 Inspector에 노출된 프리팹 필드를
다시 연결해야 함.

여러 관심사가 섞여 커밋 분리를 제안하는 경우

이번 세션에는 서로 다른 관심사(대시 쿨다운 기능 추가 + 자원 컴포넌트 초기화 리팩토링)가 섞여 있어, 커밋을 2개로 나누는 걸 제안드립니다.

feat(movement): 대시 쿨다운 시스템 추가

...

refactor(resource): ResourceManager 초기화 로직 정리

...

주의사항

• 세션에서 확인되지 않은 내용을 지어내서 body/footer에 채우지 않는다. 불확실하면 사용자에게 짧게 확인한다.
• subject 한 줄만으로 충분히 명확한 단순 변경(오타 수정, 사소한 스타일 정리 등)에는 body를 억지로 붙이지 않는다.
• scope와 type을 동시에 여러 개 나열하지 않는다 — 하나의 커밋은 하나의 핵심 관심사를 대표해야 한다는 Conventional Commits 원칙을 따른다.