하네스 엔지니어링: 에이전트보다 환경이 먼저다

같은 모델을 쓰는데 A 회사에서는 Claude가 제법 일을 해내고, B 회사에서는 엉뚱한 방향으로 달립니다. 모델을 바꿔도, 프롬프트를 다듬어도 격차는 좁혀지지 않습니다. 원인은 에이전트 자체가 아니라 에이전트를 둘러싼 환경에 있습니다.

하네스(Harness) 엔지니어링 이 2026년 기업 AI의 다음 계층으로 떠오른 배경입니다. 프롬프트·컨텍스트 위에 올라가는 더 넓은 설계 층이며, 이미 강력한 에이전트에 ‘고삐’를 채우는 일입니다.

2025는 에이전트의 해, 2026은 하네스의 해

2025년은 AI 에이전트가 실제 코드를 쓸 수 있다는 것을 증명한 해였습니다. 2026년은 “에이전트가 아니라 하네스가 진짜 어려운 부분”이라는 것을 배운 해입니다.

흐름은 2026년 초부터 빠르게 이어졌습니다. 1월에는 Aakash Gupta의 “2025 was agents. 2026 is agent harnesses.”라는 선언이 업계에 돌았습니다. 2월에 들어서면서 Mitchell Hashimoto가 본인의 AI 도입기에서 “Engineer the Harness”를 핵심 단계로 정리했고, 같은 달 OpenAI도 Codex 팀의 5개월 실험 결과를 공식 보고서로 공개했습니다. 이후 3월에는 Anthropic, 4월에는 Martin Fowler 사이트까지 하네스 설계에 관한 본격적인 정리가 계속됐습니다.

가장 간명한 정리는 같은 시기 Addy Osmani의 한 문장입니다.

A decent model with a great harness beats a great model with a bad harness.

실제 제품에서 정량 효과도 나왔습니다. 법률 AI 회사 Harvey는 2026년 4월, 12개 법률 태스크 평균 정확도를 40.8%에서 87.7%로 끌어올렸다고 공개했는데, 공개된 분석에서 이 성과를 견인한 레버로 지목된 것은 모델 파인튜닝이 아니라 하네스 재설계였습니다.

하네스란 무엇인가

“하네스(Harness)“는 원래 말(馬)에 채우는 마구(馬具)입니다. 말의 힘 자체를 키우는 도구가 아니라, 그 힘을 안전하고 유용한 방향으로 이끄는 도구입니다. 소프트웨어 엔지니어링에서도 test harness, evaluation harness는 오래된 용어이고, AI 맥락에서도 의미가 동일합니다. 에이전트 자체를 바꾸는 것이 아니라, 에이전트가 일하는 환경을 바꾸는 것.

회사에 비유하면 이렇습니다. 프롬프트 엔지니어링이 “사수가 옆에서 말해 주는 것”이라면, 하네스 엔지니어링은 “회사의 업무 시스템(온보딩 문서, 업무 매뉴얼, 코드 컨벤션, CI/CD 파이프라인)을 만드는 일”입니다. 신입사원이 와도 시스템이 잘 갖춰져 있으면 알아서 일할 수 있는 것처럼, 에이전트도 하네스가 잘 설계되어 있으면 안정적으로 일합니다.

HumanLayer는 이를 한 줄 공식으로 정리했습니다. coding agent = AI model(s) + harness. 같은 모델이라도 하네스가 다르면 결과가 달라집니다.

프롬프트 → 컨텍스트 → 하네스

프롬프트, 컨텍스트, 하네스는 서로 경쟁하는 개념이 아니라 세 개의 층입니다.

구분	프롬프트 엔지니어링	컨텍스트 엔지니어링	하네스 엔지니어링
비유	”오른쪽으로 돌아” (명령)	지도, 표지판, 지형 (맥락)	고삐, 안장, 울타리, 도로 (환경 전체)
대상	하나의 질문과 응답	에이전트가 참조하는 정보	에이전트를 둘러싼 전체 시스템
핵심 질문	”뭘 시키지?"	"뭘 알려주지?"	"어떤 구조로 시키지?”
시기	2023~2024	2025 중반	2026 본격 확산

