앞선 글 (AI 에이전트의 시대에서 하네스 엔지니어링의 시대로)에서 우리는 하나의 결론에 도달했습니다. 병목은 모델의 능력이 아니라 모델을 둘러싼 구조라는 것. 리플릿 사건이 보여준 것은 멍청한 모델도, 불량 플랫폼도 아니었습니다. 권한·도구·검증·상태·관측이라는 다섯 요소가 비어 있던 환경이었죠. 그리고 그 환경 전체를 설계하는 일에 우리는 이름을 붙였습니다. 하네스 엔지니어링^{Harness Engineering}.

그런데 이름이 생기면 늘 따라오는 일이 있습니다. 사람들이 그 이름을 자기가 이미 아는 무언가에 포개어 이해하려 한다는 것입니다. "아, 그거 결국 ○○ 아니야?"라는 반응이죠. 편리한 지름길이지만, 대개 절반만 맞고 절반은 틀립니다. 그리고 틀린 절반이 정확히 같은 사고를 다시 부릅니다.

그래서 이번에는 하네스 엔지니어링이 무엇이 아닌지로 좁혀 보려 합니다. 현장에서 가장 자주 마주치는 세 가지 오해입니다.

오해1. 하네스는 프롬프트 엔지니어링의 확장판이다

가장 흔한 첫 반응입니다. "프롬프트를 충분히 길고 정교하게 쓰면 그게 곧 하네스 아닌가?" 

이 말은 절반만 맞습니다. 좋은 프롬프트는 분명 하네스의 일부입니다. 하지만 하네스는 프롬프트에서 끝나지 않습니다.

시나리오를 하나 그려 봅시다. 시스템 프롬프트에 “DB를 절대 건드리지 말 것”이라고 적었습니다. 50번째 호출까지는 잘 지켜집니다. 그런데 51번째 호출에서 에이전트는 DROP TABLE을 실행합니다. 리플릿 사건이 규모만 줄어든 채 그대로 재현되는 셈이죠.

이유는 단순합니다. 프롬프트는 지시이지 강제가 아닙니다. 확률적 시스템에서 지시는 확률적으로만 지켜집니다. 같은 프롬프트에 같은 답이 보장되지 않는다는 것, 앞선 글에서 AI 에이전트만이 확률론적 시스템이라고 했던 바로 그 성질입니다. 50번 지켜졌다는 사실은 51번째를 보장하지 않습니다.

하네스는 같은 규칙을 다른 층에 걸어 둡니다. 도구 정의에서 DELETE·DROP 계열을 아예 허용 목록에서 빼거나, 실행 직전 검증 훅에서 위험 쿼리를 차단하거나, 별도 리뷰 에이전트의 승인 없이는 write 권한이 떨어지지 않도록 설계하는 식입니다.

그래서 둘은 의존하는 대상이 다릅니다. 프롬프트는 설득에 의존하고, 하네스는 기계적 강제에 의존합니다. 프롬프트는 말로 지시하고, 하네스는 구조로 강제합니다.

이 차이가 핵심입니다. 프롬프트가 잘못 쓰여도 하네스가 그 실수를 잡아낼 수 있고, 반대로 프롬프트가 완벽해도 하네스가 없으면 51번째 호출에서 사고가 납니다. 프롬프트 엔지니어링은 하네스 안에 포함되는 가장 안쪽 집합일 뿐, 그 바깥의 권한 경계와 검증 루프를 대신하지 못합니다.

오해 2. 하네스는 랭체인 같은 에이전트 프레임워크다

개발자에게 치명적인 오해가 이것입니다. "랭체인, AutoGen, CrewAI를 쓰고 있으면 이미 하네스를 쓰는 것 아닌가?"

답은 하나입니다. 프레임워크는 하네스를 짓는 데 쓰는 재료이지, 하네스 그 자체가 아닙니다. 목재와 콘크리트가 쌓여 있다고 건물이 세워지는 건 아닙니다.

앞선 글에서 본 세 가지 실험이 이 구분을 그대로 증명합니다. 세 실험 모두 공통된 설계 원칙을 따랐습니다. 프레임워크와 모델을 고정한 채, 하네스만 바꿨다는 것. 그런데도 점수는 눈에 띄게 올랐습니다. 같은 프레임워크, 같은 모델인데 결과가 달라졌다면, 결과를 가른 변수는 프레임워크가 아니라는 뜻입니다.

