하네스 엔지니어링의 정의
AI 에이전트를 운영 환경에 투입하면, 모델 성능보다 환경 설정이 결과를 좌우하는 상황을 자주 만난다. 같은 모델인데 프로젝트 A에서는 제대로 동작하고, 프로젝트 B에서는 엉뚱한 결과를 내놓는다. 프롬프트를 아무리 다듬어도 개선되지 않는 이 격차는 대부분 에이전트를 감싸는 환경의 차이에서 온다.
실제로 최근 OpenAI의 한 내부 실험 에서는 에이전트를 감싸는 환경만 제대로 구축했을 뿐인데, 수동으로 작성된 코드는 전혀 없이 AI가 생성한 백만 개 라인에 달하는 프로덕션 소프트웨어를 완성하는 결과를 보여주었다.
2026년 2월, 이 놀라운 차이를 만들어내는 영역에 이름이 붙었다. 바로 하네스 엔지니어링(harness engineering)이다. OpenAI가 정의하는 하네스(harness)는 AI 에이전트(Codex 등)가 안정적인 작업을 수행할 수 있도록 감싸는 스캐폴딩(scaffolding)이자 피드백 루프(feedback loop)가 구축된 전체 환경을 뜻한다. 저장소(Repository) 구조, CI 설정, 포맷 규칙, 패키지 관리자, 애플리케이션 프레임워크부터 프로젝트 지시 사항, 외부 도구 연결, 린터 등 에이전트 바깥에서 동작하는 시스템 전체가 하네스다. 이는 에이전트가 그 안에서 궤도를 이탈하지 않도록 돕는 기반 인프라 역할을 한다.
이 맥락에서 하네스 엔지니어링은 엔지니어의 주된 역할이 수동으로 코드를 작성하는 것에서 벗어나, 에이전트가 소프트웨어를 자율적으로 구축하고 유지보수할 수 있도록 환경을 설계하고, 의도를 명확히 지정하며, 피드백 루프를 구축하는 작업으로 재정의된 것을 의미한다.
프롬프트, 컨텍스트, 하네스의 관계
하네스 엔지니어링을 이해하려면 먼저 프롬프트 엔지니어링, 컨텍스트 엔지니어링과의 관계를 짚어야 한다. 세 개념은 포함 관계를 이루고 있어서 안쪽부터 바깥쪽으로 확장된다.
이 세 가지 개념은 에이전트를 설계할 때 초점을 맞추는 영역이 각기 다르다.
| 구분 | 핵심 질문 | 설계 대상 |
|---|---|---|
| 프롬프트 엔지니어링 | “무엇을 물어볼까?” | LLM에 전달하는 지시문 |
| 컨텍스트 엔지니어링 | “무엇을 보여줄까?” | LLM이 추론 시점에 보는 모든 토큰 |
| 하네스 엔지니어링 | “전체 환경을 어떻게 설계할까?” | 에이전트 바깥의 제약, 피드백, 운영 시스템 |
프롬프트 엔지니어링이 “오른쪽으로 돌아”라는 음성 명령이라면, 컨텍스트 엔지니어링은 말에게 보여주는 지도와 이정표다. 하네스 엔지니어링은 고삐, 안장, 울타리, 도로 정비까지 합쳐서 말 열 마리를 동시에 안전하게 달리게 만드는 전체 설계에 해당한다.
관계를 보는 시각은 논자마다 조금 다르다. 위 표처럼 포함 관계(하네스 > 컨텍스트 > 프롬프트)로 보는 것이 직관적이지만, “컨텍스트 엔지니어링은 모델이 잘 생각하게 돕고, 하네스 엔지니어링은 시스템이 궤도를 이탈하지 않게 막는다”는 상호 보완적 관점도 있다. 실무에서 중요한 것은 프레이밍이 아니라, 컨텍스트 설계만으로는 다루지 못하는 영역이 존재한다는 인식이다.
프롬프트에서 컨텍스트로, 컨텍스트에서 하네스로
세 개념이 순서대로 등장한 데는 AI 활용 방식의 변화가 있다.
프롬프트 엔지니어링 시기에는 ChatGPT에 질문 하나를 던지고 답변 하나를 받는 구조였다. 역할을 부여하고, 단계별로 시키고, 예시를 넣는 것만으로 원하는 결과를 끌어낼 수 있었다.
2025년 중반부터 흐름이 바뀌었다. 안드레이 카르파티(Andrej Karpathy)가 “프롬프트보다 컨텍스트 엔지니어링이 핵심”이라고 언급하면서 컨텍스트 엔지니어링이 주목받기 시작했다. 모델이 추론할 때 보는 맥락 전체를 설계해야 한다는 관점이다. LLM에 단순히 질문을 잘 쓰는 것이 아니라, 무엇을 보여줄지 시스템 수준에서 관리하는 접근이었다.
그런데 AI 에이전트가 본격적으로 운영 환경에 들어오면서 컨텍스트 설계만으로는 부족한 영역이 드러났다. 에이전트가 수많은 단계를 자율적으로 실행하는 상황에서는 다른 종류의 문제가 생긴다. 팀의 컨벤션을 지키지 않거나, 아키텍처 의존성 방향을 위반하는 코드를 생성하거나, 병렬 실행 중 파일 충돌이 발생하거나, 생성된 코드의 품질이 점진적으로 떨어지는 엔트로피 문제가 발생한다. 이런 것들은 “모델에게 무엇을 보여줄까”가 아니라 “시스템이 무엇을 막고, 측정하고, 고칠 것인가”의 문제다.
2026년 2월, 해시코프(HashiCorp) 공동 창업자인 미첼 하시모토(Mitchell Hashimoto)가 자신의 블로그 글에서 에이전트가 실수할 때마다 같은 실수를 방지하는 장치를 쌓아가는 작업을 “하네스 엔지니어링”이라 불렀다. 며칠 뒤 OpenAI도 “Harness engineering: leveraging Codex in an agent-first world”라는 글을 발표하면서 용어가 빠르게 퍼졌다.
시기별 흐름
2023~2024 프롬프트 엔지니어링 전성기
질문 한 번, 답변 한 번 구조에서 지시문 최적화
2025 중반 컨텍스트 엔지니어링 부상
Karpathy 발언, LangChain, Anthropic 공식 정의
RAG, MCP, 메모리 등 시스템 수준 맥락 설계
2026.02 하네스 엔지니어링 등장
Mitchell Hashimoto 블로그 (2026.02.05)
OpenAI 실전 보고서 (2026.02.11)
에이전트 전체 환경 설계로 범위 확장
하네스의 구성 요소
하네스는 에이전트 바깥에서 동작하는 여러 장치의 합이다. 개별 장치가 무엇이고 어떤 역할을 하는지 정리하면 다음과 같다.
컨텍스트 파일
CLAUDE.md, AGENTS.md, .cursorrules 같은 프로젝트 지시 파일이다.
에이전트가 작업을 시작할 때 읽는 문서로, 프로젝트 구조, 코딩 규칙, 네이밍 컨벤션 등을 담는다.
OpenAI는 이를 진실의 원천(System of Record)으로 삼아야 한다고 강조한다. 슬랙 대화나 사람의 머릿속에만 있는 ‘문서화되지 않은 지식’은
에이전트가 접근할 수 없으므로, 모든 아키텍처 결정과 실행 계획은 마크다운과 같은 형태의 저장소 내 문서로 존재해야 한다.
특히 OpenAI 실험에서는 초기에 “하나의 큰 AGENTS.md” 접근 방식을 시도했으나, 이는 예측 가능한 방식으로 실패했다.
컨텍스트 윈도우는 희소한 자원이기에 거대한 지침 파일은 에이전트가 주요 제약 조건을 놓치게 만들었고,
모든 것이 중요하다고 적혀 있어 오히려 에이전트가 지침을 무시하고 패턴 매칭만 수행하게 만들었다.
결국 거대 매뉴얼은 낡은 규칙들의 무덤이 되어 순식간에 망가졌다.
이를 해결하기 위해 AGENTS.md를 백과사전이 아닌 목차(Map)로 취급하는 방식으로 전환했다.
docs/
├── design-docs/
│ ├── index.md
│ └── core-beliefs.md
├── exec-plans/
│ └── tech-debt-tracker.md
├── product-specs/
└── references/
└── design-system-reference-llms.txt
이처럼 에이전트가 현재 작업 디렉터리에서 가까운 지시 파일만 읽게 하면 컨텍스트 윈도우 낭비를 줄이면서도 필요한 규칙을 정확히 전달할 수 있다.
MCP 서버
MCP(Model Context Protocol)는 에이전트가 외부 도구와 데이터 소스에 접근할 수 있게 해주는 프로토콜이다. 이슈 트래커에서 티켓을 읽거나, 브라우저를 자동화하거나, 사내 문서를 검색하는 등의 작업이 가능해진다.
# Claude Code에서 MCP 서버를 추가하는 예시
claude mcp add --transport http jira https://mcp.jira.example.com/mcp
claude mcp add --transport stdio github -- npx -y @modelcontextprotocol/server-github
다만 MCP를 많이 연결하는 것이 항상 좋은 것은 아니다. 도구 정의 자체가 토큰을 소비하기 때문에, 작업에 필요한 MCP만 선별적으로 연결하는 것이 실무에서 더 효과적이다. 이처럼 MCP 연동 방법과 주의할 점은 별도 글에서 다룬 바 있다.
스킬 파일
에이전트 스킬(Agent Skills)은
반복되는 작업 절차를 문서화한 것이다. SKILL.md 파일에 작업 지침을 정리해두면 에이전트가 필요한 시점에 읽고 수행한다.
코드 리뷰 체크리스트, 배포 워크플로우, 특정 프레임워크의 패턴 등을 스킬로 만들 수 있다.
기계적 강제(Mechanical Enforcement)와 코드 가비지 컬렉션
하네스에서 컨텍스트 엔지니어링과 가장 뚜렷하게 구분되는 부분이다. OpenAI는 에이전트가 코드를 양산하는 환경에서 아키텍처의 일관성(“취향”)을 유지하기 위해 커스텀 린터(Linter)와 구조 테스트를 사용했다.
단순히 에러만 띄우는 것이 아니라, 린터가 실패할 때 에러 메시지에 ‘어떻게 수정해야 하는지(correction instructions)’를 에이전트의 컨텍스트에 직접 주입하도록 설계했다. 예를 들어, 도메인 의존성 방향을 다음과 같이 기계적으로 강제(Mechanical Enforcement)했다.
Types -> Config -> Repo -> Service -> Runtime -> UI
이 방향을 위반하는 코드가 생성되면 린터가 이를 차단하고, 에이전트가 스스로 수정하도록 피드백 루프가 즉시 가동된다. 문서에 규칙을 적어두는 것만으로는 에이전트가 이를 위반할 수 있지만, 시스템적으로 강제하면 이를 사전에 방지할 수 있다.
엔트로피와 가비지 컬렉션 또한, 에이전트가 코드를 대량으로 생성하면 필연적으로 안 좋은 패턴을 복제하여 기술 부채(AI Slope, 엔트로피)가 쌓인다. OpenAI는 사람이 날 잡고 이를 청소하는 대신, 백그라운드 에이전트를 띄워 지속적으로 코드와 문서의 편차를 스캔하고 리팩토링 PR을 올리도록 했다. 즉, 낡은 패턴과 부채를 치우는 코드 가비지 컬렉션( Garbage Collection) 역할을 자동화한 것이며, 이 역시 하네스 설계의 중요한 부분이다.
관찰 가능성(observability) 도구도 하네스의 일부다. 에이전트에 로그(LogQL), 메트릭(PromQL), DOM 스냅샷 같은 런타임 정보에 접근하는 권한을 주면 자신이 작성한 코드를 스스로 디버깅하고 검증할 수 있게 된다.
하네스가 결과를 바꾼 실험들
개념 설명만으로는 하네스의 영향이 와닿지 않을 수 있다. 2026년 초에 공개된 실험 결과 세 가지가 이를 구체적으로 보여준다.
OpenAI Codex: 백만 개 라인, 수동 코드 0
앞서 서두에서 언급한 OpenAI 내부 팀의 실험이다. 2025년 8월부터 약 5개월에 걸쳐 Codex 에이전트만으로 프로덕션 소프트웨어를 만들었다. 엔지니어 3명으로 시작해 7명까지 늘렸고, 약 1,500개의 풀 리퀘스트를 머지했다. 수동으로 작성된 코드는 전혀 없으며, 생성된 코드 규모는 약 백만 개 라인이다. 수동 개발 대비 약 10배 빠른 속도였다고 보고됐다.
주목할 점은 처음부터 잘 된 것이 아니라는 것이다. 초기에는 환경 설정 부족, 도구 연결 미비, 에러 복구 로직 부재로 생산성이 낮았다. 하네스를 하나씩 개선해나가면서 성과가 폭발적으로 올라갔다. 팀 내부에서는 “엔지니어링 팀의 주된 역할이 에이전트가 유용한 일을 할 수 있게 만드는 것이 됐다”고 언급했다.
OpenAI Codex 실험 요약
기간 : 2025.08 ~ 2026.01 (약 5개월)
팀 규모 : 3명 → 7명
수동 코드 : 0줄 (전혀 없음)
생성 코드 : 약 백만 개 라인
풀 리퀘스트 : 약 1,500개 머지
일 평균 PR : 엔지니어 1인당 3.5개
속도 추정 : 수동 개발 대비 약 10배
Hashline: 도구 형식 하나로 6.7%에서 68.3%
보안 연구자 Can Boluk는 2026년 2월, Hashline이라는 실험을 공개했다. 16개 LLM 모델을 대상으로, 에이전트가 파일을 수정하는 방식(edit format)만 바꿔봤다. 기존에는 정확한 텍스트 재현이나 구조화된 diff를 요구했지만, Hashline은 각 줄에 2~3자리 해시를 붙여 참조하게 했다.
1:a3|function hello() {
2:f1| return "world";
3:0e|}
모델이 “2:f1 줄을 교체해라”처럼 해시로 위치를 지정하면, 정확한 문자열 재현 없이도 편집이 가능하다. 결과는 놀라웠다. Grok Code Fast 1 모델은 동일 벤치마크에서 6.7%에서 68.3%로 점수가 뛰었고, 전체 모델 평균 출력 토큰도 약 20% 줄었다. 모델 가중치를 건드리지 않고 하네스만 바꾼 결과다.
LangChain: 순위 30위에서 5위
LangChain은 자사 코딩 에이전트를 Terminal Bench 2.0 벤치마크에서 테스트했다. 모델(gpt-5.2-codex)은 고정한 채 하네스만 개선한 결과, 점수가 52.8%에서 66.5%로 13.7포인트 상승했다. 순위로는 30위권에서 5위권으로 올라갔다.
개선의 핵심은 실패 패턴을 자동 분석하는 도구였다. LangSmith 트레이스에서 실패 원인을 수집하고, 에이전트가 스스로 검증하는 루프를 추가했다. 시스템 프롬프트, 도구, 미들웨어 세 가지가 조정 대상이었다.
세 실험 모두 같은 결론을 가리킨다. 모델을 바꾸기 전에 하네스를 점검하는 것이 투자 대비 효과가 크다.
어디서부터 시작할 수 있는가
하네스 엔지니어링을 처음 적용할 때 한꺼번에 모든 장치를 갖출 필요는 없다. 아래 세 가지가 실무에서 가장 빠르게 효과를 확인할 수 있는 출발점이다.
1) 컨텍스트 파일 작성
프로젝트 루트에 CLAUDE.md나 AGENTS.md를 만들고, 프로젝트 구조, 빌드 명령, 코딩 규칙을 넣는다.
처음에는 짧게 시작하되, 에이전트가 반복적으로 틀리는 부분이 있으면 해당 규칙을 추가해나간다.
미첼 하시모토의 접근도 동일하다. 에이전트가 실수할 때마다 같은 실수를 방지하는 지시를 쌓아가는 것이 하네스의 기본이다.
# CLAUDE.md 예시 (프로젝트 루트)
## 빌드
- `./gradlew build` 로 전체 빌드
- `./gradlew test` 로 테스트 실행
## 코딩 규칙
- 패키지 의존 방향: domain -> application -> infrastructure
- infrastructure에서 domain을 직접 참조하지 않는다
- 엔티티는 지연 로딩 기본, Fetch Join으로 N+1 해결
## 커밋
- 커밋 메시지는 한국어, 마침표 없이 작성
2) MCP 연결
에이전트가 자주 참조하는 외부 시스템이 있다면 MCP로 연결한다. 이슈 트래커, 위키, 모니터링 시스템 등이 대상이다. 다만 필요한 것만 연결해야 토큰 낭비를 막을 수 있다.
3) 린터(Linter)와 CI 연동
에이전트가 생성한 코드가 기존 아키텍처 규칙을 따르는지 자동으로 검증하는 장치를 추가한다. 이미 린터와 CI가 있다면 에이전트가 그 결과를 읽을 수 있게 연결하는 것만으로도 효과가 있다. 에이전트가 CI 실패 로그를 보고 스스로 수정하는 피드백 루프가 만들어지기 때문이다.
팀마다 도구 스택과 워크플로우가 다르기 때문에, 하네스의 구체적인 구성도 달라질 수밖에 없다. 중요한 것은 “에이전트가 반복적으로 실패하는 지점”을 관찰하고, 그 지점에 하네스를 추가해나가는 접근이다.
모델이 아니라 환경이 병목이다
하네스 엔지니어링이 등장한 배경에는 한 가지 관찰이 깔려 있다. 에이전트 성능의 병목은 모델 지능이 아니라 환경 설계인 경우가 많다는 것이다.
나 역시 관련된 업무를 하면서 어떤 모델이 더 좋은 결과를 낼지 GPT, Gemini, Claude 등을 열심히 비교해 보곤 했다. 물론 모델 간 차이는 분명 존재하지만, 실제 성능 차이를 더 크게 만드는 것은 모델 자체보다 그것을 둘러싼 실행 환경인 경우가 많았다.
모델 성능은 빠르게 상향 평준화되고 있다. GPT 시리즈가 앞서면 Claude가 따라오고, Gemini도 금세 올라온다. 반면 하네스는 팀이 직접 쌓아야 하는 자산이다. 도구 연결, 에러 복구 로직, 아키텍처 제약, 문서 구조는 범용 모델처럼 한 번에 배포되지 않는다. 그래서 지금 하네스에 투자하는 것이 이후에 실질적인 생산성 격차를 갖게 될 가능성이 높다.
물론 기술 발전이 너무 빠르다 보니, 1년은커녕 당장 1 ~ 2달 뒤의 미래조차 예측하기 어려워 이 격차가 영원할 것이라 단언하기는 조심스럽다. 하지만 적어도 지금 시점에서는 개인 개발자에게도 마찬가지다. AI 도구를 설치하고 사용하는 것은 이제 진입 장벽이 아니다. 차이를 만드는 것은 그 도구가 동작하는 환경을 얼마나 잘 설계하느냐다.
오늘의 정답이 내일은 다른 정답으로 바뀌는 상황이라, 참 어렵다.