본문 바로가기
AI창고

Claude Code로 신뢰성 있는 하네스(Harness) 시스템 만들기 A to Z

by 그랬냥 2026. 6. 1.
반응형
⚠ SAFETY SYSTEM
— HARNESS ENGINEERING · ISSUE №14
HARNESS A to Z

매번 운에 맡기지 마세요.
확실하게 작동하는 시스템을 만드세요.

Claude Code로 신뢰성 있는 하네스(Harness) 시스템 만들기 A to Z — 에이전트가 매번 같은 품질로 일하게 만드는 5개 레이어 완전 가이드

바이브 코딩 시리즈 · 14 · 봄내AI해적단 ⚙ RELIABLE BUILD

🔧 IN THIS BUILD

"똑같이 시켰는데 어제는 잘 되고 오늘은 엉망이에요." 바이브 코딩의 가장 큰 좌절입니다. 같은 명령, 다른 결과. 이 글은 그 문제를 푸는 하네스(Harness) 시스템을 다룹니다. 한 번 만들면 에이전트가 매번 같은 품질로 작동하게 만드는 5개 레이어를 A to Z로 안내합니다.

안녕하세요, 봄내AI해적단 선장 이장환입니다. 시리즈 열네 번째 글이에요.

시리즈 №13에서 AI 에이전트를 만들었죠. 그런데 멘티들이 만든 에이전트를 보면 한 가지 공통 문제가 있었어요. "운에 따라 작동한다"는 것. 어떤 날은 완벽하고, 어떤 날은 엉뚱한 결과. 이걸 어떻게 "확실하게" 만들까요?

정답은 더 좋은 프롬프트가 아닙니다. 더 비싼 모델도 아니에요. 정답은 "하네스(Harness)" — 에이전트를 둘러싼 안전 시스템입니다. 2026년 AI 엔지니어링의 핵심 화두예요.

등반가는 절벽을 오를 때 안전벨트와 로프(하네스)를 착용합니다. 떨어져도 잡아주죠. AI 에이전트도 마찬가지예요. 하네스가 에이전트를 잡아주면, 실수해도 다시 시도하고, 잘못된 결과는 걸러내고, 결국 확실한 결과에 도달합니다.

📈 AI 엔지니어링 성숙도 3단계

1단계
프롬프트 엔지니어링
"뭐라고 물을까"
2단계
컨텍스트 엔지니어링
"뭘 알려줄까"
3단계 · 2026
하네스 엔지니어링
"어떻게 잡아줄까"

이 글은 시리즈의 가장 깊은 단계입니다. 어렵게 느껴질 수 있지만, 비유로 차근차근 풀어드릴게요. 끝까지 오면 본인의 에이전트가 "가끔 되는 것"에서 "항상 되는 것"으로 바뀝니다.

01
LAYER ZERO

하네스란 — 모델과 하네스의 차이.

가장 먼저 이해해야 할 핵심 구분. 모델하네스는 다릅니다.

THE BRAIN

🧠 모델 (Claude)

원초적 지능. 똑똑하지만 통제 없이 풀어두면 매번 다르게 행동. 같은 질문에 다른 답.

THE SYSTEM

⚙️ 하네스 (Harness)

지능을 감싼 시스템. 제약·검증·피드백으로 그 지능이 매번 같은 품질로 작동하게 만듦.

💡 핵심 정의

"하네스 = 에이전트를 둘러싼 모든 것 (모델만 빼고). 도구, 권한, 검증 루프, 안전장치, 로그. 이 시스템이 에이전트를 신뢰할 수 있게 만든다."

놀라운 증거 — 모델은 그대로, 하네스만 바꿔서

2026년 2월, LangChain 팀이 발표한 실험 결과가 화제였어요:

52.8%
하네스 개선 전
66.5%
하네스 개선 후

같은 모델, 하네스만 개선. 13.7%p 향상. 순수하게 시스템 설계만으로 얻은 성과.

💡 시사점 · 더 좋은 결과를 원할 때 "더 비싼 모델"부터 찾지 마세요. 같은 모델이라도 하네스를 잘 만들면 결과가 극적으로 좋아집니다. Claude Code 창시자 Boris Cherny도 "검증(verification)이 품질에 가장 중요하다"고 했어요. 그게 하네스의 핵심입니다.

02
OVERVIEW

하네스의 5개 레이어.

Claude Code 기준, 신뢰성 있는 하네스는 5개 레이어로 구성됩니다. 자동차의 안전장치처럼 겹겹이 쌓여요.

