하네스 엔지니어링: 모델보다 중요한 작업 환경 설계의 시대

애디 오스마니(Addy Osmani)가 정리한 “하네스 엔지니어링(Harness Engineering)”에 관한 분석입니다. 그는 지난 2년 동안 업계의 관심이 “어떤 AI 모델이 더 똑똑한가”라는 질문에만 쏠려 있었다고 진단합니다. GPT가 더 깔끔한 코드를 짜는지, 클로드가 환각을 덜 일으키는지를 두고 끝없이 비교가 이어졌지만, 정작 실제 코딩 AI의 성과는 모델 그 자체보다 그 모델을 둘러싼 하네스에서 결정된다는 것이 그의 주장입니다. 하네스란 모델을 제외한 모든 것을 포괄하는 말로, AI에게 일을 시키는 시스템 프롬프트, 사용할 수 있는 도구와 외부 서버, 컨텍스트 관리 정책, 실행 도중에 자동으로 끼어드는 점검 장치(훅), 안전한 실행 공간(샌드박스), 보조 AI(서브에이전트), 피드백 루프, 일이 막혔을 때 복구하는 흐름까지 전부 포함합니다. 비브 트리베디(Viv Trivedy)가 “AI 에이전트 = 모델 + 하네스”라는 한 줄로 이 개념을 정식화했고, 앤트로픽 엔지니어링 팀, 휴먼레이어(HumanLayer), 사이먼 윌리슨(Simon Willison) 같은 이들이 이 흐름을 정교하게 다듬고 있습니다. 오스마니는 이 흐름이 이제 하나의 공학 분야로 자리 잡았다고 봅니다.

핵심 내용을 풀어 보면 다음과 같습니다.

• 하네스가 무엇인가 모델만으로는 일을 끝내는 AI가 되지 못합니다. 진행 상황을 기억하고, 도구를 실행하고, 결과를 보고 다시 판단하고, 하지 말아야 할 일을 막아 주는 코드와 설정이 더해져야 비로소 “일하는 AI”가 됩니다. 클로드 코드, 커서, 코덱스, 에이더, 클라인 같은 제품은 모두 하네스이고, 그 안에 들어가는 모델이 같더라도 우리가 체감하는 행동은 하네스가 좌우합니다. 사이먼 윌리슨의 표현을 빌리면 AI 에이전트는 “목표를 이루기 위해 도구를 반복해서 돌리는 시스템”이며, 그 도구와 반복 구조를 어떻게 설계하느냐가 실력의 본질입니다.

• 모델 탓이 아니라 설정 탓이라는 관점 엔지니어들은 AI가 엉뚱한 짓을 하면 흔히 모델을 탓하고 “다음 버전을 기다리자”는 결론으로 빠집니다. 하네스 엔지니어링은 이 반응을 거부합니다. 휴먼레이어의 표현을 빌리면 “이건 모델 문제가 아니라 설정 문제(skill issue)”라는 것입니다. 같은 클로드 오푸스 4.6 모델을 쓰더라도 기본 하네스인 클로드 코드 안에서는 터미널 벤치 2.0 하위권에 머물지만, 직접 손본 하네스로 옮기면 상위권으로 뛰어오른 사례가 있습니다. 비브의 팀은 하네스만 바꿔서 같은 모델을 30위권에서 5위권으로 끌어올렸습니다. 모델이 가진 잠재력은 하네스가 깎아 먹고 있는 경우가 많다는 뜻입니다.

• 실수를 규칙으로 굳히는 “래칫(ratchet)” 원칙 AI가 한 번이라도 저지른 실수는 우연한 사고로 넘기지 않고 영구적인 신호로 봅니다. 다음번에는 같은 실수가 일어나지 않도록 규칙 문서에 한 줄을 추가하고, 자동 차단 장치를 붙이고, 검토 담당 보조 AI를 두는 식으로 한 칸씩 조여 나갑니다. 예컨대 AI가 테스트 코드를 주석 처리해 버린 일이 있다면, 다음 버전 규칙 문서에는 “테스트는 주석 처리하지 말고 지우거나 고칠 것”이라는 줄이 들어가고, 커밋 직전 검사 단계에는 그런 패턴을 잡아내는 검사기가 추가됩니다. 좋은 규칙 문서의 모든 줄은 과거에 있었던 구체적인 실패와 연결돼야 한다는 것이 핵심입니다. 그래서 하네스 엔지니어링은 누가 만들어 둔 프레임워크를 그대로 가져다 쓰는 일이 아니라, 자기 코드베이스의 실패 이력을 따라 길러 가는 “규율”에 가깝습니다.

