Claude Code 멀티 훅으로 구현하는 AI DevSecOps 통제 구조

Claude Code에서 “행동 제어 + 보안 + 품질 보장”을 동시에 구현하는 멀티 훅 구조입니다.

개념 구조 (핵심 이해)

이 설정은 한 줄로 요약하면

Claude가 어떤 작업을 하기 전/후/종료 시점에 “강제 검사 로직”을 삽입하는 구조

즉,

• AI가 실행하는 모든 행동을 Hook으로 감시 + 차단 + 검증
• 사람이 아닌 AI 코드 실행 환경에 DevSecOps 정책을 강제 적용

Hook 실행 흐름 (Lifecycle)

구조는 3단계입니다.

[PreToolUse]  → 실행 전 검증
[PostToolUse] → 실행 후 통제
[Stop]        → 전체 작업 종료 시 검증

PreToolUse (사전 차단 계층)

가장 중요한 핵심 보안 레이어

✔ Bash 실행 전

"matcher": "Bash"

적용 목적

• AI가 쉘 명령 실행하기 전에 검사

적용된 보안 정책

• dangerous-cmd-guard → rm -rf, curl | bash 같은 위험 명령 차단
• commit-msg-guard → 이상한 commit 메시지 방지
• branch-protection-guard → main/master 직접 수정 방지

AI가 서버를 망가뜨리는 행동을 못 하게 막는 1차 방어선

✔ 코드 수정 전

"matcher": "Edit|Write|MultiEdit"

적용 목적

• 코드 생성/수정 전에 검사

적용된 정책

• secret-leak-guard → API Key, token 유출 방지
• tdd-guard → 테스트 코드 없이 변경 방지
• env-example-sync-guard → .env 변경 시 example 동기화

AI 코드 품질 + 보안 + 운영 일관성 강제

PostToolUse (사후 제어 계층)

"matcher": "Bash"

실행 후 동작

• circuit-breaker 실행

의미

실행 결과를 보고 추가 제어

300x250

예

• 반복 실패 감지
• 특정 명령 이후 시스템 상태 체크
• 이상 동작 시 추가 차단

“이미 실행된 행동에 대한 2차 안전장치”

Stop Hook (최종 품질 게이트)

npm run lint
npm run build
npm run test

실행 시점

• Claude 작업 종료 시

역할

• 코드 품질 검증
• 빌드 성공 여부 확인
• 테스트 통과 확인

CI/CD 역할을 AI 세션 종료 시 자동 수행

CLAUDE_PROJECT_DIR 의미

$CLAUDE_PROJECT_DIR

Claude 실행 기준 프로젝트 루트 경로

활용 이유

• Hook 스크립트를 프로젝트 내부에서 관리 가능
• 프로젝트별 정책 분리 가능

보안 관점 핵심 정리

이 구조는 단순 자동화가 아니라 AI 행동 통제 시스템입니다.

1. 실행 통제 (Execution Control)

• 위험 명령 차단
• 브랜치 보호

2. 데이터 유출 방지 (Data Protection)

• secret-leak-guard

3. 개발 프로세스 강제 (Process Enforcement)

• TDD
• commit 정책
• env 관리

4. 안정성 확보 (Stability)

• circuit breaker
• build/test 검증

실무 적용 시 권장 구조

디렉토리 구조 예시

project/
 ├─ scripts/
 │   └─ hooks/
 │       ├─ dangerous-cmd-guard.sh
 │       ├─ secret-leak-guard.sh
 │       ├─ tdd-guard.sh
 │       ├─ circuit-breaker.sh
 │       └─ ...
 ├─ package.json
 └─ claude.json

핵심 포인트 (실무 관점)

이 설정이 중요한 이유

• AI가 개발자처럼 행동하지만 보안 통제 없이 사용하면 위험
• 따라서

  AI = 자동화된 개발자
  Hook = 보안 정책 엔진

이 설정은

Claude Code를 “통제 가능한 DevSecOps 에이전트”로 만드는 구조