git-workflow

name	git-workflow
description	VirtualMusicStudio_Unity 프로젝트의 커밋·브랜치·PR 절차. 사용자가 "커밋해", "commit", "PR 만들어줘", "PR 작성", "브랜치 추천", "브랜치 만들어", "push" 등 git/GitHub 작업을 요청할 때 사용한다. 한국어 커밋 메시지 포맷, 논리 단위 분할 절차, gh CLI 사용 원칙, pull_request_template.md 준수 같은 프로젝트별 규칙을 포함한다.
allowed-tools	Bash, Read, Grep, Glob

Git 커밋/PR 규칙

"commit 해줘", "커밋해", "PR 만들어줘" 등의 요청을 받으면 아래 절차를 따른다.

브랜치 규칙

기본 브랜치

• main: 항상 최소한 실행 가능한 상태를 유지해야 하는 브랜치

작업 브랜치 네이밍

• feat/기능명
• fix/수정내용
• chore/정리내용
• docs/문서내용
• refactor/리팩토링내용

예시:

• feat/vr-locomotion
• feat/player-interaction
• fix/xr-rig-null-reference
• chore/project-settings
• docs/git-workflow

원칙:

• 브랜치 이름은 작업 목적이 바로 드러나게 작성한다.
• 하나의 브랜치에서는 하나의 작업 주제만 다룬다.
• 사용자가 브랜치 이름 추천만 요청한 경우에는 브랜치를 새로 만들거나 변경하지 않는다.
• 브랜치 생성 또는 변경은 사용자가 명시적으로 요청했을 때만 수행한다.

GitHub 연동 원칙

• GitHub 이슈/PR 조회, 작성, 수정은 기본적으로 gh를 사용한다.
• 작업 전에 gh auth status로 인증 상태를 확인하고, git remote -v 또는 gh repo view로 대상 저장소를 확인한다.
• gh의 default repo가 upstream(kookmin-sw/2026-capstone-template)으로 잡혀 있어 인자 없는 gh issue view/gh pr list가 엉뚱한 저장소를 조회할 수 있다. 이슈/PR 명령에는 항상 --repo kookmin-sw/2026-capstone-24를 명시하거나, 세션 초반 1회 gh repo set-default kookmin-sw/2026-capstone-24로 origin을 고정한다.
• 이슈 목록 확인, 이슈 본문/댓글 확인, PR 초안 작성, PR/이슈 메타데이터 수정 같은 GitHub 쪽 작업은 gh로 처리 가능한지 먼저 확인한다.

커밋 절차

1. 변경사항 수집

git status, git diff(스테이징/언스테이징 모두), git log -5를 병렬로 실행해 변경된 파일과 기존 커밋 컨벤션을 파악한다.

2. 이상 여부 점검

커밋 전에 변경 사항 중 이상한 점이 없는지 먼저 확인한다.

• 의도하지 않은 파일이 섞였는지 확인한다.
• 로컬 설정, 자격증명, 임시 파일, 생성물 같은 불필요한 변경이 포함됐는지 확인한다.
• 씬, 프리팹, 직렬화 파일에서는 우연히 생긴 churn이나 제거/추가가 이상한 오브젝트가 없는지 확인한다.
• 스크립트 변경에서는 컴파일을 깨뜨릴 가능성이 있는 수정, 미완성 코드, 디버그 로그 잔재가 없는지 확인한다.

3. 논리 단위 분할

변경 파일을 다음 기준으로 그룹핑한다.

• type: feat / fix / refactor / chore / docs / test
• scope: VR, scene, input, UI, build, 도메인 폴더명(hands, instruments 등)
• 최소 작동 단위: 컴파일/런타임이 깨지지 않는 묶음 기준

4. 분기

• 단위가 1개이면 즉시 권장 포맷으로 커밋한다.
• 단위가 2개 이상이면 커밋하지 않고 사용자에게 분할안을 제시한다.

제시 형식:

다음과 같이 N개의 커밋으로 나눌 수 있습니다:

1. feat(hands): <설명>
   - Assets/Hands/Scripts/Foo.cs
   - Assets/Hands/Prefabs/Physics/LeftPhysicsHand.prefab
2. docs(git): <설명>
   - AGENTS.md
   - .claude/skills/git-workflow/SKILL.md

이대로 진행할까요? 아니면 다른 단위로 묶을까요?

사용자가 승인하거나 조정안을 주면 그 지시대로 순차 커밋한다.

5. 커밋 메시지 포맷

<type>(<scope>): <description>

• 커밋 메시지는 기본적으로 한국어로 작성한다.

예시:

• feat(VR): 텔레포트 이동 추가
• fix(scene): 누락된 프리팹 레퍼런스 복구
• docs(git): 브랜치 가이드 추가

scope는 생략 가능: feat: 텔레포트 이동 추가

PR 절차

0. 연관 이슈 확인

PR을 작성하기 전에 반드시 연관 이슈를 먼저 확인한다.

• 먼저 gh issue list --state open으로 열린 이슈만 훑고, 현재 브랜치명/커밋/변경 파일 기준으로 어떤 이슈와 연관되는지 판단한다.
• 연관 이슈가 불분명하면 gh issue list --state all로 범위를 넓힌다.
• 후보 이슈는 gh issue view <번호>로 본문과 TO-DO를 읽는다.
• 연관 이슈의 TO-DO 중 이번 변경으로 완료된 항목이 있으면, 이슈를 바로 수정하지 말고 완료 후보 항목을 사용자에게 먼저 보고한다.
• 사용자가 명시적으로 승인하기 전에는 이슈의 체크박스, 본문, 상태를 수정하지 않는다.
• 여러 이슈 성격이 섞여 있으면 분리를 먼저 제안한다. 사용자가 단일 PR을 명시하면 그대로 진행.
• 단일 PR 진행 시 PR 본문에 관련 이슈를 모두 나열하고 close/Related를 구분한다.

PR 제목은 커밋과 동일한 포맷을 권장한다.

<type>(<scope>): <description>

PR 본문은 반드시 루트의 pull_request_template.md를 따른다.

현재 기준 템플릿은 아래 순서를 사용한다.

📌 ## 이슈 번호 #1
- ✅ close #1

## 🛠️ 작업 사항

## 💬 기타

• PR 작성 시 템플릿의 섹션 순서뿐 아니라 아이콘과 제목 표기까지 그대로 유지한다.
• 이슈 번호와 close #번호는 실제 작업 이슈에 맞게 채운다.
• TO-DO가 모두 완료된 이슈만 close #번호, 남아 있거나 애매하면 Related #번호로 참조한다.
• 여러 이슈와 연관되어 있으면 close 대상과 참고 대상 이슈를 구분해서 적는다.
• 템플릿이 변경되면 pull_request_template.md를 최신 기준으로 간주한다.
• PR 본문 문체는 반말로 짧게 작성해도 된다.
• 작업 사항은 완전한 문장 대신 구성 정리., 로직 적용., 정리. 같은 짧은 서술형으로 적어도 된다.
• ## 💬 기타 섹션은 항상 남기되, 사용자가 별도로 요청하지 않으면 내용을 채우지 않고 비워둔다.

주의사항

• .env, 자격증명 파일, 대용량 바이너리는 스테이징에서 제외한다.
• 사용자가 명시하지 않으면 git push, --no-verify, --amend, push --force는 수행하지 않는다.