차단만 하면 같은 시도가 반복된다 — Rules·Hooks·Skills 3계층과 차단 규칙 7종

"AI가 안전하게 일하는 틀을 만들었다"는 문장은 그 자체로는 아무것도 말하지 않는다. 무엇이 그 틀을 강제하는지, 강제가 실패했을 때 무엇이 남는지가 빠져 있기 때문이다.

이 시리즈는 그 추상적 표현을 읽는 규범 / 막는 강제 / 반복되는 절차 세 계층의 실제 파일로 환원한 원 자료 한 벌을 네 편에 걸쳐 옮긴다. 첫 편인 이 글이 통제 계층 전체를 다루고, 나머지 세 편이 그 위에서 돌아가는 작업과 운영을 맡는다.

이 글에서 가장 오래 남는 관찰을 먼저 적어 둔다. 세 계층을 나란히 놓은 비교표에서 「강제력」 열이 「있음」이 되는 칸은 하나뿐이다. 나머지 둘은 모델이 지키기로 선택해야 작동한다. 그리고 그 하나뿐인 강제 계층조차 차단만 하고 대안을 돌려주지 않으면 같은 시도가 반복된다 — 원 자료가 훅 예제의 설계 요점으로 든 것이 바로 그 지점이다.

이 글이 옮긴 원 자료의 작성 기준일은 2026-07-26이다. 훅 이벤트 이름·종료코드 규약·설정 파일 위치는 그 시점의 것이며 버전에 따라 바뀐다.

아래의 Rules 5종·Hooks 5종·Skills 5종과 차단 규칙 7종은 원 자료가 제공한 예제 구현체이며, 이 글이 운영해 얻은 실적이 아니다. 가져갈 것은 계층을 어떻게 가르는가라는 판단 프레임이지 파일 목록 자체가 아니다.

용어 정리

시리즈 네 편이 공유하는 어휘다. 원 자료의 용어·약어 풀이 전량이며, 순서도 원 자료를 따랐다. 이어지는 세 편은 여기서 자기 글이 쓰는 행만 추려 다시 싣는다.

31개 행이고, 통제(Rules·Hooks·Skills·settings.json)·프롬프트(BLUF·SDD·Plan Mode)·디버깅(MRE·5-Why·git bisect)·DB와 인증(RLS·anon 키·PII)·성능과 배포(Smoke Test·Core Web Vitals)·회고(KPT·SPICED)까지 걸쳐 있다. 한 편이 다 쓰는 어휘가 아니라 시리즈 네 편의 합집합이라 이렇게 넓다.

이 시리즈가 다루는 자산

원 자료는 자기가 담고 있는 것을 세 계층으로 먼저 그려 둔다.

「15종」은 이 글이 아래에서 펼치는 Rules 5 + Hooks 5 + Skills 5의 합이다. 세어 보면 맞는다.

여덟 자산이 시리즈 어느 편으로 갔는지를 함께 적으면 이 표가 그대로 목차가 된다.

여덟 행 중 일곱은 한 편으로 떨어지고, 「프롬프트 패턴 가이드」 한 행만 세 곳으로 갈린다. 이 카테고리에 이미 발행된 글들이 그 내용의 상당 부분을 먼저 다뤘기 때문이다 — 4요소 프레임과 슬래시 커맨드·@ 파일 참조·파이프라인은 .claude 디렉터리가, 멀티턴 관리의 70% 룰과 컨텍스트 압축 흐름은 컨텍스트 예산이 다뤘다. 원 자료의 7패턴 중 남는 세 행(CLAUDE.md 컨텍스트 주입 · Plan Mode + SDD · 이미지 입력)과 안티패턴 5가지, 30초 응급처치 카드를 업종별 CLAUDE.md 템플릿 편이 잇는다. 한 칸에 링크 하나를 억지로 넣지 않고 이렇게 갈라 적는 것은 이 글의 정리다.