⊙ 5-LAYER HARNESS

L1
📚 메모리 (Memory)
CLAUDE.md — 규칙과 맥락을 박제. "무엇을 해야 하는지"
L2
🛡️ 권한·가드레일 (Guardrails)
settings.json — "무엇을 하면 안 되는지". 안전장치
L3
🔁 검증 루프 (Verification) ★
작업을 스스로 검증·수정·재시도. 가장 중요한 레이어
L4
🪝 Hooks — 자동 검사
도구 사용 전후 자동 실행. 규칙 강제
L5
👁️ 관찰가능성 (Observability)
로그 — "무슨 일이 있었나"를 기록. 디버깅의 눈

💡 초보자는 어디부터? · 5개를 한 번에 다 만들 필요 없어요. L1(메모리) → L3(검증 루프) → L2(가드레일) 순으로 시작하세요. 이 3개만 잘 해도 신뢰성이 크게 올라갑니다. L4·L5는 익숙해진 후에.

03
LAYER 1 · 📚 메모리

메모리 — 규칙을 박제하라.

첫 번째 레이어. 시리즈 №10에서 배운 CLAUDE.md입니다. 하네스 관점에서 다시 보면, 이건 "매 세션마다 자동 주입되는 규칙서"예요.

중요한 건, 하네스용 CLAUDE.md는 "검증 가능한 규칙"을 담아야 한다는 것입니다.

❌ 모호한 규칙
"코드를 잘 작성하라"
"좋은 디자인으로"
"테스트도 좀 해줘"

→ 검증 불가능. 매번 다른 결과

✅ 검증 가능한 규칙
"모든 함수에 테스트 작성"
"npm run lint 통과 필수"
"타입 에러 0개 확인"

→ 명확한 합격/불합격 기준

하네스용 CLAUDE.md 핵심 섹션

📄 CLAUDE.md (하네스 버전)
# 프로젝트 규칙

## 작업 완료의 정의 (검증 기준)
작업이 "완료"되려면 다음을 모두 통과해야 한다:
- [ ] npm run lint 통과 (에러 0)
- [ ] npm run typecheck 통과 (타입 에러 0)
- [ ] npm test 통과 (모든 테스트 green)
- [ ] 새 기능엔 반드시 테스트 추가

## 작업 절차 (반드시 이 순서로)
1. 변경 전 현재 테스트 통과 확인
2. 코드 작성
3. 위 검증 기준 모두 실행
4. 하나라도 실패하면 → 수정 후 다시 검증
5. 모두 통과해야 "완료" 보고

## 절대 규칙
- 테스트를 삭제해서 통과시키지 않는다
- 검증을 건너뛰고 완료 보고하지 않는다
- 확신 없으면 멈추고 물어본다

💡 핵심 · "작업 완료의 정의(Definition of Done)"를 체크리스트로 명시하는 게 하네스의 출발점입니다. 모호한 "잘 해줘"가 아니라, 기계가 판단할 수 있는 합격 기준을 주세요.

04
LAYER 2 · 🛡️ 가드레일

권한·가드레일 — 안전장치.

두 번째 레이어는 "하면 안 되는 것을 막는" 안전장치입니다. 자동차의 ABS 브레이크처럼, 위험한 순간에 자동으로 막아줘요.

settings.json — 권한 규칙

Claude Code의 .claude/settings.json에서 어떤 도구를 자동 허용/차단할지 정합니다.

📄 .claude/settings.json
{
  "permissions": {
    "allow": [
      "Read",
      "Bash(npm run lint)",
      "Bash(npm test)",
      "Bash(git status)"
    ],
    "deny": [
      "Bash(rm -rf*)",
      "Bash(git push --force*)",
      "Read(.env)"
    ]
  }
}
✅ allow — 자동 허용

안전한 읽기·검증 명령. 매번 묻지 않고 바로 실행. 흐름이 끊기지 않음.

🚫 deny — 절대 차단

삭제·강제 푸시·비밀 파일 읽기. 클로드가 시도조차 못 함. 사고 원천 차단.

💡 가드레일 설계 원칙 · "되돌릴 수 없는 행동은 모두 deny 또는 사람 확인". 삭제, 강제 푸시, 발송, 결제, .env 읽기. 이것들만 막아도 대형 사고의 90%를 예방합니다. 설정이 헷갈리면 클로드한테: "안전한 settings.json 만들어줘. 파괴적 명령은 차단하고."

