하네스 엔지니어링: 코딩 에이전트 성능을 바꾸는 진짜 레버

핵심 요약

코딩 에이전트의 성능은 모델 자체보다, 그 주위를 감싼 하네스 설계에 크게 좌우된다.

하네스 엔지니어링은 에이전트의 실수를 "다음부터는 못 하게 만드는 시스템"으로 바꾸는 작업이다.

좋은 하네스는 프롬프트, 도구, 훅, 샌드박스, 메모리, 검증 루프를 묶어 모델의 잠재력을 실제 작업 능력으로 바꾼다.

코딩 에이전트는 모델만이 아니다

코딩 에이전트는 단순히 LLM 하나가 아니다.

실제로는 모델 위에 프롬프트, 도구 호출, 파일 접근, 실행 환경, 검증 장치, 실패 복구 흐름이 덧씌워진 시스템이다.

그래서 같은 모델을 써도 Claude Code, Cursor, Codex, Aider, Cline이 서로 다르게 느껴진다.

차이는 "두뇌"보다 "작업장"에 있다.

짧게 말하면, 모델이 생각하는 부분이라면 하네스는 일하는 방식 전체다.

좋은 모델에 허술한 하네스를 붙이면 자주 실수하고, 평범한 모델이라도 단단한 하네스 안에서는 훨씬 안정적으로 일한다.

하네스란 무엇인가

하네스는 모델이 아닌 모든 것이다.

여기에는 시스템 프롬프트, AGENTS.md, 도구 설명, MCP 서버, 파일시스템, 브라우저, 샌드박스, 서브에이전트, 로그, 비용 측정, 훅과 미들웨어가 포함된다.

비유하면 모델은 엔진이고, 하네스는 차체·브레이크·계기판·내비게이션·안전벨트다.

엔진만 좋아서는 목적지에 안전하게 도착할 수 없다.

특히 에이전트는 "도구를 반복적으로 사용해 목표를 달성하는 루프"로 움직이기 때문에, 도구 설계와 루프 설계가 성능의 핵심이 된다.

"모델 문제"보다 "설정 문제"인 경우가 많다

에이전트가 멍청한 행동을 하면 보통 모델을 탓하기 쉽다.

하지만 하네스 엔지니어링 관점에서는 많은 실패가 읽을 수 있는 실패다.

예를 들어 규칙을 몰라 잘못 수정했다면 AGENTS.md에 규칙을 넣으면 된다.

위험한 명령을 실행했다면 차단 훅을 추가하면 된다.

긴 작업에서 길을 잃는다면 계획자와 실행자를 나누면 된다.

즉, 실패를 "다음 모델이 나오면 해결될 문제"로 미루지 않고, 지금의 시스템 설계 문제로 다룬다.

이 태도가 하네스 엔지니어링의 출발점이다.

실수는 일회성이 아니라 규칙의 재료다

좋은 하네스는 실패를 기억한다.

에이전트가 테스트를 주석 처리한 채 끝냈다면, 다음부터는 그 패턴을 금지하는 규칙을 추가한다.

