← 전체 회차
C-007● Day 072026.05.03

AI 에이전트 제어의 핵심, 하네스 엔지니어링 완벽 가이드

AI 모델의 반복적 실수를 구조적으로 차단하는 하네스 엔지니어링의 개념, 필요성, 3가지 핵심 요소와 실전 적용 방법을 완벽 해설

#ai#harness-engineering#claude-code#ai-agent#prompt-engineering#automation
01

영상

· video
▶ 17:20youtu.be/DrekqeDlO1w
03

학습 자료

· material

개요

하네스 엔지니어링(Harness Engineering)은 AI 에이전트가 반복적으로 같은 실수를 하지 않도록 구조적으로 제어하는 방법론입니다. 프롬프트에 "이렇게 하지 말아"라고 써도 AI는 계속 같은 실수를 반복하는데, 하네스는 그 실수 자체를 불가능하게 만드는 접근입니다. 2026년 2월 개발자 Mitchell Hashimoto가 처음 명명한 이 개념이 OpenAI, Anthropic, LangChain 등 업계 전체에 확산되고 있으며, AI 에이전트의 성능을 결정하는 핵심 요소로 인식되고 있습니다.

배경 / 사전 지식

AI 모델의 기본 특성

AI 모델(Claude, GPT, Gemini 등)은 기본적으로 "텍스트 입력 → 텍스트 출력"을 하는 함수입니다. 스스로는 이전 대화를 기억하지 못하고, 파일을 읽을 수 없으며, 인터넷에 접속할 수 없습니다. 우리가 Claude와 대화할 때 이전 메시지를 "기억"하는 것처럼 보이는 것은 실제로는 매번 전체 대화 기록을 새로운 입력으로 함께 제공하기 때문입니다.

AI 활용 방식의 진화

  • 프롬프트 엔지니어링: 명령을 구체적으로 작성 (예: "반응형 로그인 페이지 만들어, 다크모드 지원")
  • 컨텍스트 엔지니어링: 프로젝트 구조, 코드 스타일 같은 배경 정보 제공
  • MCP/스킬: AI가 사용 가능한 도구 목록과 가이드 문서 제공
  • 하네스 엔지니어링: 위 모든 것을 조합해 AI가 정확하게 동작할 수 있는 환경 자체를 설계

핵심 개념

하네스(Harness)란 무엇인가

"하네스"는 원래 말을 다루기 위해 사용하는 마구(saddle, bridle, reins 등)를 뜻합니다. 야생말이 경마장에 풀려나면 본능대로 날뛰고 울타리를 뛰어넘지만, 마구를 채우면 말의 힘을 억누르는 것이 아니라 올바른 방향으로 집중시켜 더 빠르고 정확하게 움직이게 됩니다.

AI 에이전트도 동일합니다. Claude, GPT 같은 모델은 그 자체로 야생말과 같은 강력한 능력을 가지고 있지만, 제약 없이 풀어놓으면 예측 불가능한 행동을 합니다. 하네스는 그 무한한 가능성을 제어하면서 동시에 최대한 활용하는 구조입니다.

모델 자체가 아닌 모델 주변의 모든 것이 하네스입니다: CLAUDE.md, settings.json, MCP, 스킬, 훅, 프리커밋, 테스트 등.

두 가지 핵심 문제

1. 컨텍스트 부패(Context Corruption)

AI는 한 번에 볼 수 있는 정보의 양이 제한되어 있습니다("컨텍스트 윈도우"). 책으로 치면 한 번에 펼쳐 볼 수 있는 페이지 수와 같습니다. 작업이 길어지면 이 창이 꽉 차고, AI는 앞서 했던 대화를 잊기 시작합니다(회차를 넘어가면 더욱 심함).

Anthropric의 실험 결과: Claude에게 Claude.ai 클론을 만들게 했을 때

  • 컨텍스트 부족으로 절반만 구현되고 중단
  • 새 세션에서 어디까지 했는지 모르고 처음부터 재분석
  • 부족한 정보로 조기 종료 선언

2. 규칙과 울타리의 문제

정보는 충분하지만 구조적 제약이 없어서 AI가 위험한 작업을 수행하는 경우입니다. 예: 결제 시스템을 만들라고 했는데 갑자기 DB 테이블을 삭제하는 경우. 이는 정보 부족이 아니라 "이건 절대 하면 안 된다"는 강제 메커니즘이 없기 때문입니다.

하네스의 핵심 철학

실수가 다시는 반복되지 않도록 하는 것

가장 중요한 원칙: 프롬프트(부탁)가 아닌 구조(강제)

  • ❌ 일반적 접근: "이 코드는 삭제하지 말아"

  • ✅ 하네스 접근: 그 파일을 삭제할 수 있는 권한 자체를 차단

  • ❌ 일반적 접근: "좋은 코드 작성해 줄래?"

  • ✅ 하네스 접근: 나쁜 코드를 저장하면 자동으로 거절됨

