Git 조작 자동화: 커밋부터 PR 머지까지

입문 코스의 여섯 번째 글입니다. 지금까지 파일을 읽고 고치고 디버깅하는 법을 배웠다면, 이 글은 그 작업을 안전하게 보관하고 검토받는 흐름을 다룹니다. Git 명령어를 외우지 않아도 됩니다. 원구연 강사의 8주 교재 3주차가 "깃허브 계정만 있는 초보"를 전제로 첫 푸시까지 가는 것처럼, 이 글도 지시문으로만 7단계를 완주합니다. 다음 글은 「바이브 코딩이란 무엇인가」입니다.

핵심 요약

• Claude Code는 git과 직접 작동합니다. 스테이징, 커밋 메시지 작성, 브랜치 생성, PR 열기를 우리말 지시로 처리합니다.
• 필요한 것은 git, GitHub 계정, GitHub CLI(gh) 세 가지입니다.
• 흐름은 초기화, 첫 커밋, 브랜치, 푸시, PR, 머지, 로컬 최신화의 7단계입니다.
• 저장소는 비공개로 만들고, git push에 승인 규칙을 걸어 의도치 않은 푸시를 막습니다.
• 작업이 한 단락 끝날 때마다 "커밋하고 푸시해 줘"가 습관이 되어야 합니다.

사전 준비: 무엇이 설치돼 있어야 하나

세 가지를 확인합니다.

1. git. macOS는 터미널에서 git --version을 치면 없을 경우 설치를 안내합니다. Windows는 Git for Windows를 설치합니다. 공식 문서는 Claude Code가 Bash 도구를 쓸 수 있도록 Git for Windows를 권장하며, 없으면 PowerShell을 셸로 씁니다.
2. GitHub 계정. github.com에서 이메일로 가입합니다. 교재의 조언대로 아이디는 영문으로, 앞으로 명함처럼 쓰인다고 생각하고 짓습니다.
3. GitHub CLI(gh). PR을 만들고 머지하는 데 씁니다. 공식 모범 사례는 "GitHub를 쓰면 gh CLI를 설치하라. gh 없이도 GitHub API를 쓸 수 있지만 인증되지 않은 요청은 속도 제한에 걸린다"고 설명합니다.

# macOS
brew install gh
# Windows (PowerShell)
winget install --id GitHub.cli --source winget
# 공통: 브라우저로 로그인
gh auth login

gh auth login은 기본적으로 브라우저 흐름으로 인증하고 토큰을 시스템 자격 증명 저장소에 보관합니다. 세 가지가 준비됐는지 Claude Code에게 확인시켜도 됩니다. "git, gh가 설치되어 있고 gh 로그인이 되어 있는지 확인해 줘."

먼저 알아둘 Git 용어 7가지

교재 3주차는 Git을 "내 작업의 기록이 남는 금고"라고 부르고 용어를 서류 작업에 비유합니다. 그 비유에 두 단어를 보탰습니다.

클로드가 작업 보고를 할 때 이 일곱 단어가 섞여 나옵니다. 뜻만 알면 대화가 됩니다. 낯설면 그 자리에서 묻습니다. "방금 한 커밋과 푸시가 각각 무슨 일을 한 건지 서류 보관 비유로 설명해 줘."

1단계: 리포지토리 초기화하기

작업 폴더에서 claude를 켜고 지시합니다.

이 폴더를 git 리포지토리로 초기화해 줘.
.gitignore를 만들어서 .env, 키 파일, 녹음 원본(*.m4a), 캐시 폴더는 제외해 줘.
어떤 파일이 추적 대상이 되는지 목록을 먼저 보여 줘.

Claude Code는 git init을 실행하겠다는 승인을 요청하고, .gitignore를 만들고, 추적 대상 목록을 보여 줍니다. 이 목록을 꼭 읽으세요. 교재 3주차의 규칙은 "키는 절대 깃허브나 문서에 원문으로 넣지 않는다"입니다. 목록에 .env나 고객 실명이 든 파일이 있으면 승인하지 말고 제외시킵니다.

