규칙 문서에 「주의한다」가 스며드는 순간

CLAUDE.md나 docs/rules/를 리뷰하다가, 이런 문장을 마주친 적이 없으신가요?

파일 삭제 시에는 의존성 부분도 함께 수정하도록

주의한다.

동명의 세션이 병행되지 않도록

주의한다.

운영 환경 반영 후에는

가능한 한 빨리 동작 확인을 수행한다.

쓴 본인은 「재발 방지책을 하나 쌓았다」고 생각합니다. 리뷰도 통과합니다. CLAUDE.md의 행수는 늘어갑니다.

하지만 이런 행들은 쓰는 순간 지켜지지 않게 됩니다. 지난 기사(Claude가 instructions를 무시하는 감각은 옳다)에서 「물리 가드 (Physical Guard)」라는 개념을 소개했습니다만, 이번에는 그 첫 번째 — 「주의한다(気をつける)」「주의한다(注意する)」「가능한 한(できるだけ)」을 물리적으로 쓸 수 없게 만드는 pre-commit hook — 을 5분 만에 도입할 수 있는 형태로 작성하겠습니다.

왜 「주의한다」가 규칙을 무효화하는가

「주의한다」는 동작을 동반하지 않는 동사입니다. 쓴 사람도 읽는 사람도, 「구체적으로 무엇을 언제 어떻게 할지」를 정하지 않고 대화를 끝낼 수 있습니다.

사람이 읽으면 「중요한 부분이구나」라고 인식합니다. 하지만 「주의한다」의 내용을 매번 수동으로 전개할 수 있는 사람은 실재하지 않습니다. 다음 주에는 이미 잊어버리고 있습니다.

LLM이 읽으면 훨씬 더 명확하게 망가집니다. Claude는 「주의한다」를 해당 부분에 『주의함』 플래그를 세우고 완료한 것으로 처리합니다. 「의존성 부분도 함께 수정하도록 주의한다」라고 적혀 있으면, 의존성 부분을 grep 하지 않고 「주의했습니다」라고 답해옵니다. 판단의 정밀도를 높이는 주문이 아니라, 단순한 체크박스로서 소비됩니다.

결과적으로 규칙은 「쓴 사람의 자기만족」이 됩니다. 발화 횟수 0 · 우회 (bypass) 횟수 0 · 효과 측정 불가능. 쓰지 않은 것과 다름없는 상태입니다.

대표적인 「무효화 동사」를 정리하면 다음과 같습니다.

공통점은 "주어가 누구이며, 언제, 어디까지 해야 완료인가"가 결정되지 않는다는 점입니다. 이는 물리 가드와 정반대의 발상으로, 쓰는 순간 운용이 파탄 납니다.

물리적으로 쓸 수 없게 하는 구현 (복사 붙여넣기로 동작)

pre-commit hook으로 .md 파일의 추가된 행을 스캔하여, 무효화 동사가 포함되어 있으면 커밋을 거부(reject)합니다. 다음 스크립트를 guards/commit/check-soft-language.sh에 저장해 주세요.

#!/usr/bin/env bash
# 목적: 「주의한다」 등의 소프트 언어를 검출하여 커밋을 차단
# 근거: 소프트 언어는 쓰는 순간 대책이 완료되었다고 착각하게 만들어, 물리 가드가 배치되지 않음
...

이 스크립트를 「효과가 있게 만들기」 위한 포인트가 5가지 있습니다.

• 에러 처리 — 미정의 변수를 즉시 에러로 만듭니다. set -u를 사용하여 PATTERN을 오타(typo) 냈을 때 「검출되지 않은 채 PASS」하는 사고를 물리적으로 방지합니다.
• 탈출구 (Bypass) — 탈출구가 없으면 운용이 돌아가지 않습니다. 인용이나 설명문에서 의도적으로 「주의한다」를 쓰고 싶은 상황은 반드시 발생합니다. ALLOW_SOFT_LANGUAGE=1이라는 bypass 탈출구를 처음부터 제공하지 않으면, 가드 자체가 무효화(hook 삭제)됩니다.
• 대상 제한 — 추가 / 변경된 파일만 대상으로 합니다. 기존 문서는 검사하지 않습니다 (가드 도입 시 대량의 reject가 발생하지 않도록) --diff-filter=AM을 사용합니다.
• 범위 제한 — diff의 추가된 행만 대상으로 합니다 (grep -E "^\+[^+]"를 사용하여 +++ 헤더를 제외). 기존 행의 소프트 언어는 건드리지 않고, 새로 도입하려는 부분만 막는 설계입니다.
• 실패 시 — pre-commit hook은 이 exit code로 커밋 자체를 reject 합니다. 「경고만 내보내는」 설계는 무의미합니다 (그냥 읽고 지나치기 때문). exit 1

