.env 파일이나 코드 속 API 키(외부 서비스를 쓰는 비밀 열쇠)가 실수로 깃허브에 올라가면, 키를 새로 바꾸고 기록을 지우는 일이 생겨요. 커밋(변경 내용을 기록으로 남기는 일) 바로 전에 검사하는 pre-commit 훅(커밋 직전에 저절로 도는 검사 스크립트)을 한 번 넣어 두면 그 실수를 내 컴퓨터에서 먼저 막을 수 있어요. 훅 스크립트는 클로드 코드(Claude Code)에 말로 시켜 만들어요.
이런 분께
- 사이드 프로젝트를 깃허브에 올리는데 .env를 같이 올릴까 늘 불안한 분
- 바이브코딩으로 만든 앱에 키를 코드에 바로 적어 둔 적이 있는 분
끝나면 이렇게 됩니다
예시 저장소(프로그램 파일을 모아 둔 폴더)에 훅을 넣고 실제로 커밋해 본 결과예요.
$ git add .env && git commit -m "설정 추가"
[막음] 비밀 파일이 커밋에 들어 있어요: .env
1:+OPENAI_API_KEY=sk-abcdefghijklmnopqrstuvwx123
[막음] 위 줄에 키나 비밀번호로 보이는 값이 있어요.
고친 뒤 다시 커밋하세요. 검사를 건너뛰려면 git commit --no-verify
$ git commit -m "환경변수로 바꿈" (API_KEY = os.environ["API_KEY"])
→ 통과, 커밋됨
키가 들어간 커밋은 멈추고, 환경변수(키를 코드 밖에 두고 불러 쓰는 방식)로 바꾼 커밋은 그대로 통과해요.
준비물
- 클로드 코드: Pro, Max, Team, Enterprise 요금제나 콘솔 계정이 있어야 해요. 무료 요금제에는 들어 있지 않아요(2026년 10월 기준, 공식 설치 문서).
- 깃(Git)이 설치된 컴퓨터와 깃으로 관리 중인 프로젝트 폴더. 윈도우는 Git for Windows를 깔아 두면 훅이 그대로 돌아요.
- 터미널(컴퓨터에 글자로 명령하는 창). 윈도우는 시작 메뉴에서 "터미널", 맥은 Spotlight에서 "터미널"을 검색해 열어요.
따라 하기
- 클로드 코드가 없다면 터미널에서 설치해요. 맥은 아래 첫 줄, 윈도우 PowerShell은 둘째 줄이에요. 설치 뒤 새 터미널 창에서
claude --version을 쳐서 버전 숫자가 나오면 된 거예요.
curl -fsSL https://claude.ai/install.sh | bash
irm https://claude.ai/install.ps1 | iex
- 터미널에서 프로젝트 폴더로 이동해(
cd 폴더경로)claude를 쳐서 시작해요. 처음이면 브라우저 로그인 안내를 따라요. - 아래 "복사해서 쓰는 프롬프트"를 붙여 넣어요. 클로드 코드가 파일을 만들거나 권한을 바꾸려 할 때마다 허락을 물으니, 내용을 읽고 허락해요.
- 다 만들어지면 클로드 코드에 "지어낸 가짜 키로 테스트해 줘"라고 시켜, 막히는 커밋과 통과하는 커밋을 둘 다 확인해요.
- 실제로 키가 든 파일이 있었다면 .gitignore(깃이 무시할 파일 목록)에 .env가 들어 있는지도 같이 확인해 달라고 해요.
복사해서 쓰는 프롬프트
이 폴더는 깃으로 관리하는 프로젝트야. 커밋 직전에 비밀 정보를 검사하는 pre-commit 훅을 만들어 줘.
- 위치: .git/hooks/pre-commit, 실행 권한까지 줘
- 막을 것 1: [.env, *.pem, id_rsa] 같은 비밀 파일이 커밋에 들어가는 경우
- 막을 것 2: 새로 더한 줄에 API 키, 비밀번호, 개인 키처럼 보이는 값이 있는 경우 (대소문자 상관없이)
- 막을 때는 어떤 파일 몇째 줄 때문인지 한국어로 알려 주고 커밋을 멈춰
- 이미 커밋된 기록은 건드리지 마
- 다 만들면 임시 폴더에 가짜 키로 테스트 저장소를 만들어서, 막혀야 하는 경우와 통과해야 하는 경우를 직접 돌려 결과를 보여 줘