세 계층 — 규범·강제·절차

여섯 행 중 판단을 가르는 것은 「강제력」 한 행이다. 세 칸 중 「있음」은 Hooks 하나이고, 나머지 둘은 괄호 안에 각각 "모델의 준수에 의존" · "호출 여부는 모델 판단"이라고 적혀 있다.

한 문장 요약: Rules는 사규, Skills는 업무 매뉴얼, Hooks는 출입 게이트다.

사규는 어기면 지적당하지만 몸이 막히지 않는다. 게이트는 카드가 없으면 문이 열리지 않는다.

그래서 정말 사고를 막아야 하는 항목은 Rules가 아니라 Hooks에 둔다.

우선순위 — 좁은 범위가 이긴다

같은 규칙이 충돌하면 좁은 범위가 이긴다. 법령 → 시행령 → 사규 구조와 같다. 이 구조가 있어야 "전사 표준은 유지하되 팀별 예외는 허용"이 가능해진다.

이 카테고리의 CLAUDE.md의 4계층 Scope 편이 같은 원리를 네 계층으로 적었다 — 그 글은 "지시가 충돌하면 더 구체적인 Scope가 우선한다(서브디렉토리 > 프로젝트 > 전역)" 고 쓰고, 로드 자체는 override가 아니라 누적이라는 점을 함께 짚는다. 위 표의 3행과 그 글의 네 계층은 계층 수가 다르므로(여기는 3+1, 그쪽은 4) 같은 목록이 아니다. 겹치는 것은 충돌 시 좁은 쪽이 이긴다는 규칙 하나이며, 이렇게 한정해 읽는 것은 이 글의 정리다.

Rules 5종 — 규범 계층

다섯 파일의 통제 대상이 코드 형태 · 데이터 위치 · 응답 방식 · 관측성 · 보안 경계로 갈린다. 다만 축이 완전히 배타적이지는 않다 — logging.md의 「PII 자동 redact」와 그 위반 리스크(「로그에 PII가 평문 축적되어 2차 유출」)는 security.md가 맡은 데이터 노출과 같은 곳에서 만난다.

각 규칙의 대표 조항 상세

Hooks 5종 — 강제 계층

다섯 훅이 붙는 이벤트가 PreToolUse · PostToolUse · UserPromptSubmit · SessionEnd · SubagentStop으로 전부 다르다. 같은 이벤트에 둘이 붙는 자리가 없다.

훅 응답 규약

⚠️ 이 네 행 중 두 행이 stderr를 서로 다르게 말한다

표를 행 단위로 대조하면 stderr가 두 번 등장하고 서술이 갈린다.

• exit 2 행 — "차단. stderr 메시지가 모델에게 전달되어 이유를 알 수 있다"
• stderr 행 — "사람·로그용. 모델 컨텍스트에 주입되지 않는다"

조건부로 읽으면 양립한다. exit 2일 때에 한해 stderr가 전달되고 그 외에는 사람·로그용이라면 두 행이 부딪히지 않는다. 그러나 표가 그 조건을 어디에도 적지 않았다 — 위 네 행이 이 규약의 전부이고, 어느 셀에도 「exit 2인 경우」라는 한정어가 없다.

어느 쪽이 맞는지는 이 표의 네 행만으로는 판정되지 않는다. 다만 원 자료가 표 밖 본문에서 조건부 독해 쪽에 근거를 남겨 두었다 — 아래 「bash-pre-guard 핵심 로직」의 세 줄 요약이 "종료코드 2와 함께 대안을 stderr로 돌려준다" 고 적고, 곧이어 "차단만 하고 대안을 안 주면 모델은 같은 시도를 반복한다" 고 잇는다. 모델이 그 stderr를 읽는다는 전제가 없으면 뒤 문장이 성립하지 않는다. 표 안에서는 갈리고 표 밖에서는 조건부 독해 쪽에 근거가 있다 — 이렇게 갈라 읽는 것은 이 글의 정리다.

