git-conventions

name	git-conventions
description	Use when creating commits, branches, pull requests, or GitHub issues. Covers Conventional Commits format (English only — enforced by commit-msg-check.sh hook), branch naming, PR/issue templates, and merge etiquette. Trigger any time a git/gh command is about to run or when drafting a PR description.

Git Conventions

커밋 메시지

Conventional Commits 형식을 사용한다.

type(scope): 메시지

타입

타입	사용 시점
feat	새로운 기능 추가
fix	버그 수정
refactor	기능 변경 없는 코드 개선
test	테스트 추가/수정
docs	문서 작성/수정
perf	성능 개선
chore	빌드/설정/의존성 변경
build	빌드 시스템 변경

스코프 (선택)

변경된 도메인/기능을 괄호 안에 명시한다.

feat(place): implement dynamic Redis TTL based on meeting endAt
fix(withdrawal): only block withdrawal for active meetings
refactor(place): enhance fault tolerance using supervisorScope
test(place): fix MeetingPlaceSearchServiceTest failure

스코프 없이 전체 프로젝트에 영향을 줄 때:

refactor: remove all benchmark dependencies from production source
feat: migrate external clients from WebClient to Ktor Client

주의

• type : (콜론 앞 공백) 형식 사용 금지 — type: 또는 type(scope): 사용
• 메시지는 영문 소문자로 시작, 마침표 없음
• 제목은 72자 이내

작업 시작 순서 (중요)

PR 작성 전에 반드시 이슈를 먼저 만든다 — 브랜치 네이밍이 이슈 번호를 요구하기 때문.

1. gh issue create  → 이슈 번호 확보 (예: #187)
2. git checkout -b feat/#187  → 이슈 번호로 브랜치
3. 작업 → commit → push
4. gh pr create  → PR 본문에 "Close #187" 또는 "Resolves #187"

이슈 없이 작업이 시작된 경우(예: 핫픽스): 작업 도중에라도 이슈를 만들고 브랜치명을 맞춘다. 이미 push 한 PR 이라도 다음 PR 부터는 이 순서를 지킨다.

브랜치 네이밍

{type}/#{issue-number}

예시:

• feat/#123
• fix/#456
• refactor/#169

❌ 안티 패턴: feat/sonar-auto-fix-workflow (이슈 번호 없이 설명형 슬러그) — PR #186 회고 참조

PR 작성

.github/PULL_REQUEST_TEMPLATE.md 양식은 무시하고 아래 형식을 사용한다. 가치 중심 서술이 핵심 — "무엇을 바꿨는가"보다 "왜 이 변경이 필요했는가"를 먼저 전달한다.

언어 규칙

• PR 제목: 영문 (Conventional Commits 와 동일 규약 — type(scope): message, 소문자 시작, 72자 이내)
• PR 본문: 한국어로 작성 (헤딩은 영문 ## Summary / ## Test plan 유지, 본문 내용은 한국어)
• 커밋 메시지: 영문 (commit-msg-check.sh 훅이 강제)
• 이슈 본문: 한국어

본문 형식

## Summary

<변경의 맥락과 목적을 1~2문장의 한국어로>

### <변경 묶음 1 제목> (커밋이 여러 개거나 주제가 나뉠 때만 ### 사용)

- 핵심 변경 사항과 이유 (한국어)
- 설계 결정이 있으면 why를 포함

### <변경 묶음 2 제목>

- ...

## Test plan

- [x] 실제로 확인한 항목만 체크
- [x] `./gradlew harness` 통과 여부
- [x] CI 통과 여부

🤖 Generated with [Claude Code](https://claude.com/claude-code)

작성 원칙

• ## Summary 바로 아래에 변경의 핵심을 먼저 — 리뷰어가 첫 문단만 읽어도 PR의 가치를 알 수 있어야 함
• 커밋이 1개거나 주제가 단일하면 ### 없이 ## Summary 아래 바로 bullets
• 커밋이 여러 개이거나 주제가 나뉠 때만 ### 서브섹션 사용
• 설계 결정이 있으면 (a) / (b) / ... 형식으로 명시 (왜 다른 방법이 아닌지 포함)
• Test plan은 실제로 검증한 것만 — 형식적 체크리스트 금지
• 헤딩은 영문 그대로(## Summary, ## Test plan), 본문 텍스트만 한국어

PR 머지 대상: dev 브랜치 (CI는 dev 브랜치 PR에서 트리거됨)

이슈 작성

두 가지 템플릿 중 선택:

기능 구현 이슈 (.github/ISSUE_TEMPLATE/기능-구현-이슈-템플릿.md):

## 어떤 기능인가요?
> 추가하려는 기능에 대해 간결하게 설명

## 작업 상세 내용
- [ ] 세부 작업 1
- [ ] 세부 작업 2

## 참고할만한 자료(선택)

수정/리팩토링 이슈 (.github/ISSUE_TEMPLATE/수정---리팩토링-관련-이슈-템플릿.md): 동일한 구조, 수정/개선 작업에 사용.