개요

배경

개인 사이드 프로젝트를 진행하면서 AI 코딩 에이전트(Claude Code)를 적극 활용하고 있었습니다. 그러나 AI 에이전트가 프로젝트의 아키텍처 규칙을 무시하거나, 계획 없이 코드를 수정하거나, 위험한 명령어를 실행하는 문제가 반복적으로 발생했습니다.

문제

• AI 에이전트가 DDD + Clean Architecture 레이어 규칙을 위반하는 코드를 생성
• 작업 계획 없이 바로 코드를 수정하여 맥락 추적이 어려움
• git reset --hard, rm -rf 같은 파괴적 명령어 실행 위험
• 레이어별 문서를 읽지 않고 코드를 작성하여 패턴 불일치 발생

무엇을 했나

AI 에이전트 가드레일 아키텍처

flowchart TD
    A[Claude Code 명령 실행] --> B{PreToolUse Hook}
    B --> C[block_dangerous.py]
    B --> D[work_plan_enforcer.py]
    B --> E[plan_completion_guard.py]
    B --> F[layer_doc_reminder.py]
    
    C -->|위험 명령어| X[차단 exit 2]
    D -->|계획 없이 src/ 수정| X
    E -->|미완료 계획 + PR/push| X
    F -->|레이어 문서 미열람| X
    
    C -->|안전| G[명령 실행 허용]
    D -->|계획 존재| G
    E -->|계획 완료| G
    F -->|문서 열람 완료| G
    
    G --> H{PostToolUse Hook}
    H --> I[plan_update_reminder.py]
    H --> J[ktlint-format.sh]
    H --> K[markdown_formatter.py]

4종 Pre-Hook 상세

1. block_dangerous.py — 파괴적 명령어 차단

• git reset --hard, git push --force, rm -rf /, DROP DATABASE 등 패턴 매칭
• 정규식 기반으로 위험 명령어를 감지하고 exit code 2로 차단

2. work_plan_enforcer.py — 작업 계획 강제