git-guardrails-claude-code

git-guardrails-claude-code 스킬 개요

git-guardrails-claude-code 스킬은 Claude Code가 실행 전에 일부 파괴적인 Git 명령을 거부하도록 돕습니다. 역할은 단순합니다. AI 코딩 세션이 무심코 git push, git reset --hard, git clean -f, git branch -D로 브랜치를 삭제하거나, git checkout ., git restore .로 작업 트리 변경사항을 날려버리지 못하도록 안전장치를 하나 더 두는 것입니다.

git-guardrails-claude-code를 써야 하는 사람

이 스킬은 특히 다음과 같은 사용자에게 잘 맞습니다.

• 실제 저장소를 대상으로 Claude Code를 직접 사용하는 사람
• AI 보조는 원하지만 되돌리기 어려운 Git 작업은 맡기고 싶지 않은 사람
• 공유 저장소, 운영 저장소, 클라이언트 코드베이스에서 작업하는 사람
• “조심해서 써” 같은 프롬프트보다 로컬 강제를 선호하는 사람

에이전트 세션 중 우발적인 코드 파손이나 승인되지 않은 push가 가장 큰 걱정이라면, git-guardrails-claude-code는 상당히 적합한 선택입니다.

일반 프롬프트와 다른 점

일반 프롬프트로도 Claude에게 위험한 명령을 실행하지 말라고 요청할 수는 있습니다. 하지만 프롬프트는 어디까지나 느슨한 지침입니다. git-guardrails-claude-code는 PreToolUse hook를 사용하므로, 제한이 대화 수준에만 머무는 것이 아니라 Claude Code의 실제 실행 경로에 들어갑니다. 이 점이 가장 큰 차별점이고, 설치할 만한 핵심 이유이기도 합니다.

실제로 무엇을 막는가

함께 제공되는 셸 스크립트는 들어오는 Bash 명령을 검사해 다음과 같은 패턴을 차단합니다.

• git push
• git reset --hard
• git clean -f
• git clean -fd
• git branch -D
• git checkout .
• git restore .
• push --force 같은 force-push 관련 패턴

차단 메시지는 해당 명령을 사용할 권한이 Claude에게 없다고 알려줍니다.

이 스킬이 하지 않는 일

git-guardrails-claude-code는 완전한 Git 정책 엔진이 아닙니다. 다음 기능은 제공하지 않습니다.

• 커밋 품질 검토
• 승인 절차 강제
• 안전한 push 대상과 위험한 push 대상 구분
• 저장소별 브랜치 규칙 이해
• 스크립트를 직접 수정하지 않는 한, 목록에 없는 패턴 보호

도입 판단에서 이 점은 중요합니다. 이 스킬은 집중된 guardrail이지, 포괄적인 거버넌스 도구는 아닙니다.

git-guardrails-claude-code 스킬 사용 방법

먼저 적용 범위부터 결정하세요

원본 스킬에서 가장 먼저 할 실질적 선택은 guardrail을 어디에 설치할지입니다.

• 현재 프로젝트 전용으로 .claude/settings.json에 설치할지
• 모든 프로젝트 공통으로 ~/.claude/settings.json에 설치할지

이 결정에 따라 스크립트를 복사할 위치와 차단이 적용되는 범위가 달라집니다. 대부분의 팀이라면 테스트 단계에서는 프로젝트 단위 설치가 더 안전합니다. 반대로 어디서나 같은 Git 제한을 걸고 싶다는 확신이 있다면 글로벌 설치가 더 잘 맞습니다.

먼저 읽어볼 파일

핵심은 아래 두 파일만 읽어도 거의 파악할 수 있습니다.

1. SKILL.md
2. scripts/block-dangerous-git.sh

이 순서가 좋은 이유는 SKILL.md가 hook 연결 방식을 설명하고, scripts/block-dangerous-git.sh가 실제로 어떤 명령 패턴을 막는지 보여주기 때문입니다. 오탐이나 누락이 걱정된다면 설명문보다 스크립트가 더 중요합니다.

git-guardrails-claude-code 설치 맥락

git-guardrails-claude-code install 과정은 대부분 Claude Code의 hook 시스템 안에서 수동으로 설정하는 작업입니다.

1. 셸 스크립트를 hooks 디렉터리로 복사
2. 실행 권한 부여
3. Bash matcher용 PreToolUse에 등록