OpenAI의 사례: 엔지니어 3명이 5개월간 코드를 한 줄도 쓰지 않았습니다. 대신 시스템을 구축했고, AI 에이전트가 그 시스템 내에서 작업을 수행하게 만들었습니다. 결과적으로 AI가 코드를 짰지만, 사람이 만든 구조 때문에 높은 품질을 유지할 수 있었습니다.

LangChain의 벤치마크: 모델을 바꾸지 않고 하네스만 개선했을 때 순위가 30위에서 5위로 상승(성능 25단계 향상). AI 에이전트의 성능은 모델의 지능이 아니라 하네스가 결정합니다.

작동 원리

하네스의 3가지 기둥

1. 컨텍스트 파일(Context Files)

CLAUDE.md, AGENT.md 같은 문서 파일입니다.

특징:

  • AI가 새 세션을 시작할 때마다 가장 먼저 읽음
  • 컨텍스트가 부족해도 항상 다시 읽음 (컨텍스트 부패 극복)
  • 신입사원이 첫 날 필독 온보딩 문서 같은 역할

작성 원칙:

  • 1000페이지 설명서가 아니라 "지도" 제공
  • 60줄 이하로 제한 (일반적으로 적용되는 것만)
  • 구체적인 규칙은 따로 파일로 분리, 필요할 때만 가져다 씀
  • 처음부터 완벽하게 설계하지 않음
  • 실패할 때마다 한 줄씩 추가 (점진적 개선)

예시: Hashimoto가 만든 Claude Code의 AGENT.md는 AI가 저질렀던 실수를 모두 한 줄씩 기록해놓았습니다.

2. 자동 강제 시스템(Automated Enforcement)

린터(Linter)

  • 코드 맞춤법 검사처럼 정해진 규칙 위반을 자동 감지
  • 사람의 판단에 의존하지 않고 기계적으로 강제

프리커밋 훅(Pre-commit Hook)

  • 저장 버튼을 누르는 순간 자동 실행되는 검사 스크립트
  • "잠깐, 이거 먼저 확인하고 저장해라" 형태의 자동 게이트
  • 예: 테스트 통과 확인, 타입 체크, 문법 검증

자동 교정 루프(Auto-correction Loop)

  • 린터가 빨간 불을 켜면 AI가 스스로 코드 수정
  • 사람이 일일이 지적할 필요 없음
  • 말의 재갈에 의해 방향이 자동으로 교정되듯이 작동

"성공은 조용히, 실패만 시끄럽게"

  • 테스트 4000개 모두 통과하면 아무 메시지 없음
  • 하나 실패하면 그것만 보고
  • 불필요한 정보로 AI를 분산시키지 않기 위함

3. 가비지 컬렉션(Garbage Collection)

프로그래밍에서 사용하지 않는 메모리를 자동 청소하는 개념을 차용했습니다.

역할:

  • 주기적으로 돌아가는 청소 에이전트 실행
  • 문서와 실제 코드의 불일치 제거
  • 규칙 위반 코드 발견 및 수정
  • 사용하지 않는 코드 정리

장점:

  • 나쁜 패턴이 눈덩이처럼 불어나는 것 방지
  • 기존 코드에 나쁜 패턴 있으면 AI가 그걸 따라하기 때문에 중요

강화 메커니즘

시간이 지날수록 하네스가 정교해집니다:

  1. AI가 실수 → 2. 새 규칙 생김 → 3. 린트 규칙 추가 / 테스트 추가 / 제약 추가 → 4. 같은 실수 불가능

예: 말이 한 번 울타리를 넘으려 했으면, 그 울타리가 점점 더 높아져서 두 번 다시 같은 실수를 할 수 없게 됩니다.

코드 예시

CLAUDE.md 샘플

# Project Guidelines

## Core Rules
1. Never delete database tables without explicit confirmation
2. Always run tests before committing
3. Follow the existing code style in `/src/styles/conventions.md`

## Common Pitfalls (실패한 것들)
- Attempted to modify the payment API without checking the schema version
- Created duplicate utility functions instead of reusing existing ones
- Ignored the existing error handling pattern in middleware

역할:

  • 첫 줄부터 읽힘 (컨텍스트가 부족해도)
  • 핵심 규칙만 기록 (세부사항은 다른 파일에)
  • 실제 실패 사항 누적 (처음부터 완벽하지 않음)

프리커밋 훅 샘플

#!/bin/bash
# .git/hooks/pre-commit

# 1. 타입 체크
npx tsc --noEmit
if [ $? -ne 0 ]; then
  echo "❌ Type checking failed"
  exit 1
fi

# 2. 린터 실행
npm run lint
if [ $? -ne 0 ]; then
  echo "❌ Linting failed"
  exit 1
fi

