여러 리포지토리를 다루다 보면 「커밋 누락」이 쌓이게 된다

개인 개발에서 Claude Code를 사용하다 보면, 어느샌가 여러 리포지토리를 병행해서 다루고 있게 되었다.

• 글로벌 설정을 관리하는 리포지토리 (.claude 하위)
• 결과물 전체를 관리하는 리포지토리 (프로젝트, 툴, 문서 일체)
• Zenn 기사를 쓰기 위한 전용 리포지토리

작업 중에는 "설정 파일을 고치는 김에 기사도 한 편 쓰고, 툴의 버그도 고치자"와 같이, 여러 리포지토리를 동시에 넘나들며 변경 사항을 넣는 일이 흔히 발생한다.

이를 수동으로 하면, 리포지토리마다 cd 하여 git status로 확인하고, 커밋해야 할 파일과 그렇지 않은 파일(작업 중인 임시 파일, 생성물)을 분류하여 git add 하고, 커밋 메시지를 작성하여 git commit 하는 흐름을 3번 반복해야 한다.

번거로울 뿐만 아니라, 번거롭기 때문에 커밋 타이밍을 놓치기 쉽다. 정신을 차려보면 하나의 리포지토리에 수십 개의 파일 분량의 변경 사항이 무질서하게 쌓여 있고, 나중에 다시 봐도 "이것이 무엇을 위한 변경이었나"를 알 수 없게 된다.

이를 해결하기 위해 만든 것이 git-management 스킬이다. "gitどう？(git 어때?)", "コミットよろ(커밋 부탁해)"라고 말하는 것만으로, 여러 리포지토리의 상태 확인부터 커밋까지 자율적으로 수행하도록 만든 메커니즘이다.

이 기사에서 다룰 내용

.claude/skills/git-management/SKILL.md로 정의한 스킬의 내용을 그대로 해설한다.

• 대상 리포지토리를 어떻게 고정하고 있는가
• 커밋해야 할 파일과 그렇지 않은 파일을 어떻게 판단하게 하는가
• 커밋 메시지 형식을 어떻게 지키게 하는가
• "push는 하지 않는다 · 파괴적인 조작은 하지 않는다"라는 설계 사상을 어떻게 스킬에 녹여냈는가

전체 구조: SKILL.md라는 하나의 사양서

git-management 스킬은 다음과 같은 frontmatter를 가진다.

---
name: git-management
description: 全リポジトリのgit状態を確認し、コミットすべきファイルを自律判断してコミットする。「gitどう？」「コミットよろ」「git確認して」などのトリガーで使う。Do NOT use for file editing, deployments, or non-git tasks.
...

Bash(git *)는 "git으로 시작하는 명령어만 승인 없이 실행할 수 있다"라는 허용 리스트 표기법이다.

포인트는 description의 작성 방식이다. Claude Code는 스킬을 발화할지 여부를 이 설명문만으로 판단한다. 본문은 판정에 사용되지 않는다. 따라서

• 무엇을 하는가 (전체 리포지토리의 git 상태 확인 + 자율 커밋)
• 언제 사용하는가 ("gitどう？", "コミットよろ"라는 트리거 워드)
• 하지 않는 것 (Do NOT use for file editing, deployments, or non-git tasks.)

이 세 가지 점을 한 문장에 담았다. 네거티브 트리거(Negative Trigger)를 적어둠으로써, 파일 편집이나 배포 태스크에서 이 스킬이 잘못 발화되는 것을 방지하고 있다.

allowed-tools도 Bash(git *)로 한정했기 때문에, 이 스킬 안에서 임의의 쉘 명령어가 돌아가는 일은 없다. git 명령어 이외를 실행하고 싶다면 별도의 스킬이나 메인 Claude가 담당한다.

관리 대상은 3개의 리포지토리로 고정

git-management가 확인하러 가는 리포지토리는 SKILL.md 내에서 고정하고 있다.

지금 어디에 있는 리포지토리를 보면 좋을지를 매번 Claude에게 찾게 하는 것이 아니라, 미리 열거하여 하네스(Harness) 측에 고정해 두었다. 새로운 리포지토리가 늘어나면 이 표에 한 줄 추가하면 된다.

Step 1: 전체 리포지토리의 스테이터스를 횡단 확인

git -C "C:/Users/YourName/.claude" status
git -C "E:/Documents/Claude" status
git -C "E:/Documents/Claude/projects/zenn-monetization" status

cd 하지 않고 git -C를 사용하여 리포지토리를 지정하여 status

를 가져온다. 이로써 3개 리포지토리 분량의 변경 사항을 한 번에 파악할 수 있다. 수동이라면 3번 cd를 하고 3번 status를 입력해야 할 것을, 단 한 번의 지시로 끝낼 수 있다.

Step 2: 커밋 여부를 분류하는 규칙

