AI 에이전트를 쓰다 보면 이런 경험 한 번쯤 있으실 겁니다. 분명히 주의를 줬는데 똑같은 실수를 반복하고, 대화가 길어지면 앞 내용을 까먹고 헛소리를 하죠. "프롬프트를 더 잘 써야 하나?" 고민하셨나요?
HashiCorp의 설립자 미첼 하시모토는 다른 해답을 제시합니다. 바로 '하네스(Harness)'입니다.
1. 하네스란 무엇인가? : "부탁이 아닌 강제"
하네스(Harness)의 사전적 의미는 마구(안장, 고삐)입니다.
- 야생마 (AI 모델): 엄청난 에너지를 가졌지만, 초원을 마음대로 뛰어다닙니다. 그냥 두면 울타리를 넘고 관중석으로 돌진하죠.
- 안장/고삐 (하네스): 말의 힘을 억제하는 게 아니라, 인간이 원하는 방향으로 집중시킵니다. 안장이 있어야 비로소 야생마는 경주마가 됩니다.
결국 모델 + 하네스 = 에이전트입니다. 우리가 쓰는 AI가 똑똑한 비서처럼 행동하는 이유는 이미 하네스(대화 기록 전달 등)가 작동하고 있기 때문입니다.
2. 왜 하네스가 필요한가? (AI의 2대 고질병)
프롬프트 엔지니어링만으로 해결할 수 없는 두 가지 결정적인 문제가 있습니다.
- 컨텍스트 부패 (Context Rot): AI가 한 번에 읽을 수 있는 양(컨텍스트 창)은 정해져 있습니다. 작업이 길어지면 앞부분의 규칙을 잊거나, 다 끝내지도 않았는데 "완료했습니다"라고 착각하며 조기 종료해 버립니다.
- 울타리의 부재: 규칙을 알고는 있지만, 실행 과정에서 슬쩍 무시하는 경우입니다. "구조적 제약"이 없어서 발생하는 문제입니다.
3. 하네스는 문제를 '어떻게' 해결하는가?
그렇다면 위와 같은 문제를 하네스는 어떻게 해결할까요?
1. 컨텍스트 부패 해결 → CLAUDE.md (혹은 AGENTS.md)
컨텍스트 부패를 해결하기 위해 하네스는 매 세션마다 리셋되는 기억을 잡아주는 고정 문서를 활용합니다.
예를 들어 회사에서 퇴사자가 아무리 바뀌어도 신입 사원이 오면 무조건 읽어야 하는 '온보딩 문서가 존재하는데 이와 같은 역할을 하는것이 바로 CLAUDE.md 파일입니다.
이러한 CLAUDE.md 파일에는 프로젝트의 핵심 규칙, 기술 스택, 절대 하지 말아야 할 행동 등을 넣습니다.
이러한 내용을 넣어 AI가 새 대화를 시작할 때마다 이 문서를 가장 먼저 읽게 함으로써 항상 일관된 기준을 유지합니다.
2. 규칙과 울타리 문제 해결 → 훅(Hooks)
AI에게 정보를 줘도 엉뚱한 짓을 하거나 제약을 무시할 때가 있습니다. 이때는 프롬프트를 고치는 게 아니라 울타리(시스템)를 쳐야 합니다.
- 작동 방식: 코드가 저장되기 직전(Pre-commit)에 자동 검사 스크립트를 실행합니다.
- 자기 수정 루프: 만약 에러가 있다면 사람이 개입하는 게 아니라, 에러 메시지를 다시 AI(Claude 등)에게 돌려보냅니다.
- 효과: 규칙을 못 지키면 저장 자체가 안 되는 구조를 만듭니다. AI는 저장에 성공할 때까지 스스로 코드를 수정하게 됩니다.
3. 하네스 엔지니어링의 핵심 기둥
하네스는 프롬프트를 고치는 기술이 아닙니다. 실수가 불가능한 구조를 만드는 설계입니다.
1. 컨텍스트 파일 (CLAUDE.md, AGENTS.md)
새 세션이 시작될 때마다 AI가 반드시 읽어야 하는 '온보딩 문서'입니다.
- 핵심: 1,000페이지 매뉴얼이 아니라, 60줄 이하의 핵심 지도를 제공하세요.
- 성장: 에이전트가 실수할 때마다 그 내용을 이 문서에 업데이트합니다. 시간이 지날수록 하네스는 강해집니다.
2. 자동 강제 시스템 (Hooks & Linters)
"잘 짜줘"라고 부탁하는 게 아니라, 규칙을 어기면 시스템이 거절하게 만듭니다.
- 프리커밋 훅 (Pre-commit Hook): 코드를 저장하기 직전 자동 검사. 에러가 있다면 AI에게 즉시 돌려보냅니다.
- 자동 교정 루프: 린터(Linter)에서 빨간불이 들어오면 AI가 스스로 수정하고 다시 제출합니다. 사람의 개입 없이 '성공'할 때까지 반복하는 구조입니다.
3. 가비지 컬렉션 (Garbage Collection)
AI는 기존 코드의 나쁜 패턴을 학습합니다. 주기적으로 청소 에이전트를 돌려 사용하지 않는 코드나 문서와 맞지 않는 코드를 정리해야 합니다.
4. 프롬프트 vs 하네스: 결정적 차이
| 구분 | 프롬프트 엔지니어링 | 하네스 엔지니어링 |
| 성격 | 부탁 ("제발 이렇게 해줘") | 강제 ("안 하면 통과 못 해") |
| 실행 | AI의 판단에 의존 | 시스템 구조에 내장 |
| 결과 | 어길 수 있음 | 어길 수 없음 |
예시: 공장 안전 수칙을 말로 설명하는 것이 '프롬프트'라면, 안전모를 쓰지 않으면 문이 열리지 않게 설계하는 것이 '하네스'입니다.
5. 개발자의 역할이 변하고 있습니다
이제 개발자의 역할은 단순히 코드를 직접 작성하는 것에서 'AI가 사고 치지 않고 달릴 수 있는 환경'을 설계하는 것으로 바뀌고 있습니다.
- 지금 바로 시작하기: 거창한 도구가 필요 없습니다. 프로젝트 루트에 지침 파일 하나를 만들고, 자동화된 검사 스크립트(Hook)를 연결하는 것부터 시작해 보세요.
- 마인드셋: 처음부터 완벽할 필요는 없습니다. AI가 실수할 때마다 하네스를 한 칸씩 조이는 것, 그것이 하네스 엔지니어링의 본질입니다.
결국 모델의 지능보다 중요한 것은 그 지능을 가두고 유도하는 하네스의 설계입니다. 여러분의 에이전트는 지금 자유로운 야생마인가요, 아니면 통제된 경주마인가요?