세 층의 위계에 대한 해석은 아직 통일되지 않았습니다. HumanLayer는 “하네스 엔지니어링은 컨텍스트 엔지니어링의 부분집합”이라고 정의하고, OpenAI와 Anthropic은 하네스를 컨텍스트를 포함하는 상위 시스템으로 다룹니다. 용어 논쟁보다 중요한 건 공통된 인식입니다. 프롬프트만으로 해결할 수 없는 문제가 있고, 그걸 환경과 메커니즘으로 해결한다.

하네스의 네 가지 구성 요소

실제로 설계할 때 무엇을 만져야 하는지는 현장에서 꽤 수렴해 있습니다. 네 개의 층입니다.

1. 컨텍스트 레이어: 에이전트가 가장 먼저 읽는 문서

CLAUDE.md(또는 AGENTS.md), docs/ 디렉토리, progress.md. 프로젝트의 목적·기술 스택·코딩 규칙·현재 진행 상황이 여기에 정리됩니다. 에이전트의 “업무 매뉴얼”입니다.

함정이 있습니다. 이 파일들을 거대하게 쓰면 실패합니다. OpenAI Codex 팀의 진단은 직설적입니다.

We tried the ‘one big AGENTS.md’ approach. It failed in predictable ways.

이유는 세 가지입니다. 컨텍스트는 희소 자원이라 거대한 instruction 파일이 실제 코드·문서를 밀어냅니다. 모든 것이 “중요”하면 아무것도 중요하지 않게 되어 에이전트가 의도적으로 네비게이션하지 않고 로컬 패턴 매칭에 빠집니다. 그리고 즉시 낡습니다. 권고 수치도 구체적입니다. HumanLayer는 일반 공감대가 300줄 이내, 가능하면 더 짧게라고 정리했고, 본인들의 루트 CLAUDE.md는 60줄이 채 안 됩니다. 프론티어 LLM조차 약 150~200개 instruction까지만 안정적으로 따른다고 보고됩니다.

2. 가드레일: 입력과 출력의 기술적 제어

프롬프트 인젝션과 기밀 혼입을 입구에서 막고, 할루시네이션과 범위 밖 작업을 출구에서 막습니다. OpenAI Codex 팀은 여기서 아키텍처 경계를 커스텀 린터와 구조 테스트로 기계적으로 강제하는 전략을 핵심으로 썼습니다. 포인트는 에러 메시지 안에 “왜 이 경계가 있는지”와 “어떻게 고치는지”를 같이 넣는 것입니다. 에러 메시지 자체가 에이전트를 가르치는 자료가 됩니다.

3. 피드백 루프와 엔트로피 관리

에이전트는 패턴 복제기입니다. 코드베이스의 기존 패턴을 찾아 복제합니다. 좋은 패턴이면 유용하지만 나쁜 패턴이면 문제가 빠르게 확산됩니다. 시간이 지날수록 품질이 썩어가는 엔트로피 증가가 하네스 설계의 가장 현실적인 숙제입니다.

상태는 대화가 아니라 파일에 기록해야 합니다. 세션이 끊기면 대화 안의 맥락은 사라집니다. Anthropic이 장기 실행 에이전트 사례에서 쓴 claude-progress.txt 패턴이 대표적입니다. 세션이 끊겨도 다음 세션이 바로 이어받을 수 있고, 에이전트가 “부분 완료”를 “완료”로 잘못 판단하는 문제도 줄어듭니다. 최근 Anthropic의 generator-evaluator 분리 설계는 여기서 한 발 더 나가, 일하는 에이전트와 판정하는 에이전트를 분리해 자기 평가의 신뢰도를 올리는 방향을 제시합니다.

4. 샌드박스와 도구 접근 제어

에이전트가 프로덕션 DB나 외부 서비스를 직접 건드리지 못하도록 격리하고, 접근 가능한 도구를 명시적으로 정의합니다. max token, cost budget 같은 비용 가드레일도 여기 속합니다. “제약은 에이전트의 능력을 제한하는 것이 아니라 집중시킨다”는 인사이트가 이 계층에 가장 직접적으로 드러납니다. 잘 제약된 에이전트가 오히려 더 좋은 결과를 냅니다. 하류 문제를 만드는 영역에 애초에 진입하지 못하기 때문입니다.

실전 사례와 설계 원칙

