ai-rules › 01-git · Git 규칙

01-git Git 규칙

에이전트 금지 명령 (CRITICAL)

Critical Rule
이 규칙에는 절대 금지 항목이 포함되어 있습니다. AI 에이전트가 위반할 경우 즉시 중단합니다.

에이전트 금지 명령 (CRITICAL)

❌ 절대 금지: rebase, merge (ff-only 제외), checkout --ours/--theirs, conflict 자동 해결, push -f/--force

✅ 허용: status/log/diff/fetch, 새 브랜치 생성(checkout -b), add/commit/push origin {branch}

  • push는 반드시 현재 브랜치 → 동일 이름 remote (push origin feature/xxx) — push origin feature/xxx:master 같은 cross-push 절대 금지

Conflict 발생 시: 즉시 --abort 후 사용자 보고 — 자동 해결 절대 금지

ff-only merge 실패 시: rebase/merge --no-ff 자동 시도 금지 → 즉시 멈추고 사용자에게 보고:

"ff-only merge가 불가합니다 (브랜치가 분기됨).
 01-git 규칙상 rebase는 금지되어 있습니다.
 1. PR 방식으로 전환 (→ origin/master)
 2. 사용자가 직접 처리"

❌ 절대 금지: rebase, checkout --ours/--theirs, conflict 자동 해결, push -f/--force

✅ 허용: merge --no-ff (충돌 없을 때), merge --ff-only, status/log/diff/fetch, 새 브랜치 생성(checkout -b), add/commit/push origin {branch}

  • push는 반드시 현재 브랜치 → 동일 이름 remote (push origin feature/xxx) — push origin feature/xxx:master 같은 cross-push 절대 금지

Conflict 발생 시: 즉시 merge --abort 후 사용자 보고 — 자동 해결 절대 금지. 충돌 없는 merge만 자동 완료.

ff-only merge 실패 시: merge --no-ff로 재시도 허용. 충돌 발생하면 즉시 merge --abort 후 사용자 보고. rebase는 여전히 금지.

작업 시작 전 환경 점검

코드 변경 작업(feat/fix/refactor) 시작 전 아래를 순서대로 확인한다. 조회/분석/테스트만 실행하는 경우 생략 가능. 문서만 변경하는 경우 1~2만 확인. continuation 세션(컨텍스트 리셋 후 이어받은 세션)도 예외 없이 실행한다.

  1. Remote 현행화: git fetch origin — 최신 참조 정보를 가져온다 (메타데이터만, 코드 변경 없음)
  2. Uncommitted 변경 확인: git status — 현재 작업 디렉토리에 커밋되지 않은 변경이 있는지 확인한다
    • clean → 정상 진행
    • dirty → 사용자에게 보고 후 지시 대기 (에이전트가 임의로 stash/reset/checkout 금지)
    • staged/unstaged 혼재 → 추가 경고 (hook이 stash/pop 과정에서 staged 버전을 소실할 수 있음)
  3. 기준 브랜치 대비 behind 확인: 아래 "브랜치 작업 시작 전 체크"와 동일 기준 적용
  4. 브랜치 선택 판단: 아래 "기존 브랜치 vs 신규 브랜치 판단"에 따라 결정

04-lifecycle Step 5에서 이미 git status를 확인한 경우 2번은 재실행하지 않는다.

기존 브랜치 vs 신규 브랜치 판단

작업 시작 시 현재 브랜치에서 이어 작업할지, 새 브랜치를 만들지 판단한다.

# 판단에 필요한 정보 수집
git branch --show-current                    # 현재 브랜치
git log --oneline -3                         # 최근 커밋 (작업 맥락 파악)
git branch -r --sort=-committerdate | head -5  # 최근 활성 remote 브랜치

기존 브랜치 이어 작업 (아래 조건 모두 충족 시)

  • 현재 브랜치가 요청된 작업과 동일 주제
  • 브랜치가 노후 기준(3일 / behind 50+) 미초과
  • 다른 에이전트/세션이 작업 중이 아님 (아래 확인)

신규 브랜치 생성 (아래 중 하나라도 해당 시)

  • 요청된 작업이 현재 브랜치 주제와 다름
  • 현재 브랜치가 노후 기준 초과
  • 현재가 main/master/develop (보호 브랜치)

다른 세션 작업 중 확인

# ~/.claude/sessions/{project}.md HANDOFF에 status: partial + 동일 브랜치면 충돌 가능
# ACTIVE_WORK.md에 해당 프로젝트의 진행 중 작업이 있으면 확인 필요
상황 판단
세션 파일에 status: partial + 같은 브랜치 ⚠️ 사용자에게 "이전 세션이 미완료 상태입니다. 이어 작업할까요?" 확인
ACTIVE_WORK.md에 다른 프로젝트 작업 진행 중 정상 진행 (프로젝트 다름)
remote에 같은 브랜치의 최근 push가 있고 로컬에 없는 커밋 ⚠️ "다른 세션에서 push된 커밋이 있습니다" 경고 + git pull --ff-only 제안
판단 불가 사용자에게 질문 — 임의 판단 금지