05
LAYER 3 · 🔁 검증 · 메인

검증 루프 — 하네스의 심장.

이 장이 글의 핵심입니다. Boris Cherny가 "품질에 가장 중요하다"고 한 바로 그것. 검증 루프(Verification Loop).

아이디어는 단순해요. 에이전트가 작업을 끝냈다고 말하면, 정말 끝났는지 스스로 검증하게 만드는 것. 통과 못 하면 다시 시도. 통과할 때까지.

기본 패턴 — fix → verify 루프

VERIFICATION LOOP

① 코드 작성 (Fix)
② 검증 실행 (Verify)
lint + typecheck + test
❌ 실패
→ ①로 돌아가 수정
✅ 통과
→ 완료 보고

통과할 때까지 ① ↔ ② 반복 (최대 횟수 제한)

CLAUDE.md에 이 루프를 글로 적어두면, 클로드가 알아서 반복합니다:

"코드를 작성한 후, 반드시 npm run lint && npm test를 실행해. 실패하면 원인을 분석하고 수정한 뒤 다시 실행해. 모두 통과할 때까지 반복하되, 5번 시도해도 안 되면 멈추고 상황을 보고해."

고급 패턴 — 이중 게이트 (Inner + Outer)

진짜 신뢰성을 원한다면 2개의 게이트가 필요합니다. 테스트만 통과하는 게 "올바른 코드"를 보장하지 않거든요.

🔧 내부 게이트 (Inner)

기계적 검증. 객관적 신호.

• lint 통과?
• 타입 에러 0?
• 테스트 green?

🔍 외부 게이트 (Outer)

품질 판단. 주관적 신호. 새 세션으로.

• 진짜 올바른가?
• 테스트 조작 없나?
• 좋은 설계인가?

⚠️ 왜 외부 게이트가 필요한가

에이전트가 테스트를 통과시키려고 "테스트를 삭제하거나, 하드코딩으로 속이는" 경우가 있어요. 자기가 짠 코드를 자기가 검토하면 못 잡습니다. 그래서 "깨끗한 새 세션"이 처음부터 다시 검토하는 외부 게이트가 필요해요. 신입이 자기 PR을 자기가 승인하면 안 되는 것과 같은 원리.

Ralph Wiggum 패턴 — 될 때까지 반복

2026년 화제가 된 패턴이에요. 이름은 심슨 캐릭터에서 따왔지만, 원리는 강력합니다.

핵심 아이디어: 성공 기준(spec)을 충족할 때까지 강제로 계속 시도. 단, 매번 깨끗한 컨텍스트로 리셋.

1️⃣ 명확한 사양(spec)을 정의
2️⃣ 에이전트가 시도
3️⃣ spec 기준으로 검증
4️⃣ 실패하면 → 컨텍스트 리셋 → 다시 (이전 실패에 오염되지 않음)
5️⃣ spec 충족하면 → 완료

실패를 "에러"가 아니라 "구조화된 피드백"으로 다룹니다. 매 시도가 깨끗하게 시작하므로, 이전 실수의 늪에 빠지지 않아요.

💡 초보자 적용법 · 이 모든 걸 직접 코딩할 필요 없어요. CLAUDE.md에 "검증 루프 규칙"을 글로 적어두는 것만으로도 80%의 효과를 얻습니다. 자동화된 루프(스크립트)는 나중에 익숙해지면 도전하세요.

06
LAYER 4 · 🪝 Hooks

Hooks — 자동 검사 장치.

네 번째 레이어. Hooks(훅)는 에이전트가 도구를 쓰기 전후에 자동 실행되는 검사 장치예요. 공장의 자동 품질 검사 라인 같은 거죠.

PreToolUse — 도구 사용 "전"

위험한 명령을 실행 전에 차단. 예: "rm 명령이면 멈춰".

PostToolUse — 도구 사용 "후"

파일 수정 후 자동으로 검사. 예: "코드 바꿨으면 lint 자동 실행".

실용 예시 — 코드 수정 후 자동 포맷

가장 흔한 활용: 클로드가 코드를 수정할 때마다 자동으로 포맷터를 돌리는 훅.

📄 .claude/settings.json (hooks 부분)
{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Edit|Write",
      "hooks": [{
        "type": "command",
        "command": "npm run format"
      }]
    }]
  }
}

이렇게 하면 클로드가 파일을 수정할 때마다 자동으로 포맷이 정리됩니다. 클로드가 깜빡해도 시스템이 강제하는 거죠.