• 원하는 행동에서 거꾸로 설계하기 비브가 제안한 가장 유용한 사고법은 “이런 행동을 원한다 → 그 행동을 가능하게 하는 하네스 부품은 무엇인가”의 순서로 거꾸로 설계하는 것입니다. 어떤 부품이 무슨 행동을 위해 존재하는지 한 줄로 설명할 수 없다면, 그 부품은 들어내는 편이 낫습니다. 구체적으로 보면, 파일 시스템과 깃은 작업 내용을 오래 보관하고 되돌리는 용도, 배시(bash)와 코드 실행은 무엇이든 시도해 볼 수 있는 만능 도구, 샌드박스는 망쳐도 본체에 영향이 가지 않는 안전한 실행 공간, 메모리 파일과 웹 검색·MCP 도구는 새로 알게 된 지식을 쌓는 통로, 요약 압축과 도구 출력 분리, 스킬 기능은 AI의 기억력 한계를 늘려 주는 장치, 그리고 랠프 루프(Ralph loop)와 계획자·평가자 분리 구조는 며칠씩 걸리는 긴 작업을 끝까지 끌고 가는 방법입니다.

• 컨텍스트 부패(context rot) 문제 AI는 한 번에 읽을 수 있는 글의 양에 한계가 있고, 그 한도에 가까워질수록 판단력이 눈에 띄게 떨어집니다. 그래서 하네스는 한정된 공간을 어떻게 잘 쓸지에 대한 장치 묶음이기도 합니다. 첫째, 한도가 차오르면 오래된 내용을 똑똑하게 요약해 압축합니다. 둘째, 2,000줄짜리 로그처럼 큰 출력물은 머리와 꼬리만 남기고 본문은 파일로 빼 뒀다가 필요할 때만 다시 읽게 합니다. 셋째, 도구와 지시문을 처음부터 전부 보여 주지 않고 그 작업에서 실제로 필요한 순간에만 꺼내 주는 “점진적 공개” 방식을 씁니다. 정말 긴 작업에서는 아예 새 창에서 인수인계 문서만 들고 처음부터 다시 시작하기도 합니다. 앤트로픽은 “긴 작업에서는 요약 압축만으로는 부족하고, 구조화된 인수인계 문서로 새로 시작해야 할 때가 있다”고 짚습니다. 사람으로 치면 신입에게 업무를 넘길 때 정리된 문서를 만들어 주는 방식과 비슷합니다.

• 긴 작업을 끌고 가는 패턴들 오늘날 모델의 약점 중 하나는 일찍 일을 끝내려 한다는 점, 큰 문제를 잘게 쪼개지 못한다는 점, 컨텍스트 창이 바뀌면 흐름이 끊긴다는 점입니다. 하네스는 이 약점을 보완해야 합니다. 랠프 루프는 모델이 일을 끝내려 할 때마다 훅이 가로채 원래 목표를 새 컨텍스트 창에 다시 주입해 작업을 이어 가게 하는 단순한 기법입니다. 매 반복은 깨끗한 상태에서 시작되지만, 직전 작업의 결과는 파일 시스템을 통해 이어집니다. 한편 앤트로픽은 “생성 담당”과 “평가 담당”을 다른 AI로 분리해야 한다고 강조합니다. AI가 자기 결과물을 스스로 평가하면 후하게 점수를 주는 경향이 있기 때문입니다. 여기에 더해 “끝났다는 게 어떤 상태인지”를 작업 시작 전에 미리 합의해 두는 “스프린트 컨트랙트” 패턴은 작업 도중 목표가 슬그머니 늘어지는 현상을 막는 데 효과가 큽니다.

