# 클루드 코드의 훅으로 “CLAUDE.md에 작성하더라도 적용되지 않는 사항을 중단한다”를 막는다

> https://bookfactory.kr/c/ai-tech/9714
> 게시판: AI·머신러닝
> 작성자: admin
> 작성일: 2026-08-15T11:42:21.736Z

---

![見出し画像](https://assets.st-note.com/production/uploads/images/303726343/rectangle_large_type_2_773749515ebe8212ec388fdc24d8c320.png?width=1280)

클루드 코드에 “이렇게 해줬으면 좋겠어”라고 전달하는 곳은 보통 CLAUDE.md입니다. 저희도 거기에 기록하고 있습니다.

단지 써놓는 것만으로는 지켜지지 않는 일이 있다.

최근에 그 일로, AI 직원 지시서 6부가 모두 망가졌습니다. 이 글에서는 그 사고의 내용과 같은 날 hooks로 멈추는 부분까지 설명합니다. CLAUDE.md에 작성했는데 제대로 지켜지지 않아 어려움을 겪고 있는 사람들에게는 그대로 사용할 수 있는 내용일 것입니다.

여기에서 다루는 환경 설정 방법은 교과서와 템플릿을 모아서 배포하고 있으며, 마지막에 링크를 첨부합니다.

## 무슨 일이 일어났는지

저희에서는 Claude Code 세션을 항상 8개 정도 병렬로 실행하고 있습니다. 담당이 분기되기 때문입니다.

어느 날 밤늦게, 제가 note의 공장(기사를 쓰는 AI 직원)을 만들어내고 있었습니다. 지시서, 지식, 규격표를 2시부터 3시까지 여러 번 수정하고 있었습니다.

그 날 14시 15분부터 15시 29분까지, 다른 세션이 같은 파일 그룹을 덮어썼습니다. 악의는 없었습니다. 그 세션이 쥐고 있던 것은 아침 시점의 버전으로, 이를 “최신”으로 덮어쓴 것뿐입니다.

찾아 헤매던 건 바로 이거예요.

- 상위 기사 102부를 분해하여 제시한 실제 측정값 표
- 실기에서 최종 확인된 제약 사항 목록 (무엇을 하면 고장 나는가)
- 개선 로그 (왜 그러한 설계를 했는지의 기록)

### 가장 힘든 점은 “움직이 버리는 것”입니다.

스크립트는 하나도 망가진 것이 없었습니다. 사라진 것은 설명뿐입니다.

그래서 다음 날 아침, 공장은 평소처럼 움직이고, 기사도 실{사}됩니다. 고장 났다는 것을 눈치채는 단서가 어디에도 없는 상태였습니다.

발견한 것은 우연한 일이었어. 단계를 한 줄 더 옮기려다 치환의 대상이 발견되지 않아 오류가 발생했어. 그래서 처음으로 내용을 확인해 보니, 삭제된 것이라는 것을 알게 되었어.

![画像](https://assets.st-note.com/img/1786791062-ol3Ht9Ne8dg07QjpRWYIGkcF.png?width=1200)

## 복구할 수 없었던 진짜 이유

Git으로 되돌아가면 됩니다. 저도 그렇게 생각했습니다.

돌려줄 수 없었습니다. 이유는 두 가지입니다.

- 이 롤은 한 번도 커밋되지 않았습니다 (git status에서 미추적 상태로 남아있음).
- 더욱 조사해 보니, .git/index.lock이 29시간 동안 남아 있었다.

세 번째가 본명이었어요. 락이 남아있으면 Git 커밋이 전부 꼬여버려요. 즉, 그 29시간 동안 어떤 세션도 커밋할 수 없었던 거죠. 마지막 커밋은 전날 오전에서 멈춰 있었어요.

아무도 알아채지 못해. 커밋이 실패해도 작업 자체는 계속된다.

결국, 기억과 일기에서 손으로 직접 다시 썼습니다.

## 클로드 코드 훅으로 중단

CLAUDE.md에 “기존의 지시서는 ‘Write’가 아닌 ‘Edit’로 수정하는 것이”라고 덧붙였다. 실제로 그렇게 작성했다.

단지 그것만으로는 같은 일이 발생합니다. CLAUDE.md는 읽히지 않을 수도 있으며, 읽더라도 다른 세션이 오래된 버전을 가지고 있었다면 의미가 없습니다.

그러고 나서 PreToolUse 훅을 만들었습니다. Claude Code가 Write나 Edit를 실행하기 직전에 끼어드는 훅입니다.

할 일은 두 가지로 줄였습니다.

### 글을 쓰기 직전에 반드시 회피한다 (이것이 진짜 본심이다).

지시서를 수정하기 직전에 해당 시점의 파일을 워크스페이스 밖으로 복사합니다.

이 블록보다 훨씬 효과적입니다. 이번 사고도, 대피만 있었다면 손으로 다시 쓰지 않아도 되었을 것입니다.

Git을 오염시키지 않기 위해 업무 공간 바깥에 저장 위치를 두었습니다. 퇴치된 파일이 차이점에 나타나면 오히려 방해가 됩니다.

### 명백히 파괴적인 방식만 중단하도록

여기서 판단을 한 번 잘못 지을 뻔했습니다.

우리 집에는 먼저 만들었던 기록용 행거가 있어서, 그곳은 “파일을 50% 미만으로 압축”을 지시합니다. 같은 조건을 사용하면 된다고 생각했는데, 이번 사고는 151행 → 85행 = 56%입니다.

50% 규칙으로는 멈출 수 없습니다.

그러므로, 실제 巻き戻し가 무엇을 했는지 확인하고 조건들을 더했습니다.

- 대제목이 2개 이상 삭제됨. Write(오래된 버전의 수정은 거의 반드시 이렇게 됨)
- 표의 행이 3행 이상 삭제됩니다. (개선 로그나 대장은 늘어나는 것이 줄어드는 것이 아닙니다.)
- 50% 미만으로 줄이고 원래 조건을 유지

![画像](https://assets.st-note.com/img/1786791065-bAu2TKZy4DsxN6S0fdje1JoX.png?width=1200)

### 부분 편집(Edit)은 멈추지 않는다.

정당한 축소 작업은 있습니다. 정리, 통합, 오기 삭제 등이 있습니다. 그것까지 멈추면 낚싯줄을 우회하는 습관이 생겨 버릴 정도로 위험합니다.

그러므로 Write만을 검토하는 데 집중했습니다. 기존 파일을 완전히 대체하는 작업만을 대상으로 합니다.

## 시연 직후에 효과가 나타났다.

잠시 후, 파일을 옮긴 후 퇴비 폴더를 확인했습니다.

제가 만져보지 못한 롤 파일이 이미 삭제되어 있었습니다. 다른 세션이 작성한 내용으로 덮어씌워진 것이었습니다.

이것이 확인된 사실은 꽤 의미 있었다. 훅이 ‘들었다고 생각했는데’ 제대로 작동하지 않는 경우가 있어, 다른 사람의 글이 실제로 삭제되었는지라는 사실이 작동의 증거가 된다.

자체 테스트도 작성했는데, 24개 중 24개에 통과되었습니다. 테스트에는 이번 사고의 재현(56% 축소 + 제목 3개 소멸)을 포함시켰습니다. 이게 멈추지 않으면, 훅을 만든 의미가 없기 때문입니다.

## 저희가 사용하고 있는 훅(hooks)과 그 역할들.

훅(Hooks)은 침투 위치가 여러 종류가 있습니다. 용도가 명확하게 분리되므로, 저희에서 실제로 사용 중인 것을 역할에 따라 분류합니다.

### 글을 쓰기 직전에 개입하다

이번에 만든 것은 이것입니다. Write나 Edit가 실행되기 전에 호출되므로, 오류가 발생하기 전에 안전하게 종료할 수 있다는 것이 강점입니다. 중단 판단도 여기서 합니다.

같은 장소에서 일기가 완전히 덮어지는 것을 막는 훅도 작동하고 있습니다. 이전에 병렬 세션에서 “새로 작성하려는 의도로” 그 날의 일기를 Write 하여 1,450행의 기록이 24행으로 줄어든 사례를 바탕으로 제작되었습니다. 이번 지시서 사고 역시 완전히 동일한 형태입니다.

### 작업 종료 시에 방해하다 (Stop)

끝내려고 하던 순간에 불려나옵니다. 저희 집에는 두 개를 사용하고 있습니다.

- 결과물을 만들었지만 열어보지 않고 멈추게 하는 것을 방지한다.
- 그 날의 기록을 쓰지 않으면 멈추게 된다 (무엇을 했는지 남기지 않고 끝내지 않도록).

둘 다 “했었다고 생각하는” 마음을 버는 데 도움이 됩니다. 사람은 기억할 필요가 없어집니다.

### 세션 시작에 개입

세션이 시작될 때 호출됩니다. 저희에서는 진행 중인 사건들의 목록을 전달하고 있습니다. 새로운 세션은 갑자기 이전 내용부터 바로 시작되는 상태가 됩니다.

### 입력할 때마다 방해한다

이것은 메시지를 받을 때마다 호출됩니다. 저희에서는 “이 단어가 나타나면 이 절차서를 먼저 읽는다”는 방식으로 사전을 참고하고 있습니다.

이 4가지 기능이 서로 다르므로, 지켜야 할 목표에 따라 장소를 선택하는 것이 빠릅니다. “고장 전에 중단하고 싶다면” PreToolUse, “실수를 하지 않도록 막고 싶다면” Stop, 이런 식으로.

## 구현 시 유의 사항

훅을 쓸 때, 저희가 지키고 있는 규칙이 3가지 있습니다.

- 훅 스스로의 실수로 작업을 멈추지 않으며(판정에 실패하면 그냥 넘어가도 된다). 보호를 위한 메커니즘이 원인으로 되어 손이 멈추는 것이 가장 본말이 전도된다.
- 마칠 때는 다음에 무엇을 해야 할지까지 제시한다 (“편집 기능을 사용하거나”, “먼저 현재 내용을 다시 읽어보는”)
- 감시 범위를 축소한다. 수정 가능한 결과물이나 타인의 원고, 개인 정보가 있는 장소는 대상에서 제외했다.

## まとめ

- CLAUDE.md에만 의존하는 것은 보장되지 않는다. 읽히지 않을 수도 있고, 다른 세션이 오래된 버전을 가지고 있다면 효과가 없을 수도 있다.
- 훅스의 본명은 블록이 아닌 회피였다. 부서져도 바로 전의 모습이 반드시 남아 있었다.
- 임계값을 재활용하지 않는다. 기존 훅 조건(50%)으로는 이번에 56%가 멈추지 않았다. 실제 사고가 무엇을 했는지 확인하여 조건을 결정한다.
- 넣어보니 다른 사람의 글이 회피되는 곳까지 확인해 보았다.

### 훅이 실제로 작동하는지 확인하는 방법

넣었는데 효과가 없다는 경우는 흔합니다. 저희가 보는 것은 이 세 가지입니다.

- 의도적으로 걸려 넘어뜨려 (자기 테스트에 사고 재현을 포함하는)
- 다른 사람의 글에 대한 답변이 회피되고 있는지 확인하고 (자신의 조작만으로는 우연히 지나갔을 가능성이 남아있을 수 있습니다).
- 멈춘 직후의 메시지를 읽고, 어떤 근거로 멈췄는지에 대한 설명이 없는 훅은 결국 우회될 것이다.

Git에 통합하는 작업도 함께 진행했습니다. 하지만, 로컬 충돌이 남아있어 커밋할 수 없는 상태가 29시간 지속되다 보니, Git에 의존한다면 그 상태를 확인하지 않으면 안 된다는 것이 이번에 얻은 가장 큰 교훈이었습니다.

### 이 기사의 환경을 그대로 조성할 수 있는 교재를 제공하고 있습니다.

![画像](https://assets.st-note.com/img/1786791068-1bMdOKt3Xa2Qi0LT75NmJGxS.png?width=1200)

저희도 병행으로 진행하고 싶고, ‘CLAUDE.md’와 ‘메모리’ 설계에 대한 정보를 얻고 싶어 하시는 분들을 위해 ClaudeCodeStudio의 6가지 특별 혜택을 준비했습니다.

- 클로드 코덱스(전 6장) — 설치부터 CLAUDE.md, 스킬, 메모리, 운영 규칙, 첫 AI 직원 출시까지
- 기억 Vault 템플릿 (Zip) — MEMORY.md, 규칙, 기술, 지식 저장소를 처음부터 전부 배치한 Obsidian Vault
- AI 부서 7가지 역할 프롬프트 모음 — CEO 및 6개 부서 구축 프롬프트

이 프롬프트 모음은 AI 부서의 효율적인 운영을 위한 다양한 역할을 수행하는 7가지 프롬프트를 제공합니다. CEO와 6개 부서 구축을 위한 프롬프트로 구성되어 있으며, 복사 붙여넣기를 통해 쉽게 활용할 수 있도록 제작되었습니다.
- 또한, 세미나 아카이브(총 4시간)・Obsidian 교과서・세트업 영상 7편

받는 방법은 이메일에 내용을 담아 공식 LINE에 암호를 보내시면 됩니다.

ClaudeCodeStudio 6가지 특별 선물 세트를 받으세요!

*   무라카미 하루키의 작품을 활용한 특별 챌린지
*   카호 주연의 영화를 기반으로 한 코딩 프로젝트
*   파이썬을 이용한 창작 도구 튜토리얼
*   자바스크립트를 활용한 웹 개발 실습
*   C++을 이용한 알고리즘 문제 풀이
*   데이터 분석 기초 강의 (데이터 시각화 포함)

지금 바로 ClaudeCodeStudio에 가입하고 6가지 선물 세트를 받아보세요!

**출처:** [note 원문](https://note.com/claudecodestudio/n/nec1b44e77a4d)

*번역: Gemma 3(.44) 초벌 + 교정 61청크*

[원문 보기](https://note.com/claudecodestudio/n/nec1b44e77a4d) | 출처: note.com