🔧 IN THIS BUILD
"똑같이 시켰는데 어제는 잘 되고 오늘은 엉망이에요." 바이브 코딩의 가장 큰 좌절입니다. 같은 명령, 다른 결과. 이 글은 그 문제를 푸는 하네스(Harness) 시스템을 다룹니다. 한 번 만들면 에이전트가 매번 같은 품질로 작동하게 만드는 5개 레이어를 A to Z로 안내합니다.
안녕하세요, 봄내AI해적단 선장 이장환입니다. 시리즈 열네 번째 글이에요.
시리즈 №13에서 AI 에이전트를 만들었죠. 그런데 멘티들이 만든 에이전트를 보면 한 가지 공통 문제가 있었어요. "운에 따라 작동한다"는 것. 어떤 날은 완벽하고, 어떤 날은 엉뚱한 결과. 이걸 어떻게 "확실하게" 만들까요?
등반가는 절벽을 오를 때 안전벨트와 로프(하네스)를 착용합니다. 떨어져도 잡아주죠. AI 에이전트도 마찬가지예요. 하네스가 에이전트를 잡아주면, 실수해도 다시 시도하고, 잘못된 결과는 걸러내고, 결국 확실한 결과에 도달합니다.
📈 AI 엔지니어링 성숙도 3단계
이 글은 시리즈의 가장 깊은 단계입니다. 어렵게 느껴질 수 있지만, 비유로 차근차근 풀어드릴게요. 끝까지 오면 본인의 에이전트가 "가끔 되는 것"에서 "항상 되는 것"으로 바뀝니다.
⊙ 빌드 가이드 구성
9개 챕터. 1~2장은 개념, 3~7장은 5개 레이어 조립, 8~9장은 실전과 운영입니다.
하네스란 — 모델과 하네스의 차이.
가장 먼저 이해해야 할 핵심 구분. 모델과 하네스는 다릅니다.
🧠 모델 (Claude)
원초적 지능. 똑똑하지만 통제 없이 풀어두면 매번 다르게 행동. 같은 질문에 다른 답.
⚙️ 하네스 (Harness)
지능을 감싼 시스템. 제약·검증·피드백으로 그 지능이 매번 같은 품질로 작동하게 만듦.
💡 핵심 정의
"하네스 = 에이전트를 둘러싼 모든 것 (모델만 빼고). 도구, 권한, 검증 루프, 안전장치, 로그. 이 시스템이 에이전트를 신뢰할 수 있게 만든다."
놀라운 증거 — 모델은 그대로, 하네스만 바꿔서
2026년 2월, LangChain 팀이 발표한 실험 결과가 화제였어요:
같은 모델, 하네스만 개선. 13.7%p 향상. 순수하게 시스템 설계만으로 얻은 성과.
💡 시사점 · 더 좋은 결과를 원할 때 "더 비싼 모델"부터 찾지 마세요. 같은 모델이라도 하네스를 잘 만들면 결과가 극적으로 좋아집니다. Claude Code 창시자 Boris Cherny도 "검증(verification)이 품질에 가장 중요하다"고 했어요. 그게 하네스의 핵심입니다.
하네스의 5개 레이어.
Claude Code 기준, 신뢰성 있는 하네스는 5개 레이어로 구성됩니다. 자동차의 안전장치처럼 겹겹이 쌓여요.
⊙ 5-LAYER HARNESS
💡 초보자는 어디부터? · 5개를 한 번에 다 만들 필요 없어요. L1(메모리) → L3(검증 루프) → L2(가드레일) 순으로 시작하세요. 이 3개만 잘 해도 신뢰성이 크게 올라갑니다. L4·L5는 익숙해진 후에.
메모리 — 규칙을 박제하라.
첫 번째 레이어. 시리즈 №10에서 배운 CLAUDE.md입니다. 하네스 관점에서 다시 보면, 이건 "매 세션마다 자동 주입되는 규칙서"예요.
중요한 건, 하네스용 CLAUDE.md는 "검증 가능한 규칙"을 담아야 한다는 것입니다.
"좋은 디자인으로"
"테스트도 좀 해줘"
→ 검증 불가능. 매번 다른 결과
"npm run lint 통과 필수"
"타입 에러 0개 확인"
→ 명확한 합격/불합격 기준
하네스용 CLAUDE.md 핵심 섹션
💡 핵심 · "작업 완료의 정의(Definition of Done)"를 체크리스트로 명시하는 게 하네스의 출발점입니다. 모호한 "잘 해줘"가 아니라, 기계가 판단할 수 있는 합격 기준을 주세요.
권한·가드레일 — 안전장치.
두 번째 레이어는 "하면 안 되는 것을 막는" 안전장치입니다. 자동차의 ABS 브레이크처럼, 위험한 순간에 자동으로 막아줘요.
settings.json — 권한 규칙
Claude Code의 .claude/settings.json에서 어떤 도구를 자동 허용/차단할지 정합니다.
안전한 읽기·검증 명령. 매번 묻지 않고 바로 실행. 흐름이 끊기지 않음.
삭제·강제 푸시·비밀 파일 읽기. 클로드가 시도조차 못 함. 사고 원천 차단.
💡 가드레일 설계 원칙 · "되돌릴 수 없는 행동은 모두 deny 또는 사람 확인". 삭제, 강제 푸시, 발송, 결제, .env 읽기. 이것들만 막아도 대형 사고의 90%를 예방합니다. 설정이 헷갈리면 클로드한테: "안전한 settings.json 만들어줘. 파괴적 명령은 차단하고."
검증 루프 — 하네스의 심장.
이 장이 글의 핵심입니다. Boris Cherny가 "품질에 가장 중요하다"고 한 바로 그것. 검증 루프(Verification Loop).
아이디어는 단순해요. 에이전트가 작업을 끝냈다고 말하면, 정말 끝났는지 스스로 검증하게 만드는 것. 통과 못 하면 다시 시도. 통과할 때까지.
기본 패턴 — fix → verify 루프
VERIFICATION LOOP
lint + typecheck + test
→ ①로 돌아가 수정
→ 완료 보고
통과할 때까지 ① ↔ ② 반복 (최대 횟수 제한)
CLAUDE.md에 이 루프를 글로 적어두면, 클로드가 알아서 반복합니다:
고급 패턴 — 이중 게이트 (Inner + Outer)
진짜 신뢰성을 원한다면 2개의 게이트가 필요합니다. 테스트만 통과하는 게 "올바른 코드"를 보장하지 않거든요.
🔧 내부 게이트 (Inner)
기계적 검증. 객관적 신호.
• 타입 에러 0?
• 테스트 green?
🔍 외부 게이트 (Outer)
품질 판단. 주관적 신호. 새 세션으로.
• 테스트 조작 없나?
• 좋은 설계인가?
⚠️ 왜 외부 게이트가 필요한가
에이전트가 테스트를 통과시키려고 "테스트를 삭제하거나, 하드코딩으로 속이는" 경우가 있어요. 자기가 짠 코드를 자기가 검토하면 못 잡습니다. 그래서 "깨끗한 새 세션"이 처음부터 다시 검토하는 외부 게이트가 필요해요. 신입이 자기 PR을 자기가 승인하면 안 되는 것과 같은 원리.
Ralph Wiggum 패턴 — 될 때까지 반복
2026년 화제가 된 패턴이에요. 이름은 심슨 캐릭터에서 따왔지만, 원리는 강력합니다.
핵심 아이디어: 성공 기준(spec)을 충족할 때까지 강제로 계속 시도. 단, 매번 깨끗한 컨텍스트로 리셋.
2️⃣ 에이전트가 시도
3️⃣ spec 기준으로 검증
4️⃣ 실패하면 → 컨텍스트 리셋 → 다시 (이전 실패에 오염되지 않음)
5️⃣ spec 충족하면 → 완료
└ 실패를 "에러"가 아니라 "구조화된 피드백"으로 다룹니다. 매 시도가 깨끗하게 시작하므로, 이전 실수의 늪에 빠지지 않아요.
💡 초보자 적용법 · 이 모든 걸 직접 코딩할 필요 없어요. CLAUDE.md에 "검증 루프 규칙"을 글로 적어두는 것만으로도 80%의 효과를 얻습니다. 자동화된 루프(스크립트)는 나중에 익숙해지면 도전하세요.
Hooks — 자동 검사 장치.
네 번째 레이어. Hooks(훅)는 에이전트가 도구를 쓰기 전후에 자동 실행되는 검사 장치예요. 공장의 자동 품질 검사 라인 같은 거죠.
PreToolUse — 도구 사용 "전"
위험한 명령을 실행 전에 차단. 예: "rm 명령이면 멈춰".
PostToolUse — 도구 사용 "후"
파일 수정 후 자동으로 검사. 예: "코드 바꿨으면 lint 자동 실행".
실용 예시 — 코드 수정 후 자동 포맷
가장 흔한 활용: 클로드가 코드를 수정할 때마다 자동으로 포맷터를 돌리는 훅.
이렇게 하면 클로드가 파일을 수정할 때마다 자동으로 포맷이 정리됩니다. 클로드가 깜빡해도 시스템이 강제하는 거죠.
💡 Hooks의 가치 · 클로드에게 "매번 포맷해"라고 부탁하는 건 잊힐 수 있어요(확률적). 하지만 Hook은 코드 수준에서 강제하므로 100% 실행됩니다(결정적). "잊힐 수 있는 규칙"을 "강제되는 규칙"으로 바꾸는 게 Hook의 역할. 초보자는 일단 건너뛰고, L1·L2·L3에 익숙해진 뒤 도전하세요.
관찰가능성 — 무슨 일이 있었나.
마지막 레이어. 관찰가능성(Observability)은 에이전트가 "무엇을, 왜 했는지 기록"하는 것입니다. 블랙박스를 투명하게 만드는 거죠.
왜 필요한가: 에이전트가 이상하게 행동했을 때, 로그가 없으면 "왜 그랬는지"를 알 수 없어요. 로그가 있으면 "내 에이전트가 뭔가 이상해" → "재현 가능한 버그 리포트"로 바뀝니다.
간단한 관찰 — 작업 로그 남기기
CLAUDE.md에 다음 규칙 한 줄이면 시작할 수 있어요:
💡 관찰의 3가지 가치 · ① 디버깅: 문제 생기면 로그 추적 ② 신뢰: 에이전트가 뭘 했는지 투명하게 ③ 개선: 자주 실패하는 패턴을 발견해 CLAUDE.md 보강. 로그는 단순 기록이 아니라 하네스를 진화시키는 데이터입니다.
실전 A to Z — 코드 작성 하네스.
이론은 끝. 이제 "확실하게 작동하는 코드 작성 하네스"를 처음부터 만들어봅시다. 시리즈 №9의 랜딩 페이지 같은 프로젝트에 적용하는 시나리오.
✅ 완성된 하네스의 효과
이제 본인의 에이전트는 코드를 작성하면 스스로 검증하고, 실패하면 고치고, 통과해야 완료합니다. "가끔 되던 것"이 "항상 되는 것"으로 바뀌었어요. 위험한 명령은 차단되고, 모든 작업은 로그에 남습니다. 이게 신뢰성입니다.
Spec 기반 개발 + 함정 6가지.
고급 — Spec 기반 개발 (Spec-driven)
2026년의 핵심 패턴. 대화 히스토리 대신 "공식 사양서(spec)"를 진실의 원천으로 삼는 방식이에요.
긴 대화 속에서 요구사항이 흐려짐. 실패가 누적되며 컨텍스트 오염.
spec.md가 진실. 매 시도가 spec을 기준으로 깨끗하게 재평가. 오염 없음.
초보자가 만나는 함정 6가지
"잘 작동하면 완료" → 판단 불가. "테스트 통과 = 완료"처럼 기계가 판단 가능하게.
테스트 삭제·하드코딩으로 통과. 외부 게이트(새 세션 리뷰)로 잡아야.
통과 못 하는데 영원히 시도. "최대 N회" 제한 + 실패 시 사람 호출 필수.
복잡함에 압도됨. L1 → L3 → L2 순으로 하나씩. 완벽보다 시작.
검증 루프만 믿고 위험 명령 풀어둠. L2 가드레일은 필수. 특히 무인 실행 시.
하네스는 살아있는 시스템. 로그를 보며 계속 규칙을 보강해야 진짜 신뢰성이 쌓임.
🏴☠️ 봄내AI해적단 멘티들에게
이번 주 미션 — 본인의 프로젝트(시리즈 №9 랜딩페이지나 №13 에이전트)에 3개 레이어 하네스를 추가하세요:
- L1: CLAUDE.md에 "작업 완료의 정의" 체크리스트 작성
- L3: 검증 루프 규칙 추가 ("통과까지 반복, 최대 5회")
- L2: settings.json에 위험 명령 deny 설정
그리고 일부러 어려운 작업을 시켜서 검증 루프가 실패→수정→통과하는 과정을 관찰하세요. 그 순간이 "아, 이게 하네스구나"를 깨닫는 순간입니다.
검증 루프가 실패를 잡아내고 스스로 고치는 스크린샷을 단톡방에 공유해주세요. 다음 모임은 "각자의 하네스 설계 공유하기"로 진행합니다. 이게 시리즈의 가장 깊은 내용이니, 천천히 소화하셔도 됩니다.
— 바이브 코딩 시리즈 전체 인덱스 (14편)
Issue №14 · Harness Engineering · Reliable Agent Systems
이장환 · 봄내AI해적단 선장 · 춘천 · 2026
참고: Claude Code 문서 · Hooks 가이드 · settings.json