Claude Mods로 업무 규칙을 AI에 내장하기 — 지시서로는 지켜지지 않았던 3가지 규칙을 '시스템'으로 만든 이야기

왜 지시서를 버리고 ‘시스템’으로 만들었는가

당사는 작은 회사이며, 기사나 서적 제작, 수주 개발의 많은 부분을 Claude Code에 맡기고 있습니다. 규칙은 오랫동안 CLAUDE.md에 작성해 왔습니다. 하지만 쓸수록 잘 지켜지지 않았습니다. CLAUDE.md가 1,000줄을 넘어서자, 규칙들끼리 모순이 생겨 AI가 지시와 반대로 움직이는 일이 발생했습니다.

그중 피해가 가장 컸던 세 가지 규칙은 다음과 같습니다.

• 실제로 한 번은 AI가 강제 push를 실행하여 브랜치가 사라진 적이 있습니다. git push --force는 금지 - 공개된 서적의 본문은 수정하지 않는다. Kindle용 가공은 kindle/ 디렉터리에서만 할 규칙입니다. - Zenn에 공개는 하루 1건까지로 제한합니다. 이를 어기면, push 자체는 통과했지만 배포만 실패하게 됩니다.

세 가지 모두 CLAUDE.md에는 굵은 글씨로 적혀 있었습니다. 그럼에도 불구하고 위반되었습니다. 원인은 명확합니다. 지시서는 그저 요청에 불과하며, 모델이 컨텍스트 내에서 이를 우선순위로 삼지 않는 순간 효력을 잃기 때문입니다.

그래서 Claude Code 본체에 도구 호출을 막는 계층을 삽입할 수 있는 'Mods(함수 후크 플러그인)'를 이용해 이 세 가지 규칙을 재작성했습니다. 도입 여부를 판단하는 입장에서 결론부터 말씀드립니다.

• 변화하는 점: 사고 1회당 복구 비용(사라진 브랜치 복원, 서적 차이점 조사, Zenn 재배포)이 구조적으로 발생하지 않게 됩니다. - 맡기는 것: 기계적으로 판별할 수 있는 금지 사항(명령어 형태나 파일 경로, 수정 내용). - 맡기지 않는 것: '이 기사의 품질은 충분한가'와 같은 판단. 이는 지금까지처럼 사람의 리뷰를 통해 처리합니다.

시스템: tool.call 후크로 ‘실행 전에 거부’하기

Mods의 후크는 on(event, matcher, hook) 형태로 등록합니다. tool.call 이벤트에서는 AI가 Edit나 Bash를 실행하는 직전에 처리가 개입됩니다. `{ deny:

하나로 통합했습니다. 이 작업은 Zenn API를 사용하여 당일 공개 여부를 확인하고, 이미 공개되었다면 다음 날로 이월합니다.

TODAY=$(date '+%Y-%m-%d')
LATEST=$(curl -s --max-time 20 "https://zenn.dev/api/articles?username=joinclass&order=latest" \
| python3 -c "import json,sys; print(json.load(sys.stdin)['articles'][0]['published_at'][:10])" 2>/dev/null)
...

판단 로직을 두 곳에 두면, 한쪽만 수정했을 때 바로 어긋납니다. 훅은 '입구를 막는' 역할로 하고, 판단은 한곳에 모으는 것이 운영해 보니 가장 효과적이었던 설계 결정이었습니다. 이 글의 파일이 published: false
으로 되어 있는 것도 같은 규칙 때문입니다.

함정 (落とし穴)

실제로 적용해 보고 걸렸던 점들을 꼽겠습니다.

• Write 도구를 잊는다. 위의 코드는 Edit만 보고 있습니다. 신규 파일 생성이나 전체 내용 덮어쓰기는 Write를 거치기 때문에, 운영에서는 { tool: 'Write' }
  에도 같은 판단(e.content을 검사)을 등록했습니다. 이 부분을 빠뜨리면 규칙 2와 규칙 3은 통과됩니다. -
  Bash 경유 우회. sed -i로 책을 수정할 수 있다면, Edit의 훅은 작동하지 않습니다. Bash 훅에 'books/
  을 대상으로 한 sed -i/> 리다이렉트' 검사도 추가해 주세요. 완벽한 방어는 목표로 하지 말고, 과거에 실제로 발생했던 경로부터 순서대로 막아가는 것이 현실적입니다. -
  거부 문구는 AI를 위해 작성한다. '금지'만 반환하면, AI는 같은 작업을 다르게 표현하여 재시도하는 경향이 있습니다. 대신 무엇을 해야 하는지(kindle/
  에서 수정하는 것, 전용 작업에 맡기는 것)까지 적어주면, 한 번에 올바른 경로로 이동시켜 줍니다. -
  정규 표현식이 너무 광범위하다. 처음에는 /--force/만 하려고 했는데, npm install --force까지 막아버렸습니다. git push를 반드시 앞에 붙여 주세요.

검증 방법

직접 해보는 날에 다음 3가지를 확인할 수 있습니다.

# 1. 매니페스트와 훅의 정적 검증 (엔진이 거부하는 방식을 사전에 감지)
claude plugin validate ~/.claude/mods/company-rules
# 2. 로드하여 실행
...

3번에서 기대대로 거부되고, AI가 대체 수단(일반 push, kindle/
하위의 편집)을 제안한다면 합격입니다. 오탐지를 찾기 위해, npm install --force와 같은 막아서는 안 되는 작업도 하나 시도해 보면 안심할 수 있습니다.

결론: 지시서는 '방침', Mods는 '규칙'

도입하면서 알게 된 것은, CLAUDE.md와 Mods는 역할이 다르다는 것입니다.

• CLAUDE.md: 문체, 우선순위, 판단 기준 등, 해석의 폭이 필요한 방침을 적는 곳 -
  Mods: 깨지면 금전적·신용상의 손해가 발생하는, 기계적으로 판별 가능한 규칙을 두는 곳

세 가지 규칙을 Mods로 옮긴 덕분에, CLAUDE.md에서는 그만큼의 '절대 ~하지 말 것'이 사라지고 짧아졌습니다. AI에게 맡길 범위를 넓히고 싶다면, 먼저 과거에 한 번이라도 사고가 난 규칙을 파악하여 그것만 코드로 만들어 보세요. 첫 번째 것은 30분 만에 쓸 수 있습니다.

당사가 Claude Code로 회사의 업무를 돌리고 있는 구조(에이전트 설계, 승인 파이프라인, 사고로부터 만든 가드레일)는 Zenn의 책에 정리되어 있습니다.

Discussion