Search
🔁

Loop — AI 에이전트 가드레일 사이드 프로젝트

개요

항목
내용
기간
2026.01 ~ 현재
역할
개인 사이드 프로젝트 (설계/구현 전체)
기술 스택
Spring Boot 4, Kotlin, DGS GraphQL Framework, Exposed ORM, PostgreSQL
GitHub
Spotit-KR/loop

배경

개인 사이드 프로젝트를 진행하면서 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]
Mermaid
복사

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 — 작업 계획 강제
•
src/ 하위 코드를 수정하려면 docs/plan/{작업명}/에 plan.md, checklist.md가 존재해야 함
•
예외 처리: 문서 수정, 설정 파일, .claude/ 디렉토리 등은 계획 없이도 수정 가능
•
Bash 명령어도 감지: sed -i, tee, 리다이렉트 등 파일 쓰기 패턴을 정규식으로 검출
3. plan_completion_guard.py — PR/push 시 미완료 계획 차단
•
gh pr create 또는 git push 실행 시, docs/plan/**/plan.md에 미완료 항목(- [ ])이 있으면 차단
•
미완료 계획이 머지되어 다른 훅이 오작동하는 것을 방지
4. layer_doc_reminder.py — 레이어 문서 선행 읽기 강제
•
세션 내 해당 레이어 파일을 처음 수정할 때, 관련 문서(docs/layers/{layer}.md)를 먼저 읽도록 차단
•
같은 세션에서 두 번째 수정부터는 통과 (마커 파일 기반)
•
Security 관련 코드는 docs/spring-security-7.md 선행 읽기 강제

CLAUDE.md — AI 에이전트 하네스

CLAUDE.md에 다음 규칙들을 코드화하여 AI가 프로젝트를 이해하도록 구성:
•
DDD + Clean Architecture 레이어 규칙 및 의존성 방향
•
TDD 사이클 (RED → GREEN → REFACTOR) 강제
•
GitHub 이슈 기반 작업 프로세스 (이슈 생성 → 계획 → 실행 → 검증)
•
파일 명명 규칙, 선택적 레이어 도입 기준, BC 간 통신 규칙

테스트

각 훅에 대한 단위 테스트를 작성하여 훅 자체의 신뢰성을 확보:
•
test_block_dangerous.py
•
test_work_plan_enforcer.py
•
test_plan_completion_guard.py (context.md → checklist.md 필수 파일 목록 포함)
•
test_layer_doc_reminder.py
•
test_plan_update_reminder.py

프로젝트 자체 기술 스택

flowchart TD
    subgraph Presentation
        A[DGS GraphQL DataFetcher]
    end
    subgraph Application
        B[Service]
    end
    subgraph Domain
        C[Entity / VO / Command / Query]
        D[Repository Interface]
    end
    subgraph Infrastructure
        E[Exposed Table + Repository 구현체]
        F[PostgreSQL]
    end
    
    A --> B
    A --> C
    B --> C
    B --> D
    E --> D
    E --> F
Mermaid
복사
•
Spring Boot 4 / Kotlin / Java 25
•
Netflix DGS GraphQL Framework + DGS Codegen
•
Exposed ORM + Flyway 마이그레이션
•
Kotest (BehaviorSpec) + MockK + SpringMockK
•
GitHub Issues 기반 작업 추적, MCP(Google Drive) 연동

배운 점

•
가드레일에는 트레이드오프가 있다. AI가 이미 맥락을 파악한 상황에서도 훅에 걸리면 토큰과 컨텍스트가 소폭 낭비됨. 훅의 예외 조건을 정교하게 설계해야 함
•
AI에게 암묵적 규칙은 통하지 않음. CLAUDE.md에 아키텍처, TDD, 작업 프로세스를 명시적으로 정의하니 아웃풋 품질이 눈에 띄게 향상됨
Made with