Alert
이 글은 Claude Code의 도움을 받아 작성되었습니다
TL;DR
하네스 엔지니어링은 AI 에이전트가 안정적으로 작동하도록 감싸는 전체 환경(저장소 구조, CI, 포맷 규칙, 외부 도구 연결 등)을 설계하는 방법론이다. 단일 에이전트의 실패 관찰에서 출발해, 역할 분리 → 평가 기준 설계 → 피드백 루프 → 경량화까지 8단계로 멀티 에이전트 시스템을 체계적으로 구축한다.
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. 실무 적용 시 고려사항
- 처음부터 멀티 에이전트를 설계하지 말고, 단일 에이전트의 한계를 먼저 확인한다
- 에이전트를 분리할 때는 조정 비용이 분리 이점보다 작은지 판단한다
- 평가 기준은 생성 품질에 직접 영향을 미치므로, 채점 루브릭 설계에 시간을 투자한다
- 에이전트 간 소통은 파일 기반으로 투명하게 관리한다
- 모델이 업그레이드될 때마다 하네스 구조를 재검증한다