OpenAI Codex 팀은 2025년 8월 빈 리포지토리에서 시작해 5개월 동안, 사람이 코드를 한 줄도 쓰지 않고 약 100만 줄의 프로덕션 시스템을 만들었다고 공개했습니다. 약 1,500개의 PR이 머지됐고, 자체 추정으로 수동 개발 대비 약 10분의 1 시간에 해당하는 속도였습니다. 소수 엔지니어로 시작해 팀이 7명까지 커졌을 때 오히려 엔지니어당 throughput(하루 약 3.5 PR)이 증가했다고 보고했습니다. (OpenAI는 Codex 성능을 긍정적으로 보이게 할 인센티브가 있으니 수치 자체는 참고 수준으로 두고, 이 실험에서 도출된 설계 원칙에 주목하는 편이 좋습니다.)

실전에서 반복되는 원칙 몇 가지입니다.

• “지루한 기술”이 에이전트에게 더 안전합니다. 트렌디한 라이브러리의 불투명한 동작과 싸우는 것보다, 오래 검증된 기술이 에이전트의 학습 분포에 더 많이 들어 있어 실수가 적습니다. 기술 스택 선택 시 “에이전트 친화성”도 함께 고려해야 합니다.
• 거대한 매뉴얼은 실패합니다. CLAUDE.md는 “지도”가 아니라 “나침반”이어야 합니다. 세부 도메인 지식은 docs/로 분리하고, 루트 파일에는 핵심 규칙과 원칙만 남깁니다.
• “하면 안 되는 것”을 명시합니다. 에이전트에게 할 일만 알려 주면 범위가 끝없이 확장됩니다. 역할 간 경계는 금지 사항으로 만들어야 합니다.
• 실패를 일회성 픽스가 아니라 제약으로 영구화합니다. Mitchell Hashimoto의 문장이 이를 가장 잘 요약합니다.

Any time you find an agent makes a mistake, you take the time to engineer a solution such that the agent never makes that mistake again.

같은 실수를 프롬프트로 받아넘기면 다음 세션에 또 나옵니다. 수정은 린트 규칙, 서브에이전트 정의, docs/ 항목 같은 재사용 가능한 제약으로 고정해야 재발이 막힙니다.

• 하네스도 과적합됩니다. 규칙을 너무 촘촘히 짜면 에이전트의 판단 여지가 사라지고 속도가 내려갑니다. 모델이 업데이트될 때마다 기존 하네스의 각 부분이 여전히 필요한지 재검토해야 합니다. 더 이상 하중을 받지 않는 고삐는 걷어 내는 쪽이 낫습니다.

하이퍼이지가 하네스를 설계하는 방식

하이퍼이지는 사내 모든 프로젝트를 하네스 기반으로 운영합니다. 루트 CLAUDE.md는 수십 줄짜리 “헌법”으로 유지하고, 세부 지침은 docs/guidelines/로 분리합니다. 진행 상태는 progress.md에 기록해 세션이 끊겨도 이어받을 수 있게 하고, 역할별 서브에이전트는 .claude/agents/에 “참조 문서 → 해야 할 것 → 하면 안 되는 것 → 산출물 위치” 네 섹션으로 정의합니다. 반복 산출물(견적서·커리큘럼·우편 표지 등)은 .claude/skills/로 스킬화해, 사내 어느 세션이 실행해도 동일한 디자인과 품질이 나오도록 고정해 뒀습니다. 새로 합류한 엔지니어도 첫날부터 같은 수준의 산출물을 냅니다.

같은 원칙을 Company OS 는 기업 고객에게 제품으로 제공합니다. 자체 온톨로지 위에 54종 이상의 MCP 커넥터와 24시간 이상 감지·자동 워크플로우가 하나로 묶인 기업용 AI 운영체계입니다. 고객이 에이전트를 바로 풀어 놓는 대신, 에이전트가 움직일 환경을 기본값으로 갖추고 시작할 수 있게 합니다. 민감 데이터를 외부로 반출하지 않는 온프레미스·하이브리드 배포도 같은 맥락에서 제공됩니다.

2025년을 지나면서 우리가 배운 건 단순합니다. 에이전트는 이미 충분히 강력합니다. 차이를 만드는 건, 그 에이전트가 일할 환경을 얼마나 정교하게 설계하느냐입니다.