프레임워크가 제공하는 것은 아키텍처의 뼈대까지입니다. 그 위에서 어떤 에이전트에게 어떤 권한을 줄지, 언제 검증을 끼워 넣을지, 상태를 어떻게 영속화할지는 개발자가 뼈대 위에 올리는 설계입니다. 그게 하네스입니다.

이 구분이 중요한 이유는 실전에서 드러납니다. 프레임워크를 바꾸면 코드는 다시 써야 합니다. 하지만 잘 설계된 하네스는 프레임워크를 갈아엎어도 대부분 그대로 옮겨집니다. 설계는 재료보다 오래갑니다. 뒤집어 말하면, "프레임워크를 도입했으니 하네스는 해결됐다"라고 믿는 순간이 가장 위험합니다. 그 믿음과 함께 가장 중요한 설계 의사결정들이 통째로 미뤄지기 때문입니다. 프레임워크는 결과가 아니라 출발선입니다.

오해 3. 하네스는 IDE·플러그인이다

“커서, 클로드 코드, 클라인 ^Cline을 설치했으니 하네스를 이미 쓰고 있는 것 아닌가?” 이번에는 하네스의 일부에 꽤 근접했습니다. 다만 핵심이 빠져 있습니다. IDE는 에이전트를 실행하는 런타임 제품이고, 하네스는 그 위에 개발자가 설계해 얹는 '구조'입니다.

둘을 가르는 결정적인 질문은 이것입니다. “무엇이 제품에 속하고, 무엇이 리포지터리에 속하는가.” 커서나 클로드 코드를 다른 도구로 바꾸면 런타임은 바뀝니다. 그러나 리포지터리에 심어 둔 .claude/agents/*.md, .claude/skills/*/SKILL.md, CLAUDE.md 포인터는 그대로 남습니다. 런타임이 이 파일들을 읽어 들이는 방식은 달라질 수 있어도, 설계물 자체는 개발자의 것입니다. 실제 파일 구조를 보면 이해가 더 빠를 것입니다.

하네스의 물리적 실체

저장소(리포지터리) 안에 놓인 규칙·역할·절차 문서. IDE는 이것을 불러들여 실행하는 런타임일 뿐입니다.

서로 다른 런타임이 같은 설계물을 읽어낼 수 있도록 AGENTS.md 같은 포맷 표준이 등장하기 시작한 것도 이 때문입니다. 하네스가 특정 제품에 묶이지 않고 리포지터리에 독립적으로 존재한다는 사실을, 업계가 표준으로 떠받치기 시작한 것이죠. IDE를 바꿨다는 이유로 "하네스를 새로 마련했다"라고 여기면, 정작 옮겨야 할 설계물은 그대로 둔 채 껍데기만 교체하게 됩니다.

세 오해는 결국 하나의 착각이다

여기까지의 세 가지 오해는 한 문장으로 정리됩니다. 하네스의 일부를 하네스 전체로 착각하는 것.

프롬프트도, 프레임워크도, IDE도 모두 하네스의 일부입니다. 어느 하나를 전체라고 믿는 순간 나머지를 놓치게 됩니다. 프롬프트만 챙기면 강제가 빠지고, 프레임워크만 챙기면 설계가 빠지고, IDE만 챙기면 리포지터리에 남아야 할 구조가 빠집니다. 그렇게 빠진 자리들이 모이면, 다시 리플릿 사고와 같은 참사로 이어집니다.

앞선 글의 표현을 빌리면, 하네스란 모델을 가두는 일이 아니라 모델 바깥의 권한·도구·검증·상태·관측을 설계해 모델의 힘이 흩어지지 않게 하는 일입니다. 그 전체를 보는 시야가 있어야 비로소 "내가 지금 하네스의 어느 부분을 다루고 있고, 어느 부분이 비어 있는가"를 물을 수 있습니다.

2025년이 에이전트의 해였다면, 2026년은 에이전트 하네스의 해입니다. 

그 첫걸음은 새로운 도구를 사는 것이 아니라, 이미 손에 쥔 것들이 하네스의 전부가 아님을 인정하는 것에서 시작됩니다.

위 콘텐츠는 『하네스 엔지니어링 with 클로드 코드』에서 발췌하여 재구성하였습니다.