하네스 엔지니어링

하네스 엔지니어링(Harness Engineering)은 AI 에이전트가 대규모로 안정적이고 일관된 결과물을 만들어내도록 환경·제약·피드백 루프를 설계하는 엔지니어링 분야다. OpenAI 엔지니어링 팀이 5개월 동안 약 100만 줄의 프로덕션 코드를 수동 작성 없이 Codex 에이전트만으로 만들어낸 실험에서 얻은 교훈 — "어려운 건 AI 에이전트가 아니라 에이전트가 일할 환경(harness)이다" — 에서 이름이 나왔다. 말에 씌우는 마구(harness)가 강력한 말의 힘을 방향과 안전 안에서 전달하듯, 에이전트 자체는 이미 충분히 강력하지만 고삐 없이 풀어놓으면 아키텍처 위반과 스타일 불일치가 쌓인다. 핵심은 에이전트를 바꾸는 것이 아니라 환경을 바꾸는 것이다.

하네스 엔지니어링은 프롬프트 엔지니어링의 변화와 대비된다. 프롬프트 엔지니어링이 "이 규칙을 지켜주세요"라는 부탁이라면, 하네스 엔지니어링은 규칙을 위반하면 CI가 실패하도록 만드는 강제다. 아무리 정교한 프롬프트도 에이전트가 잊거나 무시할 수 있지만, 하네스는 위반 자체를 구조적으로 차단한다. LangChain 팀은 이를 정량적으로 증명했는데, 에이전트 모델은 그대로 두고 미들웨어(하네스)만 개선해 벤치마크 성과를 52.8%에서 66.5%로, 순위를 Top 30에서 Top 5로 끌어올렸다.

하네스 엔지니어링은 3가지 기둥으로 구성된다. ① 컨텍스트 엔지니어링은 CLAUDE.md·AGENTS.md 같은 규칙 파일을 저장소에 두어 에이전트가 작업 시작 시 자동으로 읽게 하는 정적 컨텍스트와, CI 상태·로그·진행 중인 PR 같은 동적 컨텍스트로 구성되며, 원칙은 "저장소가 단일 진실 소스(Single Source of Truth)"라는 것 — 위키·노션·슬랙에 흩어진 정보는 에이전트가 읽을 수 없다. ② 아키텍처 제약은 의존성 방향(예: Types → Config → Repository → Service → Runtime → UI)을 구조 테스트·린터·pre-commit 훅으로 자동 강제해, 규칙 위반 import가 있으면 빌드나 커밋 자체가 실패하게 만든다. ③ 엔트로피 관리는 다수의 에이전트가 동시에 작업하며 중복 함수·네이밍 불일치·순환 의존성이 쌓이는 "코드 부패(code rot)"를, 프로그래밍 언어의 가비지 컬렉션에 비유해 정리 에이전트를 주기적으로 실행함으로써 지속적으로 탐지·복구하는 것이다.

실제 사례로 OpenAI(5개월간 100만 줄, 수동 작성 코드 0줄, 아키텍처 규칙의 머신 가독형 명세)와 Stripe("Minions" 에이전트 시스템으로 주당 1,000개 이상의 PR이 기존 코드와 동일한 품질 게이트를 통과)가 있다. 도입은 3단계로 확장 가능하다 — 개인 프로젝트는 CLAUDE.md 작성·pre-commit 훅·테스트만으로도 체감 가능한 개선이 있고, 소규모 팀은 AGENTS.md 고도화와 CI 아키텍처 테스트·PR 체크리스트를, 조직 규모는 미들웨어 레이어·관찰성 시스템·버전 관리된 하네스 자체를 갖춘다. 흔한 실수로는 과도한 제어 흐름 설계(모델이 진화하면 깨짐), 정적 하네스 방치, 문서화 경시, 피드백 루프 부재, 저장소 밖에 정보를 두는 것이 꼽힌다.

2023~2024년의 키워드가 "프롬프트 엔지니어링"이었다면 2025~2026년의 키워드는 "하네스 엔지니어링"이라는 것이 핵심 주장이다. 개발자의 역할은 "코드를 쓰는 사람"에서 "AI 에이전트가 복잡한 시스템을 안정적으로 구축할 수 있는 환경을 설계하는 사람"으로 무게중심이 옮겨가고 있다.

핵심 내용

  • 정의: AI 에이전트가 대규모로 안정적·일관된 결과물을 내도록 환경·제약·피드백 루프를 설계하는 분야
  • 프롬프트 엔지니어링(부탁) vs 하네스 엔지니어링(강제) — LangChain 사례: 미들웨어 개선만으로 벤치마크 52.8%→66.5%, Top 30→Top 5
  • 3가지 기둥: 컨텍스트 엔지니어링(CLAUDE.md 등 규칙 파일, 저장소=단일 진실 소스) · 아키텍처 제약(의존성 방향을 테스트·린터로 강제) · 엔트로피 관리(코드 부패를 GC처럼 주기적으로 정리)
  • OpenAI 사례: 5개월, 100만 줄, 수동 작성 코드 0줄 / Stripe "Minions": 주당 1,000+ PR이 동일 품질 게이트 통과
  • 도입 3단계: 개인(CLAUDE.md+pre-commit+테스트) → 팀(AGENTS.md+CI 아키텍처 테스트) → 조직(미들웨어+관찰성+버전관리된 하네스)
  • 흔한 실수 5가지: 과도한 제어 흐름, 정적 하네스 방치, 문서화 경시, 피드백 루프 부재, 저장소 밖 정보 저장

관련 개념

  • AI 에이전트 시대의 개발자 역할 — 개발자가 '코드 작성자'에서 '시스템 지휘자'로 이동한다는 문제의식을 공유하며, 맥도날드 프랜차이즈 모델(본사·지점장·직원)이 하네스의 3층 거버넌스 구조와 상통
  • 프롬프트 엔지니어링의 변화 — 프롬프트가 AI에게 "무엇을 하라고 말하는" 기술이라면 하네스는 "AI가 올바르게 작동하는 환경을 만드는" 기술
  • AI 코딩 도구 활용 — Cursor Rule 등 팀 컨벤션 자동화가 컨텍스트 엔지니어링의 실무 사례

출처

최종 업데이트: 2026-09-07 | 출처 1개