원본 스크립트의 저장소 경로는 다음과 같습니다.

scripts/block-dangerous-git.sh

대상 위치는 아래와 같습니다.

• 프로젝트 범위: .claude/hooks/block-dangerous-git.sh
• 글로벌 범위: ~/.claude/hooks/block-dangerous-git.sh

그다음 실행 권한을 부여합니다.

chmod +x .claude/hooks/block-dangerous-git.sh

또는 글로벌 범위라면:

chmod +x ~/.claude/hooks/block-dangerous-git.sh

Claude Code hook를 정확히 연결하는 법

프로젝트 범위에서는 .claude/settings.json 안에 PreToolUse hook를 넣고, 복사한 스크립트를 "$CLAUDE_PROJECT_DIR" 기준으로 실행하도록 안내합니다.

연결 시 핵심 포인트는 다음과 같습니다.

• hook event: PreToolUse
• matcher: Bash
• hook type: command
• command: block-dangerous-git.sh 경로

이 hook가 PreToolUse 아래에 등록되지 않으면, 스크립트 파일이 존재하더라도 실제 명령을 가로채지는 못합니다.

git-guardrails-claude-code 스크립트가 실제로 동작하는 방식

이 셸 스크립트는 표준 입력에서 tool input을 읽고, jq로 .tool_input.command를 추출한 뒤, 작은 위험 패턴 배열과 grep -qE로 대조합니다.

즉, 도입 시 막히는 지점도 비교적 명확합니다.

• 환경에 jq가 있어야 함
• settings에 적은 command 경로가 유효해야 함
• 스크립트에 실행 권한이 있어야 함
• Claude Code가 실제로 hook 시스템을 통해 Bash tool 호출을 처리해야 함

이 중 하나라도 어긋나면, 보호 장치가 있다고 생각한 것보다 실제 보호 수준은 훨씬 약해질 수 있습니다.

이 스킬을 쓰기 위해 사용자가 정해야 할 것

원본 스킬 자체는 많은 컨텍스트를 요구하지 않지만, 제대로 된 git-guardrails-claude-code usage 흐름을 만들려면 최소한 아래는 먼저 정해야 합니다.

• 프로젝트 전용으로 할지, 글로벌로 할지
• 기본 차단 목록으로 충분한지
• 팀에서 git tag -d, git rebase --abort, 특정 원격 대상 push 같은 추가 명령도 막고 싶은지
• 정당한 push가 필요할 때 사람이 수동으로 승인·처리하는 우회 절차를 문서화할지

이 답이 없으면 설치는 쉬워도, 실제 정책 적합성은 떨어질 수 있습니다.

막연한 목표를 좋은 프롬프트로 바꾸는 법

약한 프롬프트:

• “Set up git guardrails.”

더 좋은 프롬프트:

• “Install git-guardrails-claude-code for this project only. Copy the hook script into .claude/hooks/, make it executable, update .claude/settings.json with a PreToolUse hook for Bash, and then show me the exact blocked Git patterns from the script.”

이 프롬프트가 더 나은 이유:

• 적용 범위를 분명히 함
• 대상 경로를 지정함
• 설정과 검증을 모두 요구함
• Claude가 다른 hook 구조를 임의로 만들어낼 가능성을 줄임

첫 실행에 좋은 워크플로

실전적인 git-guardrails-claude-code guide는 보통 다음 순서가 좋습니다.

1. 프로젝트 범위인지 글로벌 범위인지 결정
2. scripts/block-dangerous-git.sh 확인
3. 스크립트를 대상 hooks 디렉터리로 복사
4. 복사한 파일에 chmod +x 적용
5. 올바른 settings 파일에 PreToolUse hook 연결
6. 안전한 저장소에서 무해한 시뮬레이션이나 명백히 차단되어야 하는 명령으로 테스트
7. 패턴을 커스터마이즈할지 결정

이 순서가 중요한 이유는, 넓게 배포하기 전에 실제 강제 목록이 무엇인지부터 확인할 수 있기 때문입니다.

설치가 제대로 됐는지 검증하는 법

“파일이 있다” 수준에서 멈추지 마세요. 동작을 검증해야 합니다.

• Claude Code가 실제로 사용하는 settings 파일 경로가 맞는지 확인
• hook command가 저장소 원본 경로가 아니라 복사된 스크립트를 가리키는지 확인
• 일회용 저장소에서 차단 대상 패턴을 직접 실행해보기
• Claude가 명령을 실행하는 대신 거부 응답을 받는지 확인

