「섹션을 추가해줘」라고 부탁했더니 상태 파일이 통째로 사라졌다——Claude Code의 Write 툴이 Edit 대신 선택되어, git 관리

Claude Code에 「이 메모에 섹션을 하나 추가해줘」라고 부탁했을 뿐인데, 오랫동안 키워온 상태 파일이 통째로, 흔적도 없이 사라진다. 게다가 툴은 「성공했습니다」라고 보고하며, git에도 남지 않는다. 실제로 일어나고 있는 사고입니다.

Issue #67917에서 보고자는 STATE.md (세션을 넘나들며 운용 기록을 남기기 위해 스스로 git 관리에서 제외해 두었던 계속용 장부)를 이틀 사이에 두 번, 이 경로로 잃었습니다. 보고자는 macOS, Claude Code는 2.1.173 버전에서의 보고입니다.

이 기사는 그 기구를 정리하고, 왜 평소의 git 운용으로는 방어할 수 없는지, 그리고 이용자 측에서 지금 바로 할 수 있는 방지법까지 정리합니다. 데이터 소실 중에서도 기존의 방어책이 빠져나갈 수 있는, 질 나쁜 유형입니다.

Claude Code의 Write 툴은 파일의 내용을 통째로 다시 쓰는 (Write) 도구입니다. 「추가하기」라는 모드는 없습니다. 지정한 내용으로 파일 전체를 교체합니다.

보통 기존 파일의 일부를 수정할 때는 Edit 툴(대상 문자열만 교체하는 외과 수술 같은 도구)이 선택됩니다. 그런데 상황에 따라 모델이 「섹션을 추가해줘」라는 지시에 대해 Write를 선택할 때가 있습니다. 이때 Write에 전달되는 것은 모델이 머릿속에서 다시 구성한 「새로운 파일의 전체 내용」입니다.

여기서 두 가지가 겹치면 사고가 됩니다.

• 모델이 원래 파일의 전문을 정확하게 유지하지 못함 (긴 파일, 문맥의 중간, 요약된 상태 등).
• 그럼에도 Write가 그 「다시 구성한 불완전한 전체」로 파일을 통째로 덮어씀.

결과적으로 「한 섹션을 추가하려 했을 뿐」인데, 원래의 수백 줄이 사라지고 모델이 기억하고 있던 단편만 남게 됩니다. Write는 성공을 반환하고, 모델도 지울 의도가 없었기에 아무도 눈치채지 못합니다. 조용하고 즉각적인 전체 소실입니다.

데이터 소실 관련 기사를 많이 읽은 사람이라면 「git으로 자주 커밋해 두었다면 되돌릴 수 있다」고 생각할지도 모릅니다. 이 유형에서는 그것이 통하지 않습니다.

사고를 당하기 쉬운 것은 바로 STATE.md와 같이 의도적으로 git 관리에서 제외한 파일이기 때문입니다.

• 세션을 넘나들며 운용 상황을 적어두는 장부
• .gitignore에 넣어둔 작업 중인 메모 - 인증 정보는 포함하지 않지만, 커밋 히스토리에 섞고 싶지 않은 운용 기록

이러한 파일은 「git의 추적 대상으로 하지 않겠다」고 스스로 결정했기 때문에, git checkout으로도 git reflog로도 되돌릴 수 없습니다. git을 성실하게 운용하는 사람일수록 「추적하지 않기로 결정한 파일」에는 git의 안전망이 애초에 쳐져 있지 않다는 맹점에 빠집니다. rm -rf나 git reset --hard와 같이 눈에 띄게 위험한 명령과는 다릅니다. 방아쇠는 「섹션을 추가해줘」라는, 가장 무해해 보이는 일상적인 지시입니다.

다음 중 하나라도 해당한다면 이 사고의 사정거리 안에 있습니다.

• 세션을 넘나드는 상태나 운용 기록을 하나의 파일 (STATE.md, NOTES.md, progress.md 등)로 키우고 있다.
• 그 파일을 의도적으로 git 관리에서 제외하고 있다 (.gitignore에 넣었거나 리포지토리 외부에 두고 있다).
• 그 파일에 대해 Claude Code에게 「추가해줘」, 「섹션을 더해줘」라고 부탁하는 경우가 있다.

이 세 가지가 갖춰지면 Write의 전체 치환이 되돌릴 수 없는 소실로 직결됩니다.

제공 측의 동작이 바뀌기를 기다리기 전에, 이용자 측에서 지금 바로 자위할 수 있습니다. 이슈 보고자 본인이 두 번째 피해를 입은 뒤 구현한 방향과 같습니다.

지키고 싶은 파일 목록을 정하고, Write가 해당 파일에 대해 호출되면 실행 전에 멈춥니다. PreToolUse 훅(hook)은 툴이 실행되기 전에 호출되며, 종료 코드 2로 실행을 차단할 수 있습니다.

#!/bin/bash
# protect-write.sh — 보호 대상 파일에 대한 Write를 차단함
# settings.json의 PreToolUse에 matcher "Write"로 등록함
...

settings.json에 등록하는 형식은 다음과 같습니다.

