하네스 엔지니어링이란? — AI 에이전트를 제어하는 구조적 시스템 설계

안녕하세요, 자바파커입니다.

AI 에이전트에게 코드를 맡겼더니, 처음엔 잘 하다가 대화가 길어지니 엉뚱한 코드를 쏟아내기 시작합니다. 비슷한 경험, 한 번쯤 해보셨죠?

프롬프트를 아무리 정교하게 써도 AI가 말을 안 듣는 순간이 옵니다. 최근 AI 업계에서는 이 문제를 해결하기 위한 새로운 개념이 주목받고 있습니다. 바로 **하네스 엔지니어링(Harness Engineering)**입니다.

결론부터 말씀드리면 — 프롬프트가 AI에게 하는 '부탁'이라면, 하네스는 규칙을 어길 수 없게 만드는 **'강제적 시스템'**입니다.

하네스 엔지니어링이란?

**하네스(Harness)**는 원래 야생말을 통제하기 위한 '마구(고삐, 안장)'를 뜻합니다. 이 비유가 AI에도 그대로 적용됩니다.

거대언어모델(LLM)이라는 강력한 야생말이 있습니다. 엄청난 능력을 가졌지만, 고삐 없이 달리게 놔두면 어디로 튈지 모릅니다. 하네스 엔지니어링은 이 야생말이 인간의 의도대로 정확하게 달릴 수 있도록 제어하고 가이드하는 구조적 시스템을 설계하는 것입니다.

프롬프트 엔지니어링과 뭐가 다른가?

프롬프트에 "절대 DB를 삭제하지 마"라고 써도, AI가 맥락을 잃으면 삭제 명령을 실행할 수 있습니다. 하네스는 애초에 DB 삭제 명령이 실행되지 못하도록 시스템 레벨에서 차단합니다.

왜 하네스가 필요한가?

AI 에이전트를 실무에 투입해보면, 두 가지 고질적 문제를 마주하게 됩니다.

문제 1: 컨텍스트 부패 (Context Rot)

대화가 길어질수록 AI가 앞선 내용을 잊어버리거나 엉뚱한 결론을 내리는 현상입니다. 처음에 "TypeScript로 작성해"라고 했는데, 대화 50턴쯤 되면 슬그머니 JavaScript로 코드를 쓰기 시작합니다.

컨텍스트 윈도우에는 한계가 있고, 대화가 쌓일수록 초기 지시사항의 영향력은 약해집니다. 프롬프트만으로는 이 문제를 근본적으로 해결할 수 없습니다.

문제 2: 규칙 및 울타리 문제

AI가 정보는 알고 있지만, 하면 안 되는 행동을 제어할 물리적 장치가 없는 문제입니다.

예를 들어:

• 프로덕션 DB에 직접 쿼리를 날리는 것
• main 브랜치에 강제 push하는 것
• 민감한 설정 파일을 수정하는 것

AI는 "이러면 안 된다"는 것을 '알고' 있어도, 시스템적 제약이 없으면 실행할 수 있습니다.

하네스를 구성하는 3대 기둥

하네스 엔지니어링은 세 가지 핵심 요소로 구성됩니다.

기둥 1: 컨텍스트 파일 (Context Files)

CLAUDE.md나 agent.md 같은 온보딩 문서입니다. AI가 새로운 세션을 시작할 때마다 가장 먼저 읽게 하여, 프로젝트의 규칙과 절대 해서는 안 될 일을 상기시킵니다.

# CLAUDE.md 예시

## 절대 규칙

- 프로덕션 DB에 직접 쿼리 금지
- main 브랜치에 직접 push 금지
- .env 파일 수정 금지

## 코딩 규칙

- TypeScript strict 모드 사용
- 테스트 없는 코드 커밋 금지
- 기존 함수 시그니처 변경 시 반드시 확인 요청

사람으로 치면 신입 사원에게 주는 온보딩 가이드와 같습니다. 매 세션마다 "우리 팀은 이렇게 일합니다"를 읽게 하는 겁니다.

핵심 포인트: 컨텍스트 파일은 대화가 아무리 길어져도 항상 최우선으로 참조됩니다. 프롬프트는 묻힐 수 있지만, 시스템에 등록된 컨텍스트 파일은 묻히지 않습니다.

기둥 2: 자동 강제 시스템 (Automated Enforcement)

AI가 코드를 저장하거나 커밋하려 할 때 자동으로 규칙을 체크하는 장치입니다.

린터(Linter)와 훅(Hook):

// .claude/settings.json 훅 예시
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "command": "npm run lint --fix"
      }
    ]
  }
}

AI가 파일을 수정할 때마다 린터가 자동으로 돌아갑니다. 규칙에 어긋나면 저장 자체가 실패합니다.

자동 교정 루프:

여기서 핵심은 오류가 발견되었을 때 사람이 개입하는 대신, 시스템이 AI에게 다시 수정을 명령한다는 점입니다. AI가 잘못된 코드를 쓰면 → 린터가 감지 → AI에게 수정 지시 → AI가 스스로 고침. 이 루프가 사람 개입 없이 돌아갑니다.

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

잘 동작할 때는 아무 일도 일어나지 않고, 문제가 생겼을 때만 시스템이 개입합니다. 이것이 좋은 하네스 설계의 원칙입니다.