이 스킬은 화면상 확인보다 동작 검증이 훨씬 더 중요합니다.

Git 워크플로에서 가장 잘 맞는 경우

git-guardrails-claude-code for Git Workflows는 특히 아래 같은 AI 작업 방식에서 유용합니다.

• 파일 수정은 Claude에게 자유롭게 맡김
• diff와 status 확인도 Claude에게 맡김
• 브랜치 삭제, force push, hard reset, 정리(cleanup) 계열 명령은 사람이 명시적으로 통제

이 분리는 효과적입니다. 코딩 작업에서는 AI 생산성을 유지하면서도, 되돌리기 어려운 저장소 조작은 수동으로 남겨둘 수 있기 때문입니다.

언제 스크립트를 커스터마이즈해야 하나

기본 차단 목록은 의도적으로 좁습니다. 아래에 해당하면 scripts/block-dangerous-git.sh를 수정하는 편이 낫습니다.

• 팀에서는 git push 자체는 허용하되 --force만 막고 싶은 경우
• git commit --amend도 함께 차단하고 싶은 경우
• 워크플로에 민감한 브랜치 삭제 패턴이 포함되는 경우
• 저장소별로 다른 규칙이 필요한 경우

핵심 트레이드오프는 단순함과 정밀함입니다. 기본 스크립트는 감사하기 쉽지만, 많이 손본 버전은 그만큼 테스트가 더 필요합니다.

git-guardrails-claude-code 스킬 FAQ

git-guardrails-claude-code는 초보자에게도 괜찮은가

네. 전제는 초보자가 이미 Claude Code를 사용하고 있고, Git 주변에 더 안전한 기본값을 원한다는 점입니다. 설정 자체는 짧고, 개념도 이해하기 쉽습니다. Bash tool 호출을 실행 전에 가로챈다는 구조이니까요. 약간 기술적인 부분은 JSON hook 설정과 셸 스크립트 실행 권한 정도입니다.

Claude에게 “절대 push하지 마”라고 하는 것보다 낫나

네, 적어도 이 스킬이 다루는 명령 범위에서는 그렇습니다. git-guardrails-claude-code는 대화 규칙을 실행 시점 검사로 바꿔줍니다. 그래서 프롬프트 기억에만 의존하는 것보다 훨씬 신뢰할 수 있습니다.

git-guardrails-claude-code가 모든 위험한 Git 명령을 막나

아니요. 스크립트에 명시된 패턴만 차단합니다. 위험 모델에 다른 명령까지 포함된다면 직접 추가해야 합니다. 이 경계는 이 스킬의 핵심적인 한계입니다.

git-guardrails-claude-code를 글로벌로 써도 되나

네. 이 스킬은 ~/.claude/settings.json과 ~/.claude/hooks/block-dangerous-git.sh를 통한 글로벌 설치를 명시적으로 지원합니다. 글로벌 설치는 편리하지만, 프로젝트마다 정책이 다를 수 있다면 프로젝트 전용 설치가 테스트하기 쉽고 더 안전합니다.

일반적인 코딩 작업을 방해하지 않나

대체로 큰 영향은 없습니다. 평소 워크플로에 Claude의 push나 파괴적인 Git 정리 작업이 포함되지 않는다면 특히 그렇습니다. Claude는 코드 수정, 테스트 실행, 변경 준비까지 맡고, 최종 Git 권한은 사람이 행사하는 방식과 가장 잘 맞습니다.

언제 이 스킬을 쓰지 말아야 하나

아래에 해당하면 git-guardrails-claude-code는 건너뛰는 편이 낫습니다.

• Claude에게 Git 작업을 처음부터 끝까지 맡기고 싶은 경우
• 단순 패턴 차단이 아니라 정교한 allowlist가 필요한 팀
• 셸 hook나 jq에 의존할 수 없는 환경
• 로컬 Claude Code 설정을 넘어 조직 전체 강제가 필요한 경우

이런 상황에서는 이 스킬이 너무 좁거나, 너무 로컬한 도구처럼 느껴질 수 있습니다.

git-guardrails-claude-code 스킬 개선 방법

차단 패턴이 실제 위험과 맞는지 먼저 점검하세요

