Git Flow Hygiene

코드 변경 작업 시작 전후로 수행할 git 위생 절차를 정의하여, 오래된 소스 기반 작업·충돌·병렬 에이전트 간섭을 예방한다

guide 2026-04-03 docs/guide/GIT_FLOW_HYGIENE.md

작성일: 2026-04-03
목적: 코드 변경 작업 시작 전후로 수행할 git 위생 절차를 정의하여, 오래된 소스 기반 작업·충돌·병렬 에이전트 간섭을 예방한다

1. 목표

core/01-git.md는 "무엇을 해서는 안 되는가"를 다룬다. 이 문서는 "무엇을 먼저 확인해야 하는가"를 다룬다.

이 문서는 01-git.md, 04-workflow.md, 06-session.md를 대체하지 않는다.
역할은 기존 core 규칙 앞단에 붙는 위생 체크를 정리하는 것이다.

해결하는 문제 세 가지:

오래된 로컬 소스 위에서 작업을 시작하는 문제
push/PR 직전에 기준 브랜치와 충돌을 뒤늦게 발견하는 문제
병렬 에이전트가 같은 파일을 동시에 수정하는 문제

2. 적용 조건

모든 세션에서 매번 점검하면 불필요한 토큰과 시간을 소비한다. 단일 판정 게이트를 사용한다.

판정 질문: "이 세션에서 커밋을 생성할 가능성이 있는가?"

작업 유형	Pre-Work (섹션 3)	Pre-Ship (섹션 5)	병렬 격리 (섹션 6)
코드 변경 (feat/fix/refactor)	필수	필수	해당 시 필수
문서만 변경 (docs)	경량 (remote + uncommitted만)	생략 가능	해당 시 필수
조회/분석/보고	생략	해당 없음	생략
테스트/lint만 실행	생략	해당 없음	생략

06-session과의 중복 방지

06-session.md Step 5에서 git status를 이미 확인한다. 역할이 다르다:

06-session: 로컬 상태 파악 (현재 브랜치, uncommitted 변경)
Git Flow Hygiene: remote 대비 상태 파악 (behind 수, 기준 브랜치 변경 여부)

06-session에서 이미 확인한 항목은 재실행하지 않는다.

3. Pre-Work Hygiene (작업 시작 전)

코드 변경 작업을 시작하기 전, 아래를 순서대로 확인한다.

3-1. Remote 상태 가져오기

remote의 최신 참조 정보를 로컬로 가져온다. 코드를 변경하는 것이 아니라 메타데이터만 동기화한다.

참고: git CLI에서는 git fetch origin

3-2. Uncommitted 변경 확인

현재 작업 디렉토리에 커밋되지 않은 변경이 있는지 확인한다.

clean → 정상 진행
dirty → 사용자에게 보고 후 지시 대기
- 에이전트가 임의로 stash, reset, checkout으로 변경사항을 폐기하거나 숨기지 않는다
staged/unstaged 혼재 → 추가 경고
- 같은 파일에 staged 변경과 unstaged 변경이 동시에 있으면 hook(lint-staged 등)이 stash/pop 과정에서 staged 버전을 소실할 수 있다

참고: 06-session Step 5에서 이미 git status를 확인했으면 결과를 재사용한다

3-3. 기준 브랜치 대비 behind 확인

현재 브랜치가 기준 브랜치(develop/main)보다 뒤처진 커밋 수를 확인한다.

01-git.md 기존 규칙(behind 50+ 또는 3일 이상 → 경고)과 동일 기준 적용
여기서는 "작업 시작 시점에 빨리 잡는 것"이 목적

참고: git CLI에서는 git rev-list --count HEAD..origin/{base-branch}

Pre-Work 결과 요약 형식

[Git Hygiene] Pre-Work
  remote: 동기화 완료
  uncommitted: 없음 (또는 N개 파일 — 사용자 확인 필요)
  behind {base-branch}: N commits

4. 브랜치 생성 규칙

새 feature 브랜치는 반드시 기준 브랜치의 remote 최신 시점에서 분기한다.

로컬에 캐시된 오래된 기준 브랜치에서 분기하지 않는다
섹션 3-1의 remote 상태 가져오기가 선행되어야 한다

참고: git CLI에서는 git checkout -b feature/{YYMMDD}-{desc} origin/{base-branch}

금지:

remote 상태를 가져오지 않고 브랜치 생성
로컬 develop/master에서 분기 (remote와 어긋날 수 있음)

5. Pre-Ship Hygiene (Push/PR 전)

push 또는 PR 생성 직전, 아래를 확인한다.

