하네스 엔지니어링이란? 프롬프트를 넘어 에이전트를 길들이는 새로운 엔지니어링
AI 에이전트 시대, 프롬프트는 '부탁'이고 하네스는 '강제'다. OpenAI Codex 팀이 100만 줄을 수동 작성 없이 만든 비결, 하네스 엔지니어링의 정의와 핵심 구성요소를 정리했습니다.
2026년 2월, OpenAI 내부의 3명의 엔지니어가 5개월 만에 약 100만 줄의 프로덕션 코드를 만들었습니다. 놀라운 건 규모가 아닙니다. 인간이 직접 작성한 코드가 단 한 줄도 없다는 점입니다. Codex 에이전트에게 작업을 지시하고, PR을 검토하고, CI 파이프라인을 관리했을 뿐이죠.
그런데 이 실험에서 팀이 얻은 가장 중요한 교훈은 AI의 코딩 능력에 관한 것이 아니었습니다. 초기 진행이 예상보다 느렸는데, 원인은 에이전트의 능력 부족이 아니라 에이전트가 일할 환경이 갖춰지지 않았기 때문이었습니다.
이 환경을 설계하는 분야가 바로 **하네스 엔지니어링(Harness Engineering)**입니다.
하네스의 어원
"하네스(Harness)"는 말에게 씌우는 마구(馬具)입니다. 고삐, 안장, 재갈, 등자로 이루어진 장비 전체를 뜻하죠. 말은 빠르고 강하지만, 마구 없이는 짐을 나를 수도, 기수의 의도대로 움직일 수도 없습니다. 마구는 말의 능력을 제한하는 것이 아니라, 그 힘을 원하는 방향으로 전달하고 제어하는 장치입니다.
AI 에이전트도 같은 상황입니다. GPT-5든 Claude든, 2026년의 프론티어 모델은 이미 코드를 쓰고, 테스트를 만들고, 버그를 찾아 수정하는 능력을 갖추고 있습니다. 문제는 고삐 없이 풀어놓았을 때 벌어지는 일이죠.
에이전트 하나가 한 번 작업하는 건 어떻게든 됩니다. 문제는 규모가 커질 때입니다. 10개의 에이전트가 동시에 100개의 파일을 수정하면, 제약 없이는 카오스가 됩니다. 프로젝트 코딩 컨벤션은 무시되고, 이미 있는 유틸 함수를 중복 생성하고, 데이터베이스를 UI 레이어에서 직접 호출하는 식이죠.
프롬프트는 부탁이고, 하네스는 강제다
"프롬프트 엔지니어링이랑 뭐가 다른가요?"라는 질문이 자연스럽게 나옵니다. 차이는 명확합니다.
프롬프트 엔지니어링은 에이전트에게 "코딩 컨벤션을 지켜주세요", "아키텍처 레이어를 위반하지 마세요"라고 부탁하는 것입니다.
하네스 엔지니어링은 컨벤션 위반 시 린터가 차단하고, 레이어 위반 시 아키텍처 테스트가 실패하고, 테스트 누락 시 CI 파이프라인이 실패하게 만드는 강제입니다.
프롬프트는 아무리 정교하게 작성해도 에이전트가 잊거나, 무시하거나, 자기 나름의 해석을 적용할 수 있습니다. 하네스는 규칙을 위반하면 코드가 저장소에 들어갈 수 없게 만드는 구조적 장치입니다.
| 구분 | 프롬프트 엔지니어링 | 컨텍스트 엔지니어링 | 하네스 엔지니어링 |
|---|---|---|---|
| 범위 | 모델에 보내는 지시문 | 매 단계 모델에 조립되는 모든 정보 | 모델을 감싸는 전체 인프라 |
| 초점 | 무엇을 하라고 시키는가 | 행동할 때 무엇을 아는가 | 시스템이 어떻게 제약·검증·교정하는가 |
| 신뢰성 향상 | 5~15% | 15~30% | 50~80% |
LangChain 팀이 이를 정량적으로 증명했습니다. 에이전트 모델은 그대로 두고 하네스만 개선했더니 벤치마크 성과가 52.8%에서 66.5%로, 순위로는 Top 30에서 Top 5로 올라갔습니다. 같은 모델, 같은 프롬프트, 다른 하네스, 극적으로 다른 결과.
왜 지금 필요한가
AI 코딩 도구가 진화하면서 개발자의 역할이 근본적으로 바뀌고 있습니다.
| 단계 | 방식 | 인간의 역할 | 대표 도구 |
|---|---|---|---|
| Phase 1 | 자동완성 | 코드의 주도권은 인간 | GitHub Copilot |
| Phase 2 | 페어 프로그래밍 | AI와 함께 작성 | Cursor, Windsurf |
| Phase 3 | 에이전트 위임 | 인간은 관리, AI가 실행 | Codex, Claude Code |
Phase 3에서는 개발자가 여러 에이전트에게 작업을 분배하고, 에이전트들이 자율적으로 코드를 작성·테스트·배포합니다.
그런데 역설적인 일이 벌어지고 있습니다. AI가 코드 생성 속도를 극적으로 높였는데, 오히려 문제가 더 커진 것입니다. 2026년 3월 Harness(DevOps 플랫폼) 보고서에 따르면, AI 코딩 도구가 개발 속도를 높였지만 테스트·보안·배포 등 후속 파이프라인이 따라가지 못하면서 배포 불안정성이 증가하고 있습니다. 73%의 팀이 표준화된 서비스 템플릿이나 골든 패스가 거의 없다고 응답했습니다.
고속도로에서 차가 300km/h로 달리는데, 톨게이트는 여전히 수동 정산인 상황입니다.
하네스의 5가지 핵심 구성요소
1. 컨텍스트 엔지니어링 — "무엇을 해야 하는가"
에이전트에게 프로젝트의 규칙과 상태를 머신이 읽을 수 있는 형태로 제공하는 것입니다. AGENTS.md나 CLAUDE.md 같은 파일이 에이전트의 "입사 첫날 문서" 역할을 합니다.
OpenAI 팀의 교훈은 "1,000페이지의 매뉴얼이 아닌 **지도(map)**를 제공하라"는 것이었습니다. 거대한 AGENTS.md 하나는 예측 가능한 방식으로 실패했습니다. 대신 짧은 AGENTS.md(약 100줄)를 목차로 두고, 구조화된 docs/ 디렉터리에 심층 정보를 배치했습니다.
핵심 원칙은 **저장소가 단일 진실 소스(Single Source of Truth)**가 되어야 한다는 것입니다. 위키, 노션, 슬랙에 흩어진 정보는 에이전트가 읽을 수 없습니다.
Vercel은 에이전트의 사용 가능 도구를 15개에서 2개로 줄였더니, 정확도가 80%에서 **100%**로 올라가고, 토큰 소비가 37% 감소했습니다.
2. 아키텍처 제약 — "무엇을 해서는 안 되는가"
컨텍스트가 방향을 알려준다면, 아키텍처 제약은 경계를 강제합니다.
// architecture.test.ts
describe('Architecture constraints', () => {
test('UI layer must not import from Repository', () => {
const uiFiles = getFilesIn('src/ui/');
for (const file of uiFiles) {
const imports = getImports(file);
expect(imports).not.toContainPath('src/repository/');
}
});
});
OpenAI는 이를 의존성 방향 강제로 구현했습니다.
Types → Config → Repository → Service → Runtime → UI
(역방향 의존은 빌드가 실패한다)
에이전트가 아무리 "이렇게 하는 게 더 효율적인데"라고 판단해도, 이 테스트가 실패하면 코드는 저장소에 들어갈 수 없습니다.
3. 검증 루프 — "각 단계를 통과시켜라"
각 단계의 출력을 다음 단계로 넘기기 전에 자동 검증하는 장치입니다. 가장 ROI가 높은 컴포넌트로, 스키마 기반 검증 하나만 추가해도 작업 완료율을 83%에서 96%로 올릴 수 있습니다.
구현 비용은 단계당 50~150ms의 추가 지연이지만, 그 대가로 무음 장애(silent failure)가 전체 작업 체인으로 퍼지는 것을 방지합니다.
4. 비용 봉투 관리 — "예산을 초과하지 마라"
작업별 예산 한도를 설정해 재시도 루프에 의한 비용 폭주를 방지합니다. 비용 봉투는 단순한 재무 통제가 아니라 신뢰성 신호이기도 합니다. 예산 한도에 도달한 작업은 대부분 비정상적으로 동작하고 있다는 뜻이기 때문입니다.
Manus는 KV-cache 최적화와 컨텍스트 관리로 10배 비용 절감을 달성했습니다.
5. 엔트로피 관리 — "시간이 지나도 일관성을 유지하라"
에이전트 A가 유틸 함수를 만들고, 에이전트 B가 같은 기능의 함수를 또 만듭니다. 개별적으로는 올바르지만, 전체적으로는 불일치가 쌓입니다.
OpenAI Codex 팀도 초기에는 매주 금요일(일주일의 20%)을 "AI 슬로프" 정리에 사용했지만, 그 방식은 확장되지 않았습니다. 대신 "황금 원칙"을 리포지터리에 인코딩하고, 정기적으로 편차를 검사하고 리팩터링 PR을 생성하는 백그라운드 정리 에이전트를 운영하기 시작했습니다.
이것은 **가비지 컬렉션(GC)**과 같습니다. 기술 부채를 한꺼번에 갚는 것보다 조금씩 꾸준히 갚아나가는 편이 훨씬 낫습니다.
세 거인이 독립적으로 같은 결론에 도달했다
하네스 엔지니어링이 특정 회사의 마케팅 용어가 아님을 보여주는 증거가 있습니다.
| 조직 | 핵심 교훈 |
|---|---|
| Anthropic | 초기화 에이전트 + 코딩 에이전트 2단계 구조, 세션 간 상태 관리 |
| OpenAI | 지도 vs 매뉴얼, 기계적 강제, 관찰 가능성 시스템 |
| Stripe | Minions 시스템으로 주당 1,000+ PR 처리, 기존 품질 게이트 동일 적용 |
질문은 달랐지만 답은 같았습니다. 환경을 설계하라.
Mitchell Hashimoto(HashiCorp 공동 창업자)는 이를 한 문장으로 압축했습니다.
"에이전트가 실수할 때마다, 그 실수를 다시는 하지 않도록 해결책을 엔지니어링하라."
실제 결과로 증명된 효과
| 회사 | 하네스 투자 | 결과 |
|---|---|---|
| OpenAI (Codex) | 샌드박스 환경, 검증 루프, 구조화된 도구 접근 | 3명이 5개월 만에 100만+ 줄 코드 |
| LangChain | 하네스 인프라 개선 (모델 변경 없음) | 작업 완료율 52.8% → 66.5% |
| Vercel | 도구 축소 (15→2), 컨텍스트 최적화 | 정확도 80% → 100%, 토큰 -37% |
| Stripe | 에이전트 하네스 코드 변경 시스템 | 주당 1,000+ PR 병합 |
| Manus | KV-cache 최적화, 컨텍스트 관리 | 10배 비용 절감 |
공통 패턴은 명확합니다. 모델을 바꾸면 1015%가 변하고, 하네스를 바꾸면 5080%가 변합니다.
하네스 엔지니어링을 시작하는 5단계
- 실패 모드 감사: 에이전트를 50
100개 대표 작업에 돌려보고 실패를 분류합니다. 대부분 6070%의 실패가 2~3개 근본 원인으로 수렴합니다. - 검증 루프 추가 (최우선): 모든 도구 호출 후 스키마 기반 검증을 추가합니다. 단계당 50~150ms 비용으로 대부분의 무음 장애를 잡을 수 있습니다.
- 관측 가능성 계측: 각 에이전트 단계의 구조화된 실행 추적을 기록합니다. 보이지 않으면 개선할 수 없습니다.
- 비용 봉투 설정: 중앙값의 3배를 기본 한도로 설정합니다. 구현에 30분이면 충분하고, $2,400짜리 야간 서프라이즈를 방지합니다.
- 평가 파이프라인 구축: 20~50개 대표 테스트 작업을 정기적으로 실행해 성과를 측정합니다.
개발자 역할의 재정의
하네스 엔지니어링의 핵심 메시지는 결국 이것입니다. 모델은 교체 가능한 부품이고, 하네스가 신뢰성이 사는 곳입니다.
개발자의 역할이 "코드를 작성하는 사람"에서 **"에이전트가 일할 수 있는 환경을 설계하는 사람"**으로 전환되고 있습니다. 코드를 직접 쓰는 시간은 줄어들고, 린터 규칙을 설계하고, CI 파이프라인을 구축하고, 아키텍처 테스트를 작성하고, 관측 가능성 스택을 구성하는 시간이 늘어날 것입니다.
프롬프트 엔지니어링이 쓸모없어지는 것은 아닙니다. 좋은 프롬프트는 에이전트가 올바른 방향을 향하게 하고, 좋은 하네스는 잘못된 방향으로 가는 것 자체를 불가능하게 만듭니다. 하네스 엔지니어링은 프롬프트 엔지니어링을 대체하는 것이 아니라, 그 위에 구조적 안전장치를 쌓는 것입니다.
참고 자료