커밋 전 3분 점검: Claude Code가 건드린 범위를 확인하고 확정하기

금요일 저녁, 저는 “글의 버튼 문구만 고쳐줘”라고 Claude Code에게 부탁했습니다. 돌아와서 git status를 봤더니 변경된 파일이 18개. 문구만 바뀌었어야 하는데 상품 링크 매핑, 관련 글 삽입, 거기에 “겸사겸사 고쳤다”는 번역 파일까지 줄줄이 늘어서 있었습니다.

하나하나 보면 “친절하게 해준” 변경입니다. 하지만 그대로 전부 커밋했다면, 다른 작업 중이던 저장 안 한 수정까지 휩쓸려 들어가서, 다음 날 배포에서 원인 모를 에러로 반나절을 날릴 뻔했습니다.

똑똑한 AI일수록 부탁한 범위를 살짝 넘어서 일을 합니다. 악의는 없습니다. 그래서 더더욱, 확정하기 직전에 “여기서 멈추고 사람이 눈으로 본다”는 한 박자가 필요합니다.

핵심 요약

• Claude Code는 요청에 충실해도 손대는 범위가 조용히 넓어집니다. 확정 전 확인은 그 “삐져나옴”을 찾아내는 작업입니다.
• 확인은 3분짜리 정해진 순서로 돌립니다. 범위 확인 → diff 확인 → 검증 → 파일을 골라서 스테이징, 이 4단계입니다.
• AI에게 맡기는 것은 “변경의 실행”, 사람이 판단하는 것은 “어디까지를 이번 확정에 포함할지”입니다. 여기를 섞지 않습니다.
• 복사해서 쓸 수 있는 확인 스크립트를 넣어 뒀습니다. git status와 diff 요약을 한 화면에 띄워서 놓치는 것을 줄입니다.
• 빌드가 통과했다고 안심하지 않습니다. 공개 후의 화면과 번역 내용은 다른 눈으로 다시 봐야 합니다.

왜 “확정하기 직전”에 확인을 두는가

확인 타이밍은 작업을 시작하기 전도, 작업 도중도 아닌, 커밋하기 직전이 가장 잘 듣습니다. 이유는 단순합니다. AI가 실제로 건드린 파일의 전체 그림이 그 순간에만 확정되기 때문입니다.

시작하기 전에 아무리 “여기만 건드려”라고 지시해도, AI는 작업 중에 “겸사겸사 고치는 게 낫겠다”고 판단한 것에 손을 댑니다. 도중에 멈추면 아직 작업이 끝나지 않아서 무엇을 봐야 할지 알 수 없습니다. 전부 끝나고, 확정하기 한 걸음 앞. 여기서 비로소 “부탁한 것과 실제로 바뀐 것”을 맞대 볼 수 있습니다.

제가 자주 사고를 치는 부분은 수익과 관련된 곳입니다. 예를 들어 상품 페이지로 가는 링크가 한 글자 어긋나기만 해도, 클릭한 독자가 “페이지를 찾을 수 없습니다”로 떨어집니다. 글의 품질이 아무리 좋아도 링크 끝이 죽어 있으면 매출 기회는 거기서 끝납니다. 그래서 diff를 볼 때는 링크 끝이 바뀌지 않았는지를 가장 먼저 확인합니다.

Claude Code의 기본 사용법을 아직 다지지 않은 분은 먼저 Claude Code 입문 가이드에서 전체 그림을 잡아 두면, 이 확인 절차의 의미가 또렷해집니다.

3분에 도는 확인 순서

매일 이어 갈 수 없으면 의미가 없으므로, 절차는 4단계로 좁혔습니다. 완벽한 감사가 아니라 가벼운 안전장치입니다.

1. 범위를 소리 내어 말한다. 이번 요청이 무엇이었는지 한 문장으로 다시 말합니다. “글의 버튼 문구 수정”처럼요. 이것이 이후 판단의 잣대가 됩니다.
2. 변경 파일 목록을 본다. git status로 바뀐 파일들의 면면을 확인합니다. 한 문장으로 말한 범위에서 벗어난 파일이 있으면, 거기에 포스트잇을 붙이는 마음으로 표시해 둡니다.
3. 표시한 파일의 diff를 읽는다. 범위 밖 파일만 내용을 봅니다. 친절한 변경이면 남기고, 무관한 변경이면 이번에는 빼고, 를 하나씩 정합니다.
4. 필요한 파일만 골라서 스테이징한다. git add .로 전부 넣지 않습니다. 이번 요청에 필요한 파일만 이름을 짚어서 추가합니다.

핵심은 3번입니다. AI가 넓힌 범위를 “전부 받아들인다” 또는 “전부 거절한다”의 양자택일로 만들지 않는 것. 하나씩, 남길지 뺄지를 사람이 정합니다. 수수하지만 여기를 건너뛰면 첫머리의 18개 파일 사고가 일어납니다.