이 섹션은 01-git.md의 커밋 전 검증(tsc --noEmit, backend imports, reviewer gate 등)을 대체하지 않는다. 여기서 다루는 것은 remote 대비 drift와 충돌 가능성의 조기 감지다.

5-1. Remote 재동기화

작업 중에 기준 브랜치가 진행되었을 수 있다. remote 상태를 다시 가져온다.

5-2. 기준 브랜치와 변경 파일 겹침 확인

현재 브랜치의 변경 파일 목록과, 브랜치 분기 이후 기준 브랜치에서 변경된 파일 목록을 비교한다.

겹치는 파일 없음 → 정상 진행
겹치는 파일 있음 → 충돌 가능성을 사용자에게 보고

참고: git CLI에서는

내 변경: git diff --name-only origin/{base-branch}...HEAD

기준 브랜치 변경: git diff --name-only {merge-base}..origin/{base-branch}

5-3. 충돌 감지 시 대응

에이전트가 merge/rebase로 충돌을 해결하지 않는다 (01-git.md 규칙).

사용자에게 선택지를 제시한다:

사용자가 직접 rebase/merge
그대로 PR 생성 (GitHub/GitLab에서 충돌 해결)
v2 브랜치로 재작업

6. 병렬 에이전트 격리

2개 이상 에이전트가 동일 저장소에서 동시에 코드 변경 작업을 수행할 때 적용한다. 단일 에이전트 환경에서는 이 섹션을 생략한다.

기본값: 독립 브랜치 + worktree 격리

사용자의 별도 지시가 없으면, 각 에이전트는 독립 브랜치 + 독립 작업 디렉토리에서 작업한다. 이것이 가장 안전한 기본값이다.

에이전트당 독립된 작업 디렉토리에서 작업한다 (같은 디렉토리 공유 금지)
같은 파일을 두 에이전트가 동시에 수정하지 않는다
병렬 작업 완료 후 → 사람 주도 통합 또는 PR 기반 통합 → 검증 → push
CI 워크플로우 파일(.github/workflows 등)은 단일 에이전트만 담당

참고: git CLI에서 독립 작업 디렉토리 생성은 git worktree add

01-git.md 규칙상 에이전트는 rebase, 일반 merge, conflict 자동 해결을 수행하지 않는다. 따라서 여기서 말하는 "통합"은 에이전트 자동 merge가 아니라, 사람이 수행하거나 PR로 넘기는 정리 단계를 의미한다.

사용자 지시어로 예외 허용

01-git.md의 보호 브랜치 예외 패턴과 동일하게, 기본값은 격리이고 허용은 사용자 명시 지시로 연다. 에이전트가 스스로 예외를 판단하여 여는 것은 금지한다.

브랜치 공유 허용:

"같은 브랜치에서 작업해"
"feature/260403-xxx 브랜치 공유해서 작업해"

→ 같은 feature 브랜치를 공유하되, 도메인 분리가 필수로 따라온다.

도메인 지정:

"A는 backend/*, B는 frontend/*"
"A는 서비스 로직, B는 UI"

→ 에이전트별 수정 가능 파일 범위를 선언한다. 파일 락 테이블에 자동 반영.

순서 제어:

"A 먼저 커밋하고, B가 이어서"
"A 끝나면 B 시작해"

→ 순차 모드. 한 에이전트가 커밋+푸시 완료 후 다른 에이전트가 pull하여 최신화 후 시작.

지시어 없을 때 → 기본값(독립 브랜치 + worktree 격리) 적용.

에이전트 자율 예외 금지

에이전트가 "파일이 겹치지 않으니 같은 브랜치에서 해도 되겠다"고 스스로 판단하여 격리 규칙을 완화하는 것을 금지한다.

이유:

에이전트는 다른 에이전트의 향후 수정 계획을 완전히 알 수 없다
"지금은 안 겹친다"가 "앞으로도 안 겹친다"를 보장하지 않는다
에이전트끼리 주고받는 텍스트 지시를 사람 지시로 오인할 위험이 있다
01-git.md의 보호 브랜치 규칙도 동일한 원칙: 에이전트가 "이 프로젝트는 예외"라고 자율 판단하지 않음

예외가 필요하면 반드시 사람이 재확인 문구로 인증해야 한다. 위험도별 승인 방식, 권한 위임 모델, agent-to-agent 지시 오인 방지 등 상세는 HUMAN_AUTHORITY_MODEL.md 참조.

판단 기준표

