하네스 엔지니어링은 점점 똑똑해지는 LLM과, 막상 써보면 답답한 현실 사이의 간극을 메우는 가장 중요한 기술이다. 모델 교체만으로는 절대 해결되지 않는 영역이다.
GPT-5, Claude Opus 4.6, Gemini 3까지 매달 벤치마크 기록이 갱신된다. 그런데 정작 내 프로젝트에 붙여 쓰면 엉뚱한 함수를 호출하고, 규칙을 잊어버리고, 같은 실수를 반복한다. 왜 이런 괴리가 생기는지 그 원리와 해법을 5가지 관점에서 정리한다.
모델은 똑똑한데 왜 내 AI는 멍청한가
벤치마크 점수와 실제 체감 성능은 전혀 다른 차원의 이야기다. MMLU나 SWE-Bench 점수가 오르는 속도와, “내 프로젝트에서 AI가 유능하게 느껴지는 속도”는 거의 무관하다고 해도 과언이 아니다.
모델의 지능이 10 오르는 동안, 내가 모델에게 건네는 맥락의 질은 그대로인 경우가 대부분이기 때문이다. 엔진만 페라리로 바꾸고 바퀴는 손수레 바퀴를 그대로 쓰는 셈이다.
근본 원인: LLM은 입력 토큰만 본다
LLM은 그 순간 주어진 입력 토큰 외에는 아무것도 모른다. 내 머릿속에 있는 프로젝트 구조, 코딩 컨벤션, 어제 내린 의사결정, 이 고객사의 특수한 제약은 토큰으로 들어가지 않으면 존재하지 않는 것과 같다.
인간 개발자라면 “아, 우리 프로젝트는 원래 이렇게 하잖아요”라고 암묵적으로 합의되는 것들이, LLM에게는 매번 처음 듣는 얘기다. 멍청해 보이는 것이 아니라, 맥락이 없는 것이다.
착각의 함정
“모델이 똑똑해졌으니까 대충 말해도 알아듣겠지”라는 기대가 모든 실망의 출발점이다. 오히려 모델이 똑똑해질수록, 불충분한 맥락에서 “그럴듯하게 지어내는” 능력까지 같이 올라가기 때문에 환각은 더 정교해진다.
트랜스포머: 다음 토큰 확률 기계
하네스 엔지니어링을 이해하려면 먼저 트랜스포머의 본질을 직시해야 한다. 2017년 구글의 “Attention is All You Need” 논문 이후 모든 주요 LLM의 뼈대가 된 이 구조는, 놀랍도록 단순한 목표를 가지고 있다. 지금까지의 토큰을 보고 다음 토큰의 확률 분포를 계산하는 것. 그게 전부다.
관련 논문 링크
https://arxiv.org/abs/1706.03762
Self-Attention의 작동 원리
트랜스포머의 핵심은 Self-Attention이다. 입력된 각 토큰은 다른 모든 토큰과의 관련도를 계산한다. 이때 Query, Key, Value 세 개의 벡터가 만들어지고, Query와 Key의 내적으로 “이 토큰이 저 토큰을 얼마나 중요하게 봐야 하는가”라는 가중치가 결정된다.
그 가중치에 Value를 곱해 합치면 “문맥이 반영된 새로운 표현”이 나온다. 이 과정이 수십 층에 걸쳐 반복되면 우리가 “문맥 이해”라고 부르는 현상이 만들어진다. 하지만 그 본질은 여전히 확률적 패턴 매칭이지, 이해가 아니다.
벡터 기반 추론의 본질
트랜스포머가 다루는 모든 단어, 문장, 코드 조각은 고차원 벡터로 임베딩된다. Claude나 GPT 같은 모델은 보통 수천 차원의 공간에서 의미를 표현한다. 유명한 예시인 “왕 – 남자 + 여자 = 여왕”이 성립하는 이유는, 단어들이 의미 공간 위의 좌표로 변환되어 산술 연산이 가능해졌기 때문이다.
추론이 아니라 기하학
- 모든 토큰은 의미 공간의 한 점으로 매핑된다
- “비슷한 의미”는 “공간에서 가까운 거리”로 표현된다
- 모델은 이 공간에서 가장 그럴듯한 다음 점을 예측한다
- 따라서 입력 벡터의 질이 출력 벡터의 질을 곧바로 결정한다
여기서 결정적인 통찰이 나온다. 모델 자체의 지능을 끌어올리는 것보다, “어떤 벡터를 입력으로 넣느냐”를 설계하는 것이 체감 성능을 훨씬 더 크게 움직인다는 사실이다. 같은 모델이라도 입력 맥락이 정제되어 있으면 놀라울 만큼 유능해지고, 그렇지 않으면 멍청해진다.
하네스 엔지니어링이 필요한 이유
여기서 하네스 엔지니어링이 등장한다. Harness는 원래 말을 제어하는 “마구”를 뜻한다. AI 맥락에서는 LLM을 감싸, 실제로 일을 할 수 있게 만들어주는 시스템 전체를 의미한다. 모델은 토큰 예측만 할 뿐, 스스로 파일을 열거나 명령을 실행하거나 상태를 기억하지 못한다. 그 모든 것을 대신해 주는 껍데기가 하네스다.
하네스가 감싸는 것들
하네스의 영역은 생각보다 넓다. 도구 호출(Tool Use), 권한 관리, 세션과 Context 유지, Memory(CLAUDE.md 같은 영속 지침), 파일·명령 실행 인터페이스, 샌드박스, 에러 피드백 루프가 모두 여기에 포함된다. 이 중 어느 하나라도 부실하면 모델이 아무리 똑똑해도 체감 성능은 추락한다.
Claude Code라는 대표 사례
Anthropic의 Claude Code는 대표적인 Agentic Harness다. 사용자 입력을 받으면 모델이 추론하고, 필요한 도구를 호출하고, 결과를 관찰한 뒤 다음 판단으로 이어지는 Agentic Loop를 반복한다. 이 루프의 설계 품질, 즉 하네스의 품질이 곧 “Claude Code가 얼마나 유능해 보이는가”를 결정한다. 똑같은 Claude 모델을 API로 직접 호출할 때와 Claude Code로 쓸 때 체감이 전혀 다른 이유가 바로 이것이다.
실전 하네스 엔지니어링 설계 원칙
내 AI를 덜 멍청하게 만들고 싶다면, 모델 교체가 아니라 내가 쓰는 하네스를 다듬어야 한다. 실전에서 통하는 다섯 가지 원칙을 제시한다.
다섯 가지 원칙
- Context를 명시하라. 프로젝트 규칙, 코딩 컨벤션, 도메인 용어, 금지 사항을 CLAUDE.md나 시스템 프롬프트에 못 박는다. 암묵지를 문서화하는 만큼 AI가 똑똑해진다.
- Memory를 분리하라. 세션마다 휘발되어야 할 정보와 영속되어야 할 정보를 명확히 구분한다. 모든 것을 장기 기억에 쌓으면 Context Window가 쓰레기통이 된다.
- 도구를 제한하라. 필요한 도구만 노출해 판단 공간을 좁혀라. 100개의 MCP 툴을 붙이는 것보다 5개의 정제된 툴이 훨씬 낫다.
- 루프를 짧게 유지하라. 한 번에 하나의 목표만 맡기고, 거대한 태스크는 작은 단위로 쪼개라. Context가 길어질수록 모델은 산만해진다.
- 관찰을 자동화하라. 실패 로그, 테스트 결과, 린터 출력을 다음 Context에 자동으로 되먹여라. 하네스는 결국 피드백 루프의 품질 싸움이다.
이 다섯 가지만 제대로 지켜도, 같은 모델이 갑자기 두세 배 똑똑해진 것처럼 느껴진다. 체감 지능은 모델이 아니라 하네스가 만든다.