AI에게 맡기는 범위와, 사람이 판단하는 범위

이 선 긋기를 애매하게 두면 확인 자체가 형식만 남습니다. 저는 다음과 같이 나눕니다.

할 일	담당	이유
문장이나 코드 수정을 실행한다	AI	양이 많고 기계적으로 처리할 수 있다
문법 에러나 명백한 실수를 고친다	AI	규칙이 명확해 자동화하기 쉽다
변경을 이번 확정에 포함할지 정한다	사람	요청의 의도를 아는 건 사람뿐이다
링크 끝이나 공개 후 화면을 확인한다	사람	빌드가 통과해도 내용은 보장되지 않는다
삭제·운영 데이터·결제 관련 작업	사람	되돌릴 수 없는 사고는 사람 승인을 필수로 한다

AI에게 “포함할지 정하는 것”까지 맡기면, AI는 자기가 고친 것을 당연하다는 듯 전부 포함하려 합니다. 판단만은 손에 남깁니다. 이것이 사고를 줄이는 가장 중요한 급소입니다.

복사해서 쓰는 프롬프트 템플릿

확인을 AI에게 돕게 할 때는, AI에게 “자가 채점”을 시키지 말고 “사실을 늘어놓게” 하는 것이 요령입니다. 다음 템플릿을 그대로 붙여서 쓰면 됩니다.

지금부터 커밋합니다. 확정 전에 다음을 사실만 보고해 주세요. 판단은 제가 합니다.

1. 이번 요청을 한 문장으로 요약
2. git status로 변경된 파일을 목록으로 (추적 안 되는 파일 포함)
3. 그중 요청의 한 문장에서 벗어나 보이는 파일과 그 이유
4. 링크나 공개 후 화면에 영향을 줄 만한 변경이 있으면 해당 부분

"문제없습니다"라고는 쓰지 마세요. 판단 재료만 늘어놓아 주세요.

마지막 한 문장이 잘 듣습니다. 이걸 넣지 않으면 AI는 “특별히 문제없습니다, 커밋해도 괜찮습니다”라고 기분 좋게 정리해 버려서 확인의 의미가 사라집니다. 프롬프트를 짜는 세세한 방법은 프롬프트 엔지니어링 응용편에 자세히 정리해 뒀습니다.

복사하면 바로 도는 확인 스크립트

매번 git status와 git diff를 나눠 치는 건 번거로우니, 변경의 전체 그림을 한 화면에 띄우는 스크립트를 넣어 두겠습니다. PowerShell과 bash 둘 다 준비했습니다. 내용은 “변경 파일 목록”과 “파일별 추가·삭제 줄 수”를 늘어놓는 것뿐입니다.

PowerShell 버전(Windows).

# precommit-check.ps1
# 커밋 전에, 변경 파일과 변경량을 한 화면에서 확인한다

Write-Host "=== 이번에 건드린 파일 ===" -ForegroundColor Cyan
git status --short

Write-Host "`n=== 파일별 변경량 (추가 / 삭제) ===" -ForegroundColor Cyan
git diff --stat HEAD

Write-Host "`n=== 확인 체크리스트 ===" -ForegroundColor Yellow
@(
  "요청을 한 문장으로 말할 수 있다",
  "범위 밖 파일이 섞여 있지 않다",
  "링크 끝과 공개 후 화면을 봤다",
  "이번에 필요한 파일만 스테이징한다"
) | ForEach-Object { Write-Host "  [ ] $_" }

bash 버전(macOS / Linux / Git Bash).

#!/usr/bin/env bash
# precommit-check.sh
# 커밋 전에, 변경 파일과 변경량을 한 화면에서 확인한다

echo "=== 이번에 건드린 파일 ==="
git status --short

echo ""
echo "=== 파일별 변경량 (추가 / 삭제) ==="
git diff --stat HEAD

echo ""
echo "=== 확인 체크리스트 ==="
for item in \
  "요청을 한 문장으로 말할 수 있다" \
  "범위 밖 파일이 섞여 있지 않다" \
  "링크 끝과 공개 후 화면을 봤다" \
  "이번에 필요한 파일만 스테이징한다"; do
  echo "  [ ] $item"
done

실행은 이게 전부입니다.

bash precommit-check.sh

이 스크립트는 아무것도 자동으로 판단하지 않습니다. 판단은 사람이 한다는 전제를 무너뜨리지 않기 위해, 일부러 “늘어놓아 보여주기만” 하게 만들었습니다. 체크리스트 4항목이 전부 채워지면, 필요한 파일만 git add 파일명으로 추가해서 커밋합니다.

실무에서 잘 듣는 3가지 장면

1. 글이나 자료의 공개 전. 여러 언어의 글을 한꺼번에 공개할 때, 번역 파일이 영어 그대로 남아 있는 경우가 있습니다. 빌드는 통과하는데 내용이 번역되어 있지 않은 거죠. diff에서 파일명만 보고 만족하지 말고, 공개 후 페이지에서 본문의 언어까지 확인합니다.

