GitHub 저장소 claude-code-mistake-guards는 Claude Code가 반복해서 저지른 실수를 막기 위한 가드 7종을 제공한다. 훅 3개와 배포 전후에 쓰는 스크립트 4개로 구성되며, 제작자는 실제 작업에서 나온 실수 기록을 바탕으로 만들었다고 설명한다.
제작자에 따르면 2026년 6월부터 10월까지 앱·게임·스토어 등록·서버와 여러 세션이 함께 쓰는 Git 저장소에서 Claude Code를 매일 사용하며 실수를 기록했고, 그 기록은 500건을 넘었다. 같은 실수가 되풀이되자 메모에 규칙을 더하는 대신 되돌리기 어려운 순간에 작업을 차단하는 방식을 택했다. 저장소는 Claude Code 2.1.310(2026-10)에서 테스트했으며, 별도 프로젝트에서 git pull 차단과 답변 재작성도 확인했다고 밝힌다.
가드에는 pkill -f와 pgrep -f 대기 루프의 위험한 사용, 공유 작업 트리에서의 git pull, 너무 짧은 저장 요청, 검색 결과만으로 계정 자격을 판단하거나 트래픽을 수요로 해석하는 답변 등을 막는 규칙이 포함된다. 배포 스크립트는 태그 제한·금지어·미리보기 영상 등을 확인하고, 생성 작업과 데이터 추가, 장면 렌더링 단계에도 각각 검사를 둔다. 뒤의 네 스크립트는 제작자의 자체 작업 흐름을 위한 사례이므로, 자기 파이프라인에 맞게 표를 바꾸도록 안내한다.
가드는 검사 지점에 전달된 정보만 확인한다. 예를 들어 guard_bash.py는 $VARIABLES에 숨겨진 경로나 ssh "..." 안의 명령을 건너뛰고, ship_check.py는 PDF나 이미지 안의 문구가 아니라 제목·태그·설명을 읽는다. stop_check.py는 단어 패턴을 확인하므로 알려진 잘못된 주장의 반복을 잡을 뿐, 잘못된 주장 전반을 판별하지는 않는다. 자체 오류가 나면 명령을 통과시키는 방식이며, 규칙을 너무 자주 발동시키면 가드를 끄게 될 수 있어 오탐도 시험했다고 제작자는 설명한다.
설치에는 Python 3이 필요하다. baseline_check.py에는 Pillow, ship_check.py의 영상 검사는 ffmpeg가 필요하다. 기존 .claude/settings.json을 덮어쓰지 말고 저장소의 settings.json에서 hooks 설정을 병합해야 한다. 이미 Bash용 PreToolUse 항목이 있다면 그 항목에 guard_bash.py를 넣어야 한다. 제작자는 Bash 항목을 세 개로 나누면 긴 세션에서 차단이 불안정했지만 하나로 합치자 매번 차단됐다고 덧붙이며, 설치 후 실제 세션에서 차단돼야 할 명령으로 동작을 확인하라고 권한다.
git clone https://github.com/hadiux0295/claude-code-mistake-guards.git
cd your-project
mkdir -p .claude/hooks tools
cp ../claude-code-mistake-guards/hooks/*.py .claude/hooks/
cp ../claude-code-mistake-guards/tools/*.py tools/
각 파일 상단의 값과 설정을 프로젝트에 맞게 바꿔야 한다. 테스트는 다음 명령으로 실행하며, 저장소는 차단 대상과 통과 대상 양쪽을 확인한다고 안내한다.
bash run_all.sh # ends with "== result: ALL PASS"
전체 실수 기록은 한국어 전자책 300건 이상이며, 영어로 공개한 50건은 MISTAKES.md에서 볼 수 있다. 영어 번역문은 아직 사람이 교정하지 않았다고 밝혔으며, 코드는 MIT 라이선스로 제공되지만 사용 전 각자 환경에서 테스트해야 한다.
댓글 (0)
로그인하면 이 기사에 내 생각을 남길 수 있어요