하네스 엔지니어링: 실제로 작동하는 AI 에이전트를 구축하는 방법

대부분의 사람들은 AI 에이전트를 엉뚱한 계층에서 고치려 하고 있습니다.

에이전트가 실패하면 프롬프트를 다시 작성합니다. 또 실패하면 지시사항을 더 추가하거나, 모델을 바꾸거나, 컨텍스트 윈도우를 늘리거나, 다른 도구를 연결합니다.

그리고 똑같은 문제가 다시 돌아옵니다.

에이전트는 중요한 결정을 잊어버립니다. 잘못된 도구를 사용합니다. 세 단계 전에 무슨 일이 있었는지 놓칩니다. 결과를 확인하지 않고 작업이 끝났다고 선언합니다. 예산이 바닥날 때까지 실패한 동작을 반복합니다.

문제가 항상 모델에 있는 것은 아닙니다.

문제는 모델을 둘러싼 환경입니다.

그 환경이 바로 하니스(harness) 입니다.

하니스 엔지니어링(Harness Engineering)은 모델 주변에 시스템을 구축하는 실천법입니다. 이 시스템은 모델이 무엇을 볼 수 있는지, 무엇을 할 수 있는지, 무엇을 기억하는지, 무엇이 성공인지, 그리고 무언가 실패했을 때 어떤 일이 벌어지는지를 결정합니다.

더 나은 프롬프트는 단 한 번의 응답을 개선할 수 있습니다.

더 나은 하니스는 모든 실행을 개선합니다.

AI 에이전트, 자동화, 프로덕션 시스템에 대한 실용적인 분석을 더 보려면 제 Substack 을 구독하세요:

substack.com/@lunarresearcher

1. 모델은 에이전트가 아니다

모델은 추론하고, 생성하고, 비교하고, 선택할 수 있습니다.

하지만 그것만으로 신뢰할 수 있는 에이전트가 되지는 않습니다.

진짜 에이전트는 올바른 컨텍스트를 찾고, 도구를 사용하고, 상태를 보존하고, 권한을 준수하고, 자신의 작업을 검증하며, 환경이 예상과 다르게 동작할 때 복구할 수 있어야 합니다.

모델은 그저 추론 엔진일 뿐입니다.

하니스는 그 추론을 실제 실행으로 바꿔주는 모든 것입니다.

1사용자 요청
2      |
3      v
4+-----------------------------+
5|           하니스            |
6|                             |
7| 계약(Contract)  컨텍스트    |
8| 도구(Tools)     상태(State) |
9| 정책(Policy)    검증        |
10| 추적(Traces)    복구        |
11+-----------------------------+
12      |
13      v
14    모델(MODEL)
15      |
16      v
17실제 환경

똑같은 모델을 채팅창에 넣으면 질문에 답을 합니다.

터미널 접근 권한, 테스트, 브라우저 도구, 프로젝트 메모리, 제어된 권한, 리뷰 루프가 갖춰진 저장소에 넣으면 실제 작업을 완수할 수 있습니다.

모델은 변하지 않았습니다.

하니스가 달라진 것입니다.

2. 모든 요청을 계약으로 바꿔라

자연어는 유연합니다.

자율 실행은 그래서는 안 됩니다.

다음과 같은 요청은:

온보딩 흐름을 개선해 줘.

사람이 모델 옆에 앉아 있을 때는 괜찮습니다.

하지만 프로덕션 지시사항으로는 형편없습니다.

에이전트가 행동하기 전에, 요청을 범위가 명확한 작업 계약(task contract)으로 바꾸세요.

1objective: 온보딩 이탈률 감소
2
3inputs:
4  - 제품 요약서
5  - 분석 데이터
6  - 저장소
7
8constraints:
9  - 인증 로직 유지
10  - 데이터베이스 스키마 변경 금지
11  - 현재 모바일 동작 유지
12
13deliverable:
14  - 리뷰 가능한 풀 리퀘스트
15
16done_when:
17  - 테스트 통과
18  - 분석 이벤트 정상 발생
19  - 데스크톱 흐름 리뷰 통과
20  - 모바일 흐름 리뷰 통과
21
22approval_required:
23  - 프로덕션 배포