이 부분이 이 스킬의 핵심이다. 단순히 "변경 사항이 있으면 커밋한다"가 아니라, 확장자 및 경로 패턴별로 "커밋 대상인지 여부"를 판단하게 하고 있다.

반드시 커밋한다

• *.py, *.js, *.ts, *.go — 소스 코드 (Source Code)
• *.md — 문서 · 기사 (Documentation/Articles)
• *.bat, *.sh — 스크립트 · 런처 (Scripts/Launchers)
• *.json, *.yaml, *.toml, *.ini — 설정 파일 (Configuration Files)
• *.txt, *.csv — 데이터 정의 · 요건 (Data Definition/Requirements)
• *.png, *.jpg — analysis/ 하위의 그래프 · 도표 (Artifacts)
• deploy/ 하위의 서비스 정의 파일
• requirements.txt, package.json, *.lock
• .env.example (실제 값이 없는 템플릿)

반드시 무시한다 (.gitignore에 추가하여 스킵)

• *.db, *.sqlite — 데이터베이스 (생성물)
• *.parquet, *.arrow — 데이터 파일 (생성물)
• *.log — 로그 파일 (Log Files)
• *.lnk — Windows 바로가기 (바이너리 · 환경 의존적)
• input/ — 임시 입력 파일
• reports/ 하위의 자동 생성된 리포트
• data/ 하위의 자동 생성된 데이터
• __pycache__/, *.pyc — Python 캐시
• .env (실제 값이 포함된 파일) — 기밀 정보

**커밋하지 않는다 (.gitignore는 불필요)

• 이미 gitignore 되어 있는 것
• 세션 임시 파일

이 세 가지 분류가 있음으로써 "추적되지 않은 파일(Untracked files)이 전부 커밋 대상"이라는 무모한 판단을 피할 수 있다. 실제로 생성물이나 로그가 섞인 채로 git add .를 하면 리포지토리가 비대해질 뿐만 아니라, .env와 같은 기밀 파일이 섞여 들어갈 리스크도 높아진다. 확장자와 디렉토리 패턴으로 기계적으로 분류함으로써 그 리스크를 구조적으로 차단하고 있다.

추적되지 않은 파일 중에 무시해야 할 카테고리의 것이 있다면, 먼저 .gitignore에 추가한 뒤 스테이징(Staging)한다는 순서도 정해두었다. 커밋 대상을 고른 뒤에 무시 리스트를 업데이트하는 것이 아니라, 무시 리스트를 먼저 확정한 뒤에 스테이징한다. 이 순서를 반대로 하면 무시해야 할 파일을 아주 잠시라도 스테이징 영역에 올려버릴 가능성이 있기 때문이다.

Step 3: 커밋 메시지 형식을 준수하게 함

글로벌 설정인 CLAUDE.md에는 다음과 같이 적혀 있다.

## 커밋 메시지
- 일본어로 작성할 것
- 형식: "[타입] 설명" (예: `[feat] 새로운 기능 추가`)
...

git-management의 SKILL.md 측에서는 이를 리포지토리 횡단 실무에 맞춰 더욱 세분화한 표로 만들었다.

CLAUDE.md는 모든 프로젝트 공통의 영구 규칙으로서 매번 자동으로 읽힌다. git-management의 SKILL.md는 git 커밋 시 무엇을 우선적으로 판단할지에 대한 실무 수준의 상세 내용을 담고 있다. 이 이층 구조로 설계한 이유는 CLAUDE.md에 실무의 세부 사항까지 적으면 파일이 비대해져 다른 중요한 규칙들이 묻혀버릴 수 있기 때문이다. 영구 규칙과 실무 상세를 분리하여, 필요한 때에만 상세 측을 읽어들이도록 설계했다.

Step 4: 커밋하고, 리포지토리별로 결과를 보고

분류와 메시지 작성이 끝나면 리포지토리별로 커밋을 실행한다. 마지막에는 반드시 "무엇을 커밋했는지 / 무엇을 스킵했는지 / 이유"를 간결하게 보고하도록 한다.

이를 통해 Claude에게 전적으로 맡기더라도 나중에 "이 리포지토리에서는 어떤 일이 일어났는지"를 한 줄씩 추적할 수 있다. 블랙박스 상태에서 멋대로 커밋되는 것이 아니라, 판단 과정이 보이는 상태로 유지하는 것이다.

push는 하지 않는다. 파괴적인 작업은 범위 밖으로 한다

git-management가 자동화하는 것은 git add와 git commit뿐이다. git push는 포함되지 않는다.

SKILL.md의 보안 제약 사항에는 이렇게 쓰여 있다.

## 보안 제약
- `git push` 금지 (pre-push hook으로 차단)
- 원격 추가 금지
...