{
  "hooks": {
    "PreToolUse": [
      ...

이로써 보호 대상 파일에 Write (전체 치환)가 실행되려 하면, 실행 전에 중단됩니다. 내용을 추가하고 싶을 때는 Edit를 사용하거나, 일단 보호를 해제한 후 수정해야 합니다.

이 hook은 Write라는 **도구 (Tool)**에 적용됩니다. Write가 선택되는 경로의 사고(#67917의 본론)는 막을 수 있지만, 셸 (Shell)을 통한 덮어쓰기는 막을 수 없습니다. > STATE.md, tee STATE.md, mv tmp STATE.md, sed -i, 히어 도큐먼트(cat > STATE.md <<EOF)는 Bash 도구를 통하므로, Write를 감시하는 이 hook의 대상에서 제외됩니다. 궁극적으로 도구에도, OS에도, 철자에도 좌우되지 않는 확실한 방어는 파일 그 자체에 "보호 대상"임을 선언할 수 있는 제공 측의 메커니즘이며, #67917에서는 바로 그것을 요구하는 논의가 이어지고 있습니다.

또한, 위의 수동 hook을 직접 구성하지 않더라도, 무료 안전 hook 모음인 cc-safe-setup에는 이를 담당하는 유지보수된 hook인 core-file-protect-guard.sh가 이미 포함되어 있습니다. 환경 변수 CC_PROTECTED_FILES에 보호하고 싶은 파일의 패턴(예: *state*:*STATE*:*progress*)을 나열하면, 해당 패턴의 파일에 대한 Edit · Write 실행을 직전에 중단하며, 나아가 Bash의 sed -i · awk -i를 통한 덮어쓰기도 중단합니다 (수동으로 만든 Write 전용 hook보다 한 단계 더 넓은 범위입니다). 다만 > STATE.md · tee · mv · 히어 도큐먼트까지는 추적할 수 없습니다. 보호 대상으로 지정한 파일은 Claude로부터의 편집이 모두 중단되므로, 수정할 때는 일단 보호 패턴에서 제외해야 합니다. 한 단계 더 탐지망을 넓힙니다. 보호 대상 파일의 행 수나 바이트 수를 기록해 두었다가, SessionStart hook에서 이전보다 급격히 줄어들어 있다면 경고를 보냅니다. 만일 감시망을 뚫더라도, 알아차리기 전에 덮어쓰기가 누적되는 것을 방지할 수 있습니다.

macOS의 기본 파일 시스템(APFS)은 대소문자를 구분하지 않습니다. STATE.md와 state.md는 동일한 파일을 가리킵니다. 보호 판정 시 대소문자를 그대로 비교하면, 한쪽의 철자로 인해 검사를 통과해 버립니다. 위의 hook처럼 소문자로 통일한 후 비교해 주세요.

• Write는 "추가"가 아니라 "통째로 치환". 긴 파일에 대한 "섹션 추가"가 전체 소실로 변할 수 있음. - 표적이 되기 쉬운 것은 의도적으로 git 관리에서 제외한 상태 파일. git의 안전망이 원리적으로 작동하지 않음.
• PreToolUse hook으로 보호 대상에 대한 Write를 막고, SessionStart에서 크기 감소를 감시함. macOS에서는 대소문자를 통일하여 비교함.

이 기사의 메커니즘은 이슈 #67917의 보고(macOS · 2.1.173 · 두 번의 실제 피해와 보고자 본인이 구현한 자위책)와, Write 도구가 전체 치환이라는 사양에 기반하여 작성되었습니다. 해당 이슈는 현재 enhancement로 취급되고 있으며, 제공 측의 대응은 앞으로 이루어질 예정이지만, 이용자 측에서는 위의 hook을 통해 지금 바로 예방할 수 있습니다. 저의 검증 환경은 Linux이며, macOS APFS의 대소문자 동작 자체는 직접 재현하지 않았습니다. 확인된 사실과 확인되지 않은 범위를 나누어 작성했습니다.

무료 안전 hook 모음인 cc-safe-setup(MIT)에는 rm -rf, git reset --hard, Windows의 파괴적인 명령어 등 눈에 띄게 위험한 조작을 실행 전에 막는 hook이 약 800개 준비되어 있습니다. 위의 Write 보호 hook은 이와 동일한 PreToolUse 메커니즘을 사용하며, 자신의 운영 방식에 맞춰 추가할 수 있습니다.

"섹션을 추가해줘"가 전체 소실로 변하는 이 유형처럼, Claude Code의 사고는 위험한 명령어 목록을 차단하는 것만으로는 방지할 수 없는 암묵적인 경로에서 발생합니다. 데이터 소실 · 폭주 · 무단 과금 · 파괴적인 조작을 "중단하기 · 지키기 · 되돌리기"의 3단계로, 증상별로 정리하여 해결책을 제시하는 전자책을 출간했습니다. Claude Code 사고 방지 가이드 (¥800 · Zenn). 실제 발생한 사고의 이슈를 1차 자료로 사용했습니다. 제3장까지는 무료로 읽을 수 있습니다.

매달 발생하는 새로운 사고와 사양 변경을 실기(実機)로 검증하여 정리한 월간 소식지도 있습니다(Claude Code 안전 운용 소식 · ¥500 · 첫 달 무료). 책이 「변하지 않는 지침서」라면, 소식지는 「그 달의 운용」입니다.

사실에 기반하여 작성하고 있습니다. 과장이나 확인되지 않은 단정은 피하고 있습니다. 오류를 발견하시면 댓글로 알려주세요. 수정하겠습니다.