Harness engineering이란: AI 에이전트를 실제로 쓸 수 있는 도구로 만드는 방법

쉽게 설명하는 harness engineering

Harness engineering은 언어 모델 주변에 모델이 실제 작업을 안정적으로 수행할 수 있는 환경을 만드는 방법을 다루는 엔지니어링 분야입니다. harness라는 단어는 "마구(馬具)"라는 뜻입니다. 모델은 강력하지만 스스로는 어디로 가야 하는지, 어떤 도구를 써야 하는지, 언제 멈춰야 하는지 알지 못합니다. 하네스는 그 힘의 방향을 잡아줍니다.

가장 짧은 공식은 다음과 같습니다:

에이전트 = 모델 + 하네스

모델은 추론하고 텍스트나 코드를 생성할 수 있는 가중치입니다. 하네스는 그 밖의 모든 것입니다: 시스템 지침과 CLAUDE.md 또는 AGENTS.md 같은 파일, 도구 세트(shell, 파일 편집, MCP 서버), 에이전트가 명령을 실행하는 sandbox, 세션 사이의 상태를 담는 파일, 그리고 에이전트에게 실수를 알려 주는 테스트, linter, hook. 하네스를 빼면 텍스트로만 답하는 채팅창만 남습니다.

에이전트가 때로는 "시니어", 때로는 "주니어"처럼 보이는 이유

익숙한 상황입니다. 한 저장소에서는 에이전트가 숙련된 개발자처럼 일하지만, 다른 저장소에서는 헤매고, 어제 내린 결정을 잊고, 작동하지 않는 기능을 "완료"라고 보고합니다. 처음 드는 생각은 더 새로운 모델로 바꾸는 것입니다. 하지만 두 경우 모두 모델은 같으므로 보통 도움이 되지 않습니다. 차이는 환경에 있습니다.

여기서 harness engineering의 핵심 사고방식이 시작됩니다: 에이전트가 고장 난 것이 아니라, 그 주변이 고장 난 것입니다. 에이전트가 테스트에 접근할 수 없으면 테스트를 실행할 수 없습니다. 어디에도 기록되지 않은 내용은 이전에 무엇을 시도했는지 기억하지 못합니다. 아무 검사도 기능이 깨졌다고 알려 주지 않으면 에이전트는 그것을 알아차리지 못합니다. 이것은 모델의 "성격"이 아니라 설계상의 결함이며, 체계적으로 고칠 수 있습니다.

나쁜 하네스의 전형적인 징후

• 매 세션이 환경을 고치는 일로 시작됩니다: 의존성이 맞지 않고, 데이터베이스가 뜨지 않고, 변수가 없습니다.
• 에이전트는 이전 세션을 기억하지 못해 이미 기각된 해결책을 반복합니다.
• 규칙이 지침에 분명히 적혀 있는데도 에이전트가 무시합니다.
• "테스트는 초록색"이라고 하지만 기능은 깨져 있습니다. 테스트가 다른 것을 검사했기 때문입니다.
• 에이전트가 세 가지 작업을 동시에 시작하고 어느 하나도 끝내지 못합니다.

하네스는 다섯 가지 구성 요소로 이루어집니다

흔한 실수는 하네스를 프롬프트가 든 파일 하나로 생각하는 것입니다. 실제로는 다섯 가지 장치의 조합이며, 각각은 자기만의 방식으로 망가집니다.

지침

지침은 "에이전트가 올바른 규칙을 찾을 수 있는가?"에 답합니다. 좋은 진입 파일은 교과서가 아니라 지도입니다: 짧은 목차, 검증 명령, 엄격한 제약이 담겨 있고, 세부 내용은 에이전트가 필요할 때 여는 별도 문서에 있습니다. 좋은 지침은 불변 조건을 정의합니다("모든 SQL 쿼리는 매개변수화한다"). 구현을 한 줄씩 지시하지 않습니다.

도구

에이전트는 접근할 수 있는 것만 검증할 수 있습니다. linter를 실행할 수 없다면 "커밋 전에 linter를 실행하라"는 규칙은 아무 소용이 없습니다. 도구는 에이전트의 내장 기능(파일 읽기·쓰기, 명령 실행)과 MCP를 통해 연결됩니다. MCP는 데이터베이스, 브라우저, 작업 추적기에 에이전트를 연결하는 프로토콜입니다.

