들어가며
Claude Code를 사이드 프로젝트에서 적극 활용하면서, AI 에이전트가 생산성을 높여주는 동시에 예상치 못한 문제를 일으키는 것을 경험했다. 아키텍처 규칙을 무시하고, 계획 없이 코드를 수정하고, 위험한 명령어를 실행하는 경우가 반복되었다.
이 글에서는 Claude Code의 Hooks 기능을 활용하여 AI 에이전트가 프로젝트 규칙을 따르도록 강제하는 가드레일 시스템을 설계한 경험을 공유한다.
문제 상황
AI 에이전트를 아무런 제약 없이 사용하면 다음과 같은 문제가 반복된다:
1.
아키텍처 위반: DDD 레이어 규칙(Domain → Infrastructure 의존 금지 등)을 무시한 코드 생성
2.
계획 없는 코드 수정: 작업 계획 없이 바로 src/ 코드를 수정하여 맥락 추적이 어려움
3.
파괴적 명령어 실행: git reset --hard, rm -rf 같은 명령어를 아무 경고 없이 실행
4.
패턴 불일치: 레이어별 문서를 읽지 않고 코드를 작성하여 기존 패턴과 불일치
Claude Code Hooks란?
Claude Code의 Hooks는 AI가 도구(tool)를 사용하기 전후에 사용자 정의 스크립트를 실행할 수 있는 기능이다.
•
PreToolUse Hook: AI가 Bash 명령어, 파일 수정 등을 실행하기 직전에 트리거
•
PostToolUse Hook: AI의 도구 사용이 완료된 직후에 트리거
Hook 스크립트가 exit code 2를 반환하면 해당 작업이 차단된다.
가드레일 아키텍처
4종의 Pre-Hook과 3종의 Post-Hook을 설계했다.
Pre-Hook 1: block_dangerous.py — 파괴적 명령어 차단
가장 기본적인 가드레일. 정규식 패턴 매칭으로 위험한 명령어를 감지한다.
차단 대상: git reset --hard, git push --force, rm -rf /, DROP DATABASE 등
구현은 단순하다 — stdin으로 전달되는 도구 입력에서 위험 패턴을 정규식으로 매칭하고, 매칭되면 exit 2를 반환한다.
Pre-Hook 2: work_plan_enforcer.py — 작업 계획 강제
src/ 하위 코드를 수정하려면, docs/plan/{작업명}/에 plan.md와 checklist.md가 존재해야 한다.
이렇게 하면 AI가 "먼저 계획을 세우고, 계획에 따라 코드를 수정하는" 워크플로우를 강제할 수 있다.
예외 처리도 중요하다:
•
문서 수정, 설정 파일, .claude/ 디렉토리 등은 계획 없이도 수정 가능
•
Bash 명령어로 파일을 수정하는 경우도 감지해야 함 (sed -i, tee, 리다이렉트 등)
Pre-Hook 3: plan_completion_guard.py — PR/push 시 미완료 계획 차단
gh pr create 또는 git push 실행 시, docs/plan/**/plan.md에 미완료 항목(- [ ])이 있으면 차단한다.
미완료 계획이 머지되면 work_plan_enforcer가 오작동할 수 있기 때문이다.
Pre-Hook 4: layer_doc_reminder.py — 레이어 문서 선행 읽기 강제
세션 내 해당 레이어 파일을 처음 수정할 때, 관련 문서(docs/layers/{layer}.md)를 먼저 읽도록 차단한다. 같은 세션에서 두 번째 수정부터는 통과한다(마커 파일 기반).
이렇게 하면 AI가 레이어별 패턴(예: Service는 BC당 1개, 150줄 초과 시 분리 등)을 숙지한 상태에서 코드를 작성한다.
Post-Hooks
•
plan_update_reminder.py: 코드 수정 후 계획 문서 업데이트를 리마인드
•
ktlint-format.sh: Kotlin 코드 수정 후 자동 포매팅
•
markdown_formatter.py: 마크다운 파일 수정 후 포매팅
CLAUDE.md — AI 에이전트 하네스
CLAUDE.md에 다음 규칙들을 코드화했다:
•
DDD + Clean Architecture 레이어 규칙 및 의존성 방향
•
TDD 사이클 (RED → GREEN → REFACTOR) 강제
•
GitHub 이슈 기반 작업 프로세스
•
파일 명명 규칙, 선택적 레이어 도입 기준
이렇게 하니 AI의 아웃풋 품질이 눈에 띄게 향상되었다. 암묵적 규칙은 AI에게 통하지 않는다. 명시적으로 코드화해야 한다.
트레이드오프: 안전성 vs 효율성
가드레일의 가장 큰 단점은 토큰과 컨텍스트의 소폭 낭비다.
AI가 이미 맥락을 충분히 파악한 상황에서도 Hook에 걸리면, 문서를 다시 읽거나 계획 파일을 확인하는 데 토큰이 소모된다. 특히 layer_doc_reminder는 세션 초반에 한 번 걸리면 이후에는 통과하지만, 그 "한 번"이 컨텍스트 윈도우에서 불필요한 공간을 차지한다.
따라서 Hook의 예외 조건을 정교하게 설계하는 것이 중요하다. 안전성을 100% 확보하면 효율이 떨어지고, 효율을 100% 확보하면 안전성이 떨어진다. 이 균형점은 프로젝트마다 다르다.
각 Hook의 테스트
Hook 자체가 버그가 있으면 AI의 정상적인 작업을 방해한다. 따라서 각 Hook에 대한 단위 테스트를 작성했다:
•
test_block_dangerous.py
•
test_work_plan_enforcer.py
•
test_plan_completion_guard.py
•
test_layer_doc_reminder.py
•
test_plan_update_reminder.py
Hook이 잘못 작동하면 AI가 아무 작업도 하지 못하는 상황이 발생하므로, 테스트의 중요성이 높다.
결론
AI 에이전트는 생산성을 높여주지만, 규칙 없이 풀어놓으면 프로젝트의 일관성을 해칠 수 있다. Claude Code Hooks를 활용한 가드레일 시스템은 이 문제에 대한 하나의 답이다.
핵심은 두 가지다:
1.
CLAUDE.md로 "해야 할 것"을 명시하고, Hooks로 "하지 말아야 할 것"을 강제하라
2.
가드레일의 트레이드오프(토큰 낭비 vs 안전성)를 인지하고, 예외 조건을 정교하게 설계하라
AI를 잘 활용하는 것은 AI에게 자유를 주는 것이 아니라, AI가 따를 수 있는 규칙을 잘 만드는 것이다.
