AI 에이전트 하네스란 무엇이고 무엇으로 구성되는가

정의

AI 에이전트의 하네스(agent harness)는 언어 모델 주변의 소프트웨어 구조입니다. 모델 자체를 제외한 나머지 모든 것이지만, 에이전트가 일하는 방식에 영향을 줍니다. 공식은 다음과 같습니다: 에이전트 = 모델 + 하네스. 모델은 추론하고 코드를 쓸 줄 알지만, 하네스는 모델이 무엇을 보는지, 무엇으로 행동할 수 있는지, 명령이 어디서 실행되는지, 세션 사이에 무엇이 남는지, 그리고 에이전트가 자신의 실수를 어떻게 알게 되는지를 결정합니다.

하네스의 다섯 가지 구성 요소

• 지침 — 시스템 프롬프트와 CLAUDE.md, AGENTS.md 같은 프로젝트 파일, 주제별 문서, skills.
• 도구 — shell에서 명령 실행, 파일 편집, 브라우저, MCP 연결.
• 환경 — 운영 환경을 위협하지 않고 에이전트가 코드를 실행하는 sandbox나 container.
• 상태 — 계획과 진행 파일, git 기록: 세션이 끝나도 남는 기억.
• 피드백 — 에이전트에게 오류 신호를 돌려주는 테스트, linter, 타입 검사, hooks.

하네스는 프롬프트가 든 파일 하나가 아닙니다. 에이전트에게 테스트 접근 권한이 없거나 환경이 아예 올라오지 않는다면, 아무리 긴 AGENTS.md도 도움이 되지 않습니다. 안정성은 다섯 가지 중 가장 약한 부분이 결정합니다.

예시

에이전트가 세 번째 세션 연속으로 같은 버그를 고치려 하고 있습니다. 재시작할 때마다 이전에 무엇을 시도했는지 기억하지 못합니다. 처음에는 모델의 문제처럼 보입니다. 하지만 실제로 고장 난 것은 상태 구성 요소입니다. 해결책은 PROGRESS.md 파일입니다. 에이전트는 세션이 끝날 때 효과가 없었던 가설과 다음 단계를 여기에 적습니다:

## 버그: 같은 요청을 재시도할 때 이중 결제
검토 후 기각:
- HTTP 클라이언트의 타임아웃 — 영향 없음
- webhook 핸들러의 경쟁 상태 — 재현되지 않음
다음 단계: payments/service.py에서 idempotency key 확인

새 세션은 파일을 읽고 바로 멈춘 지점에서 이어 갑니다. 모델은 바뀌지 않았습니다. 하네스가 바뀌었습니다.

요약

AI 에이전트의 하네스는 모델 주변의 지침, 도구, 환경, 상태, 피드백입니다. 같은 에이전트가 안정적으로 일할지 아니면 무너질지를 결정하는 것이 바로 이것입니다. 각 구성 요소를 어떻게 만드는지는 실제 프로젝트를 다루는 실습 과정에서 설명합니다.