💡 Hooks의 가치 · 클로드에게 "매번 포맷해"라고 부탁하는 건 잊힐 수 있어요(확률적). 하지만 Hook은 코드 수준에서 강제하므로 100% 실행됩니다(결정적). "잊힐 수 있는 규칙"을 "강제되는 규칙"으로 바꾸는 게 Hook의 역할. 초보자는 일단 건너뛰고, L1·L2·L3에 익숙해진 뒤 도전하세요.

07
LAYER 5 · 👁️ 관찰

관찰가능성 — 무슨 일이 있었나.

마지막 레이어. 관찰가능성(Observability)은 에이전트가 "무엇을, 왜 했는지 기록"하는 것입니다. 블랙박스를 투명하게 만드는 거죠.

왜 필요한가: 에이전트가 이상하게 행동했을 때, 로그가 없으면 "왜 그랬는지"를 알 수 없어요. 로그가 있으면 "내 에이전트가 뭔가 이상해" → "재현 가능한 버그 리포트"로 바뀝니다.

간단한 관찰 — 작업 로그 남기기

CLAUDE.md에 다음 규칙 한 줄이면 시작할 수 있어요:

"모든 작업 후 logs/agent-YYYYMMDD.md에 다음을 기록해: ① 무엇을 했는지 ② 어떤 검증을 통과했는지 ③ 실패한 시도가 있었다면 그 이유 ④ 사람이 확인해야 할 사항."
📄 logs/agent-20260530.md
## 14:32 로그인 기능 추가
✅ 작업: LoginForm 컴포넌트 + 검증 로직
✅ 검증: lint 통과, test 12개 통과, 타입 에러 0
⚠️ 시도 2회: 첫 시도에 이메일 정규식 오류 → 수정
👤 확인 필요: 비밀번호 정책 (현재 8자, 검토 요망)

💡 관찰의 3가지 가치 · ① 디버깅: 문제 생기면 로그 추적 ② 신뢰: 에이전트가 뭘 했는지 투명하게 ③ 개선: 자주 실패하는 패턴을 발견해 CLAUDE.md 보강. 로그는 단순 기록이 아니라 하네스를 진화시키는 데이터입니다.

08
BUILD · 실전

실전 A to Z — 코드 작성 하네스.

이론은 끝. 이제 "확실하게 작동하는 코드 작성 하네스"를 처음부터 만들어봅시다. 시리즈 №9의 랜딩 페이지 같은 프로젝트에 적용하는 시나리오.

🔧 하네스 빌드 — 6단계
STEP 1
L1 메모리 — CLAUDE.md에 검증 기준 작성

"작업 완료의 정의" 체크리스트 작성: lint 통과, 타입 에러 0, 테스트 통과, 새 기능엔 테스트 추가. (3장 템플릿 활용)

STEP 2
L2 가드레일 — settings.json 작성

클로드한테 시키기:

".claude/settings.json 만들어줘. Read와 npm 검증 명령은 allow, rm·force push·.env 읽기는 deny."
STEP 3
L3 검증 루프 — 핵심 규칙 추가

CLAUDE.md에 검증 루프 규칙 추가:

"코드 작성 후 npm run lint && npm test 실행. 실패하면 수정 후 재실행, 통과까지 반복(최대 5회). 통과해야 완료 보고."
STEP 4
테스트 — 일부러 어려운 작업 시키기

"로그인 폼에 이메일 검증 추가해줘"처럼 검증이 필요한 작업을 시킴. 클로드가 작성 → 자동 검증 → 실패 시 수정하는 과정을 관찰.

STEP 5
L5 관찰 — 로그 규칙 추가

CLAUDE.md에 "작업 후 logs/에 기록" 규칙 추가. 며칠 운영하며 어떤 작업이 자주 실패하는지 관찰.

STEP 6
반복 개선 — 하네스를 진화시키기

로그에서 발견한 반복 실패 패턴을 CLAUDE.md의 규칙으로 추가. 하네스는 한 번 만들고 끝이 아니라, 계속 진화합니다.

✅ 완성된 하네스의 효과

이제 본인의 에이전트는 코드를 작성하면 스스로 검증하고, 실패하면 고치고, 통과해야 완료합니다. "가끔 되던 것"이 "항상 되는 것"으로 바뀌었어요. 위험한 명령은 차단되고, 모든 작업은 로그에 남습니다. 이게 신뢰성입니다.

09
ADVANCED

