같은 모델을 쓰는데도 어떤 팀의 코딩 에이전트는 매번 기대한 결과를 내고, 어떤 팀의 에이전트는 같은 실수를 반복한다. 차이는 모델이 아니라 모델을 감싼 환경에서 나온다는 관찰이 늘고 있다. 이 환경을 의도적으로 설계하는 일을 하네스 엔지니어링(harness engineering)이라고 부른다. 2026년 들어 OpenAI와 Anthropic이 잇달아 실무 사례를 공개하면서, 프롬프트 엔지니어링 다음 단계의 개발 기술로 자리 잡는 추세다.
에이전트는 모델과 하네스의 합이다
실무자들 사이에서 자주 쓰이는 공식은 “에이전트 = 모델 + 하네스”다. 하네스는 모델을 뺀 나머지 전부를 가리킨다. 모델이 읽는 지침과 문서, 호출할 수 있는 도구, 해서는 안 되는 일의 경계, 결과를 검증해 되돌려 주는 장치가 모두 여기에 들어간다.
이 관점이 퍼진 계기는 OpenAI 엔지니어링 블로그의 Harness engineering 글이다. 2026년 2월 공개된 이 글에서 OpenAI 팀은 약 다섯 달 동안 사람이 직접 코드를 한 줄도 쓰지 않고 내부 베타 제품을 만들어 출시한 실험을 소개했다. 애플리케이션 로직, 테스트, CI 설정, 문서까지 Codex가 작성했고, 팀은 손으로 짰을 때보다 약 10분의 1 시간이 들었다고 추정했다. 글의 요지는 “사람은 방향을 잡고, 에이전트는 실행한다”는 한 줄로 요약된다. 사람의 일이 코드 작성에서 의도를 명세하고 실행을 제약하고 결과를 검증하는 쪽으로 옮겨 간다는 뜻이다.
Anthropic도 2025년 11월 엔지니어링 블로그에서 장시간 작업하는 에이전트용 하네스를 다뤘다. 첫 세션에서 프로젝트 골격과 기능 목록을 만드는 초기화 에이전트를 두고, 이후 세션의 코딩 에이전트는 진행 기록 파일과 git 이력을 읽고 이어서 일하도록 설계한 구조다. 컨텍스트 창이 바뀔 때마다 앞의 작업을 잊는 문제를 모델이 아니라 하네스로 푼 사례로 알려져 있다.
하네스를 이루는 네 가지 층
하네스는 막연한 개념처럼 보이지만, 실제로 손대는 지점은 대체로 네 층으로 나뉜다.
| 층 | 하는 일 | 대표 수단 |
|---|---|---|
| 컨텍스트 | 에이전트가 알아야 할 규칙과 배경을 준다 | AGENTS.md, CLAUDE.md, 설계 문서 |
| 도구 | 에이전트가 할 수 있는 행동을 정한다 | MCP 서버, 스킬, 사내 CLI |
| 제약 | 해서는 안 되는 일을 막는다 | 권한 설정, 훅, 린터, 구조 테스트 |
| 피드백 | 결과를 측정해 다음 시도에 반영한다 | 테스트, 평가 도구, 관측 도구 |
네 층 중 하나만 강해서는 효과가 제한적이다. 규칙 파일을 아무리 길게 써도 검증 장치가 없으면 에이전트가 규칙을 지켰는지 알 수 없고, 평가 도구만 있고 규칙이 없으면 같은 실패가 계속 측정만 된다.
규칙 파일: 에이전트가 처음 읽는 문서
가장 먼저 손대는 층은 저장소 루트의 규칙 파일이다. Codex를 비롯한 여러 코딩 에이전트는 AGENTS.md를, Claude Code는 CLAUDE.md를 세션 시작 시 읽는다. 여기에 빌드 명령, 코드 규칙, 금지 사항, 자주 틀리는 지점을 적는다.
- 짧고 구체적으로. “깔끔하게 짜라”보다 “API 응답 타입은 packages/types에만 정의한다”가 효과적이다.
- 반복된 실수를 기록한다. 에이전트가 같은 실수를 두 번 하면 그 자리에서 규칙으로 옮기는 방식이 많이 쓰인다.
- 목차 역할을 맡긴다. 긴 설계 문서는 따로 두고, 규칙 파일에는 “어떤 작업이면 어떤 문서를 읽어라”만 남기는 편이 컨텍스트를 아낀다.
훅과 스킬: 기억이 아니라 강제로
규칙 파일의 한계는 분명하다. 모델이 읽고 기억해서 지켜야 하므로, 긴 작업 중에는 놓치는 일이 생긴다. 그래서 반드시 지켜야 하는 규칙은 하네스가 강제하도록 옮기는 추세다.
Claude Code의 훅(hooks)이 대표적이다. 훅은 도구 호출 전후 같은 생명주기 지점에서 사용자가 정한 셸 명령을 실행한다. 도구 실행 전에 걸리는 훅은 호출 자체를 막을 수 있어서, “운영 서버 배포 명령은 차단”, “파일 저장 후 포매터와 린터 실행” 같은 규칙을 모델의 판단에 맡기지 않고 확정적으로 적용할 수 있다.
스킬은 반대 방향의 도구다. 특정 작업에 필요한 절차와 스크립트를 묶어 두면, 에이전트가 그 작업을 할 때만 불러와 따른다. 글쓰기, 배포 점검, 데이터 마이그레이션처럼 단계가 정해진 작업을 매번 같은 품질로 반복하게 만드는 수단이다.
하네스 엔지니어링의 핵심 질문은 “이 규칙을 모델이 기억해야 하는가, 시스템이 강제해야 하는가”다. 어기면 사고로 이어지는 규칙일수록 강제 쪽으로 옮긴다.
평가 도구: 하네스를 바꿨으면 측정한다
규칙 파일을 고치거나 훅을 추가했다면 결과가 실제로 좋아졌는지 확인해야 한다. 감으로 판단하면 한두 번의 성공 사례에 속기 쉽다. 이 단계에서 쓰이는 도구가 프롬프트·에이전트 평가 도구다.
오픈소스 평가 도구 promptfoo는 같은 과제를 여러 프롬프트와 모델 조합으로 돌려 결과를 표로 비교하고, 기대 조건을 자동으로 채점한다. MIT 라이선스로 공개돼 있으며, 2026년 OpenAI에 합류한 뒤에도 오픈소스로 유지된다고 밝혔다. 설정 파일 하나에 테스트 케이스를 쌓아 두면, 하네스를 바꿀 때마다 같은 묶음으로 회귀 테스트를 돌릴 수 있다.
평가와 함께 쓰이는 축이 관측(observability) 도구다. LangSmith, Langfuse 같은 도구는 에이전트가 실제로 어떤 순서로 도구를 부르고 어디서 시간을 쓰고 어디서 실패했는지 추적 기록으로 남긴다. 평가가 “결과가 좋아졌나”를 묻는다면, 관측은 “왜 실패했나”를 보여 준다.
하네스를 직접 짜는 경우
기존 코딩 에이전트에 규칙과 훅을 얹는 방식으로 부족하면, 하네스 자체를 코드로 만드는 선택지가 있다. Claude Agent SDK, OpenAI Agents SDK, LangGraph가 많이 쓰이는 출발점이다. 에이전트 루프, 도구 정의, 권한 판단, 상태 저장을 직접 통제할 수 있어서 사내 업무 자동화나 제품 안의 에이전트 기능을 만들 때 주로 쓰인다.
도입 순서는 대체로 다음과 같다.
- 에이전트가 반복해서 틀리는 지점을 기록하고 규칙 파일에 옮긴다.
- 어기면 사고가 나는 규칙을 골라 훅이나 권한 설정으로 강제한다.
- 반복 작업을 스킬로 묶어 절차를 고정한다.
- 대표 과제 10~20개로 평가 묶음을 만들고, 하네스를 바꿀 때마다 돌린다.
- 그래도 부족하면 SDK로 하네스를 직접 구성한다.
주의할 점
- 규칙 파일 비대화. 규칙을 계속 덧붙이기만 하면 컨텍스트를 잡아먹고 서로 충돌한다. 주기적으로 정리해 실제로 쓰이는 규칙만 남긴다.
- 훅의 부작용. 모든 파일 저장마다 무거운 검사를 걸면 작업이 느려진다. 강제할 규칙과 권고할 규칙을 구분한다.
- 평가 묶음의 편향. 쉬운 과제로만 평가하면 하네스 개선 효과가 과장된다. 실제로 실패했던 사례를 평가 묶음에 넣는 편이 정확하다.
정리
하네스 엔지니어링은 모델 성능 경쟁과 별개로, 같은 모델에서 더 안정적인 결과를 끌어내는 기술로 보인다. 규칙 파일로 맥락을 주고, 훅과 권한으로 경계를 강제하고, 평가와 관측 도구로 효과를 측정하는 흐름이 실무 표준으로 자리 잡는 중이다. 처음부터 거창한 시스템을 만들기보다, 에이전트가 두 번 틀린 지점 하나를 규칙이나 훅으로 바꾸는 데서 시작하는 편이 현실적이다.