sam-docs/standards/git-conventions.md

Git 커밋 컨벤션

업데이트: 2025-12-02

---

커밋 메시지 형식

[타입]: [scope] 작업내용

- 세부항목 (생략가능)
- 세부항목 2

Issue: URL (생략가능)

예시

feat: [calendar] 달력 기능 개선

- 클릭시 오류 기능 개선
- 색상 변경
- 각 항목별 색상 지정

Issue: https://www.notion.so/hamss/2269c8d34ba080489680e0607a95d9c4

fix: [auth] 로그인 시 세션 만료 오류 수정

refactor: [user] UserService 메서드 분리

- validateUser 메서드 추출
- 중복 코드 제거

---

Commit Types

Type	설명	예시
feat	새로운 기능 추가	feat: [file] 파일 업로드 기능 추가
fix	버그 수정	fix: [auth] 세션 만료 오류 수정
chore	설정, 빌드 등 변경	chore: composer 패키지 업데이트
refactor	프로덕션 코드 리팩토링	refactor: [user] 서비스 메서드 분리
style	포맷/코딩 스타일 수정	style: Pint 포맷팅 적용
test	테스트 추가/수정	test: Product API 테스트 추가
docs	문서 변경	docs: API 문서 업데이트

fix vs feat vs refactor 판단 기준

"고치는 작업"이 많으므로 타입 선택 시 다음 기준을 따른다:

상황	타입	핵심 기준
기존 기능이 의도대로 동작하지 않는 것을 수정	fix	원래 되어야 하는데 안 되는 것
계산 결과가 틀림, 데이터가 누락됨, 에러 발생	fix	기대 결과와 실제 결과가 다름
기존 기능에 새 조건/필터/옵션을 추가	feat	없던 것을 새로 만드는 것
요청에 의한 동작 변경 (사양 변경)	feat	버그가 아닌 새로운 요구사항
동작은 동일, 코드 구조만 개선	refactor	결과는 같고 내부만 변경
설정 파일, 의존성, 빌드 변경	chore	코드 동작과 무관한 관리 작업

✅ fix  = "깨진 것을 고친다" (버그, 오류, 잘못된 결과)
✅ feat = "없던 것을 만든다" (신규 기능, 사양 변경, 기능 확장)
✅ refactor = "같은 것을 더 좋게 만든다" (구조 개선, 중복 제거)

---

커밋 빈도 가이드

원칙: "논리적 단위"로 커밋

❌ 파일 하나 수정할 때마다 커밋 (너무 잦음)
❌ 몇 시간 작업을 한 번에 커밋 (되돌리기 어려움)
✅ 하나의 의미 있는 변경이 완성되면 커밋

"의미 있는 변경" 기준

• 마이그레이션 1건 완성
• Service/Controller 로직 수정 1건 완성
• Swagger 문서 업데이트 완성
• 설정 파일 변경 완성

예시 — WorkOrder API 수정 작업

# 1) DB 변경 완성 → 커밋
fix: [work-order] options 컬럼 추가 마이그레이션

# 2) 비즈니스 로직 완성 → 커밋
fix: [work-order] 옵션 필터링 로직 수정

# 3) 문서 업데이트 → 커밋
docs: [work-order] options 파라미터 Swagger 추가

장점

• 되돌리기 용이: 마이그레이션만, 로직만, 문서만 선택적 revert 가능
• 코드 리뷰 용이: 커밋 단위로 변경 의도 파악 가능
• 작업 손실 방지: 중간에 문제 발생 시 이전 커밋까지 안전

---

Claude 서명 제외 정책

커밋 메시지에 다음 내용을 포함하지 않음:

❌ 🤖 Generated with [Claude Code](https://claude.com/claude-code)
❌ Co-Authored-By: Claude <noreply@anthropic.com>

• Git hooks로 자동 제거됨
• 간결하고 명확한 한글 커밋 메시지만 유지

---

저장소별 커밋

# 각 저장소에서 개별 커밋
cd api && git add . && git commit -m "feat: [scope] 작업 내용"
cd ../mng && git add . && git commit -m "feat: [scope] 작업 내용"
cd ../react && git add . && git commit -m "feat: [scope] 작업 내용"

---

Branch 전략

Feature Development

# main/master에서 직접 작업 금지
git checkout -b feature/file-storage-system
# 작업 진행...
git commit -m "feat: [file] ..."
# PR 생성

Hotfix

git checkout -b hotfix/login-session-bug
# 긴급 수정...
git commit -m "fix: [auth] ..."
# PR 또는 즉시 병합

---

커밋 전 체크리스트

✓ ./vendor/bin/pint 실행 (코드 포맷팅)
✓ php artisan migrate:status 확인
✓ 테스트 실행 (해당하는 경우)
✓ git diff 로 변경사항 검토
✓ 불필요한 파일 제외 (.env, node_modules 등)
✓ CURRENT_WORKS.md 업데이트

---

푸시 정책

• 사용자가 수동으로 푸시 진행
• 자동 푸시 하지 않음
• 커밋 후 푸시 여부를 묻지 않음

---

중요 사항

• 각 저장소는 독립적으로 운영
• 저장소별 개별 커밋 메시지 사용
• 일관된 커밋 타입 및 형식 유지

관련 문서

• 개발 명령어
• 품질 체크리스트

---

최종 업데이트: 2025-12-02