pre-commit hook 설치

3개의 명령어로 끝납니다.

# 1. 스크립트 배치
mkdir -p guards/commit
# (위 스크립트를 guards/commit/check-soft-language.sh 로 저장)
...

첫 번째 reject(거절)를 경험하기까지 5분 남았습니다. reject를 당하면 README.md의 차분(diff)을 버리고, 쓰고 싶었던 내용을 물리적 가드(Physical Guard)로 대체하는 것이 본래의 흐름입니다. "앞으로는 주의해서 쓰겠습니다"라고 쓰고 싶어진 순간은, 그것이 pre-commit이나 CI에서 검출해야 할 패턴을 발견한 순간이기도 합니다.

가드를 너무 늘리지 않기 위한 채택 기준

"효과가 있다"고 느끼면 비슷한 가드를 차례차례 추가하고 싶어집니다. 하지만 물리적 가드를 너무 늘리면, 자신의 리포지토리(Repository)에서 개발할 수 없는 상태가 됩니다. 커밋(Commit) 한 번에 10종류의 hook이 실행되고, 커맨드 라인(Command line)은 bypass(우회) 플래그로 가득 차며, 결국 전부 --no-verify로 우회되는 모습이 눈에 선합니다.

새로운 가드를 추가하기 전에, 다음 4개 항목을 모두 ✅로 만든 후에 채택하십시오. 하나라도 No라면 아직 채택할 타이밍이 아닙니다.

• 위반했을 때 어느 라인에서 물리적으로 멈추는지 말할 수 있는가? ─ "pre-commit hook에서 reject 된다", "CI workflow가 exit 1로 종료된다" 등, 멈추는 장소를 한 줄로 설명할 수 있어야 함
• 그 물리적 게이트는 Claude가 CLAUDE.md를 읽지 않아도 작동하는가? ─ 규칙 문서에 기재하는 것을 전제로 하는 가드는 "물리적"인 것이 아니라 단순한 소프트 규율(Soft discipline)임
• bypass(우회) 절차가 명시되어 있는가? ─ ALLOW_*=1과 같은 환경 변수 기반의 탈출구를 에러 메시지 자체에 적어둘 것
• 효과를 수치로 측정할 수 있는가? ─ 발화 횟수, bypass 횟수, false positive(오탐) 횟수를 주 단위로 관측할 수 있을 것

더불어, 3개월 동안 사용하여 발화 횟수가 0인 가드는 삭제하십시오. "만일을 위해"라는 이유만 있는 가드는 리포지토리의 운용성만 떨어뜨릴 뿐입니다. 물리적 가드는 "효과가 있다는 증거"를 계속 제시하지 못하면 정리 대상입니다.

요약 및 다음 기사

이 스크립트로 방지할 수 있는 것은 "소프트 언어를 포함한 신규 commit"뿐입니다. 기존 문서에 이미 섞여 있는 "주의한다", "조심한다" 등은 별도의 태스크로 grep 하여 찾아내야 합니다 (grep -rnE '気をつけ|注意する|できるだけ' docs/를 한 번 실행하면 정리 목록을 얻을 수 있습니다).

"주의한다"를 쓰지 못하게 만드는 것만으로도 규칙 문서의 질은 명확히 올라갑니다. 쓰려고 하는 순간 reject 되기 때문에, 쓰는 사람이 "이것은 구체적으로 어떤 행동을 의미하는가?"를 생각할 수밖에 없게 만드는 것이 이 가드의 가장 큰 효과입니다. 텍스트로 지키게 하는 것이 아니라, 쓰는 사람의 사고 프로세스(Thought process)를 바꾸어 버리는 것 ─ 그것이 물리적 가드의 흥미로운 점입니다.

다음 기사에서는 **병행 세션 문제(Parallel session problem)**를 다룹니다. 여러 개의 Claude 세션이 동일한 파일을 동시에 편집하여 한쪽의 변경 사항이 다른 쪽에 덮어씌워지는 사고를, WORKING.md + check-concurrent-sessions.sh로 물리적 차단하는 운영 설계에 대해 알아봅니다.

• 물리적 가드 최소 세트 (무료 · MIT): https://github.com/naoya643/claude-code-os
• 풀 키트 (가드 일체 + 30건의 실제 실패 기록): BOOTH에서 구매

자신의 프로젝트에 적용해보고 "이 부분이 효과가 있었다 / 여기에 허점이 있었다"와 같은 피드백이 있다면, GitHub Issues나 X를 통해 알려주시면 감사하겠습니다. 타인의 reject 사례는 가드 본체보다 가치가 있습니다 (다음에 같은 함정에 빠질 사람을 한 발 앞서 구할 수 있기 때문입니다).