필요하면 diff에서 .skip(나 xit(를 찾는 훅을 달고, 리뷰용 서브에이전트도 같은 문제를 잡게 만든다.

핵심은 "실수를 웃고 넘기지 말고, 시스템 규칙으로 고정하라"는 것이다.

그래서 좋은 AGENTS.md의 각 문장은 과거의 실제 사고 기록과 연결되어야 한다.

브레인스토밍으로 늘린 규칙집보다, 실패 이력으로 다듬은 짧은 규칙집이 더 강하다.

원하는 행동에서 거꾸로 하네스를 설계한다

좋은 설계 방식은 먼저 원하는 행동을 정하는 것이다.

그다음 그 행동을 만들 하네스 요소를 붙인다.

예를 들어 "코드를 고친 뒤 항상 타입체크가 돌았으면 좋겠다"면, 프롬프트에만 적는 것이 아니라 edit 후 훅으로 자동 실행하게 만드는 식이다.

이 방식의 장점은 각 구성요소가 왜 존재하는지 분명해진다는 점이다.

어떤 부품이 어떤 행동을 보장하는지 설명할 수 없다면, 그 부품은 복잡성만 늘릴 가능성이 크다.

하네스는 기능 모음집이 아니라, 행동을 설계하는 장치여야 한다.

파일시스템, Git, Bash는 에이전트의 기본 체력이다

파일시스템은 장기 작업의 바닥이다.

모델은 컨텍스트에 들어온 것만 직접 다루지만, 파일시스템이 있으면 문서·코드·중간 결과물을 바깥에 저장하고 다시 읽을 수 있다.

여기에 Git이 붙으면 진행 상황 추적, 실험 분기, 롤백이 가능해진다.

Bash와 코드 실행은 범용 도구다.

모든 행동을 전용 API 도구로 만들 수도 있지만, 셸을 주면 에이전트는 필요한 도구를 스스로 조합한다.

이건 "단일 주방기구 하나 주기"와 "주방 전체를 열어주기"의 차이에 가깝다.

현대 코딩 에이전트가 셸 중심으로 강해지는 이유다.

샌드박스와 기본 도구는 안전한 작업장을 만든다

에이전트가 만든 코드를 바로 로컬에서 실행하는 것은 위험하다.

그래서 하네스는 샌드박스를 제공해 격리된 환경에서 실행하게 한다.

샌드박스는 명령 허용 범위를 조절하고, 네트워크를 제한하고, 병렬 작업용 환경을 여러 개 띄웠다가 지울 수 있게 해준다.

또 좋은 샌드박스는 언어 런타임, 패키지, Git, 테스트 도구, 헤드리스 브라우저 같은 기본 장비를 미리 갖춘다.

에이전트가 자기 결과를 검증하려면 실행 환경과 관찰 수단이 함께 필요하다.

즉, "어디서 실행하고 무엇으로 확인할지"는 모델의 능력이 아니라 하네스의 책임이다.

메모리와 검색은 가벼운 지속 학습 장치다

모델은 학습이 끝난 뒤 새로운 지식을 저절로 얻지 못한다.

그래서 하네스는 컨텍스트 주입으로 이를 보완한다.

대표적인 방식이 AGENTS.md 같은 메모리 파일이다.

매 세션 시작 때 이 파일을 넣어주고, 에이전트가 수정하면 다음 세션에도 반영되게 한다.

정교한 학습은 아니지만, 반복적으로 같은 실수를 줄이는 데는 충분히 효과적이다.

또 최신 라이브러리 문서나 현재 데이터처럼 학습 시점 이후의 정보는 웹 검색이나 Context7 같은 도구로 메운다.

이 역시 사용자가 일일이 처리하기보다 하네스에 기본 내장될수록 강해진다.

긴 작업의 적은 컨텍스트 부패다

컨텍스트가 길어질수록 모델의 추론 품질이 흐려지는 현상을 흔히 컨텍스트 로트라고 본다.

좋은 하네스는 이를 줄이기 위해 오래된 대화를 압축하고, 긴 로그는 앞뒤만 남기고 파일로 빼며, 필요한 기술이나 도구만 그때그때 드러낸다.

아주 긴 작업에서는 아예 세션을 새로 시작하고, 핵심 상태만 정리한 인수인계 파일로 이어가는 방식도 쓴다.

이건 사람 팀에서 새 담당자에게 브리핑 문서를 주는 것과 비슷하다.

핵심은 메모리를 무한히 늘리는 것이 아니라, 중요한 상태만 살아남게 만드는 것이다.

장기 실행에는 계획, 검증, 역할 분리가 필요하다

긴 작업에서 모델은 너무 일찍 멈추거나, 복잡한 문제를 잘게 나누지 못하거나, 시간이 갈수록 일관성을 잃기 쉽다.

그래서 하네스는 종료 시도를 가로채 다시 이어서 일하게 하거나, 계획 파일을 먼저 쓰게 하고 그 계획을 따라 움직이게 만든다.

또 각 단계 뒤에는 테스트, 타입체크, 리뷰 기준 같은 검증 루프를 둔다.

특히 생성자와 평가자를 분리하는 방식이 중요하다.

코드를 만든 주체가 자기 결과를 스스로 채점하면 대체로 후해지기 쉽기 때문이다.

먼저 "무엇이 완료인가"를 합의한 뒤 작업하게 만드는 스프린트 계약도 범위 이탈을 줄이는 데 효과적이다.

훅은 지시를 규칙으로 바꾸는 집행 장치다

프롬프트는 부탁이고, 훅은 강제다.

훅은 도구 호출 전, 파일 수정 후, 커밋 전, 세션 시작 시점처럼 특정 순간에 자동으로 실행되는 스크립트다.

예를 들어 모든 수정 뒤 타입체크와 테스트를 돌리고, 실패하면 그 에러를 다시 모델에게 넣어 수정하게 할 수 있다.

또 rm -rf, git push --force, DROP TABLE 같은 파괴적 행동을 사전에 막을 수 있다.

좋은 피드백 루프는 평소엔 조용하고, 실패할 때만 자세하다.

성공했을 때는 토큰을 낭비하지 않고, 실패했을 때만 바로 고칠 수 있는 정보를 주는 방식이 가장 효율적이다.

AGENTS.md와 도구 수는 적을수록 강하다

루트의 AGENTS.md는 매우 작은 문서지만 영향력은 크다.

보통 매 턴 시스템 컨텍스트에 들어가기 때문에, 패키지 매니저, 테스트 방식, 금지 구역, 로깅 규칙 같은 팀 규범을 담기에 적합하다.

하지만 길수록 좋은 것은 아니다.

규칙이 너무 많으면 하나하나의 중요도가 떨어지고, 모델도 덜 따른다.

그래서 짧고 선명해야 한다.

스타일 가이드가 아니라 조종석 체크리스트처럼 써야 한다.

도구도 마찬가지다.

비슷한 도구를 잔뜩 주는 것보다, 역할이 분명한 몇 개를 주는 편이 모델이 더 잘 쓴다.

또 MCP 서버 설명 자체가 프롬프트에 들어가므로, 부주의하거나 악의적인 도구 설명은 프롬프트 인젝션 위험이 될 수 있다.

모델이 좋아질수록 하네스가 사라지는 것이 아니라 이동한다

모델 성능이 오르면 어떤 하네스 부품은 불필요해진다.

예전에는 컨텍스트 한계에 대한 불안 때문에 필요했던 보조 장치가, 더 강한 모델에서는 쓸모없어질 수 있다.

하지만 그게 하네스의 종말은 아니다.

대신 더 어려운 문제를 다루기 위한 새로운 하네스가 필요해진다.

예를 들어 며칠짜리 메모리 정책, 여러 전문 에이전트의 협업, UI 품질을 평가하는 별도 평가자 같은 요소가 새로 중요해진다.

즉, 하네스는 작아지는 것이 아니라 문제 수준에 맞게 자리를 옮긴다.

모델이 잘하게 된 것은 빼고, 새 한계를 넘기 위한 구조를 더해야 한다.

하네스와 모델은 함께 진화한다

최신 에이전트 제품의 모델은 특정 하네스 안에서 후속 학습되는 경우가 많다.

그래서 파일 조작, Bash 사용, 계획 작성, 서브에이전트 호출 같은 행동은 어떤 하네스 안에서 특히 더 잘 작동한다.

이 말은 곧, 모델이 특정 도구 방식에 어느 정도 익숙해져 있을 수 있다는 뜻이다.

예를 들어 도구 로직을 살짝 바꿨는데 예상 못 한 성능 저하가 생길 수 있다.

실무적으로는 두 가지가 중요하다.

하네스는 한 번 세팅하고 끝나는 정적 설정이 아니라 계속 조정해야 하는 살아 있는 시스템이라는 점, 그리고 "모델이 원래 훈련된 하네스"가 아니라 "내 작업에 맞는 하네스"가 최선일 수 있다는 점이다.

하네스 API 시대와 앞으로의 방향

이제는 단순한 LLM API보다, 루프·도구·컨텍스트 관리·훅·샌드박스를 묶어 제공하는 하네스 API가 중요해지고 있다.

개발자는 밑바닥 루프를 매번 새로 짜기보다, 이미 잘 나뉜 프레임워크 위에서 시스템 프롬프트, 도구, 컨텍스트, 서브에이전트를 조정하는 쪽으로 이동한다.

이 변화는 반복 개선을 쉽게 만든다.

처음부터 완벽한 에이전트를 만들기보다, 작은 v0.1을 만든 뒤 실패를 규칙으로 바꾸며 키워갈 수 있기 때문이다.

앞으로는 여러 에이전트의 병렬 협업, 자기 추적 로그를 분석해 스스로 하네스 문제를 고치는 구조, 작업마다 필요한 도구와 문맥을 즉시 조립하는 동적 하네스가 더 중요해질 가능성이 크다.

정적인 설정 파일에서, 상황에 맞게 구조를 생성하는 컴파일러 같은 방향으로 진화하는 셈이다.

인사이트

코딩 에이전트 성능을 올리고 싶다면 먼저 모델 교체보다 하네스를 의심하는 습관이 유용하다.

가장 실용적인 출발점은 세 가지다. 짧은 AGENTS.md를 만들고, 자주 나는 실수 하나를 훅으로 막고, 수정 뒤 자동 검증을 붙이는 것이다.

핵심 원칙은 단순하다. 에이전트의 실패를 운으로 넘기지 말고, 다음번엔 구조적으로 불가능하게 만들어라.

출처 및 참고 : AddyOsmani.com - Agent Harness Engineering