managing-branch-pr-workflow

name	managing-branch-pr-workflow
description	Enforce branch-based workflow with meaningful Korean commits and PR creation for traceable decision history.

브랜치 + PR 기반 작업 워크플로우

설명

사용자의 요청(User Request)은 main 브랜치에 auto-commit으로 기록되어 생각의 흐름을 보존합니다. Claude의 작업은 feature 브랜치에서 수행하며, 각 커밋에 WHY(의사결정 근거)를 포함하여 작업 이력을 추적할 수 있도록 합니다. 작업 완료 후 PR을 생성하여 전체 변경사항의 요약과 근거를 문서화합니다.

워크플로우

1. 계획 수립 후 브랜치 생성

git checkout -b feature/{작업-설명}

• 브랜치명은 영문 소문자, 하이픈 구분 (예: feature/cqrs-refactor, feature/sqlite-persistence)
• 계획(Plan)이 승인된 직후, 코드 변경 전에 생성

2. 첫 번째 커밋 (자동)

• Stop 훅(auto-commit.mjs)이 feature 브랜치에서 자동으로 빈 커밋 생성:

  [요구사항]
  {사용자가 요청한 내용}
  

• .last_prompt 파일에서 사용자 요청을 읽어 --allow-empty 커밋으로 기록
• 코드 변경 없이 요구사항만 기록하므로 이후 커밋과 분리됨

3. 작업 중 의미 있는 한글 커밋

git add {관련-파일들}
git commit -m "{타입}: {무엇} - {왜}"

• 논리적 단위마다 커밋 (하나의 커밋 = 하나의 논리적 변경)
• 커밋 메시지는 반드시 한글로 작성
• 커밋 메시지에 반드시 WHY를 포함

4. 작업 완료 후 PR 생성

gh pr create --title "{제목}" --body "## 요약\n- ...\n\n## 의사결정 근거\n- ..."

• PR 본문에 의사결정 근거 섹션 포함
• 테스트 결과 포함

커밋 메시지 형식

{타입}: {무엇을 했는지} - {왜 이렇게 했는지}

타입 종류

타입	용도
기능	새 기능 추가
수정	버그 수정
리팩토링	코드 리팩토링 (동작 변경 없음)
테스트	테스트 추가/수정
문서	문서 변경
기타	빌드, 설정 등

나쁜 예

# main에 직접 작업, 의사결정 근거 없음
[User Request] CQRS 패턴형태로 코드를 리펙토링 해야합니다...

# 모든 변경사항이 하나의 커밋에, WHY 없음

좋은 예

# main: 사용자 요청 기록
[User Request] CQRS 패턴형태로 코드를 리펙토링 해야합니다...

# feature/cqrs-refactor: Claude 작업 이력
[요구사항] CQRS 패턴형태로 코드를 리펙토링 해야합니다...     ← 자동 (auto-commit.mjs)
기능: Query/Command 요청 record 정의 - 읽기/쓰기 의도를 타입 시스템으로 명시
기능: Handler 인터페이스 분리 - DI를 통한 테스트 격리와 구현 교체 용이성 확보
리팩토링: Program.cs 엔드포인트를 Handler로 위임 - Minimal API 구조 유지하면서 비즈니스 로직 분리
테스트: Handler mock 테스트 추가 - 비즈니스 로직을 DB 없이 독립 검증

# PR #1: CQRS 패턴 적용
## 요약
- Query/Command 분리로 CQRS 구현
## 의사결정 근거
- Handler를 인터페이스로 분리한 이유: Moq 기반 단위 테스트 지원
- Request를 record로 정의한 이유: 불변성 보장 + 값 기반 동등성

auto-commit 동작

• auto-commit.mjs는 브랜치 인식
  • main: 모든 변경사항을 [User Request] 커밋 (기존 동작)
  • feature: 코드 변경 없이 [요구사항] 빈 커밋만 자동 생성 → Claude가 코드 커밋 직접 관리