팀 Git·GitHub 협업 규칙 만들기

팀 Git·GitHub 협업 규칙은 여러 사람이 같은 main 브랜치를 공유할 때 "누가 해도 같은 결과가 나오게" 만드는 합의입니다. 개인 작업에서는 문제가 되지 않던 습관이 팀에서는 곧바로 남의 작업을 덮거나 diff를 못 읽게 만들기 때문에, 명령어보다 먼저 정해야 할 것이 있습니다.

이 글은 무엇을 정해야 하는지, 그리고 정한 것을 어디에 적어야 사람이 바뀌어도 살아남는지 정리합니다. Claude Code로 커밋·PR을 만드는 조작 자체는 Git 조작 자동화에서 다루므로 여기서는 반복하지 않습니다.

핵심 요약

• 팀 Git 사고의 대부분은 명령어를 몰라서가 아니라 사람마다 다르게 해서 생깁니다.
• 먼저 정할 것은 다섯 가지입니다. 브랜치 이름 규칙, PR 크기와 설명, 리뷰어 수와 응답 시간, 머지 방식, 보호 규칙.
• 합의를 문서에만 두면 잊힙니다. 초기 설정 스크립트, .gitattributes, 보호 규칙처럼 시스템으로 옮겨야 유지됩니다.
• 줄바꿈은 개인의 core.autocrlf가 아니라 리포지터리의 .gitattributes로 고정해야 합니다.
• 보호 규칙은 "사람이 조심하기"를 "플랫폼이 거부하기"로 바꾸는 장치입니다.

개인 Git과 팀 Git은 어디서 갈라지나

혼자 쓰는 리포지터리에서 main은 내 작업 공간입니다. 언제 커밋하든, 이력을 다시 쓰든, 강제로 밀어 넣든 피해를 보는 사람은 나뿐입니다. 팀에서는 같은 main을 여러 명이 동시에 바라보기 때문에 세 가지가 달라집니다.

첫째, 내 이력이 남의 로컬에 복제돼 있습니다. 이미 다른 사람이 받아 간 커밋을 고쳐 쓰면 그 사람의 리포지터리와 내 리포지터리가 서로 다른 역사를 갖게 되고, 다음 pull에서 정체불명의 충돌이 생깁니다.

둘째, 내 PC 설정이 남의 화면에 보입니다. 줄바꿈 설정이나 에디터의 자동 포맷이 다르면 한 줄만 고쳐도 diff가 파일 전체로 뜹니다. 리뷰어는 무엇이 실제 변경인지 알 수 없습니다.

셋째, 되돌리는 방법이 달라집니다. 혼자일 때는 이력을 지우는 것이 가장 깔끔하지만, 공유된 뒤에는 "반대 변경을 새로 기록하는" 방식만 안전합니다. 이 판단 기준은 잘못된 커밋·push 되돌리기에서 상황별로 정리했습니다.

먼저 정할 다섯 가지는 무엇인가

아래 표를 조별 또는 팀별로 한 번에 채우고, 각 칸 옆에 "왜 그렇게 정했는지" 한 줄을 남깁니다. 이유가 남아 있어야 나중에 바꿀지 말지 판단할 수 있습니다.

정답이 하나 있는 선택은 아닙니다. 다만 "정하지 않음"은 선택지가 아닙니다. 또 하나, 각 항목마다 예외 절차를 한 줄씩 붙여 두세요. 급한 장애 수정처럼 규칙을 건너뛰어야 하는 순간은 반드시 오는데, 그때 절차가 없으면 규칙 전체가 무시됩니다.

머지 방식은 어떻게 고르나

세 방식의 차이는 main에 남는 이력의 모양입니다. 깊이 들어가기 전에 아래 정도만 보고 하나로 통일하면 충분합니다.

중요한 것은 어느 쪽이 우월한가가 아니라 팀에서 하나만 허용하는 것입니다. 리포지터리 설정에서 나머지 두 버튼을 꺼 두면 개인의 기억에 의존하지 않아도 됩니다.

초기 설정을 왜 스크립트로 통일하나