⚠️ 같은 카테고리의 다른 두 글도 이 채널을 서로 다르게 적었다

자료	차단 사유가 나가는 채널
settings.json과 훅의 2차 방어선	"exit 2가 차단의 핵심이다. 표준 에러로 출력한 메시지가 차단 사유로 전달된다."
커맨드·스킬·훅과 플러그인 번들	"훅은 이벤트 JSON을 stdin으로 받고, 결과를 stdout으로 돌려주는 양방향 통신 계약을 갖는다." — 차단 사유는 stdout JSON의 reason 필드로 나간다
이 글이 옮긴 원 자료	위 4행 표. exit 2 행은 stderr가 전달된다고 하고, stderr 행은 주입되지 않는다고 한다

두 번째 글은 이 불일치를 이미 자기 본문에 적어 두었다 — "두 자료가 서로 다른 채널을 들고 있으며 어느 쪽이 현재 사양인지는 두 자료 안에서 판정되지 않는다. 실제로 훅을 걸 때는 exit 2 직후의 출력 채널을 직접 확인한다."

이 글은 그 판정을 뒤집지 않는다. 세 자료를 나란히 놓으면 갈리는 자리가 하나 더 늘어날 뿐이고, 실무의 결론은 그 글이 적은 것과 같다 — exit 2 직후의 출력 채널을 자기 환경에서 직접 확인한다. 세 자료를 이렇게 나란히 놓는 것은 이 글의 정리다.

bash-pre-guard 핵심 로직 (발췌)

INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // ""')

if echo "$COMMAND" | grep -qE '\brm\s+-rf?\s+(/|/\*|\$HOME|~|--no-preserve-root)'; then
  echo "차단: 시스템 루트 또는 홈 디렉터리 전체 삭제 시도" >&2
  echo "대안: 명시적 경로를 지정하세요. 예: rm -rf ./build" >&2
  exit 2
fi

세 줄로 요약하면 — (1) 훅 입력 JSON에서 실제 명령을 꺼내고, (2) 정규식으로 위험 패턴을 판정하고, (3) 종료코드 2와 함께 대안을 stderr로 돌려준다. 차단만 하고 대안을 안 주면 모델은 같은 시도를 반복한다. "왜 막혔는지 + 무엇으로 대체하는지"를 함께 돌려주는 것이 이 훅의 설계 요점이다.

차단 규칙 7종

7번 항목이 특히 실무적이다. 파괴적 명령만 막는 훅은 흔하지만, **"확인해보려고 키를 출력하는 습관"**이 CI 로그에 영구 기록으로 남는 사고를 막는 규칙은 드물다. 게다가 완전 차단이 아니라 "앞 8자만 보라"는 대안을 제시해 디버깅 실무를 죽이지 않는다.

⚠️ 훅 표가 요약한 사고는 다섯인데 규칙은 일곱이다 — 하나씩 배정해 본다

앞의 Hooks 5종 표에서 bash-pre-guard.sh 행의 「차단·예방하는 사고」 칸은 다섯 항목을 나열한다 — "시스템 파괴·권한 상승·미검증 원격 코드 실행·메인 강제 푸시·시크릿 평문 출력". 바로 아래 차단 규칙 표는 일곱 행이다. 일곱을 다섯에 하나씩 배정하면 이렇게 된다.

일곱 행을 전수 배정한 결과 다섯이 대응하고 둘이 남았다. 4번과 6번을 남긴 근거는 문구 대조다.

• 4번의 사고는 「전역 권한 파괴」다. 2번의 「권한 상승」과 방향이 반대다 — 하나는 자기 권한을 올리는 것이고 다른 하나는 모두에게 여는 것이다. 같은 항목으로 묶을 근거가 두 셀 어디에도 없다.
• 6번의 사고는 「디스크 직접 쓰기」다. 1번의 「시스템·홈 디렉터리 전체 삭제」와 별개 행으로 적혀 있고, 요약 5항목의 「시스템 파괴」는 1번의 문구를 그대로 줄인 형태다.