2. 기존 파일의 다시 쓰기. 문장을 고친 줄 알았는데 페이지 안의 링크나 상품명까지 바뀌어 있는 경우가 있습니다. “문장 개선”이라고 한 문장으로 범위를 정해 두면, 링크 변경은 범위 밖으로 보고 한 번 멈춰 설 수 있습니다.

3. 팀에 도입할 때. Claude Code가 어디까지 자동으로 진행했고, 어디서 사람에게 물었는지를 기록으로 남깁니다. 승인 규칙(자동으로 진행해도 되는 작업, 반드시 사람에게 묻는 작업)이 애매한 채로 운영하면, 멤버마다 사고 나는 방식이 달라져서 수습이 안 됩니다.

자주 빠지는 함정과 고치는 법

함정 1: git add .로 전부 넣어 버린다. 저장 안 한 다른 작업의 변경까지 휩쓸려 들어갑니다. 고치는 법은 단순합니다. .를 쓰지 말고 파일명을 이름으로 짚어 스테이징하는 습관을 들이는 것. 번거롭게 느껴져도 이게 가장 빠른 보험입니다.

함정 2: 빌드가 통과했으니 안심한다. 빌드는 문법을 볼 뿐, 링크 끝이 맞는지, 번역이 내용까지 번역됐는지는 보지 않습니다. 고치는 법은 공개 후 페이지를 실제로 열어서 제목·본문·링크 끝을 눈으로 확인하는 것. 기계의 합격과 사람의 합격은 다른 것입니다.

함정 3: AI에게 “문제없어?”라고 물어보고 끝낸다. AI는 부탁받으면 “괜찮습니다”라고 말하기 쉽습니다. 고치는 법은 앞의 프롬프트 템플릿처럼 “판단은 쓰지 말고 사실만 늘어놓아”라고 지시하는 것. 판단의 주어를 사람에게 되돌리면 확인이 작동하기 시작합니다.

확인을 습관으로 정착시키는 요령은 Claude Code 생산성 향상 팁에도 정리해 뒀습니다. git의 --stat 같은 공식 동작은 Git 공식 문서에서 확인할 수 있습니다.

자주 묻는 질문

Q. 확인에 매번 3분이나 들일 여유가 없습니다. A. 변경이 작은 날은 1분이면 끝납니다. 3분 걸리는 건 범위 밖 파일이 많은 날인데, 그건 애초에 확인이 필요한 날입니다. 걸리는 시간의 길이는 위험도의 바로미터라고 생각해 주세요.

Q. AI에게 스테이징까지 맡기면 안 되나요. A. 안전하다고 알고 있는 작은 작업이면 맡겨도 괜찮습니다. 다만 “어떤 파일을 포함할지”의 최종 판단만은 사람에게 남겨 두기를 권합니다. 여기가 사고의 입구가 되기 쉬운 곳입니다.

Q. 커밋 메시지에는 무엇을 쓰면 되나요. A. “무엇을 바꿨는지”와 “무엇으로 확인했는지” 두 가지입니다. 예를 들어 “버튼 문구 수정, 공개 후 페이지에서 링크 끝 확인”처럼요. 나중에 봤을 때 확인했는지 안 했는지가 한눈에 보입니다.

Q. 범위 밖 파일이 사실은 고치는 게 나은 변경이었다면. A. 그래도 이번에는 뺍니다. 다른 커밋으로 나누는 것뿐이지, 지우는 게 아닙니다. 하나의 커밋에 하나의 의도, 를 지키면 나중에 따라가기 쉬워집니다.

실제로 해본 결과

첫머리의 18개 파일 사건 이후, 저는 이 4단계를 매번 확정 전에 끼워 넣게 됐습니다. 시험해 본 건 글 공개, 파일 다시 쓰기, 설정 변경의 3가지 패턴입니다.

가장 잘 들었던 건 “요청을 한 문장으로 다시 말한다”는 첫 단계였습니다. 이걸 입 밖으로 내기만 해도 범위 밖 파일이 시야에 확 들어오게 됩니다. 확인 스크립트를 돌린 뒤 git add .를 치는 걸 그만두고 파일을 이름으로 짚어 스테이징하게 했더니, 다른 작업을 휩쓰는 사고는 0이 됐습니다.

그리고 의외였던 건, AI에게 묻는 방식을 “문제없어?”에서 “사실만 늘어놓아”로 바꾼 효과입니다. 같은 AI가 갑자기 쓸모 있는 확인 파트너가 됐습니다. 더 똑똑한 AI를 찾기보다, 확인의 주어를 사람에게 되돌린다. 이것이 저에게는 가장 수수하면서도 가장 잘 들었던 한 수였습니다.

권한 설계와 공개 전 점검을 팀 전체의 운영까지 녹여 내고 싶을 때는, 연수·상담에서 구체적인 설계를 함께 짜고 있습니다.