# 3. 테스트 실행
npm test
if [ $? -ne 0 ]; then
  echo "❌ Tests failed"
  exit 1
fi

echo "✅ All checks passed"
exit 0

작동:

  • 개발자가 git commit 시도 → 자동 실행
  • 하나라도 실패하면 커밋 자체 불가
  • AI가 "좋은 코드 작성해"라는 부탁을 받지 않음
  • 대신 "나쁜 코드는 저장 불가"라는 강제 경험

함정·실수

1. 처음부터 완벽하게 설계하려는 실수

문제:

  • 하네스를 사용하려고 1000페이지 설명서 작성
  • 모든 가능한 규칙을 미리 정의하려고 함
  • 실제로는 AI 사용 전에 지쳐서 포기

올바른 접근:

  • 처음에는 최소한의 가이드만 (CLAUDE.md 1~2장)
  • 실제 실패가 발생했을 때 그것을 규칙으로 추가
  • 점진적 강화 ("fail → learn → enforce" 루프)

2. 명확하지 않은 요구사항에 하네스를 먼저 구축

문제:

  • 아이디어가 모호한데 완벽한 시스템부터 만들려고 함
  • 결국 잘못된 시스템을 강하게 강제하게 됨

올바른 접근:

  • 먼저 "결과물 자체"가 나올 수 있게 빠르게 만듦
  • 그 결과물이 정말 맞는지 검증
  • 이후 하네스 구축

3. GIGO 원칙 무시

문제:

  • GIGO = Garbage In, Garbage Out
  • 문제나 기획 자체가 구리면 아무리 하네스를 적용해도 결과는 구름

올바른 접근:

  • 하네스는 좋은 것을 더 좋게 만드는 도구
  • 나쁜 것을 좋게 만드는 마법이 아님
  • 기획부터 검증

4. 모든 것을 컨텍스트 파일에 넣으려는 실수

문제:

  • CLAUDE.md가 100줄 이상으로 비대화
  • AI가 매번 읽기만 해도 컨텍스트 소비

올바른 접근:

  • 60줄 이하 (정말 필요한 것만)
  • 세부사항은 docs/ 폴더 같은 곳에 분리
  • 필요할 때만 "읽어보세요" 지시

베스트 프랙티스

1. 단계별 실행 (Level 1부터 시작)

Level 1: 최소 구성

  • CLAUDE.md 또는 AGENT.md 작성 (1~2시간)
  • 프리커밋 훅 설정 (30분)
  • 끝

Level 2: 점진적 강화

  • 실제 실패 사항 기록
  • CLAUDE.md에 한 줄씩 추가
  • 필요한 린트 규칙 추가

Level 3: 자동 시스템 완성

  • 가비지 컬렉션 에이전트 구축
  • 자동 테스트 확대
  • 모니터링 시스템 추가

2. "실패 → 규칙 도출" 루프

AI 실수 발생
    ↓
  분석 (왜 했나?)
    ↓
새 규칙 작성
    ↓
CLAUDE.md / 린터 / 테스트에 추가
    ↓
같은 실수 불가능하게 됨
  • 처음부터 모든 걸 알 수 없음
  • 실제 사용 과정에서 약점 발견 → 보강

3. 성공은 조용히, 실패만 시끄럽게

AI의 맥락에서:

  • 테스트 100개 통과 → 출력 없음 (AI 분산 방지)
  • 테스트 1개 실패 → 명확한 에러 메시지만

이유:

  • AI도 토큰(비용, 시간) 낭비 방지
  • 작업에 집중할 수 있는 깔끔한 피드백

4. 마인드셋

"Just ship first"

  • 아이디어 검증이 먼저
  • 결과물 빠르게 만들기
  • 이후 하네스 구축

"Iterate, don't pre-design"

  • 한 번에 완벽하게 하려고 하지 말기
  • 실패할 때마다 그 케이스를 모아서 개선
  • 자연스러운 강화

5. 팀 확산

  • CLAUDE.md를 프로젝트 리포지토리에 커밋
  • 팀원들이 공통으로 추가/개선
  • "누가 어떤 실수를 했는가"는 저장, "실패 케이스"만 규칙화

참고

영상에서 언급된 소스:

  • OpenAI 공식 블로그 (5개월 엔지니어 3명 사례)
  • Anthropic 연구팀 실험 (Claude Clone 연구)
  • LangChain 코딩 에이전트 벤치마크 (30위 → 5위 사례)
  • Mitchell Hashimoto의 원문 (2026년 2월 첫 주장)

추가 학습:

  • Claude Code 공식 문서 (CLAUDE.md 작성법)
  • Git Hooks 설정 가이드 (프리커밋 구현)
  • LLM 컨텍스트 윈도우 이해 (각 모델별 한계)
  • 강화 학습(Reinforcement Learning) 개념 (피드백 루프)

AI 정보공유 오픈카톡: https://open.kakao.com/o/gK5uAeRh