Claude Code, 명령 한 줄로 안전하게 — cc-guard OSS 소개

2-1

Claude Code 쓰다 보면 한 번쯤 이런 순간이 옵니다. AI가 알아서 척척 명령을 실행해주는 게 편하긴 한데, 문득 "어? 방금 그거 그냥 실행해버린 거야?" 싶은 거죠. rm -rf 같은 위험한 명령이나 .env 커밋 같은 걸 AI가 거리낌 없이 해버릴 수 있다는 게 좀 불안하고요.

cc-guard는 바로 그 불안을 없애주는 도구입니다. 터미널에 딱 한 줄만 치면 됩니다.

npx @gaebalai/cc-guard

이거 한 번 실행하고 Claude Code 재시작하면 끝이에요. 10초면 8개의 안전 hook이 깔립니다. 의존성도 제로라서 뭐 따로 설치할 것도 없고요.

그래서 'hook'이 뭔데?

처음 듣는 분들을 위해 짧게 설명하자면, hook은 Claude Code가 명령을 실제로 실행하기 전에 그 내용을 한 번 검사하는 장치예요.

공항 보안 검색대를 떠올리면 딱 맞습니다. 탑승구(명령 실행) 앞에 체크포인트(hook)가 있어서, 위험물(rm -rf 같은 거)을 들고 있으면 통과를 안 시켜주는 거죠. AI가 아무리 자신 있게 위험한 명령을 내밀어도 그 앞단에서 한 번 걸러주는 겁니다.

실제로 뭘 막아주냐면

말로만 "안전합니다" 하면 와닿지 않으니까, 구체적으로 어떤 게 달라지는지 볼게요.

동작	cc-guard 없을 때	cc-guard 있을 때
`rm -rf /`	그냥 실행됨 😱	차단
`git push --force`	그냥 실행됨	차단
`git push origin main`	그냥 실행됨	차단
`git add .env`	그냥 실행됨	차단
`cat ~/.netrc`	토큰이 그대로 노출	차단
Python 구문 오류	모르고 지나감	자동 감지
컨텍스트 고갈	갑자기 뚝 끊김	단계적으로 경고

보다시피 한 번 사고 나면 복구가 골치 아픈 것들이 대부분이에요. 메인 브랜치 강제 푸시라든가, 시크릿 파일 커밋이라든가. 이런 걸 사후 수습하는 것보다 애초에 못 하게 막는 게 훨씬 마음 편하잖아요.

단순 차단기가 아니에요

cc-guard가 흥미로운 건, 그냥 "위험한 명령 막아준다" 수준에서 그치지 않는다는 점입니다. Anthropic 공식 이슈 트래커에 올라온 71건 이상의 실제 문제에 대응하도록 만들어졌어요. 그래서 막아주는 범위가 꽤 디테일합니다.

특히 세션 보호 쪽이 알찹니다. Claude Code 오래 돌리다 보면 은근히 겪는 문제들이 있잖아요. 토큰이 줄줄 새거나, 세션이 날아가거나, compaction 후에 CLAUDE.md 규칙을 까먹어버리거나. cc-guard에는 이런 걸 잡아주는 hook들이 들어 있습니다.

큰 파일을 통째로 cat 해서 컨텍스트 낭비하는 거 경고
세션 시작할 때 JSONL 백업 떠두기 (날아가도 복구 가능)
compaction 직전에 전체 백업
토큰 예산 상한 넘으면 도구 호출 차단
서브에이전트가 부모 신분 사칭하거나 대화 이력 흘리는 거 방지

요즘 멀티 에이전트로 작업하는 분들이라면 마지막 항목들이 특히 반가울 거예요. 자식 에이전트가 위험한 git 명령 날리는 걸 막거나, 거짓 보고를 검증하도록 유도하는 hook까지 있습니다.

한국에서 쓰는 사람을 위한 배려