팀원 다섯 명에게 git config --global --list 를 각자 실행해 비교해 보면 거의 예외 없이 값이 갈립니다. user.name 표기(한글·영문·사번)부터 다르고, pull.rebase 와 core.autocrlf 는 설치할 때 무심코 누른 선택지가 그대로 남아 있습니다. 이 상태에서 첫 PR을 올리면 diff가 전 파일로 뜨거나, pull 할 때마다 불필요한 머지 커밋이 쌓입니다.

그래서 합의한 값을 실행 가능한 스크립트 한 개로 만들어 리포지터리에 커밋합니다. 새로 합류한 사람은 이 스크립트를 한 번 실행하는 것으로 환경이 맞춰집니다.

#!/usr/bin/env bash
# scripts/setup-git.sh — 실행 전 현재 값을 백업한다
git config --global --list > ~/git-config-backup-$(date +%Y%m%d).txt

git config --global init.defaultBranch main
git config --global pull.ff only          # 팀에서 합의한 값으로 바꾼다
git config --global core.quotepath false  # 한글 파일명이 \354... 로 깨져 보이지 않게
git config --global core.longpaths true   # Windows 긴 경로 대비

첫 줄의 백업이 중요합니다. 이 스크립트는 개인 PC의 전역 설정을 덮어쓰기 때문에, 원래 값을 남겨 두지 않으면 다른 프로젝트 작업이 갑자기 달라졌을 때 되돌릴 근거가 없습니다.

맞춰졌는지 확인하는 쪽도 함께 만듭니다. 기대 값과 현재 값을 비교해 다른 항목만 출력하게 해 두면, 온보딩 체크리스트가 "스크립트 실행 → 확인 스크립트가 아무것도 출력하지 않음" 두 줄로 끝납니다.

#!/usr/bin/env bash
# scripts/verify-git.sh
check() {
  actual=$(git config --global --get "$1")
  [ "$actual" = "$2" ] || echo "다름: $1 = '$actual' (기대: '$2')"
}
check init.defaultBranch main
check pull.ff only
check core.quotepath false

Windows가 표준인 팀이라면 같은 내용을 PowerShell 스크립트로 두고, 실행 정책 때문에 막힐 때 현재 세션에만 허용하는 방법을 온보딩 문서에 함께 적어 둡니다. 이런 합의를 팀 전체가 같은 기준으로 내리는 실습은 1일 과정에서 다룹니다.

.gitattributes로 줄바꿈을 고정하는 법

core.autocrlf 는 개인 설정입니다. 팀 전원이 같은 값을 넣기로 합의해도, 새 노트북을 받거나 새 인원이 합류하면 그날부터 다시 갈립니다. 개인 합의는 사람이 바뀌면 깨지고, 파일 속성은 리포지터리에 남습니다.

리포지터리 루트에 .gitattributes 를 두면 파일 단위로 줄바꿈을 고정할 수 있고, 이 속성이 지정된 파일에는 개인의 core.autocrlf 값보다 속성이 우선합니다. 즉 개인 설정은 속성이 없는 파일에만 영향을 줍니다.

* text=auto eol=lf

*.ps1 text eol=crlf
*.bat text eol=crlf

*.png binary
*.pdf binary
*.xlsx binary

첫 줄은 텍스트로 판별된 파일을 저장소 안에서 LF로 통일합니다. Windows에서만 실행되는 스크립트는 CRLF가 아니면 동작이 이상해질 수 있어 따로 고정합니다. 이미지·PDF·엑셀을 binary 로 지정하는 이유는, 이 파일들에 줄바꿈 변환이 들어가면 파일이 깨지기 때문입니다.

.gitattributes 를 추가한 직후에는 이미 들어가 있던 파일을 한 번 정리해야 합니다.

git add --renormalize .
git commit -m "chore: .gitattributes 기준으로 줄바꿈 정규화"

이 커밋은 의도적으로 많은 파일을 건드립니다. 팀에 미리 알리고, 다른 작업 브랜치가 적을 때 하루를 잡아 처리하는 편이 좋습니다.

보호 규칙은 어떤 사고를 막나