차단 규칙 표 앞뒤에 붙은 산문 — 앞의 「bash-pre-guard 핵심 로직」 세 줄 요약과 뒤의 7번 항목 해설 — 은 어느 쪽도 다섯 항목과 일곱 규칙을 짝지어 적지 않는다. 이 배정은 이 글의 정리이며, 원 자료가 대응표를 제시한 것이 아니다.

훅 운영 규약

마지막 항목은 예제 훅들이 공통으로 쓰는 기법이다. 정리 작업을 매번 하지 않고 요일 == 일요일 && 시각 == 01시 같은 조건에서만 수행한다. 부수 작업이 주 경로를 느리게 만들지 않게 하는 설계로, 훅 도입 후 체감 지연이 생기는 가장 흔한 원인을 미리 제거한다.

Skills 5종 — 절차 계층

Skill 설계에서 배울 점 3가지

첫 행은 이 카테고리의 커맨드·스킬·훅과 플러그인 번들 편이 같은 주장을 더 앞에서 적었다 — "에이전트는 사용자 입력이 들어오면 스킬 디렉토리를 탐색해 각 description을 읽고 가장 적합한 스킬을 고른다. 즉 description이 곧 라우팅 키다." 두 자료가 같은 결론에 도달했고, 이 글의 원 자료는 거기에 "트리거 어구 5개 이상"이라는 개수 기준을 덧붙였다.

각 스킬 파일은 공통적으로 When to invoke 표 → Step 1~4 절차 → 출력 형식 예시 → 응용 → 주의사항 순서를 따른다. 이 골격 자체가 "반복 업무를 절차로 고정하는 서식"으로 재사용 가능하다.

세 계층이 언제 개입하는가

이 흐름도가 말하는 것은 하나다. 모델의 선의에 의존하는 지점(Rules, Skills)과 프로세스가 강제하는 지점(Hooks)이 분리되어 있다. 검증 파이프라인을 설계한다는 것은 이 두 지점을 어디에 배치할지 정하는 일이다.

차단 경로(H → E)가 흐름의 시작이 아니라 계획 수립 단계로 되돌아간다는 점이 앞의 "대안을 함께 돌려준다"와 이어진다. 사유와 대안을 받은 모델이 계획을 고쳐 다시 내려오는 구조다.

자주 발생하는 실수 7가지

일곱 항목 중 넷(실행 권한 누락 · set -e 누락 · matcher를 빈 문자열로 방치 · stdout 긴 출력)은 앞의 「훅 운영 규약」 여섯 항목과 같은 것을 반대편에서 적은 것이다. matcher 쌍이 가장 뚜렷하다 — 규약의 「필요한 도구로 좁힌다」가 이 표의 「해결」 칸에 같은 문구로 다시 나온다. 짝이 닫히는지 양쪽에서 세면, 규약 여섯 중 짝이 없는 것은 kill switch·로그 회수 둘이고(4 + 2 = 6), 실수 일곱 중 짝이 없는 것은 Rules 20개 초과·Skill description 모호·Rules와 CLAUDE.md 중복 셋이다(4 + 3 = 7). 규약 표는 "이렇게 하라"이고 이 표는 "안 하면 이렇게 된다"이다. 두 표를 이렇게 짝지어 읽는 것은 이 글의 정리다.

이 시리즈의 나머지

통제 계층은 여기까지다. 남은 세 편은 이 계층 위에서 실제로 돌아가는 것들이다.

남은 세 편 중 마지막 편이 이 글로 되돌아오는 자리가 있다. 5-Why를 끝까지 밀면 답이 코드가 아니라 규칙·게이트로 바뀐다 — 원 자료가 디버깅 절에서 이 글의 Rules·Hooks 계층을 명시적으로 되짚는 이유다.