Spec 기반 개발 + 함정 6가지.

고급 — Spec 기반 개발 (Spec-driven)

2026년의 핵심 패턴. 대화 히스토리 대신 "공식 사양서(spec)"를 진실의 원천으로 삼는 방식이에요.

❌ 대화 기반

긴 대화 속에서 요구사항이 흐려짐. 실패가 누적되며 컨텍스트 오염.

✅ Spec 기반

spec.md가 진실. 매 시도가 spec을 기준으로 깨끗하게 재평가. 오염 없음.

💡 방법: spec.md 파일에 "무엇을 만들지"를 명확히 적고, 클로드에게 "spec.md를 기준으로 구현하고, spec의 모든 항목을 만족하는지 검증해"라고 시킴. 시리즈 №10의 PLAN을 검증 가능한 spec으로 발전시킨 것.

초보자가 만나는 함정 6가지

🚨 TRAP 1 · 검증 기준이 모호함

"잘 작동하면 완료" → 판단 불가. "테스트 통과 = 완료"처럼 기계가 판단 가능하게.

🚨 TRAP 2 · 에이전트가 검증을 속임

테스트 삭제·하드코딩으로 통과. 외부 게이트(새 세션 리뷰)로 잡아야.

🚨 TRAP 3 · 무한 루프 (멈추지 않음)

통과 못 하는데 영원히 시도. "최대 N회" 제한 + 실패 시 사람 호출 필수.

🚨 TRAP 4 · 처음부터 5개 레이어 다 만들기

복잡함에 압도됨. L1 → L3 → L2 순으로 하나씩. 완벽보다 시작.

🚨 TRAP 5 · 가드레일 없이 자동 실행

검증 루프만 믿고 위험 명령 풀어둠. L2 가드레일은 필수. 특히 무인 실행 시.

🚨 TRAP 6 · 하네스를 한 번 만들고 방치

하네스는 살아있는 시스템. 로그를 보며 계속 규칙을 보강해야 진짜 신뢰성이 쌓임.

FINAL THOUGHTS

"운에 맡기던 것을, 시스템에 맡기세요."

바이브 코딩의 마법은 빠른 속도예요. 그런데 속도만 있고 신뢰성이 없으면, 만든 걸 믿을 수 없습니다. 하네스는 그 "빠르지만 믿을 수 있는" 상태를 만들어줘요.

2026년, 진짜 실력은 더 이상 "좋은 프롬프트"가 아닙니다. "좋은 시스템을 설계하는 능력"이에요. 무엇을 제약하고, 어떻게 검증하고, 언제 사람이 개입할지. 이게 하네스 엔지니어링이고, 본인을 진짜 AI 엔지니어로 만드는 능력입니다.

🏴‍☠️ 봄내AI해적단 멘티들에게

이번 주 미션 — 본인의 프로젝트(시리즈 №9 랜딩페이지나 №13 에이전트)에 3개 레이어 하네스를 추가하세요:

  1. L1: CLAUDE.md에 "작업 완료의 정의" 체크리스트 작성
  2. L3: 검증 루프 규칙 추가 ("통과까지 반복, 최대 5회")
  3. L2: settings.json에 위험 명령 deny 설정

그리고 일부러 어려운 작업을 시켜서 검증 루프가 실패→수정→통과하는 과정을 관찰하세요. 그 순간이 "아, 이게 하네스구나"를 깨닫는 순간입니다.

검증 루프가 실패를 잡아내고 스스로 고치는 스크린샷을 단톡방에 공유해주세요. 다음 모임은 "각자의 하네스 설계 공유하기"로 진행합니다. 이게 시리즈의 가장 깊은 내용이니, 천천히 소화하셔도 됩니다.

— 바이브 코딩 시리즈 전체 인덱스 (14편)

№1 Skills 만드는 법
№2 Claude Design
№3 Claude Code 입문
№4 Agent Teams
№5 6단계 워크플로우
№6 SQL 기초
№7 디버깅 기초
№8 GitHub 기초
№9 랜딩 페이지 실전
№10 PLAN 세우기
№11 MCP + n8n 자동화
№12 Cowork + 카카오톡 비서
№13 AI 에이전트 A to Z
№14 하네스 시스템 A to Z ← 현재 글

Issue №14 · Harness Engineering · Reliable Agent Systems

이장환 · 봄내AI해적단 선장 · 춘천 · 2026

참고: Claude Code 문서 · Hooks 가이드 · settings.json

반응형