• 훅(hook)의 역할 “AI에게 그렇게 하라고 말해 두는 것”과 “시스템이 강제로 그렇게 만드는 것”은 다릅니다. 훅은 그 차이를 메우는 자동 장치로, 도구를 쓰기 전, 파일을 고친 뒤, 커밋 직전, 세션이 시작될 때 같은 시점에 끼어들어 동작합니다. 코드를 고칠 때마다 자동으로 문법 검사·린트·테스트를 돌리거나, rm -rf나 git push --force 같은 위험한 명령을 막거나, PR을 올리기 전에 사람의 승인을 받게 하는 식입니다. 원칙은 “성공은 조용히, 실패는 시끄럽게”입니다. 검사가 통과하면 AI는 아무 소리도 듣지 못하고, 실패하면 그 오류 메시지가 그대로 흐름에 주입돼 스스로 고치게 됩니다. 평소에는 비용이 거의 들지 않으면서 문제가 생긴 순간에만 정확히 도움을 주는 구조입니다.

• 규칙 문서와 도구 선택은 짧고 분명하게 프로젝트 루트에 두는 AGENTS.md는 매 턴 시스템 프롬프트에 들어가는 가장 영향력 있는 설정 파일입니다. 휴먼레이어는 이 문서를 60줄 이하로 유지하라고 권합니다. 길어질수록 각 줄의 무게가 옅어지므로, 평소 스타일을 적어 두는 안내서가 아니라 비행기 조종사의 점검표처럼 꼭 필요한 항목만 남기라는 권고입니다. 도구도 마찬가지로, 이름과 설명, 스키마가 매 요청마다 프롬프트에 박히기 때문에 비슷비슷한 도구 50개보다 잘 다듬은 10개가 낫습니다. 휴먼레이어는 보안 측면도 함께 짚습니다. 도구 설명이 곧 AI가 읽는 텍스트이기 때문에, 검증되지 않은 외부 MCP 서버를 붙이는 일은 AI에게 누군가 미리 써 둔 지시를 몰래 주입하는 통로가 될 수 있습니다.

장점으로 볼 만한 부분입니다.

• 공들일 지점이 분명해짐 모델을 바꾸지 않고도 행동을 크게 끌어올릴 수 있는 지점이 하네스라는 사실이 벤치마크 데이터로 드러납니다. “다음 모델만 기다리자”는 막연한 기대 대신, 지금 당장 손볼 수 있는 구체적인 영역이 생긴다는 뜻입니다.
• 노하우가 쌓이는 구조 실수를 규칙으로 바꿔 두는 래칫 방식 덕분에 한 번 배운 교훈이 팀 자산으로 남습니다. 사람이 바뀌어도 규칙 문서와 훅은 그대로 남아 다음 사람을 보호합니다.
• 기성 하네스 등장(HaaS) 비브가 “하네스 서비스(Harness-as-a-Service)”라고 부르는 흐름이 빠르게 자리 잡고 있습니다. 클로드 에이전트 SDK, 코덱스 SDK, 오픈AI 에이전트 SDK처럼 작업 루프와 도구, 컨텍스트 관리, 훅, 샌드박스를 미리 묶어 주는 제품들이 등장하면서, 처음부터 다 만들지 않고도 자기 도메인 지식에 집중할 수 있게 됐습니다.

부담스러운 부분도 있습니다.

• 챙겨야 할 영역이 넓음 지시문, 도구, 안전한 실행 공간, 자동 점검, 로그 관찰까지 모두 직접 책임져야 합니다. 모델 공급자가 알아서 해 주는 영역이 아니라는 점이 핵심입니다.
• 모델과 하네스의 결합 위험 오늘날의 모델은 특정 하네스 안에서 후처리 학습되기 때문에, 다른 하네스로 옮기면 갑자기 성능이 떨어지는 일이 생깁니다. 도구 이름 하나, 인자 형식 하나만 바꿔도 결과가 흔들립니다. 진짜로 일반적인 모델이라면 도구 이름에 영향을 받지 말아야 하지만, 함께 학습되는 구조 때문에 일종의 과적합이 생기는 셈입니다.
• 외부 도구의 보안 위험 MCP 서버는 도구 설명문이 그대로 AI에게 읽히기 때문에, 검증되지 않은 도구를 붙이는 순간부터 사용자가 한 글자도 입력하기 전에 이미 외부 텍스트가 AI에게 영향을 주기 시작합니다.