git-guardrails-claude-code를 가장 빠르게 개선하는 방법은 기본 패턴 목록을, 팀이 실제로 우려하는 Git 실수와 비교해보는 것입니다. 많은 팀은 모든 push 자체보다 다음을 더 민감하게 봅니다.

• force push
• 보호 브랜치에서의 브랜치 삭제
• monorepo에서의 파괴적 cleanup
• 디버깅 중 작업 트리 reset

정책이 다르다면 기본값을 그대로 받아들이지 말고 패턴 배열을 수정하세요.

Claude에게 더 강한 설치 지시를 주세요

Claude에게 이 스킬 적용을 맡긴다면, 요청에 구체적인 조건을 넣는 것이 좋습니다.

• 범위
• 정확한 대상 경로
• 기존 hooks를 유지할지 병합할지
• 최종 JSON 파일을 검토용으로 출력할지
• 설정 후 hook 테스트까지 할지

더 좋은 요청 예시는 다음과 같습니다.

• “Install git-guardrails-claude-code only in this repo, merge with any existing .claude/settings.json hooks instead of overwriting them, and show the final settings diff.”

이렇게 해야 가장 흔한 실패 중 하나인 기존 hook 설정 덮어쓰기를 피할 수 있습니다.

hook 병합 실수를 경계하세요

현실적으로 더 큰 문제는 셸 스크립트보다 settings 파일 수정입니다. 저장소에 이미 hooks 설정이 있다면, 성급한 설치는 이를 덮어써버릴 수 있습니다. 따라서 다음을 요구하는 편이 안전합니다.

• 무조건 재작성하지 말고 diff를 보여줄 것
• 기존 PreToolUse 항목을 보존할 것
• 여러 command가 실행될 때 hook 순서를 설명할 것

많은 사용자에게는 차단 명령 목록 자체보다 이 부분이 더 중요합니다.

오탐과 우회 가능성을 테스트하세요

이 스크립트는 패턴 매칭을 사용하므로, 아래를 직접 확인해야 합니다.

• 통과되어야 하는 정상 명령
• 막혀야 하는 차단 명령
• 막힐 것 같지만 실제로는 안 막힐 수 있는 변형
• 비슷한 텍스트가 예상 밖 방식으로 포함된 command 문자열

특히 글로벌로 넓히기 전에는, 여기서 git-guardrails-claude-code usage에 대한 신뢰도를 높이는 것이 맞습니다.

실제 누락을 보기 전까지는 과도하게 조이지 마세요

처음부터 패턴을 많이 추가하고 싶을 수 있습니다. 하지만 근거가 없다면 서두르지 않는 편이 낫습니다. 짧고 읽기 쉬운 blocklist가 더 믿기 쉽고 유지보수도 수월합니다. 다음이 관찰된 뒤에 확장하세요.

• Claude가 자주 시도하는 명령
• 사용자가 위험하다고 보는 명령
• 빠져나간 패턴
• 막히면 안 되는데 막힌 명령

그래야 guardrail을 이해 가능한 상태로 유지할 수 있습니다.

사람의 승인 경로를 함께 두세요

운영 측면에서 좋은 개선은 guardrail과 함께 명확한 규칙을 두는 것입니다. 예를 들면:

• Claude는 커밋 준비와 push 절차 설명까지는 가능
• 최종 push나 파괴적 cleanup은 사람이 수동으로 수행

이렇게 하면 사용자가 guardrail과 싸우지 않고, guardrail을 전제로 워크플로를 설계하게 됩니다.

글로벌 범위가 맞는지, 프로젝트 범위가 맞는지 다시 보세요

초기 사용 후에는 적용 범위를 재평가하는 것이 좋습니다.

• 모든 저장소에서 규칙이 잘 맞는다면 글로벌로 이동
• 일부 저장소는 Git 동작이 더 느슨해야 한다면 프로젝트 로컬 유지
• 팀마다 다르면 프로젝트별 스크립트 버전을 따로 운영

코드를 바꾸지 않고도 적합성을 높일 수 있는 가장 쉬운 방법 중 하나입니다.

스크립트는 읽기 쉽게 유지하세요

git-guardrails-claude-code를 커스터마이즈하더라도, 셸 스크립트는 감사하기 쉬운 상태를 유지하세요. 지나치게 영리한 로직보다, 명확한 패턴 목록과 하나의 일관된 에러 경로가 낫습니다. 안전장치에서는 가독성 자체가 신뢰성의 일부입니다.