조건	모드	사용자 지시어
완전 독립 작업 (서로 다른 기능)	독립 브랜치 + worktree	불필요 (기본값)
같은 기능, 파일 겹침 없음	브랜치 공유 + 도메인 분리	"같은 브랜치에서 작업해" + 도메인 지정
같은 기능, 파일 겹침 가능	브랜치 공유 + 순차 모드	"A 먼저, B 이어서"
같은 기능, 파일 겹침 + 병렬 필수	독립 브랜치 + worktree → PR 통합	불필요 (기본값이 이미 최적)

파일 락 확인

이 섹션은 검증된 core 절차가 아니라 candidate 운영 패턴이다. 현재 공통 세션 규칙에는 락 필드가 강제되지 않으므로, 프로젝트별로 SESSION.md 또는 별도 락 파일을 진실원으로 정해야 한다.

작업 시작 전 SESSION.md의 files_touched 또는 Active Locks 테이블에서 다른 에이전트가 점유 중인 파일을 확인한다.

겹치는 파일이 있으면:

사용자에게 보고
독립 작업 디렉토리로 격리하거나 대기

파일 락 테이블 형식 (권장):

## Active Locks

| Agent | Files | Started | Expires |
|-------|-------|---------|---------|
| claude-1 | backend/services/* | 2026-04-03 10:00 | 2026-04-03 12:00 |
| claude-2 | frontend/pages/* | 2026-04-03 10:30 | 2026-04-03 11:30 |

도메인 분리 (브랜치 공유 시 필수)

브랜치 공유 모드에서는 도메인 분리가 필수다. 독립 브랜치 모드에서는 강력 권장이다.

## Domain Ownership

| Domain | Primary Agent | Backup |
|--------|--------------|--------|
| backend/* | agent-1 | human |
| frontend/* | agent-2 | human |
| docs/* | any | - |

7. 도구 중립 표현 가이드

이 문서의 본문은 도구 중립 표현으로 작성되어 있다. 구체적인 명령어는 각 섹션의 "참고" 블록과 아래 매핑 테이블에 분리한다.

이유: ai-rules는 Claude Code, Cursor, Windsurf, plain 등 여러 adapter로 출력된다. 구체 명령어가 본문에 들어가면 특정 도구에 종속되어 다른 adapter에서 노이즈가 된다.

매핑 테이블

도구 중립 표현	git CLI 예시	비고
remote 상태를 가져온다	`git fetch origin`	메타데이터만, merge 없음
uncommitted 변경을 확인한다	`git status`	06-session Step 5와 공유 가능
기준 브랜치 대비 behind 수를 확인한다	`git rev-list --count HEAD..origin/{base}`	01-git 기존 패턴
기준 브랜치의 remote 최신에서 분기한다	`git checkout -b {branch} origin/{base}`	fetch 후 실행
변경 파일 목록을 기준 브랜치와 비교한다	`git diff --name-only origin/{base}...HEAD`	충돌 사전 확인용
독립 작업 디렉토리를 생성한다	`git worktree add ../{dir} {branch}`	병렬 에이전트 격리

8. Core 승격 후보 태그

이 문서의 각 섹션은 검증 후 core 규칙으로 승격할 수 있다. 승격 대상:

섹션	승격 대상	추가 형태
섹션 2 (적용 조건)	`04-workflow.md`	Minimal Footprint 원칙에 Git Hygiene 적용 조건 1문단
섹션 3 (Pre-Work)	`01-git.md`	"브랜치 작업 시작 전 체크"에 항목 추가
섹션 4 (브랜치 생성)	`01-git.md`	"브랜치 규칙"에 분기 시점 규칙 추가
섹션 5 (Pre-Ship)	`01-git.md`	"커밋 & 푸시 프로세스"에 0단계 추가
섹션 6 (병렬 격리)	`10-subagent-patterns.md`	Teammate 패턴 아래 "격리 규칙" 섹션

승격 경로: candidate (이 문서) → 2개 이상 프로젝트 적용 → validated → core 승격

출처

이 문서는 아래 프로젝트에서 검증된 패턴을 도구 중립 형태로 일반화한 것이다:

AITEM docs/guide/BRANCH_STRATEGY.md — 작업 전 최신화, 파일 락 시스템, 멀티 에이전트 시나리오
AX-Studio docs/guide/BRANCH_STRATEGY.md — locks.json 기반 자동 검증, 도메인 분리
AX-Studio .claude/agents/git-guardian.md — 충돌 감지 → worktree 격리 제안
AITEM docs/guide/AI_AGENT_FAILURE_CASEBOOK.md — 병렬 에이전트 worktree 필수, lint-staged stash 문제