「될 것이다」라는 생각으로 돌진하여 망가뜨리기

Claude Code에게 5개 파일의 일괄 리팩토링 (Refactor)을 요청했다. 작업은 문제없이 진행되었고, 마지막으로 git commit까지 마쳤다. 하지만 그 브랜치에는 조금 전 다른 작업으로 넣어둔 미커밋 (Uncommitted) 변경 사항이 남아 있었다. Claude는 이를 알아차리지 못하고, 의도하지 않은 변경 사항까지 함께 커밋해 버렸다.

원인은 단순하다. Claude는 전제 조건이 갖춰져 있다고 의심하지 않고 진행한다. 브랜치가 예상대로인지, 미커밋 변경 사항이 섞여 있지 않은지, 락 파일 (Lock file)이 남아 있지 않은지——이러한 현재 상태를 확인하지 않고, 의뢰받은 조작만을 실행하려고 한다.

Claude Code의 시스템 프롬프트 (System Prompt)에는 「파괴적인 조작을 수행하기 전에 git status를 실행한다」라는 원칙이 있다. 하지만 이는 일반적인 마음가짐일 뿐, 어느 타이밍에, 무엇을, 어떤 기준으로 확인할지까지는 정의되어 있지 않다. 결과적으로 확인 여부는 해당 세션의 흐름에 따라 달라지게 된다.

이를 메커니즘으로서 고정하기 위해 만든 것이 preflight-check 스킬이다.

이 기사에서 다룰 내용

• preflight-check 스킬의 발화 조건과, 의도적으로 발화시키지 않는 조건을 명확히 한다. - 실제 체크 항목 (Git 상태·스코프·기밀 정보)을 그대로 보여준다.
• 이 스킬이 읽기 전용 (Read-only) 툴만 가지도록 설계된 이유를 설명한다.
• CLAUDE.md의 「파괴적 조작의 사전 확인」 원칙과 어떻게 보완되는지 정리한다.

해결책의 전체상

preflight-check는 독립된 에이전트 (Agent)가 아니라, Claude Code 자신이 태스크 (Task) 직전에 호출하는 검증 전용 스킬이다. 무언가를 변경하기 전에 「현재 상태를 보는」 페이즈 (Phase)를 강제적으로 삽입한다.

포인트는 이 스킬 자체가 아무것도 변경하지 않는다는 점이다. 상태를 읽고 보고할 뿐, 수정이나 실행은 수행하지 않는다. 판단과 실행은 반드시 메인 Claude와 사용자에게 돌려준다.

구현 상세

발화 조건 (frontmatter)

실제 SKILL.md는 다음과 같이 정의되어 있다.

---
name: preflight-check
description: Verify preconditions before Git operations or multi-file changes. Use proactively before commits, large refactors, or changes to 5+ files. Do NOT use for read-only queries or single-file edits.
...

Bash(git *)는 「git으로 시작하는 명령만 승인 없이 실행할 수 있다」라는 허가 리스트 (Allowlist) 표기법이다. 이 한 줄이 있음으로써, 이 스킬 안에서 git 이외의 임의 명령이 동작하는 일은 없다.

여기서 중요한 것은 description과 when_to_use 모두에 네거티브 트리거 (Negative Trigger)가 명시되어 있다는 점이다.

• 사용할 때: git commit 전, 대규모 리팩토링 전, 5개 파일 이상의 변경, 사용자가 「확인하고 진행해줘」, 「먼저 확인해줘」라고 말했을 때
• 사용하지 않을 때: 읽기 전용 쿼리 (Read-only query), 단일 파일 편집

이 네거티브 트리거가 없으면, Claude는 만약을 위해 매번 이 스킬을 거치려 한다. 단 한 줄의 버그 수정이나 코드 설명을 요청했을 뿐인데 매번 Git 상태 체크가 끼어들면, 그 자체로 방해가 된다. 안전 확인은 필요한 상황에서만 발동하는 것을 전제로 하며, 상시 발동은 오히려 신뢰를 떨어뜨린다.

또 하나 중요한 것이 allowed-tools이다. Bash(git *) · Read · Glob만을 가진다. Write나 Edit는 포함되어 있지 않다. 즉, 이 스킬은 구조적으로 아무것도 변경할 수 없다. 확인 결과를 보고 「그럼 고치자」라고 판단하는 것은 메인 Claude와 사용자의 역할이며, preflight-check 스스로가 멋대로 손을 댈 수는 없다. 권한을 제한함으로써 역할을 강제하고 있는 것이다.

체크 항목 1: Git 상태 확인

# 현재 브랜치와 상태
git status --short
git branch --show-current

확인하는 것은 다음 세 가지 점이다.

• 예상하고 있는 브랜치에 있는가?
• 미커밋된 의도하지 않은 변경 사항이 혼입되어 있지 않은가?
• .gitignore로 기밀 파일이 보호되고 있는가?

서두에 언급한 사고는 바로 이 첫 번째, 두 번째 항목만으로도 방지할 수 있는 종류의 것이었다. 현재 어떤 브랜치에 있는지, 무엇이 이미 스테이징(staging)되어 있는지를 확인하고 조작하는 것만으로도, 의도하지 않은 변경 사항을 포함할 리스크를 크게 낮출 수 있다.