차별되는 관점입니다.

• 모델 중심 담론과의 거리두기 더 똑똑한 GPT를 기다리는 분위기 대신, 지금 가진 모델로 갈 수 있는 한계를 끌어올리는 공학적 방법을 제시합니다. 오늘 보이는 AI의 한계와 모델이 실제로 가진 능력 사이의 간극은 대부분 하네스 간극이라는 진단입니다.
• 하네스는 사라지지 않고 자리를 옮긴다 모델이 좋아지면 어떤 하네스 부품은 필요 없어집니다. 예컨대 오푸스 4.6는 클로드 소넷 4.5에서 흔하던 “컨텍스트가 곧 끝날 것 같으니 빨리 마무리해야겠다”는 식의 조급증을 거의 없애 버렸고, 그 덕분에 그동안 쓰이던 안심용 보조 장치들이 통째로 죽은 코드가 됐습니다. 그러나 모델이 닿게 된 새로운 영역에는 새로운 약점이 있고, 그 약점을 메우는 새 하네스가 또다시 필요해집니다. “하네스의 모든 부품은 모델이 혼자 못하는 일이 무엇인지에 대한 가정을 담고 있다”는 앤트로픽의 표현이 잘 어울립니다.
• 모델과 하네스의 학습 순환 비브가 짚은 또 하나의 흐름은 하네스 설계와 모델 학습 사이의 되먹임 고리입니다. 하네스에서 유용한 패턴이 발견되면 그것이 표준화되고, 다음 세대 모델이 그 패턴을 기준으로 학습되며, 다시 그 모델 위에서 새로운 하네스 패턴이 만들어집니다. 그래서 “좋은 하네스”는 모델이 학습된 그 하네스가 아니라 자기 작업에 맞춰 다시 다듬은 하네스라는 결론이 나옵니다.
• 업계가 같은 모양으로 수렴 클로드 코드, 커서, 코덱스, 에이더, 클라인 같은 코딩 AI들은 속에 든 모델은 다르지만 하네스의 모양은 점점 닮아 가고 있습니다. 모델은 다 다른데 하네스는 비슷해진다는 사실은, 이 분야가 어디에 안착하고 있는지를 보여 주는 신호로 읽힙니다.

오스마니의 글은 코딩 AI의 경쟁력이 모델 선택보다 그 주변 하네스의 설계에 더 크게 좌우되며, 하네스는 한 번 세팅하고 끝나는 설정 파일이 아니라 실패 이력에 따라 계속 갱신되는 살아 있는 시스템이라는 관점을 제시합니다. 모델이 좋아진다고 해서 하네스가 사라지는 것이 아니라, 다루는 문제의 층위가 한 단계 위로 옮겨 가면서 새로운 하네스가 그 자리를 메우게 됩니다. 그가 인용한 비브의 표현처럼 “좋은 에이전트를 만드는 일은 반복의 예술이고, 첫 버전이 없으면 반복도 없다”는 말은 이 분야가 결국 누가 빨리 시작해 더 자주 다듬느냐의 싸움이라는 뜻으로 읽힙니다. 결국 엔지니어가 시간을 쏟아야 할 곳은 화제가 되는 모델을 매번 갈아 끼우는 일이 아니라, 자기 일에 맞는 하네스를 끊임없이 손보면서 모델이 닿는 천장을 한 칸씩 끌어올리는 작업이라는 결론으로 정리됩니다.

[click]

SDD 같은 건 벌써 hype가 죽었고 이제는 하네스인가봅니다.
하네스에서 좀 신기한 부분이 분명 학습 데이터에 없는데 모델이 harness 라는 개념을 금방 이해하더라고요
원래 존재하던 단어의 의미를 그대로 사용해서 그런지 언급도 안했는데 먼저 harness 를 갱신합니다 같은 언급도 하고요

[kimjoin2]

점점 마케팅 용어만 엄청 생기는 느낌이내요.

[kurthong]

별 알맹이 없는 얘기를 그럴듯하게 하는 고급개발자의 글을 분석까지 한 내용이네요(개인적으로 구글을 싫어해서 죄송합니다). 물론 현상에 대한 이해로의 접근은 좋은 시도라고 봅니다.