브랜치 규칙

  • 브랜치명: feature/{YYMMDD}-{description} (예: feature/260120-auth-refactor)
  • 에이전트는 항상 feature 브랜치에서 작업 — develop/main 직접 커밋 금지
  • 새 브랜치는 기준 브랜치의 remote 최신 시점에서 분기한다 — 로컬에 캐시된 오래된 기준 브랜치에서 분기 금지
  • 기준 브랜치 = PR 타겟 브랜치 — 분기 base 와 PR 타겟이 달라지면 두 브랜치 간 divergence 로 고아 커밋이 딸려 들어가거나 역방향 싱크가 발생한다. 아래 원칙을 따른다:
    • develop 이 있는 프로젝트: origin/develop 에서 분기 → PR 타겟 develop
    • develop 이 없는 프로젝트: origin/main(또는 master) 에서 분기 → 먼저 develop 을 생성 → 이후 origin/develop 에서 분기 (04-lifecycle 에 "develop 브랜치가 없는 프로젝트는 자동 생성한다" 명시)
    • main 과 master 는 동일하게 취급
    • 에이전트 모드가 production (→ main) 인 경우에만 예외적으로 origin/main 에서 분기 → PR 타겟 main
  • feature → develop PR → 사용자 승인 후 병합
  • 브랜치 노후 기준: 3일 이상 또는 develop 대비 behind 50+ commits → 경고 + v2 브랜치 전환 제안

브랜치 작업 시작 전 체크

모든 feature 브랜치 시작 전:

git rev-list --count HEAD..origin/develop  # behind 커밋 수 확인
git log --oneline -1                       # 브랜치 나이 확인

3일 이상 또는 behind 50+: 사용자에게 경고 → 아래 선택지 제시:

"1. 사용자가 직접 rebase 후 재작업 (에이전트 실행 금지)
 2. v2 브랜치 새로 생성 (→ feature/{YYMMDD}-{desc}-v2)
 3. 위험 감수하고 현재 브랜치 그대로 진행"

커밋 규칙

  • 형식: {type}({scope}): {설명} (conventional commits) — commitlint이 commit-msg hook에서 검증 (tooling.commitlint)
    • type: feat, fix, docs, chore, refactor, test, style
  • Co-Authored-By 필수:
    Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

커밋 & 푸시 프로세스