규칙을 켠 뒤에는 한 번 직접 시도해 보는 것을 권합니다. main에서 곧바로 push를 해 보고 거부 메시지를 눈으로 확인하면, 왜 이 규칙이 있는지가 팀에 훨씬 오래 남습니다.

PR 템플릿과 CODEOWNERS는 무엇을 자동화하나

PR 템플릿은 .github/pull_request_template.md 에 두면 PR 작성 화면에 자동으로 채워집니다. "설명을 잘 쓰자"는 당부를 빈칸으로 바꾸는 장치입니다.

## 목적
(이 PR이 해결하는 문제 · 연결 이슈 번호)

## 변경 요약
(무엇을 바꿨는지 3줄 이내)

## 확인 방법
(리뷰어가 직접 재현할 수 있는 절차)

## 영향 범위
(같이 봐야 할 파일 · 되돌릴 때 주의할 점)

"확인 방법" 칸은 사람이 직접 채우는 것을 규칙으로 둡니다. 변경 요약은 도구에 맡겨도 되지만, 실제로 무엇을 어떻게 확인했는지는 작성자만 알기 때문입니다.

CODEOWNERS는 경로별 담당자를 지정해 해당 파일이 바뀐 PR에 리뷰어를 자동으로 붙입니다. .github/CODEOWNERS 에 둡니다.

*               @team/maintainers
/docs/          @team/planning
/site/          @team/frontend
/.github/       @team/maintainers

아래쪽 규칙이 위쪽을 덮으므로 넓은 규칙을 먼저, 좁은 규칙을 나중에 적습니다. 담당자가 퇴사하거나 팀을 옮기면 이 파일이 조용히 죽으니, 월 1회 점검 항목에 넣어 둡니다.

사내 프록시·사설 인증서 환경에서는 무엇을 더 넣나

사내망에서 clone이 인증서 오류로 실패하는 상황은 흔합니다. 원인은 대개 회사가 트래픽을 검사하기 위해 자체 인증서로 중간에서 연결을 다시 맺기 때문이고, Git 입장에서는 모르는 발급자로 보입니다.

git config --global http.proxy http://proxy.example.com:8080
git config --global http.sslCAInfo /path/to/company-ca.pem

세 가지를 함께 정해 둡니다. 첫째, 비밀번호는 설정 파일에 넣지 않습니다. 프록시 인증이 필요하면 자격 증명 관리자에 맡깁니다. 둘째, 이 두 줄은 회사 밖에서는 오히려 연결을 막으므로 초기 설정 스크립트에서 주석 처리해 두고 사내 인원만 풀게 합니다. 셋째, Windows에서는 인증서 파일 경로 대신 Windows 인증서 저장소를 쓰는 http.sslBackend 방식이 관리하기 쉬운 경우가 있어, 사내 표준을 정하기 전에 두 방식 중 어느 쪽이 배포 가능한지 확인합니다.

Windows 팀이 추가로 정할 것

전원이 Windows인 팀에서는 다음 세 가지가 자주 문제를 만듭니다.

마지막 항목이 특히 중요합니다. 네이티브 실행과 WSL을 섞으면 설정 파일 경로와 줄바꿈 처리가 다시 갈려서, 기껏 통일한 설정이 사람별로 어긋납니다.

자주 겪는 문제

정리

• 다섯 가지 결정을 먼저 하고, 각 결정에 이유와 예외를 한 줄씩 남깁니다.
• 합의는 반드시 시스템으로 옮깁니다. 스크립트, .gitattributes, 보호 규칙, 템플릿이 그 자리입니다.
• 사고가 났을 때의 판단 기준은 잘못된 커밋·push 되돌리기에 따로 정리했습니다.
• 규칙을 정한 뒤 Claude Code에게도 같은 규칙을 따르게 하려면 CLAUDE.md에 짧게 옮기고 권한 설정으로 위험한 조작을 막습니다. 일상적인 커밋·PR 조작은 Git 조작 자동화에 있습니다.
• 팀 전체가 같은 리포지터리를 하루 동안 함께 돌려 보며 이 규칙을 세우는 실습은 기업 교육 1일 과정에서 다룹니다.