약한 AI의 원인은 모델이 아니라 환경이었다 — 하네스 엔지니어링
조이
조이의 연습장 (Blog)
카테고리
- 자동화
"왜 이렇게 멍청하지?"
Opus로 잘 쓰다가 최근 모델 테스트를 한답시고 이것 저것 테스트를 해보다보니, 에이전트가 내놓는 결과물이 기대에 한참 못 미치는 거예요. 같은 작업을 시켜도 매번 다른 포맷으로 나오고, 토큰은 하루에 수십 달러씩 빠져나가고, 심지어 엉뚱한 도구를 호출하기도 했습니다.
"모델을 바꿔야 하나?" 하고 검색을 시작했는데, 결론은 전혀 다른 곳에 있었습니다.
하네스(Harness)가 뭔데?
하네스는 에이전트가 작동하는 환경 전체를 말합니다.
에이전트가 두뇌라면, 하네스는 몸입니다. 두뇌가 아무리 뛰어나도 몸이 엉망이면 아무것도 할 수 없어요. 눈이 흐리면 잘 못 보고, 손이 떨리면 잘 못 쥐고, 다리가 아프면 걷지를 못합니다. 에이전트도 마찬가지예요.
에이전트가 언제 깨어나는지, 무엇을 읽는지, 어떤 도구를 쓸 수 있는지, 실패하면 어떻게 하는지, 결과물을 어떤 형식으로 내놓는지 — 이 모든 게 하네스가 결정합니다. 모델의 능력이 아니라 하네스의 설계가 에이전트의 실제 퍼포먼스를 좌우하는 거예요.
회사로 비유하면 더 와닿습니다. 에이전트는 신입사원이고, 하네스는 그 신입이 일하는 회사 환경이에요. 책상 배치, 업무 규칙, 팀 구조, 보고 양식 같은 것들이요. 신입이 일을 못하면 사람을 탓하기 전에 환경을 먼저 봐야 합니다. 매뉴얼이 없는데 알아서 하라고 하면 누가 와도 헤매거든요.
Phil Schmid(Hugging Face)는 이걸 컴퓨터에 비유합니다.
모델은 CPU, 컨텍스트 윈도우는 RAM, 하네스는 운영체제(OS)다.
CPU가 아무리 빨라도 운영체제가 엉망이면 컴퓨터가 제대로 돌아가지 않는 것처럼, 모델이 아무리 좋아도 하네스가 나쁘면 에이전트는 제대로 일하지 못합니다.
Martin Fowler는 하네스를 두 축으로 나눕니다. Feedforward(예방)와 Feedback(자기교정)이에요.
•
Feedforward — 에이전트가 실수하기 전에 방향을 잡아주는 것. AGENTS.md에 규칙을 쓰고, OUTPUT-SCHEMA.md로 출력 형식을 미리 정해두는 게 여기에 해당합니다.
•
Feedback — 에이전트가 행동하고 나서 잘못됐을 때 스스로 고칠 수 있게 해주는 것. 테스트 실행, 자동 검수, 린터 같은 장치들이에요.
"Feedback만 있으면 같은 실수를 반복하고, Feedforward만 있으면 규칙은 있는데 지켜지는지 모른다." 이 두 가지가 같이 있어야 에이전트가 제대로 작동합니다.
AI 에이전트가 본격적으로 쓰이기 시작하면서, 하네스 엔지니어링이 하나의 전문 영역으로 떠오르고 있습니다. 개발자 커뮤니티에서 "모델 선택보다 하네스 설계가 더 중요하다"는 말이 나오는 배경이기도 해요. 어떤 모델을 쓰느냐보다, 그 모델이 일하는 환경을 어떻게 짜느냐가 결과를 결정한다는 뜻입니다.
awesome-harness-engineering를 만나다
GitHub에 awesome-harness-engineering이라는 오픈소스 자료가 있습니다. AI 에이전트 하네스 설계에 관한 베스트 프랙티스, 패턴, 실전 사례를 한데 모아놓은 레포지터리예요. 개발자들이 "에이전트 팀을 운영하다 보면 결국 다 겪는 문제들"을 체계화해놓은 자료입니다.
읽으면서 계속 "이거 우리 팀이잖아" 싶었어요. 매번 다른 출력 형식, 예상 못한 실패, 도구 오남용 — 전부 우리가 겪고 있던 문제 그대로였거든요. 남의 이야기가 아니라 우리 팀 일지를 읽는 느낌이었습니다.
이 자료에서 정리한 핵심 개념 네 가지가 있습니다.
•
Context budget — 에이전트가 한 번에 읽을 수 있는 정보량은 한정되어 있습니다. 뭘 읽게 하고 뭘 빼느냐가 성능을 좌우합니다.
•
Output schema — 출력 형식을 미리 정해줘야 일관된 결과가 나옵니다. 안 그러면 매번 다른 모양이에요.
•
Retry / Fallback — 에이전트도 실패합니다. 실패했을 때 어떻게 복구할지 미리 설계해놔야 합니다.
•
Tool definition — 에이전트에게 쓸 수 있는 도구를 알려줄 때, 설명이 정확해야 올바르게 씁니다. 애매하면 엉뚱한 도구를 골라요.
숫자로 보면 더 확실합니다. LangChain 팀이 실험한 결과, 컨텍스트 관리 개선만으로 과제 완료율이 52.8%에서 66.5%로 올랐습니다. 모델은 바꾸지 않고요. Terminal Bench 2.0 벤치마크에서도 30위에서 5위로 뛰었습니다. 하네스 엔지니어링이 중요한 이유를 숫자가 직접 보여준 셈입니다.
Anthropic도 같은 말을 합니다. "가장 성공적인 구현들은 복잡한 프레임워크를 쓰지 않는다. 단순하고 조합 가능한 패턴으로 만든다."
실제로 겪은 문제 세 가지
토큰 폭탄
어느 날 비용을 확인했더니 글냥이가 하루에 $10.2, 토큰 28.8M개를 소비하고 있었습니다. 원인을 추적해보니 에이전트 컨텍스트에 파일 전문과 결과물 전문이 통째로 올라가고 있었어요. 에이전트가 매번 수만 토큰짜리 문서를 처음부터 끝까지 읽고 있었던 겁니다.
Context budget 원칙을 적용했습니다. 에이전트에게는 파일 경로와 요약만 전달하고, 전문은 실제 작업을 수행하는 Claude Code에게만 넘기도록 구조를 바꿨어요. 결과는 확실했습니다. 토큰 사용량이 대폭 줄었고, 에이전트의 판단도 오히려 더 정확해졌습니다. 정보가 적으니까 핵심에 집중하게 된 거죠.
비슷한 원리를 Anthropic도 씁니다. MCP 도구를 컨텍스트에 전부 올리면 150,000 토큰입니다. 대신 에이전트가 디렉토리를 탐색해서 필요한 것만 찾게 하면 2,000 토큰. 98.7% 절감이에요. 우리가 한 것도 본질적으로 같은 접근이었습니다.
OUTPUT-SCHEMA.md 도입
같은 "초안 작성"을 시켜도 에이전트가 매번 다른 형식으로 결과를 내놓았습니다. 어떤 때는 마크다운 제목이 H2로 시작하고, 어떤 때는 H3으로 시작하고. 메타 정보를 넣을 때도 있고 안 넣을 때도 있고. 결국 사람이 매번 "이런 형식으로 다시 줘"라고 고쳐달라고 해야 했어요.
각 에이전트 워크스페이스에 OUTPUT-SCHEMA.md 파일을 만들어서 출력 형식을 고정했습니다. 제목 레벨, 섹션 순서, 메타 정보 위치까지 명시해뒀더니, 별도 지시 없이도 일관된 결과물이 나오기 시작했습니다. 검수 시간이 눈에 띄게 줄었어요.
runtime: "acp" 파라미터 하나
글냥이가 복잡한 작업을 할 때 Claude Code를 불러와야 하는데, 계속 일반 서브에이전트로 돌아가는 문제가 있었습니다. 한참을 디버깅했어요. 프롬프트 문제인가, 권한 문제인가, 설정 파일을 뒤지고 또 뒤졌습니다.
결국 원인은 sessions_spawn 호출에서 runtime: "acp" 파라미터 하나가 빠져 있었던 것이었습니다. 파라미터 하나. 이걸 AGENTS.md에 필수 파라미터로 명시해두고 나서야 문제가 해결됐습니다.
도구 정의가 명확하지 않으면 에이전트는 잘못된 도구를 씁니다. 사람도 매뉴얼이 불명확하면 실수하는 것처럼요.
에이전트의 자기 평가 편향
에이전트에게 "이 결과물 어때?"라고 물으면, 거의 항상 잘 됐다고 답합니다. Anthropic 엔지니어링 팀이 장기 실행 에이전트를 연구하면서 발견한 현상이에요. 에이전트는 자기가 만든 결과물을 평가할 때 늘 긍정적으로 평가하는 편향이 있습니다.
이전트에게 "이 결과물 어때?"라고 물으면, 거의 항상 잘 됐다고 답합니다. Anthropic 엔지니어링 팀이 장기 실행 에이전트를 연구하면서 발견한 현상이에요. 에이전트는 자기가 만든 결과물을 평가할 때 늘 긍정적으로 평가하는 편향이 있습니다.
이건 단순히 "AI가 거짓말을 한다"는 게 아닙니다. 같은 컨텍스트 안에서 작업과 평가를 동시에 하면, 자기 논리에 갇히는 거예요. 사람도 자기가 쓴 글의 오타를 잘 못 찾는 것처럼요.
해결 방법은 분리입니다. 작업하는 에이전트와 평가하는 에이전트를 따로 두는 거예요. 별도의 검수 에이전트가 있어야 진짜 피드백이 나옵니다. 우리 팀에서 달밤이(비서실장)가 Claude Code 결과물을 검수하는 역할로 분리된 것도 같은 원리입니다. 작업자와 검수자가 같으면 품질 관리가 안 돼요.
하네스 엔지니어링이란 결국
에이전트가 좋은 결과를 낼 수 있는 환경을 설계하는 기술입니다.
거창한 게 아니에요. Context budget, Output schema, Tool definition — 이 세 가지만 제대로 챙겨도 같은 모델이 완전히 다른 퍼포먼스를 보여줍니다. 저도 모델을 바꿀 생각부터 했지만, 실제로 바꿔야 했던 건 모델이 일하는 환경이었습니다.
비싼 모델을 찾기 전에, 환경부터 점검해보세요.
'zoeylog' 구독하기
사이트를 구독하면 새 포스트 등 최신 업데이트를 알림과 메일로 가장 먼저 받아보실 수 있습니다.
Slashpage에 가입하고 'zoeylog'을 구독하세요!
Slashpage에 가입하고 'zoeylog'을 구독하세요!