환경

환경은 에이전트가 명령을 실행하는 곳입니다. 명령 한 번으로 올라와야 하고, 세션마다 동일해야 하며, 실수의 피해를 제한해야 합니다: 운영 환경에 접근할 수 없는 sandbox, 별도 브랜치나 작업 사본, 그리고 몇 분 안에 모든 것을 처음 상태로 되돌릴 수 있는 방법.

상태

모델은 세션 사이에 기억이 없습니다. 저장소에 기록되지 않은 것은 context 창과 함께 사라집니다. 그래서 목표, 완료된 작업, 내린 결정, 막다른 길, 다음 단계는 파일에 남아 있어야 합니다. 확인 방법은 간단합니다: 새 세션을 열고 에이전트에게 "계속해"라고 말해 보세요. 바로 일을 시작하는지, 아니면 무엇을 해야 하는지 묻기 시작하는지 보면 됩니다.

피드백

피드백 루프는 가장 중요한 요소입니다. 피드백이 없으면 에이전트는 자신의 유일한 심판이 되고, 작업이 끝났다고 성실하게 믿어 버립니다. 테스트, 타입 검사, linter, 변경할 때마다 실행되는 hook, 브라우저에서의 E2E 시나리오는 모두 오류가 아직 저렴할 때 에이전트에게 빨간불을 보여 줍니다.

하네스는 목록이 아니라 순환입니다

다섯 구성 요소는 닫힌 순환처럼 작동합니다. 모델은 지침을 받고, 도구로 환경에서 행동하며, 저장소를 변경하고, 검증이 결과를 확인합니다. 빨간 결과는 수정을 위해 모델로 되돌아가고, 초록 결과는 상태에 기록됩니다. 상태는 다음 세션의 지침도 갱신합니다.

지침 → 모델 → 도구 → 환경 → 변경
          ↑                       ↓
          └──── 빨강 ── 검증 ─────┘
                           ↓ 초록
                       상태 → (다음 세션)

화살표 하나를 제거하면 순환은 바로 그 지점에서 끊어집니다. 검증이 없으면 에이전트는 오류를 알지 못합니다. 상태가 없으면 다음 세션은 작업 대신 흔적 찾기로 시작합니다. 그래서 한 구성 요소에 투자해도 다른 구성 요소의 허점을 메우지 못합니다: 다섯 페이지짜리 AGENTS.md는 빠진 테스트를 대신할 수 없습니다.

Harness engineering은 prompt 및 context engineering과 어떻게 다른가

이 개념들은 서로 경쟁하는 것이 아니라 서로 안에 포함됩니다.

Prompt engineering은 지침 구성 요소의 일부입니다. Context engineering은 지침과 상태를 모두 다룹니다. 즉 에이전트가 매 순간 무엇을 보는지입니다. Harness engineering은 context 창에 들어갈 수 없는 것까지 더합니다: 접근 권한, sandbox, 테스트, hooks, 작업 절차. 아무리 잘 쓴 프롬프트도 에이전트가 테스트를 실행할 수 없다면 소용이 없습니다.

긴 작업의 수학: 하네스가 필요한 이유

단계의 95%를 올바르게 수행하는 모델은 거의 완벽해 보입니다. 하지만 에이전트의 작업은 많은 단계로 이루어지고 오류는 쌓입니다. 단계가 서로 독립적이라면, 오류 없이 모든 단계를 통과할 확률은 확률의 곱입니다:

0.95 ^ 10 ≈ 0.60
0.95 ^ 20 ≈ 0.36
0.95 ^ 50 ≈ 0.08

열 번째 단계까지 오류 없이 도달하는 실행은 약 60%뿐이고, 쉰 번째 단계까지는 열 번에 한 번도 되지 않습니다. 모델을 97%까지 개선하는 것은 비용이 크고 여러분의 손에 달려 있지도 않습니다. 하지만 오류가 발생한 바로 그 단계에서 잡아내어 에이전트에게 되돌려 주는 것은 하네스의 역할입니다. 피드백 루프는 "한 오류가 다음 오류를 끌고 온다"는 사슬을 짧고 고칠 수 있는 단계들의 사슬로 바꿉니다.