핵심은 done_when 입니다.

이것이 없으면 에이전트는 문제를 조금 더 쉬운 버전으로 풀어놓고도 자신 있게 작업이 완료되었다고 말할 수 있습니다.

이것이 있으면 완료 여부가 측정 가능해집니다.

에이전트는 이렇게 물어선 안 됩니다:

다음에 뭘 해야 하나요?

이렇게 물어야 합니다:

현재 환경을 계약된 결과에 더 가깝게 만드는 행동은 무엇인가?

이것이 훨씬 강력한 루프입니다.

3. 거대한 컨텍스트 윈도우 대신 지도를 주어라

에이전트가 실수할 때 흔히 하는 반응은 모델에게 컨텍스트를 더 주는 것입니다.

문서를 더 넣고,

대화 기록을 더 넣고,

파일을 더 넣고,

도구 출력을 더 넣습니다.

결국 에이전트는 모든 것을 받지만 이해하는 것은 줄어듭니다.

컨텍스트는 저장소가 아닙니다.

주의력(attention) 예산입니다.

매 실행마다 프로젝트 전체를 쏟아붓는 대신, 유용한 정보가 어디에 있는지 알려주는 작은 지도를 에이전트에게 주세요.

1프로젝트 지도
2
3제품 규칙     -> docs/product/
4아키텍처      -> docs/architecture.md
5프론트엔드    -> apps/web/
6백엔드        -> services/api/
7테스트        -> tests/
8명령어        -> docs/commands.md
9보안          -> docs/security.md

그리고 필요할 때만 확장하세요.

1작업(TASK)
2  |
3  v
4프로젝트 지도
5  |
6  v
7관련 시스템
8  |
9  v
10정확한 파일
11  |
12  v
13로컬 지시사항

원문에서는 이를 점진적 공개(progressive disclosure)라고 설명합니다. 하니스는 단순히 정보가 존재한다는 이유로가 아니라, 작업이 필요로 하기 때문에 더 많은 정보를 로드해야 합니다.

목표는 최대 컨텍스트가 아닙니다.

목표는 최대 유효 신호(signal)입니다.

4. 모델과 도구 사이에 게이트웨이를 두어라

도구가 20 개 있다고 해서 모델의 능력이 자동으로 20 배 향상되는 것은 아닙니다.

오히려 실패할 수 있는 경로가 20 개 늘어난 것일 수 있습니다.

모든 도구에는 계약이 있어야 합니다.

1도구: edit_file
2
3입력(INPUTS)
4path
5patch
6
7사전 조건(PRECONDITIONS)
8path 가 존재함
9path 가 워크스페이스 내부에 있음
10
11성공(SUCCESS)
12patch 적용됨
13diff 반환됨
14
15실패(FAILURE)
16구조화된 오류
17부분 덮어쓰기 없음
18
19위험도(RISK)
20되돌리기 가능

그러면 실행 경로는 다음과 같이 바뀝니다:

1모델이 제안
2      |
3      v
4게이트웨이가 검증
5      |
6      v
7정책이 승인
8      |
9      v
10도구가 실행
11      |
12      v
13하니스가 결과 기록

모델은 어떤 행동을 원하는지 결정합니다.

하니스는 그 행동이 유효하고 허용되며 안전한지 결정합니다.

이 구분은 도구가 메시지를 보내거나, 프로덕션을 수정하거나, 비용을 쓰거나, 데이터를 삭제할 수 있을 때 결정적으로 중요해집니다.

잘 만든 도구 게이트웨이는 타임아웃을 추가하고, 인자를 검증하고, 파일 경로를 제한하고, 오류를 정규화하며, 재시도를 안전하게 만들 수도 있습니다.

좋은 도구는 모델이 추측해야 할 것의 수를 줄여줍니다.

5. 메모리를 대화 밖으로 빼내라