로컬 환경에서는 pre-push hook을 통해 git push 자체가 물리적으로 차단되도록 설정되어 있다. 만약 Claude가 실수로 push를 하려고 해도, hook 측에서 멈춘다. 스킬의 기술 명세와 hook 구현이라는 이중 방어 체계를 갖추고 있는 것이다.

이는 로컬 전용 정책이라는 설계 사상에 기반하고 있다. 커밋은 자율적으로 진행해도 좋지만, 원격에 반영할지 여부는 반드시 인간이 판단한다는 선을 긋는 것이다. 커밋 단위로 작업 이력을 남기는 것은 자동화의 장점이 크지만, 원격으로 반영하는 것은 되돌릴 수 없는(不可逆性) 높은 위험도를 가진 작업이므로, 그 부분만은 인간의 의사결정을 거치도록 한 것이다.

또 하나 중요한 점은, 파괴적인 작업을 이 스킬의 대상에서 제외했다는 것이다. 파일이나 데이터를 삭제하기 전에는 삭제 대상 목록과 이유를 제시하여 승인을 받는다는 원칙이 있다. git-management가 다루는 것은 add와 commit이라는 가역적(可逆的)인 작업에 한정되며, git reset --hard나 git push --force 같은 비가역적이거나 파괴적인 작업은 애초부터 자동화 범위에 넣지 않았다.

자율 판단을 허용할 수 있는 작업과 반드시 인간의 승인을 거쳐야 하는 작업을 스킬 설계 단계에서 명확히 분리했다. 편리하다고 해서 모든 것을 자동화하는 것이 아니라, 가역성 여부를 기준으로 자동화의 경계선을 그은 것이다.

사용자 확인이 필요한 경우

완전히 방임하지 않고, 다음 사례에 대해서만 확인을 거치도록 설계했다.

• 기밀 정보가 포함되어 있을 가능성이 있는 파일명
• 100KB를 초과하는 예상치 못한 바이너리 파일
• 상기 판단 규칙으로 어느 쪽에도 해당하지 않는 새로운 카테고리

평소의 커밋은 자율적으로 진행하되, 판단에 어려움이 있거나 위험성이 있는 경우만 인간에게 넘긴다. 매번 확인을 받아 결국 번거로워지는 상황과, 무엇이든 멋대로 커밋되어 불안한 상황, 이 두 가지를 모두 피하고 있다.

얼마나 편리해졌는가

수동으로 이 작업을 할 경우, 리포지토리 1개당 「cd → git status 확인 → 파일 분류 → git add → 커밋 메시지 작성 → git commit」라는 6단계가 발생한다. 3개의 리포지토리를 한다면 단순 계산으로 18단계이다.

git-management 스킬을 사용하면, 이 18단계가 「'git 어떻게 할까?'」라는 한 번의 발화로 대체된다. 단계 자체가 줄어드는 것이 아니라, 그 모든 단계를 Claude가 대신 처리해 주는 것이 실질적인 내용에 가깝다.

만약 리포지토리 1개당 수동 git 작업에 23분이 걸린다고 가정하고 추산하면, 3개의 리포지토리는 69분이다. 일일로 진행한다면 월 20 영업일 기준으로 120~180분 정도의 작업이 스킬 호출 1회로 대체되는 계산이 된다(실측값이 아닌 추정치). 하지만 더 효과적인 것은, 귀찮다고 미루는 것을 방지할 수 있다는 점이다. 즉, 커밋의 단위가 세밀하게 유지되어 나중에 이력을 따라가기 쉬워진다는 것이다.

요약

• git-management 스킬은 3개의 고정 리포지토리(.claude 설정, E:\Documents\Claude 결과물, Zenn 기사)를 가로질러 git status를 확인하고 - 파일은 확장자 및 경로 패턴에 따라 '반드시 커밋', '반드시 무시', '무시가 불필요함(기존 .gitignore 대상)'의 3가지 분류를 거쳐 git add를 수행한다. - 커밋 메시지는 [유형] 설명 형식으로, CLAUDE.md의 영구 규칙과 SKILL.md의 실무 상세라는 이중 구조로 지키게 한다. - 자동화하는 것은 add와 commit이라는 가역적 작업에 한정하며, push는 pre-push hook으로 차단하고, reset --hard 같은 파괴적인 작업은 처음부터 스킬 대상에서 제외한다. - 기밀 정보 의혹/거대 바이너리/미분류 신규 카테고리에 대해서만 인간에게 확인을 요청하도록 설계했다.

여러 리포지토리를 병행하는 개인 개발자일수록, 이러한 하네스(Harness)는 효과를 발휘할 것이다.

이러한 설계 사상(무엇을 자동화하고, 무엇을 인간의 승인으로 남길 것인가)을 체계적으로 정리한 유료 도서 「Claude Code 하네스 엔지니어링 실전 Playbook」에서 다른 스킬 설계에 대해서도 해설하고 있다.

좋아요나 댓글로 반응해 주시면 큰 힘이 됩니다!

Discussion