Harness engineering: 신뢰할 수 있는 AI 에이전트를 만드는 방법
아티클: 8
Harness engineering(하네스 엔지니어링)은 언어 모델 주변에 AI 에이전트가 실제 작업을 안정적으로 수행할 수 있는 환경을 설계하는 분야입니다. 이 주제의 공식은 다음과 같습니다: 에이전트 = 모델 + 하네스. 같은 모델도 어떤 프로젝트에서는 숙련된 개발자처럼 일하고, 다른 프로젝트에서는 맥락을 잃고 동작하지 않는 기능을 "완료"라고 보고합니다. 그 차이는 거의 항상 모델이 아니라 하네스에서 나옵니다.
이 가이드는 주제의 지도입니다. 핵심 개념과 학습 순서를 한데 모았습니다. 각 주제는 별도의 글에서 자세히 다룹니다.
하네스의 다섯 가지 구성 요소
- 지침 — CLAUDE.md와 AGENTS.md 파일, 주제별 문서, skills: 에이전트가 프로젝트에 대해 아는 내용.
- 도구 — shell, 파일 편집, 브라우저, MCP 서버: 에이전트가 행동하는 수단.
- 환경 — sandbox, container, 격리된 작업 사본: 에이전트가 명령을 실행하는 장소.
- 상태 — 계획과 진행 파일, git 기록: 세션 사이의 기억.
- 피드백 — 테스트, linter, hooks, 독립된 검증자: 에이전트가 자신의 실수를 아는 방법.
이 요소들은 닫힌 순환을 이룹니다. 어느 하나라도 빠지면 순환이 끊어집니다. 검증이 없으면 에이전트는 실수를 보지 못하고, 상태가 없으면 매 세션이 처음부터 시작됩니다.
어디서 시작할까
주제가 낯설다면 harness engineering이 무엇인지, 그리고 prompt 및 context engineering과 어떻게 다른지 설명하는 글부터 읽으세요. 짧은 정의와 예시는 에이전트 하네스 글에 있습니다.
그다음에는 실전 부분으로 넘어가세요. 누구나 처음 마주치는 파일은 프로젝트 지침입니다. CLAUDE.md와 AGENTS.md에 무엇을 써야 하고 무엇을 쓰지 말아야 하는지, 그리고 에이전트가 파일에 명시된 규칙을 왜 무시하는지 살펴봅니다.
에이전트가 이미 프로젝트에서 일하고 있다면 신뢰성의 문제가 등장합니다. 단계별 계획은 실패 기록과 MTBF, MTTR 지표에서 시작해, 저비용 롤백, 피드백 루프, 파일 기반 기억을 거쳐 에이전트가 감독 없이 몇 시간씩 일하는 자율 순환으로 이어집니다.
핵심 원칙
- 에이전트가 망가진 것이 아니라 환경이 망가진 것입니다. 모델을 바꾸기 전에 하네스의 허점을 찾으세요.
- 피드백부터 시작하세요. 검증 명령 하나가 지침 페이지 전체보다 더 가치가 있습니다.
- 지침은 교과서가 아니라 지도입니다: 짧은 진입 파일과 필요할 때 여는 상세 문서.
- 중요한 것은 context 창이 아니라 파일에 남아야 합니다.
- 측정하세요: 느낌이 아니라 실패 기록에 근거하세요.
다섯 가지 구성 요소와 하네스 전체를 조립하는 방법은 실제 프로젝트를 중심으로 한 실습 과정에서 다룹니다.