예시: 같은 에이전트, 두 저장소

과제: FastAPI로 만든 결제 백엔드에 프로모션 코드 할인을 추가하기.

하네스가 없을 때

에이전트는 파일 몇 개를 읽고 할인 계산 함수와 그 함수만 격리해서 검사하는 단위 테스트를 작성합니다. 테스트는 초록색이고 에이전트는 "완료"라고 씁니다. 에이전트는 총액 계산이 다른 모듈에서 이루어진다는 것을 몰랐고, 데이터베이스를 띄워 주문 흐름 전체를 실행하지도 못했습니다. 하루 뒤 장바구니에서 할인이 전혀 적용되지 않는다는 것이 드러납니다.

하네스가 있을 때

루트에는 수십 줄짜리 AGENTS.md가 있습니다. 환경을 어떻게 띄우는지, 어떤 검증 명령이 필수인지, 결제 아키텍처가 어디에 설명되어 있는지 적혀 있습니다. 환경은 docker compose up -d로 올라갑니다. 저장소에는 완료 기준이 적힌 계획 파일이 있습니다: "프로모션 코드가 적용된 주문 흐름의 E2E 시나리오가 통과한다". 변경할 때마다 hook이 linter와 타입 검사를 실행하고, 완료를 선언하기 전에 에이전트는 E2E 테스트를 반드시 돌려야 합니다.

# AGENTS.md (일부)
## 검증 — "완료"라고 말하기 전에 필수
make lint        # ruff + mypy
make test        # pytest, 단위 및 통합
make e2e         # 주문 흐름 시나리오

## MUST
- 금액은 정수 원 단위(int)로 계산하며, float은 쓰지 않는다
- 모든 SQL 쿼리는 매개변수화한다
- 운영에 적용된 migration은 수정하지 않는다

모델은 같습니다. 하지만 이제 에이전트는 프로젝트 지도를 통해 금액 계산 모듈을 찾고, E2E 테스트는 첫 시도에서 실패합니다. 에이전트는 할인이 장바구니에 도달하지 않는다는 것을 확인하고 고친 다음, 초록색 실행 후에만 보고합니다. 결과의 차이는 전부 하네스 덕분입니다.

어디서부터 시작할까

1. 에이전트가 자신의 작업을 어떻게 검증하는지 적으세요: 반드시 실행해야 하는 명령 한두 개입니다. 피드백이 가장 큰 효과를 내므로 여기서 시작하세요.
2. 환경을 재현 가능하게 만드세요: 명령 한 번으로 올라오고, 빠르게 되돌릴 방법이 있어야 합니다.
3. 상태 파일을 만드세요: 목표, 완료된 작업, 결정 사항과 막다른 길, 다음 단계.
4. 지침을 지도 수준으로 줄이세요: 검증 명령, 엄격한 규칙, 상세 문서 링크.
5. 에이전트의 실패 기록을 남기세요: 실패할 때마다 어떤 구성 요소가 책임이 있었는지 적습니다. 이 기록이 다음에 무엇을 고쳐야 할지 알려 줍니다.

유용한 연습: 다섯 구성 요소를 각각 1에서 5 사이로 평가하고, 가장 약한 것에 30분을 투자한 뒤, 같은 대표 작업 몇 개를 개선 전후에 실행해 보세요. 이렇게 하면 하네스 개선이 "느낌"이 아니라 측정 가능한 결과가 됩니다.

마무리

Harness engineering은 모델이 아니라 모델을 둘러싼 모든 것, 즉 지침, 도구, 환경, 상태, 피드백 루프를 다룹니다. 에이전트의 신뢰성은 이 순환에서 가장 약한 고리가 결정하므로, 모델을 바꾸는 것으로는 불안정성이 거의 해결되지 않지만 테스트 하나나 계획 파일 하나를 추가하는 것으로는 종종 해결됩니다. 다섯 구성 요소와 하네스 전체를 조립하는 방법은 실제 결제 백엔드 프로젝트를 중심으로 한 실습 과정에서 다룹니다.