2단계: 첫 커밋 만들기

지금까지 작업을 커밋해 줘. 메시지는 설명적으로.

공식 문서의 예시도 이와 같습니다. claude "commit my changes with a descriptive message". Claude Code는 변경 파일을 스테이징하고, 변경 내용을 읽어 메시지를 쓰고, git commit 승인을 요청합니다. 첫 커밋 뒤에는 "커밋 목록을 보여 줘"로 기록이 남았는지 확인합니다.

커밋 메시지의 chore: 는 무엇인가

Claude Code가 쓴 메시지 앞에 feat:, fix:, chore:, docs: 같은 접두어가 붙는 경우가 많습니다. 변경의 성격을 한 단어로 표시하는 관례입니다. feat는 새 기능, fix는 버그 수정, docs는 문서, chore는 기능과 무관한 정리 작업(설정 파일, 의존성, 폴더 정리)입니다. 첫 커밋이 chore: 프로젝트 초기화로 나오는 이유입니다. 팀 관례가 다르면 CLAUDE.md에 적어 두면 그대로 따릅니다.

언제 커밋해야 하나

교재 5주차의 순서가 답입니다. 작업 전 커밋, 작업, QA 통과, 커밋. 기능 하나가 끝났을 때, 대량 수정이 일어났을 때, 다음 기능으로 넘어가기 전, DB나 권한이나 배포 관련 수정 후가 커밋 시점입니다. "AI가 잘못 수정한 게 문제가 아니라, 되돌릴 기준점을 안 만든 게 문제입니다." 커밋이 잘게 남아 있을수록 디버깅 글에서 배운 이분 탐색도 빨라집니다.

3단계: 브랜치를 만들어 기능 추가하기

원본을 건드리지 않고 새 기능을 시도할 때 브랜치를 만듭니다.

feature/monthly-report 브랜치를 만들어서 거기서 작업하자.
월간 보고서 기능을 추가하고, 끝나면 브랜치에 커밋해 줘.

공식 빠른 시작의 예시도 "feature/quickstart라는 새 브랜치 생성"입니다. 브랜치 이름은 영문 소문자와 슬래시, 하이픈만 씁니다. 지금 어느 브랜치에 있는지 헷갈리면 "현재 브랜치와 커밋되지 않은 변경을 보여 줘"라고 묻습니다.

4단계: GitHub 리포지토리를 만들어 푸시하기

교재 3주차의 실습 문장을 그대로 씁니다.

이 폴더를 깃허브에 백업하고 싶어. 나는 깃허브 계정만 있는 초보야.
계정 연결부터 첫 저장(푸시)까지 한 단계씩 안내해 줘.
저장소는 반드시 비공개(Private)로 만들어 줘.

Claude Code는 gh repo create로 저장소를 만들고 git push로 올립니다. 비공개가 중요합니다. 우리 폴더에는 고객 자료가 있고, 공개로 만들면 전 세계에 공개됩니다. 완료 확인은 브라우저입니다. 내 GitHub 저장소에 들어가 방금 올린 파일이 보이면 성공입니다.

의도치 않은 push 막기

푸시는 되돌리기 어렵습니다. 특히 강제 푸시(--force)는 남의 기록까지 지울 수 있습니다. 세 겹으로 막습니다.

첫째, 권한 규칙입니다. 프로젝트의 .claude/settings.json에 git push를 요청(ask) 규칙으로 두면 다른 명령을 자동 승인하는 모드에서도 푸시 전에는 반드시 묻습니다. 공식 문서의 예시 구성은 커밋은 허용하고 푸시는 거부(deny)하는 형태입니다.

{
  "permissions": {
    "allow": ["Bash(git commit *)", "Bash(git status)", "Bash(git diff *)"],
    "ask": ["Bash(git push *)"],
    "deny": ["Bash(git push --force *)"]
  }
}

