같은 모델에게 같은 작업을 시켰는데 결과가 완전히 다르게 나온 경험이 있을 것이다. 어떤 날은 멀쩡한 코드를 만들어내고, 어떤 날은 작동하지 않는 결과물을 자신 있게 내민다. 이 차이를 모델 탓으로 돌리기 쉽지만, 최근에는 다른 결론이 자리 잡고 있다. 모델이 아니라 모델이 일하는 환경이 결과를 가른다는 것이다. 이 환경을 설계하는 일에 붙은 이름이 하네스 엔지니어링(Harness Engineering)이다
결론부터 말하면 하네스 엔지니어링은 새로운 기술이 아니다. Claude Code를 쓰면서 CLAUDE.md에 규칙을 적고, permissions로 위험한 명령을 막고, hook으로 검증을 자동화하던 행위가 곧 하네스 엔지니어링이다. 같은 모델로도 환경만 바꾸면 결과가 달라진다는 사실이 누적되면서 비로소 이름이 붙었을 뿐이다. 프롬프트 엔지니어링과 컨텍스트 엔지니어링이 같은 경로를 거쳤다
하네스 엔지니어링의 정의
하네스(harness)는 말을 원하는 방향으로 이끌 때 쓰는 마구를 뜻한다. AI도 똑똑한 것과 별개로 방향을 잡아주지 않으면 제멋대로 움직인다. 그 방향을 잡아주는 환경이 하네스다. Claude Code 공식 문서는 Claude Code 자체를 “Claude 모델을 감싸는 하네스”라고 표현한다. 모델 단독으로는 프로젝트 폴더 구조도, 팀 컨벤션도, 실행 가능한 명령도 모른다. Claude Code라는 하네스 안에 들어가야 비로소 파일을 읽고 수정하고 터미널을 실행할 수 있다. 다만 Claude Code가 제공하는 하네스는 빈 틀이다. 어떤 규칙을 넣을지, 어떤 명령을 막을지, 어떤 검증을 자동화할지는 사용자가 설계해야 한다. 이 빈 틀을 채우는 행위에 처음 이름을 붙인 사람은 HashiCorp 공동 창립자 Mitchell Hashimoto다. 그의 정의는 다음과 같다
하네스 엔지니어링은 에이전트가 실수를 저지를 때마다 그 실수를 다시는 반복하지 않도록 솔루션을 설계하는 데 시간을 투자하는 것이다.
핵심은 AI가 실수했을 때 모델을 탓하지 않고 환경을 고친다는 발상이다. AI한테 “무엇을 해라”가 아니라 “어떤 환경에서 일해라”를 설계한다.
환경이 결과를 가르는 이유
Anthropic이 2026년 3월 공식 블로그에서 같은 Claude 모델로 두 차례 실험한 결과를 공개했다. 작업은 동일하게 “레트로 게임 메이커 만들기”였다
| 구분 | 환경 | 비용·시간 | 결과물 |
|---|---|---|---|
| 하네스 없음 | 그냥 지시만 전달 | 20분 / $9 | 캐릭터는 등장하지만 조작 불가 |
| 하네스 적용 | 스펙·완료 기준·자동 테스트 구조 설계 | 6시간 / $200 | 실제 동작하는 앱 |
$9를 써서 망한 앱과 $200을 써서 동작하는 앱 중 가치가 큰 쪽은 분명하다. 모델은 같았고 달라진 것은 환경뿐이었다. Anthropic이 두 차례 공식 블로그에서 밝힌 실패 원인은 크게 세 가지로 정리된다
세션 간 기억 소실
AI는 새 대화가 시작되면 이전 세션에서 무엇을 했는지 기억하지 못한다. Anthropic은 이 상황을 “이전 담당자가 무엇을 했는지 전혀 모르는 채로 출근하는 교대 근무 엔지니어”에 비유했다. 다음 세션의 AI가 이미 만들어진 결과물을 보고 “다 끝난 작업”이라고 판단해 절반만 완성된 채로 마무리하는 일이 자주 발생한다
컨텍스트 불안 (Context Anxiety)
하나의 대화 안에서도 문제가 생긴다. 작업이 길어져 컨텍스트 윈도우가 차오르면 AI는 일관성을 잃는다. 더 심각한 점은 할 일이 남아 있는데도 스스로 작업을 조기 종료한다는 것이다
자기 평가의 신뢰 불가
AI에게 자신이 만든 결과물을 평가하라고 요청하면 사람이 보기에도 명백히 문제가 있는 경우조차 자신 있게 좋다고 답한다. 만든 주체와 검증하는 주체가 같다는 구조 자체가 문제다. 세 가지 모두 모델 성능이 부족해서 생기는 문제가 아니다. 환경이 비어 있을 때 드러나는 구조적 한계다
Claude Code에서 하네스를 채우는 여섯 가지 방법
빈 틀로 주어진 Claude Code의 하네스를 어떻게 채울지가 실무 과제다. 여섯 가지 도구를 순서대로 본다
CLAUDE.md로 규칙을 전달한다
Mitchell Hashimoto가 제시한 하네스 엔지니어링의 두 가지 형태 중 하나다. AI가 실수할 때마다 그 실수를 막는 규칙을 문서에 적는다. 다음 세션의 AI가 이 문서를 읽고 같은 실수를 반복하지 않게 된다. Claude Code에서는 CLAUDE.md가 그 역할을 한다. 매 세션 시작 시 자동 로드되므로 세션 간 기억 소실 문제를 직접 보완한다
permissions로 위험한 작업을 차단한다
CLAUDE.md에 “위험한 명령을 실행하지 마라”라고 적어둘 수는 있지만, 이것은 맥락이지 강제가 아니다. AI가 항상 지킨다는 보장이 없다. Claude Code의 permissions는 다르다. 파일 읽기는 허용하되 파일 삭제는 실행 자체를 막는 식으로 동작 수준에서 차단한다
CLAUDE.md → 맥락 (지키면 좋은 것) permissions → 강제 (어길 수 없는 것)
hook으로 검증을 자동화한다
테스트와 같은 검증 단계도 CLAUDE.md에 적어두면 AI가 잊는다. hook을 쓰면 도구 호출 라이프사이클의 특정 시점에서 항상 셸 명령이 실행되므로 우회가 불가능하다. 부탁이 아니라 자동 실행이다. Anthropic도 Playwright MCP를 hook과 함께 연결해 자동 브라우저 테스트를 강제하는 구조를 권장한다
테스트 도구를 직접 붙여준다
Mitchell Hashimoto가 제시한 두 번째 형태다. AI에게 도구를 만들어 쥐여 준다. 코드만 보면 멀쩡한데 실제 화면에서는 버튼이 안 눌리는 경우가 흔하기 때문이다. Anthropic 공식 블로그에서도 Puppeteer나 Playwright 같은 브라우저 자동화 도구를 Claude에 연결하자 성능이 크게 향상되었다고 밝혔다. AI가 사용자처럼 클릭하고 화면 상태를 확인할 수 있게 되는 순간 결과 품질이 달라진다
만드는 AI와 검증하는 AI를 분리한다
세 번째 실패 원인이었던 자기 평가 문제의 해법이다. 같은 AI에게 “비판적으로 봐”라고 요청하는 것보다 검증 전용 에이전트를 따로 두는 편이 훨씬 효과가 크다
[Generator Agent] → 코드 생성
│
▼
[Evaluator Agent] → 코드 리뷰·검증
Claude Code에서는 sub-agent를 활용하거나 별도 컨텍스트에서 코드 리뷰를 돌리는 방식으로 같은 원리를 적용할 수 있다
모델이 발전하면 하네스도 다시 본다
하네스에 적힌 규칙 하나하나는 “이건 모델 혼자서는 못한다”라는 가정 위에 서 있다. 모델이 좋아지면 그 가정도 다시 검증해야 한다. Anthropic은 Claude Opus 4.6 출시 이후 자체 하네스에서 스프린트 구조를 통째로 제거했다고 밝혔다. 모델이 좋아지면서 더 이상 필요 없어진 제약이었다. 모델이 좋아져 규칙이 불필요해지면 지우고, 새로운 실패가 발견되면 추가한다. 하네스는 고정값이 아니라 모델과 함께 진화하는 살아 있는 문서다
정리
정리하면 하네스 엔지니어링은 AI가 일을 잘할 수 있는 환경을 설계하는 일이다. $9짜리 망한 앱과 $200짜리 동작하는 앱의 차이는 모델이 아니라 환경이었다. AI가 이상한 결과를 낼 때 가장 먼저 손볼 곳은 모델이 아니라 CLAUDE.md 한 줄, permissions 한 항목, hook 한 개다