기둥 3: 가비지 컬렉션 (Garbage Collection)

프로그래밍에서 가비지 컬렉션이 안 쓰는 메모리를 정리하듯, AI가 만들어낸 나쁜 코드 패턴이나 안 쓰는 코드를 주기적으로 청소합니다.

왜 이게 중요할까요? AI는 기존 코드베이스를 참고해서 새 코드를 작성합니다. 만약 이전에 AI가 만든 나쁜 패턴이 그대로 남아있으면, AI가 그것을 '정상적인 코드'로 학습하고 같은 실수를 반복합니다.

나쁜 코드 잔존 → AI가 참고 → 비슷한 나쁜 코드 생성 → 나쁜 코드 더 쌓임 → ...

이 악순환을 끊으려면 주기적으로 코드를 정리해서 AI가 참고할 코드베이스의 품질을 유지해야 합니다.

실전 예시: 프롬프트 vs 하네스

같은 문제를 프롬프트와 하네스로 각각 해결하는 방식을 비교해보겠습니다.

상황: AI가 테스트 없이 코드를 커밋하려 한다

프롬프트 방식:

"코드를 작성한 후 반드시 테스트를 작성하고, 테스트가 통과한 후에만 커밋하세요."

→ 대화가 길어지면 잊어버리고 테스트 없이 커밋할 수 있음

하네스 방식:

# pre-commit 훅
#!/bin/bash
npm test
if [ $? -ne 0 ]; then
  echo "테스트 실패: 커밋이 차단되었습니다"
  exit 1
fi

→ 테스트가 실패하면 물리적으로 커밋이 불가능

상황: AI가 프로덕션 환경 설정을 건드리려 한다

프롬프트 방식:

"절대로 .env.production 파일을 수정하지 마세요."

→ 맥락 혼동 시 수정할 수 있음

하네스 방식:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "command": "node scripts/block-production-files.js"
      }
    ]
  }
}

→ 시스템이 차단하므로 AI의 의도와 무관하게 수정 불가

개발자 역할의 변화: '선수'에서 '감독'으로

하네스 엔지니어링이 부상하면서 개발자의 역할도 변하고 있습니다. 이전에는 코드 한 줄 한 줄을 직접 짜는 엄밀함이 중요했다면, 이제는 AI가 올바르게 동작할 수 있는 환경(시스템)을 설계하는 엄밀함이 요구됩니다.

이것을 **'엄밀함의 재배치'**라고 표현할 수 있습니다.

기술적 수준이 낮아지는 것이 아닙니다. 오히려 더 높은 차원의 설계 능력이 필요합니다. 축구로 비유하면, 훌륭한 선수에서 훌륭한 감독이 되는 것과 같습니다.

솔직히 말하면, OpenAI는 코드 한 줄 쓰지 않고 시스템 개선만으로 AI 에이전트의 성능을 크게 올렸다는 사례도 있습니다. 코드를 잘 짜는 능력보다 시스템을 잘 설계하는 능력이 더 큰 레버리지를 만들어내는 시대가 오고 있습니다.

지금 바로 시작할 수 있는 것들

하네스 엔지니어링이 거창하게 느껴질 수 있지만, 당장 적용할 수 있는 것들이 있습니다.

1. CLAUDE.md 작성하기 — 프로젝트 루트에 AI를 위한 온보딩 문서를 만들어보세요
2. pre-commit 훅 설정 — 린터, 테스트 자동 실행으로 기본적인 품질 게이트 설정
3. 코드 정리 루틴 — 주기적으로 안 쓰는 코드, 나쁜 패턴을 정리하는 습관
4. AI 실수 패턴 기록 — AI가 반복하는 실수를 발견하면 컨텍스트 파일에 규칙으로 추가

FAQ

하네스 엔지니어링은 프롬프트 엔지니어링을 대체하나요?

대체가 아니라 보완입니다. 프롬프트는 AI에게 '무엇을 할지' 알려주는 역할이고, 하네스는 '하면 안 되는 것'을 시스템으로 차단하는 역할입니다. 좋은 프롬프트 + 견고한 하네스 = 신뢰할 수 있는 AI 에이전트입니다.

소규모 프로젝트에도 하네스가 필요한가요?

CLAUDE.md 하나만 작성해도 하네스의 시작입니다. 프로젝트 규모와 관계없이, AI와 협업한다면 최소한의 규칙 문서는 만들어두는 것을 추천합니다. 투자 대비 효과가 가장 큰 시작점입니다.

Claude Code에서 하네스를 어떻게 적용하나요?

Claude Code는 CLAUDE.md 파일을 자동으로 인식하고, hooks 설정을 통해 자동 강제 시스템을 구성할 수 있습니다. 즉, 하네스 엔지니어링을 가장 자연스럽게 적용할 수 있는 도구 중 하나입니다.

AI 에이전트 시대에 개발자의 역량은 코드를 잘 짜는 것에서 시스템을 잘 설계하는 것으로 이동하고 있습니다. 하네스 엔지니어링은 그 변화의 핵심 키워드입니다.

여러분은 AI 에이전트와 협업할 때 어떤 '고삐'를 사용하고 계신가요? 댓글로 공유해주세요!