규칙은 deny, ask, allow 순서로 평가되므로 git push --force는 항상 차단되고, 일반 git push는 항상 묻습니다. 둘째, 대화에서 경계를 말해 둡니다. 자동 모드에서는 "푸시하지 마"라고 말한 경계를 분류기가 차단 신호로 취급하며, 강제 푸시는 기본적으로 차단 대상입니다. 셋째, 원격의 브랜치 보호입니다. GitHub 저장소 설정에서 main 브랜치에 직접 푸시를 막고 PR을 통해서만 합치게 하면 도구와 무관하게 적용됩니다.

5단계: PR 만들기

브랜치 작업이 끝나면 검토 요청서를 만듭니다.

지금까지 변경 사항을 요약하고, main으로 PR을 만들어 줘.
PR 설명에 무엇을 왜 바꿨는지, 어떻게 확인했는지 넣어 줘.

공식 문서는 "create a pr"만으로도 되고, 요약을 먼저 받은 뒤 만들 수도 있다고 안내합니다. gh pr create로 PR이 만들어지면 세션이 그 PR에 자동으로 연결되어, 나중에 claude --from-pr 번호로 그 세션을 재개할 수 있습니다. PR 설명은 사람이 읽고 승인하는 문서입니다. 교재 5주차의 QA 관점(기존 기능 유지, 콘솔 에러 없음, 민감정보 없음)이 설명에 들어가 있으면 좋은 PR입니다.

6단계: PR 머지하기

PR 12번을 확인하고, 문제 없으면 머지해 줘. 머지 후 브랜치는 삭제해 줘.

머지 전에 Claude Code에게 검토를 시킬 수도 있습니다. 세션 안에서 /review 12를 실행하면 읽기 전용으로 PR을 한 번 훑고 문제를 보고합니다. 우리 교육에서는 결제나 보안처럼 중요한 코드는 만든 도구와 다른 AI로 교차 검수한 뒤 머지하는 것을 관문으로 둡니다. 자동 모드의 분류기는 사람이 승인하지 않은 PR 머지를 기본적으로 차단하므로, 머지는 사람이 승인 버튼을 누르는 단계로 남겨 두는 것이 맞습니다.

7단계: 로컬 main 최신화하기

GitHub에서 머지된 내용은 내 컴퓨터의 main에는 아직 없습니다.

main 브랜치로 돌아가서 원격의 최신 내용을 받아 줘.
머지된 feature 브랜치는 로컬에서도 정리해 줘.

Claude Code가 git checkout main과 git pull을 실행합니다. 최신화를 빼먹으면 다음 브랜치가 오래된 main에서 갈라져 나중에 충돌이 납니다. 충돌이 나더라도 "병합 충돌을 해결하는 데 도움을 줘"라고 시키면 충돌 지점을 보여 주고 어느 쪽을 남길지 물어봅니다. 이제 다시 3단계로 돌아가 다음 기능의 브랜치를 만들면 됩니다. 이 일곱 단계가 한 바퀴이고, 교재에서는 매주 과제가 끝날 때마다 이 바퀴를 한 번씩 돕니다.

한눈에 보는 지시어 표

읽기 전용 형태의 git 명령(git status, git log, git diff)은 승인 없이 실행되고, 변경을 만드는 명령은 기본 모드에서 승인을 요청합니다.

정리

• Git은 되돌릴 기준점을 만드는 도구이고, Claude Code는 그 명령어를 대신 쳐 줍니다.
• 7단계 한 바퀴: 초기화, 커밋, 브랜치, 푸시, PR, 머지, 최신화.
• 저장소는 비공개, 키는 .gitignore로 제외, 푸시는 항상 묻게 설정합니다.
• 머지는 사람이 승인하는 단계로 남기고, 중요한 코드는 교차 검수 뒤 합칩니다.

자주 묻는 질문