대화가 시스템의 공식 기록이 되어서는 안 됩니다.

장시간 실행되는 에이전트는 결국 컨텍스트 한계에 부딪히거나, 충돌하거나, 재시작되거나, 다른 세션으로 작업을 넘깁니다.

중요한 결정이 모두 대화 기록 안에만 있다면 워크플로는 깨지기 쉽습니다.

영속적인 상태는 별도로 저장하세요.

1{
2  "task_id": "feature_042",
3  "status": "verifying",
4  "current_step": "mobile_check",
5
6  "completed": [
7    "implementation",
8    "unit_tests",
9    "desktop_check"
10  ],
11
12  "decisions": [
13    "기존 내보내기 엔드포인트 재사용",
14    "현재 날짜 형식 유지"
15  ],
16
17  "artifacts": [
18    "export.csv",
19    "desktop-after.png"
20  ],
21
22  "open_risks": [
23    "모바일 툴바 오버플로우 가능성"
24  ],
25
26  "next_action": "모바일 뷰포트 렌더링"
27}

유용한 시스템은 메모리를 네 가지 범주로 나눕니다:

1사실(FACTS)
2변하지 않는 지식
3
4결정(DECISIONS)
5무엇을 왜 선택했는가
6
7상태(STATE)
8현재 실행이 어느 단계에 있는가
9
10교훈(LESSONS)
11향후 실행에 영향을 주어야 할 실패 사례

다음 에이전트 세션은 이전 대화를 압축한 이야기가 아니라, 작업의 상태를 이어받아야 합니다.

6. 증거를 완료의 관문으로 만들어라

에이전트가 "완료"라고 말하는 것이 작업이 끝났다는 증거는 아닙니다.

그것 역시 모델의 출력일 뿐입니다.

하니스에는 관찰 가능한 증거가 필요합니다.

1주장(CLAIM)                   증거(EVIDENCE)
2
3"버그가 수정됨"               실패하던 테스트가 이제 통과함
4
5"페이지가 작동함"             브라우저 흐름이 완료됨
6
7"데이터가 정확함"             값이 원본과 일치함
8
9"마이그레이션이 안전함"       드라이 런 + 롤백 통과
10
11"작업이 완료됨"               모든 인수 조건 검사 통과

먼저 결정론적 검사를 사용하세요.

1구문(syntax)
2  |
3  v
4타입(types)
5  |
6  v
7집중 테스트(focused tests)
8  |
9  v
10통합 테스트(integration tests)
11  |
12  v
13시각 / 의미론적 리뷰
14  |
15  v
16사람의 승인

컴파일러, 테스트, 스키마, 데이터베이스 쿼리가 증명할 수 있는 것을 다른 모델에게 묻지 마세요.

판단은 모델에게 맡기세요.

사실은 결정론적 시스템으로 확인하세요.

모델은 산출물을 만듭니다.

환경은 그 산출물에 대한 증거를 만듭니다.

하니스는 증거가 충분한지 결정합니다.

7. 만드는 사람과 검증하는 사람을 분리하라

셀프 리뷰에는 또 다른 문제가 있습니다.

실수를 만든 에이전트는 리뷰할 때도 같은 전제를 그대로 가져가는 경우가 많습니다.

더 견고한 아키텍처는 작업자(worker)와 검증자(verifier)를 분리합니다.

1빌더(BUILDER)
2   |
3   v
4후보안 생성
5   |
6   v
7검증자(VERIFIER)
8   |
9   +-- 계약 확인
10   +-- 누락된 케이스 탐색
11   +-- 근거 없는 주장 테스트
12   +-- 결과를 망가뜨려보기 시도
13   |
14   +------ 통과(PASS) ------> 수용(ACCEPT)
15   |
16   +------ 실패(FAIL) ------> 증거 반환(RETURN EVIDENCE)

검증자는 이렇게 물어선 안 됩니다:

이거 괜찮아 보이나요?

이렇게 물어야 합니다:

무엇이 이 결과를 수용 불가능하게 만드는가?

이렇게 하면 리뷰가 단순한 확인에서 반증 시도로 바뀝니다.

원문에서는 검증 단계에 자체적인 거부 기준을 주고, 첫 번째 결과를 만든 전제에 의문을 제기할 수 있을 만큼의 독립성을 부여할 것을 명시적으로 권장합니다.

8. 권한을 모델 밖으로 빼내라

일부 규칙은 모델이 기억하는 것에 의존해서는 절대 안 됩니다.

1승인 없이 배포하지 말 것
2비밀 정보를 노출하지 말 것
3지출 한도를 초과하지 말 것
4워크스페이스 외부에 작성하지 말 것
5실행하지 않은 테스트를 통과했다고 주장하지 말 것

이것은 프롬프트 제안이 아닙니다.

이것은 정책(policy)입니다.

간단한 권한 사다리는 다음과 같습니다:

1낮은 위험(LOW RISK)
2
3읽기
4검색
5검사
6
7-> 자동
8
9되돌리기 가능(REVERSIBLE)
10
11워크스페이스 편집
12테스트 실행
13초안 작성
14
15-> 자동 + 추적 기록
16
17외부 영향(EXTERNAL EFFECT)
18
19전송
20배포
21구매
22
23-> 승인 필요
24
25되돌리기 불가 / 민감(IRREVERSIBLE / SENSITIVE)
26
27데이터 삭제
28자격 증명 교체
29전역 배포
30
31-> 엄격한 차단 또는 금지

결과가 심각할수록 통제도 강력해야 합니다.

모델은 행동을 추천할 수 있습니다.

하니스가 그것을 승인합니다.

도구가 그것을 실행합니다.

자율성은 통제의 부재가 아닙니다.

강제된 경계 안에서의 자유입니다.

9. 눈 감고 재시도하는 것을 멈춰라

최악의 복구 정책 중 하나는 이것입니다:

뭔가 실패했다. 다시 해봐.

아무것도 바뀌지 않는다면, 시스템은 같은 실패를 재현하기 위해 돈을 쓰는 셈입니다.

실패는 먼저 분류해야 합니다.

1도구 타임아웃
2-> 백오프와 함께 재시도
3
4유효하지 않은 인자
5-> 도구 호출 수정
6
7누락된 컨텍스트
8-> 누락된 소스 조회
9
10테스트 실패
11-> 실패한 동작 조사
12
13권한 거부
14-> 승인 요청
15
16상충하는 요구사항
17-> 에스컬레이션
18
19변화 없이 반복되는 실패
20-> 중단

유용한 에이전트 루프는 다음과 같습니다:

1관찰(OBSERVE)
2   |
3   v
4결정(DECIDE)
5   |
6   v
7행동(ACT)
8   |
9   v
10측정(MEASURE)
11   |
12   +---- 수용(ACCEPT)
13   |
14   +---- 수정(REPAIR)
15   |
16   +---- 에스컬레이션(ESCALATE)
17   |
18   +---- 중단(STOP)

모든 루프에는 시도 횟수, 시간, 비용, 파괴적 범위에 대한 제한이 있어야 합니다.

신뢰할 수 있는 에이전트는 어떻게 계속 진행할지 알아야 합니다.

또한 언제 더 이상의 시도가 무의미해지는지도 알아야 합니다.

10. 반복되는 지시사항을 인프라로 전환하라

프롬프트에 이런 내용이 있다고 가정해 봅시다:

항상 포매터를 실행할 것.

포매터가 자동으로 실행된다면 이 규칙은 훨씬 강력해집니다.

지시사항에 이렇게 적혀 있다고 가정해 봅시다:

UI 코드는 데이터베이스에 직접 접근할 수 없다.

규칙이 깨졌을 때 실패하는 아키텍처 테스트로 만들면 훨씬 강력해집니다.

발전 과정은 다음과 같습니다:

1설명(EXPLANATION)
2      |
3      v
4체크리스트(CHECKLIST)
5      |
6      v
7템플릿(TEMPLATE)
8      |
9      v
10자동화된 검사(AUTOMATED CHECK)
11      |
12      v
13강제되는 정책(ENFORCED POLICY)

프롬프트는 판단의 기준을 설명해야 합니다.

하니스는 불변 조건(invariant)을 강제해야 합니다.

반복되는 모든 실수는 이 사다리를 한 단계씩 내려가야 합니다.

결국 모델은 그 교훈을 기억할 필요가 없어집니다.

환경이 모델을 대신해 기억해 주기 때문입니다.

11. 실행을 기록하라

완벽한 최종 산출물이 끔찍한 실행 경로를 숨길 수 있습니다.

에이전트가 잘못된 소스에 접근했을지도 모릅니다.

실패한 명령을 무시했을지도 모릅니다.

외부 동작을 두 번 반복했을지도 모릅니다.

예상 예산의 10 배를 썼을지도 모릅니다.

틀린 이유로 정답을 맞혔을지도 모릅니다.

무슨 일이 있었는지 재구성할 수 있을 만큼 충분한 정보를 기록하세요.

109:14  작업 계약 생성
209:15  architecture.md 로드
309:17  checkout.ts 편집
409:18  집중 테스트 실패
509:21  구현 코드 수정
609:22  집중 테스트 통과
709:24  통합 테스트 통과
809:25  배포 차단: 승인 필요

유용한 추적 기록에는 컨텍스트 출처, 도구 호출, 상태 변경, 검증 결과, 재시도 사유, 승인 결정, 비용, 지연 시간이 포함됩니다.

재미 삼아 로그를 모으자는 것이 아닙니다.

실패를 국지화(localize)하자는 것입니다.

18 단계에서 문제가 생겼다면, 18 단계만 수정할 수 있어야 합니다.

실행 전체를 처음부터 다시 돌릴 필요가 없어야 합니다.

12. 모든 실행에 영수증을 발급하라

사람이 메시지 40 개짜리 대화 기록을 전부 리뷰하도록 강요하지 마세요.

결과를 간결한 영수증으로 정리하세요.

1목표(OBJECTIVE)
2
3쿠폰 중복 적용 문제 수정.
4
5변경 사항(CHANGED)
6
7결제 검증 로직
8회귀 테스트
9
10검증 완료(VERIFIED)
11
12lint 통과
13유닛 테스트 통과
14통합 테스트 통과
15
16미검증(NOT VERIFIED)
17
18프로덕션 결제 제공업체
19
20위험 요소(RISKS)
21
22레거시 모바일 클라이언트 사용 불가
23
24승인 필요(APPROVAL NEEDED)
25
26스테이징 배포

이는 모델이 일어났다고 주장하는 내용의 요약이 아닙니다.

하니스가 실제로 일어났음을 증명할 수 있는 내용의 요약입니다.

이 차이가 영수증을 리뷰, 업무 인수인계, 향후 에이전트 세션에 유용하게 만듭니다.

13. 모든 실패가 하니스를 개선하게 만들어라

대부분의 팀은 실패한 출력물만 고칩니다.

더 나은 접근법은 그 실패를 허용한 시스템을 고치는 것입니다.

1컨텍스트 누락
2-> 프로젝트 지도 개선
3
4잘못된 도구
5-> 라우팅 또는 도구 계약 개선
6
7나쁜 출력
8-> 검증기(validator) 추가
9
10반복되는 루프
11-> 재시도 상한 추가
12
13안전하지 않은 동작
14-> 권한 게이트 추가
15
16잊혀진 결정
17-> 상태 영속화
18
19알 수 없는 실패
20-> 추적 기능 개선

여기서부터 하니스 엔지니어링의 복리 효과가 시작됩니다.

출력물 하나를 고치면 한 번의 실행만 좋아집니다.

하니스 하나를 고치면 이후의 모든 실행이 좋아집니다.

최고의 에이전트 시스템은 실수가 인프라로 남기 때문에 점점 더 신뢰할 수 있게 됩니다.