이 부분이 개인적으로 제일 마음에 들었는데요, cc-guard는 국내 규제 환경을 따로 챙겨놨습니다. 회사에서 Claude Code 도입하려고 할 때 보안팀이 꼭 물어보는 것들 있잖아요.

규제/표준	충돌 지점	대응
개인정보보호법(PIPA)	주민번호·연락처가 로그/프롬프트에 노출	secret-guard, output-secret-mask 등
정보통신망법	미인가 외부 송신	network-guard, webfetch-domain-allow 등
ISMS-P 인증	접근 통제, 변경 이력, 권한 분리	permission-audit-log 등
금융보안원 전자금융감독규정	운영 계정/키 노출, prod 직접 변경	credential-exfil-guard, deploy-guard 등

물론 cc-guard가 컴플라이언스 인증을 대신해주는 건 아니에요. 어디까지나 보조 통제 수단으로 쓰는 출발점이고, 실제 적용은 조직별 위험 평가랑 보안 담당자 검토를 거쳐야 합니다. 그래도 "AI 코딩 툴 쓰면 규제 어떻게 맞추냐"는 질문에 바로 들이밀 만한 답이 생긴 거죠.

토큰 많이 쓰는 것 같으면

요금 폭탄 무서워하는 분들을 위한 무료 진단 도구도 붙어 있습니다. Token Checkup에서 30초면 내 토큰 소비 패턴을 확인할 수 있어요. CLAUDE.md 최적화나 컨텍스트 관리 가이드는 COOKBOOK 쪽에 정리돼 있고요.

참고로 2026년 6월 15일부터 Anthropic이 programmatic 과금을 분리한다는 점도 알아두면 좋습니다. claude -p나 SDK 호출이 별도 크레딧으로 라우팅되거든요. 모델이 자기 과금 로직을 학습 데이터로 검증할 수 없다 보니, 이 시점 이후로는 모델이 "이만큼 썼어요" 하는 말과 실제 청구 사이 괴리가 더 커질 수 있어요. 그래서 더더욱 이런 진단·제어 도구가 필요해지는 거고요.

더 깊게 쓰고 싶다면

기본 8개로 부족하다 싶으면 example hook이 무려 772개나 준비돼 있습니다. 개별로 골라 깔 수도 있고요.

# 모든 example 둘러보기
npx @gaebalai/cc-guard --examples

# 원하는 것만 골라 설치
npx @gaebalai/cc-guard --install-example permission-audit-log

# 아예 최대 안전 모드 (스택 감지해서 권장 hook 자동 선택)
npx @gaebalai/cc-guard --shield

# 우리 환경 안전 점수 매겨보기 (0~100점)
npx @gaebalai/cc-guard --audit

자연어로 "이런 거 막아줘" 하면 커스텀 hook을 만들어주는 --create 명령도 있고, 팀끼리 설정을 공유하는 --export / --team 같은 것도 있어요. CLI 명령만 56개니까, 한 번 --help 쳐보면 생각보다 할 수 있는 게 많다는 걸 알게 될 겁니다.

정리하자면

준비물은 간단해요. jq 하나(brew install jq 또는 apt install jq)랑 Claude Code 2.1 이상이면 됩니다. 라이선스는 MIT라 부담 없이 쓰면 되고요.

Claude Code를 진지하게 쓰는 사람일수록 "편한 만큼 불안하다"는 감각을 한 번쯤 느껴봤을 거예요. cc-guard는 그 불안을 명령 한 줄로 바꿔주는 도구입니다. 일단 깔아두면 사고가 안 나는 게 당연해지고, 그제야 마음 놓고 AI한테 일을 맡길 수 있게 되거든요.

궁금하면 일단 한 번 돌려보세요. 10초면 됩니다.

npx @gaebalai/cc-guard

GitHub: https://github.com/gaebalai/cc-guard
웹 도구 모음: https://claudecode.to/cc-guard/

이메일문의: jaewoo@claudecode.to

프로필(Linktr.ee): https://linktr.ee/jaewookim

Jaewoo Kim by AI-fluent liberal arts Engineer