체크 항목 2: 스코프(Scope) 확인

# 변경될 파일 목록 (Git 조작 전)
git diff --name-only HEAD
git diff --cached --name-only

• 변경 파일 수가 예상 범위 내인가 (10개 이상이라면 이 스킬만으로 끝내지 않고, 더 무거운 복수 에이전트(multi-agent) 검증 공정으로 넘긴다)
• 의도하지 않은 파일이 포함되어 있지 않은가?
• 로컬 운영 정책상 금지된 조작(force push, 원격 저장소 추가 등)에 해당하지 않는가?

'5개 이상의 파일 변경 시 발화'라는 조건 자체도 여기에 직결되어 있다. 몇 개의 파일에 대한 작은 수정이라면 문제는 잘 발생하지 않지만, 변경 범위가 넓어질수록 의도하지 않은 파일이 섞여 들어갈 리스크는 높아진다. 여기서 한 번 스코프를 가시화함으로써, 예상보다 넓은 범위까지 손을 뻗고 있지는 않은지 기계적으로 확인할 수 있다.

체크 항목 3: 기밀 정보 스캔

# 기밀 정보 패턴 확인 (오탐 주의)
git diff --cached | grep -iE "(password|secret|token|api.key|credential)" || echo "기밀 정보 없음"

• API 키, 토큰, 비밀번호가 포함되어 있지 않은가?
• .env나 인증 정보 파일이 스테이징(staging)되어 있지 않은가?

grep 기반의 단순한 패턴 매칭이므로 오탐(false positive)은 있을 수 있다. 하지만 커밋 전에 반드시 한 번 스캔한다는 기계적인 공정이 있는 것만으로도, 실수로 API 키를 포함한 채 커밋하는 사고는 상당히 줄어든다.

결과 포맷

체크가 끝나면 다음과 같은 형식으로 결과를 출력한다.

## Preflight Check 결과
### Git 상태
- 브랜치: <이름>
...

'계속 진행 가능', '확인 필요'라는 이진(binary) 판정을 내리는 것이 포인트다. Claude가 스스로 '뭐, 괜찮겠지'라며 모호하게 판단하는 것이 아니라, 체크 항목에 비추어 기계적으로 Yes/No를 내놓는다. '확인 필요'인 경우에는 무엇이 걸려 있는지와 대처법까지 세트로 제시하므로, 사용자는 무엇을 승인할지 구체적으로 판단할 수 있다.

나쁜 예 / 좋은 예

# 나쁜 예
사용자: "5개 파일 리팩토링해서 커밋해줘"
Claude: (전제를 확인하지 않고) 수정 → git add . → git commit
...

「파괴적 조작의 사전 확인」 원칙과의 관계

글로벌 운영 규칙에는 "파일·데이터 삭제 전에 삭제 대상 목록과 이유를 제시하여 사용자의 승인을 얻을 것", "조작은 가역적(reversible)으로 하여 복구 경로를 확보할 것"이라는 원칙이 있다. preflight-check는 이 원칙을 절차화한 것에 해당한다.

원칙만 있으면 "삭제 대상 목록을 제시한다"라는 해석이 세션마다 흔들릴 수 있다. 무엇을 목록화할지, 어디까지 확인하면 충분할지를 Claude 자신의 재량에 맡겨버리게 된다. preflight-check는 "Git 상태", "스코프", "기밀 정보"라는 3가지 항목으로 고정하고 결과 포맷까지 통일함으로써, 매번 동일한 입도의 확인을 강제한다. 원칙이 무엇을 해야 하는지를 정의한다면, 스킬은 그것을 어떻게 매번 같은 형태로 실행할지를 담당하는 관계다.

시스템 프롬프트의 "파괴적 조작 전에 git status를 실행한다"라는 원칙도 마찬가지로, preflight-check를 통해 발화 조건, 체크 항목, 출력 포맷까지 구체화되어 자동화되어 있다. 원칙만 있다면 실행 여부가 매 세션의 기분에 좌우될 수 있지만, 스킬화함으로써 재현성 있는 절차로 변한다.

요약

• preflight-check는 Git 조작, 5개 이상의 파일 변경, "확인하고 진행해"라는 한마디로 발화하며, 읽기 전용 쿼리나 단일 파일 편집에는 사용하지 않는다. 체크 항목은 Git 상태, 스코프, 기밀 정보의 3개 계통이다. 판정은 '계속 진행 가능/확인 필요'의 이진 값으로 제시한다.
• allowed-tools가 Bash(git *), Read, Glob으로만 제한되어 있기 때문에, 구조적으로 "확인은 하지만 변경은 하지 않는" 설계로 되어 있다. "파괴적 조작의 사전 확인"이라는 원칙을 매번 동일한 체크 항목과 동일한 출력 포맷으로 실행하는 절차로 구현한 것이 이 스킬이다.

이러한 원칙을 스킬로 녹여내는 설계나 다른 하네스(harness) 요소와의 조합 방법은 유료 도서에서 더욱 체계적으로 다루고 있다.

좋아요와 댓글로 반응해 주시면 큰 힘이 됩니다!

Discussion