14. 가장 작고 유용한 하니스부터 시작하라

시작한다고 거대한 오케스트레이션 플랫폼이 필요한 것은 아닙니다.

계층별로 구축하세요.

1레벨 0
2
3프롬프트
4모델
5
6레벨 1
7
8작업 계약
9프로젝트 지도
10도구
11
12레벨 2
13
14구조화된 상태
15검증
16제한된 루프
17
18레벨 3
19
20권한
21추적
22복구
23사람 개입 게이트

짧은 리서치 작업이라면 프롬프트와 한 번의 리뷰만 필요할 수 있습니다.

파일 접근, 네트워크 접근, 배포 기능이 포함된 6 시간짜리 코딩 작업이라면 훨씬 더 많은 것이 필요합니다.

실패 표면(failure surface)이 복잡성을 요구할 때 복잡성을 추가하세요.

에이전트 아키텍처가 멋져 보여서가 아닙니다.

하니스 엔지니어링 체크리스트

에이전트에게 실질적인 자율성을 부여하기 전에 다음을 자문해 보세요:

1[ ] 실행 전에 성공 기준이 정의되어 있는가?
2
3[ ] 에이전트가 모든 것을 로드하지 않고도
4    올바른 컨텍스트를 찾을 수 있는가?
5
6[ ] 모든 도구에 명확한 목적, 스키마,
7    실패 상태가 있는가?
8
9[ ] 중요한 결정이 대화 밖의 어딘가에
10    저장되는가?
11
12[ ] 완료에 증거가 요구되는가?
13
14[ ] 위험한 동작이 정책으로 보호되는가?
15
16[ ] 모든 루프에 재시도 제한이 있는가?
17
18[ ] 중단 후에도 실행을 재개할 수 있는가?
19
20[ ] 모든 중요한 동작을 재구성할 수 있는가?
21
22[ ] 실패가 규칙, 도구, 테스트, 지도,
23    권한 중 하나를 개선하는가?
24
25[ ] 최종 변경 사항을 롤백할 수 있는가?

여러 항목의 답이 '아니오'라면, 더 강력한 모델이 에이전트를 자동으로 신뢰할 수 있게 만들어 주지는 않습니다.

오히려 실패를 더 빠르고 비싸게 만들 뿐일 수 있습니다.

진정한 전환

프롬프트 엔지니어링은 이렇게 묻습니다:

모델에게 무엇을 말해야 할까?

컨텍스트 엔지니어링은 이렇게 묻습니다:

모델이 지금 당장 무엇을 알아야 할까?

하니스 엔지니어링은 이렇게 묻습니다:

어떤 시스템이 모델이 행동하고, 자신의 작업을 검증하고, 실패에서 복구하며, 안전하게 운영되도록 할 것인가?

1프롬프트(PROMPT)
2-> 지시사항
3
4컨텍스트(CONTEXT)
5-> 작업 중인 뷰
6
7하니스(HARNESS)
8-> 운영 환경
9
10루프(LOOP)
11-> 국지적 수정
12
13그래프(GRAPH)
14-> 조율(coordination)

모델은 계속 바뀔 것입니다.

지속 가능한 이점은 모델 주변에 존재합니다.

당신의 계약이 나아집니다.

당신의 도구가 나아집니다.

당신의 테스트가 나아집니다.

당신의 상태가 깔끔해집니다.

당신의 권한이 안전해집니다.

당신의 복구 로직이 똑똑해집니다.

당신의 실패가 인프라로 바뀝니다.

그렇게 유능한 모델이 신뢰할 수 있는 에이전트가 됩니다.

그것이 바로 하니스 엔지니어링입니다.

여기까지 읽으셨다면

이 가이드를 북마크하세요.

X 에서 저를 팔로우하세요: x.com/0xjmori

제 Substack 을 구독하세요: substack.com/@lunarresearcher

여전히 모든 에이전트 실패를 더 긴 프롬프트로 해결하려는 사람에게 이 글을 공유해 주세요.