# 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`