TL;DR
하네스 엔지니어링은 AI 에이전트가 안정적으로 작동하도록 감싸는 전체 환경(저장소 구조, CI, 포맷 규칙, 외부 도구 연결 등)을 설계하는 방법론이다. 단일 에이전트의 실패 관찰에서 출발해, 역할 분리 → 평가 기준 설계 → 피드백 루프 → 경량화까지 8단계로 멀티 에이전트 시스템을 체계적으로 구축한다.
AI-assisted
Source
1. Harness Engineering이란
AI 에이전트를 개발할 때, 모델 자체의 성능만으로는 실제 프로덕션에서 안정적으로 작동하기 어렵다. 에이전트가 올바른 방향으로, 일관되게, 반복적으로 좋은 결과를 내려면 에이전트 “바깥”의 환경을 잘 설계해야 한다. 이 바깥 환경 전체를 하네스(harness) 라고 부른다.
하네스에 포함되는 것들:
- 저장소 구조와 파일 조직
- CI/CD 파이프라인 설정
- 코드 포맷 규칙과 린트 설정
- 외부 도구 연결 (API, 브라우저 자동화 등)
- 에이전트 간 소통 프로토콜
- 평가 기준과 피드백 루프
즉, 프롬프트 엔지니어링이 “에이전트에게 뭘 말할까”에 집중한다면, 하네스 엔지니어링은 “에이전트가 일할 환경을 어떻게 만들까”에 집중하는 방법론이다.
2. Deep Insight 프로젝트
AWS SA(Solutions Architect) 팀의 6명이 v-team을 이루어 개발한 오픈소스 리포팅 에이전트 프로젝트다. 멀티 에이전트 구조를 채택하여 프로덕션 환경에서 운영 중이며, 하네스 엔지니어링의 실전 적용 사례로 블로그 시리즈를 공개했다.
시리즈 구성:
- 멀티 에이전트 아키텍처 설계
- 컨텍스트 엔지니어링 기법
- 하네스 엔지니어링 (로컬 개발 → 프로덕션 운영)
3. 8가지 핵심 원칙
하네스 엔지니어링의 핵심은 “인간 조직의 역할 분리와 프로세스 설계를 AI 에이전트에 적용하는 것”이다.
3-1. 실패 관찰부터 시작
멀티 에이전트 설계를 하기 전에, 먼저 단일 에이전트로 돌려본다. 이때 발생하는 실패를 세 가지로 분류한다:
- 방향 오류: 기획 자체가 잘못된 경우
- 실행 버그: 구현 과정에서 발생하는 오류
- 품질 부족: 결과물의 완성도가 떨어지는 경우
Point
화려한 아키텍처보다 단일 에이전트의 실패를 꼼꼼히 관찰하는 것이 출발점이다.
3-2. 역할 분리 기준
에이전트를 나눌 때는 명확한 기준이 필요하다:
- 인지적 충돌: 생성과 평가처럼 상충하는 역할은 분리한다
- 추상화 수준 차이: 플래너(계획) → 제너레이터(생성) → 이밸류에이터(평가)
- 비용 대비 이점: 분리의 이점이 에이전트 간 조정 비용을 넘을 때만 분리한다
3-3. 채점 기준 설계
평가 에이전트가 사용할 채점 기준을 세밀하게 설계한다:
- 평가 대상을 독립적인 축으로 분해
- 구체적인 긍정/부정 예시와 가중치 부여
- 채점 기준 문구가 생성 에이전트의 방향성까지 좌우하므로 신중하게 작성
3-4. 평가 에이전트 튜닝
- “결함을 적극적으로 찾아라”는 명시적 지시를 포함
- 브라우저 자동화 같은 실제 상호작용 도구 제공
- 로그 기반 반복 교정으로 판단 기준 정렬
3-5. 파일 기반 소통 설계
에이전트 간 소통은 모두 명시적 파일로 기록한다:
- 구조화된 스프린트 계약으로 사전 합의
- 정보 손실 최소화
- 디버깅과 추적 가능성 확보
Why File-based?
에이전트 간 소통이 컨텍스트 윈도우 안에서만 이뤄지면 정보가 유실되기 쉽다. 파일로 남기면 언제든 참조할 수 있고, 사람이 중간 과정을 감사(audit)할 수 있다.
3-6. 피드백 루프 설계
- 점수가 고원(plateau)에 도달하면 반복을 중지
- 점수가 정체되면 완전히 다른 방향으로 피벗
- 각 반복의 결과물 스냅샷을 보존하여 롤백 가능
3-7. 경량화
- 한 번에 하나의 구성 요소만 제거해 영향도 측정
- 모델 업그레이드 시 각 구성 요소 재검증
- 불필요해진 것은 제거하고, 새로운 역량은 추가
3-8. 지속적 진화
하네스는 일회성 설계가 아니다. LLM 모델이 발전하면 에이전트의 역량도 달라지므로, 기존에 필요했던 가드레일이나 역할 분리가 불필요해질 수 있다. 모델 변화에 맞춰 구조를 지속적으로 재설계해야 한다.
4. Prompt Engineering vs Context Engineering vs Harness Engineering
| 구분 | 대상 | 핵심 질문 |
|---|---|---|
| Prompt Engineering | 프롬프트 텍스트 | 에이전트에게 뭘 말할까? |
| Context Engineering | 컨텍스트 윈도우 | 에이전트에게 어떤 정보를 줄까? |
| Harness Engineering | 에이전트 외부 환경 전체 | 에이전트가 일할 환경을 어떻게 만들까? |
세 가지는 상호 보완적이며, 프로덕션 수준의 에이전트를 만들려면 세 가지를 모두 고려해야 한다.
5. 실무 적용 시 고려사항
- 처음부터 멀티 에이전트를 설계하지 말고, 단일 에이전트의 한계를 먼저 확인한다
- 에이전트를 분리할 때는 조정 비용이 분리 이점보다 작은지 판단한다
- 평가 기준은 생성 품질에 직접 영향을 미치므로, 채점 루브릭 설계에 시간을 투자한다
- 에이전트 간 소통은 파일 기반으로 투명하게 관리한다
- 모델이 업그레이드될 때마다 하네스 구조를 재검증한다