bibimbap/docs/development/git-workflow.md

Git Workflow — 브랜치 / 커밋 / push 정책

반복 적용되는 git 작업 규칙의 정본(canonical)이다. CLAUDE.md '작업 원칙'의 커밋 관련 불릿은 이 문서를 가리킨다. 하니스 기본규칙("Commit or push only when the user asks. If on the default branch, branch first.")을 프로젝트 차원에서 보충·명시화한다.

브랜치 분류

• 메인스트림 브랜치: main, master, 그리고 origin 상의 보호 브랜치(릴리스/배포 브랜치 등). 현재 프로젝트 default 는 main(.git/config, origin/HEAD 기준).
• 비-메인스트림 브랜치: 위를 제외한 모든 작업 브랜치 — feat/*, fix/*, chore/*, docs/* 등. 현재 활성 작업 브랜치 feat/v2 가 여기 속한다.

커밋 표준 승인 (durable authorization)

• 비-메인스트림 브랜치에서 커밋은 표준 승인된 행위다. 작업 단위가 완결될 때마다 사용자에게 매 건 묻지 않고 커밋한다. 이는 하니스 기본규칙의 '사용자 요청 시에만 커밋' 원칙을, 프로젝트 지침이 사전·상시 승인을 부여하는 형태로 만족시키는 것이다(자동 커밋 재량 위임이 아니라, 사용자가 부여한 표준 승인의 실행).
• 메인스트림 브랜치에는 표준 승인이 적용되지 않는다. main/master/보호 브랜치 위에서는 직접 커밋하지 않고, 먼저 작업 브랜치를 생성한 뒤 비-메인스트림 규칙으로 진행한다.
• push 는 브랜치와 무관하게 항상 사용자 명시 요청 시에만 수행한다. 표준 승인은 로컬 커밋에 한정되며 원격 반영(push)·PR 생성은 포함하지 않는다.
• 작업 전후로 git status --short 로 사용자 변경을 보호한다(섞인 미관련 변경을 같은 커밋에 넣지 않는다).

커밋 단위

• 한 커밋은 하나의 논리적 변경으로 한정한다. 코드 변경과 그에 대한 문서/그래프 메타 갱신처럼 결합이 강한 산출물은 함께 묶되, 성격이 다른 변경(예: 기능 구현 vs 빌드 스크립트 vs 정책 문서)은 분리한다.
• 버그 수정 커밋은 docs/development/verification-strategies.md 의 회귀 테스트 의무를 따른다(재현 테스트 동반).
• .atp/work-session/<timestamp>/ 산출물은 추적 대상이며, 해당 세션의 코드/문서 변경과 함께 또는 별도 chore/docs 커밋으로 기록한다.

커밋 메시지 규약

• Conventional Commits 형식을 사용한다: type(scope): subject. 사용 중인 type: feat, fix, docs, chore. scope 는 한국어 가능(예: docs(graph), chore(dev)).

• subject 는 한국어로 변경의 핵심을 간결히 적는다(이모지 미사용).

• 본문은 '왜'가 자명하지 않을 때 추가하고, 변경 항목은 불릿으로 정리한다. 검증 결과(예: ./mvnw test N/N GREEN)가 있으면 본문에 명시한다.

• 모든 에이전트 생성 커밋에는 트레일러를 포함한다:

  Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
  

  세션 추적이 필요하면 Claude-Session: <url> 트레일러를 추가할 수 있다.

참고

• 검증 의무(L1/L2/L3, 변경 범주별): docs/development/verification-strategies.md
• 에이전트 출력/압축 규약: docs/development/agent-output-conventions.md