기본값: 에이전트 모드에 따름 (04-lifecycle 참조, 기본 auto)

  1. 브랜치 보호 체크 (CRITICAL — 커밋 전 필수) — guard-branch.sh hook이 이중 차단 (governance):
    • git branch --show-current로 현재 브랜치 확인
    • main/master/develop 브랜치이면 커밋 실행 금지 → 사용자에게 알림
    • 사용자가 예외를 선택해야만 진행 가능
  2. 소스 검증 — lint-staged가 pre-commit hook에서 자동 실행 (tooling.lint_staged)
    • 검증 실패 시 커밋 자동 중단
    • 검증 우회(// @ts-ignore, eslint-disable) 금지
  3. Diff 보고: 변경 파일 + 줄 수, 1000줄+ 경고
  1. 모드별 동작:
    • manual: 커밋만 (푸시 차단, PR 차단)
    • auto: 사용자 승인 후 커밋+푸시 — "커밋+푸시 (→ origin/{branch})" / "커밋만 (로컬)" / "취소"
    • auto-push: 자동 커밋+푸시 (feature 브랜치에서만)
    • 기타 모드: 프로젝트 extension 정의 따름
  1. 모드별 동작:
    • manual: 커밋만 (푸시 차단, PR 차단)
    • auto / auto-push: 자동 커밋+푸시 (feature 브랜치에서만, 승인 불필요)
    • 기타 모드: 프로젝트 extension 정의 따름

변명 방지 테이블

에이전트 변명 현실 올바른 행동
"feature 브랜치 만들 시간이 없어서 develop에 직접 커밋" 보호 브랜치 규칙은 긴급성과 무관 checkout -b feature/... 후 커밋
"rebase하면 깔끔해지니까 자동으로 해도 될 것" 에이전트 rebase는 절대 금지 즉시 --abort + 사용자 보고
"push --force로 빨리 정리하면 되니까" force push는 R2 비가역 작업 사용자 확인 문구 재입력 필수
"이전 세션에서 push 승인받았으니 이번에도 가능" 세션 간 승인은 이전되지 않음 현재 세션에서 재확인

Push/PR 전 충돌 사전 확인

push 또는 PR 생성 직전, 아래를 확인한다. 이 단계는 소스 검증(tsc, lint 등)과 별개다.

  1. Remote 재현행화: 작업 중 기준 브랜치가 진행되었을 수 있으므로 remote 상태를 다시 가져온다
  2. 기준 브랜치와 변경 파일 겹침 확인: 현재 브랜치 변경 파일과 기준 브랜치 변경 파일을 비교한다
    • 겹치는 파일 없음 → 정상 진행
    • 겹치는 파일 있음 → 충돌 가능성을 사용자에게 보고
  3. 충돌 감지 시: 에이전트가 merge/rebase로 해결 시도 금지 (기존 규칙). 사용자에게 선택지 제시:
    • 사용자가 직접 rebase/merge
    • 그대로 PR 생성 (GitHub/GitLab에서 충돌 해결)
    • v2 브랜치로 재작업

sync tool 예외 (화이트리스트 기반)

일반 원칙: 에이전트는 develop/main 직접 커밋·병합 금지.

예외: .claude/sync-tool-allowlist 에 등록된 결정론적 배포 스크립트는 아래 조건을 모두 만족할 때 develop 에 직접 병합할 수 있다.

  • worktree 에서 격리 실행 (본체 working tree 미변경)
  • ff-only 병합만 (충돌 시 PR 폴백)
  • 커밋 메시지 형식: chore(sync): apply {tool}@{sha}
  • push 실패 시 로컬 develop 자동 롤백 (병합 전 SHA 로 reset)

현재 등록된 예외 (ai-rules 기준):

  • scripts/sync.mjs — 규칙 문서를 각 프로젝트로 배포 (ai-rules self-sync 한정)

예외 추가 절차: PR 로 .claude/sync-tool-allowlist 수정 + docs/changes/ 에 결정 문서. LLM 추론이 개입하는 스크립트는 예외 대상이 아니다.

배포 / 보호 브랜치 병합

자동 금지 (에이전트 자체 판단)

에이전트가 스스로 판단하여 운영 배포, main/master 병합, 프로덕션 환경 변경, 보호 브랜치 직접 커밋을 실행하지 않는다.

사용자 명시 요청 시 — 지시 자체가 휴먼 승인

"운영 배포해줘" / "main에 병합해줘" / "stg 배포해줘" / "dev>stg>main pr 생성 병합" 같은 명시 지시는 그 자체가 휴먼 승인이다. 재확인 문구·추가 버튼 불필요. 지시에 포함된 플로우를 끝까지 실행하고 결과만 보고한다.

단, 아래는 명시 요청에도 확인 문구 1회 유지 (치명 R2):

  • force-push (push -f, push --force)
  • cross-push (push origin branchA:branchB)
  • .env / 시크릿 파일 수정

보호 브랜치 직접 커밋 vs PR 병합

행위 에이전트 가능?
보호 브랜치 체크아웃 후 git commit ❌ 금지 (명시 요청에도) — feature 브랜치 우회
보호 브랜치로 git push origin main 직접 ❌ 금지 (명시 요청에도)
PR 생성 + PR merge (gh pr merge) ✅ 명시 요청 시 가능
병합 후 자동 배포 트리거 ✅ 명시 요청 시 가능

"보호 브랜치 push 금지"는 feature 브랜치를 거치지 않는 직접 커밋을 막기 위한 것이지, PR을 통한 정상 병합까지 막는 것이 아니다.

휴먼 승인의 범위 (세션 내)

명시 지시의 휴먼 승인은 그 지시 시점까지 완료된 업무에 한해 유효하다.

  • [1] 사용자: "기능 A 작업" → feature/A → develop 병합 (auto 기본)
  • [2] 사용자: "main 배포" → 현재 develop HEAD → main 배포 (이 시점까지 완료된 것까지)
  • [3] 사용자: "기능 B 작업" → feature/B → develop까지만 (auto 기본 복귀)
  • [4] 사용자: "B도 main까지" → 새 명시 지시 → main 배포

[2]의 승인이 [3] 이후 작업에 자동 적용되지 않는다. 이전 세션의 승인이 전이되지 않는 것과 동일하게, 같은 세션 내에서도 새 작업은 새 승인이 필요하다.

프로젝트 브랜치 구조 감지

"main 배포" / "운영 배포" 지시를 받으면 git branch -r 로 실제 브랜치 구조를 확인해 플로우를 결정한다. "stg 없는데 어떻게 할까요?" 같은 재질문은 하지 않는다.

존재하는 브랜치 실행 플로우
develop + stg + main develop → stg → main (2단계 PR+병합)
develop + main (stg 없음) develop → main (1단계 PR+병합)
main 만 (develop 없음) 현재 feature → main (단일 PR+병합)

실제 존재하는 중간 단계만 거쳐 main(master)까지 도달한다.

CI 규칙

  • 테스트 약화 금지: 테스트를 통과시키기 위해 테스트를 수정하거나 우회하지 않음
  • 체크 우회 금지: eslint-disable, @ts-ignore 등으로 CI 체크 우회 금지
  • 오픈 PR 충돌: 다른 오픈 PR과 파일 충돌 시 → 커밋 없이 코멘트만
  • 에이전트 PR 추가 검증: 에이전트가 생성한 PR은 사람이 작성한 PR보다 reviewer subagent 통과를 필수로 적용 (GitHub Copilot Agent / Devin 표준 패턴)
    • reviewer subagent 미통과 시 PR 생성 금지
    • PR 본문에 🤖 Generated by agent 표기 필수