요즘 에이전트 이야기를 하는 팀들을 보면, 대화 주제가 조금씩 바뀌고 있습니다. 예전에는 “어떤 모델이 더 코드를 잘 쓰는가"가 중심이었다면, 지금은 “이 에이전트를 어떤 프레임 안에서 움직이게 할 것인가"가 더 중요한 질문이 됐습니다. 같은 모델을 써도 어떤 팀은 PR 품질과 운영 안정성이 같이 올라가고, 어떤 팀은 재시도만 늘고 리뷰 피로만 커집니다.

이 차이를 만드는 게 바로 Harness Engineering입니다. 여기서 harness는 단순 래퍼 스크립트가 아닙니다. 컨텍스트를 어떻게 주입하고, 어떤 도구를 언제 열어 주고, 어떤 결과만 통과시키고, 실패하면 어디서 멈추고 사람에게 넘길지를 정하는 실행 프레임에 가깝습니다.

즉 2026년의 경쟁 포인트는 “더 똑똑한 모델 1개"보다, 덜 흔들리는 실행 구조 1개에 있습니다.

이 글에서 얻는 것

  • Harness Engineering이 왜 프롬프트 튜닝 다음 단계가 아니라, 이미 별도 설계 분야로 올라왔는지 이해할 수 있습니다.
  • 컨텍스트, 권한, 검증, 복구를 어떤 순서로 묶어야 에이전트 품질이 안정되는지 기준을 잡을 수 있습니다.
  • 팀이 실제 도입 여부를 판단할 때 필요한 숫자 기준, 운영 우선순위, 실패 중단 조건을 바로 가져갈 수 있습니다.

핵심 개념/이슈

1) 프롬프트보다 실행 경계가 더 큰 품질 차이를 만든다

초기에는 프롬프트를 잘 쓰면 품질이 올라가는 구간이 분명 있었습니다. 하지만 팀 단위 운영으로 들어가면 프롬프트보다 더 큰 차이를 만드는 요소가 나타납니다.

  • 잘못된 컨텍스트를 얼마나 빨리 차단하는가
  • 허용되지 않은 도구 호출을 어떻게 막는가
  • 초안이 나왔을 때 어떤 검증기를 반드시 거치게 하는가
  • 실패했을 때 무한 재시도 대신 어디서 중단하는가

이 네 가지가 약하면 모델이 좋아도 결과가 흔들립니다. 그래서 최근 흐름은 프롬프트 엔지니어링에서 끝나지 않고, Schema-Constrained Output + Runtime Validator나 Tool Permission Manifest + Runtime Attestation처럼 계약과 실행 증적을 먼저 붙이는 구조로 이동하고 있습니다.

2) 좋은 harness는 ‘무엇을 더 하게 할지’보다 ‘무엇을 못 하게 막을지’를 먼저 정의한다

실무에서 에이전트 사고는 대체로 기능 부족보다 경계 부족에서 시작합니다.

  • 읽기 전용이어야 할 작업이 쓰기 권한까지 가진 상태로 실행
  • 테스트 증거 없이 코드 수정 결과를 그대로 PR에 반영
  • 저장소 전체를 읽을 필요가 없는데 과도한 컨텍스트를 계속 주입
  • 실패한 작업을 같은 조건으로 반복 실행

결국 harness의 첫 역할은 생산성 증폭이 아니라 위험 반경 제한입니다. 이 점은 이미 AI 코딩 에이전트 런타임 거버넌스와 AI 에이전트 관측/통제 흐름에서 드러났고, 최근에는 그 위에 더 세밀한 하네스 레이어가 붙고 있습니다.

3) 컨텍스트 주입, 도구 권한, 결과 검증, 실패 복구는 분리 설계해야 한다

Harness를 한 덩어리 설정 파일로 관리하면 빠르게 복잡해집니다. 실무에서는 보통 네 층으로 쪼개는 편이 안정적입니다.

  1. Context layer: 어떤 저장소 정보, 문서, 히스토리를 넣을지 결정
  2. Capability layer: 읽기/쓰기/명령 실행/외부 호출 권한을 제한
  3. Validation layer: 스키마, 테스트, 정책, 위험 경로 검증
  4. Recovery layer: 재시도, 인간 승인, 중단, 롤백 흐름

이 네 층이 섞이면 수정이 어려워지고, 실패 원인도 안 보입니다. 반대로 분리하면 같은 모델을 써도 작업 유형별로 harness만 달리 적용할 수 있습니다. 최근 코드베이스 지식 그래프 + 시맨틱 인덱스가 주목받는 것도 context layer를 별도 자산으로 보기 시작했기 때문입니다.

4) 품질 평가는 정답률보다 ‘머지 가능성’과 ‘재작업률’이 더 중요하다

데모 단계에서는 응답 품질이 중요하지만, 운영 단계에서는 다른 지표가 더 중요합니다.

  • 첫 시도 후 머지 가능 비율
  • 리뷰어 수동 수정량
  • 재시도 횟수
  • 정책 위반 차단 건수
  • 위험 경로 변경 시 인간 승인 전환 비율

즉 harness는 모델 성능을 보기 좋게 만드는 장치가 아니라, 팀이 받아들일 수 있는 결과만 통과시키는 게이트입니다. 그래서 최근 실무에서는 생성량보다 “검증 후 통과율"이 더 중요한 KPI가 됩니다.

도입 초기에 가장 자주 터지는 실패 패턴

1) 읽기 컨텍스트는 넓은데 쓰기 권한이 그대로 열려 있는 경우

이 조합은 현업에서 정말 자주 보입니다. 저장소 전체를 읽을 수 있게 열어 놓고, 수정도 바로 가능하게 두면 에이전트는 빠르게 움직이지만 동시에 잘못된 파일까지 건드릴 확률도 올라갑니다. 특히 오래된 문서, 실험 코드, 생성 산출물이 섞인 저장소에서는 최신 경로와 폐기 경로를 구분하지 못한 채 수정이 퍼집니다.

실무에서는 먼저 읽을 수 있는 범위와 쓸 수 있는 범위를 분리해야 합니다. 예를 들어 전체 저장소 읽기는 허용하더라도, 쓰기는 특정 앱 디렉터리나 문서 경로만 허용하고 민감 디렉터리는 승인 게이트로 넘기는 식입니다. 이 구조가 있어야 Tool Permission Manifest + Runtime Attestation 같은 통제 레이어가 실제 효과를 냅니다.

2) 테스트는 돌리지만 통과 기준이 느슨한 경우

많은 팀이 “테스트를 붙였다"고 말하지만, 실제로는 일부 단위 테스트만 통과해도 결과를 올려버립니다. 이러면 하네스가 있어도 품질이 안정되지 않습니다. 중요한 건 테스트 실행 여부가 아니라 어떤 증거가 있어야 다음 단계로 넘어갈 수 있는지입니다.

예를 들어 코드 수정 작업이라면 정적 분석 통과 + 변경 경로 테스트 통과 + 위험 파일 변경 여부 확인 세 가지를 동시에 만족해야 제출 가능하게 만드는 편이 낫습니다. 문서 수정 작업도 마찬가지로 링크 점검, front matter 검증, 중복 확인이 빠지면 운영 품질이 계속 흔들립니다.

3) 실패 복구가 재시도 루프 하나로 끝나는 경우

재시도는 복구 전략의 일부일 뿐, 복구 그 자체가 아닙니다. 같은 컨텍스트와 같은 권한으로 세 번 반복하면 품질이 올라가기보다 비용만 늡니다. 그래서 recovery layer에는 최소한 아래 세 가지가 필요합니다.

  • 동일 오류 반복 시 read-only 강등
  • 정책 차단과 테스트 실패를 구분한 분기
  • 인간 승인 또는 handoff로 전환하는 상한선

이 원칙이 없으면 에이전트 운영은 자동화가 아니라 반복 실패의 자동 확장이 됩니다. 최근 Inference Router + Quality-Cost Gateway가 주목받는 이유도, 결국 모델 선택보다 먼저 실패 비용을 통제하는 프레임이 필요하기 때문입니다.

실무 적용

1) 언제 Harness Engineering 투자가 필요한가

아래 조건 중 2개 이상이면 프롬프트 개선보다 harness 투자가 먼저입니다.

  • AI 생성 결과의 재작업률이 20% 이상
  • 동일 유형 작업의 성공 품질 편차가 큰 편
  • PR 생성까지는 빠르지만 머지 리드타임이 줄지 않음
  • 민감 경로 변경, 외부 호출, 명령 실행이 함께 섞여 있음
  • 실패 원인이 모델 탓인지 권한/검증/컨텍스트 탓인지 구분이 안 됨

반대로 문서 초안, 요약, 비민감 read-only 작업 위주라면 무거운 harness가 과할 수 있습니다.

2) 의사결정 기준(숫자·조건·우선순위)

권장 우선순위는 무단 실행 방지 > 결과 검증 가능성 > 재현성 > 처리 속도 > 비용 입니다.

초기 운영 기준 예시:

  • 미허용 도구 호출 차단률: 100%
  • 스키마/정책 검증 통과 전 자동 제출률: 0%
  • 첫 시도 머지 가능 비율: 60% 이상 목표
  • 재작업률: 20% 미만
  • 동일 작업 재시도 3회 초과 비율: 5% 미만
  • 인간 승인 대기 p95: 10분 이내

자동 완화 규칙 예시:

  • 동일 작업 2회 연속 정책 차단 시 read-only 모드로 강등
  • 테스트 실패 + 민감 경로 변경 동시 발생 시 자동 중단
  • 컨텍스트 stale 추정치 15분 초과 시 쓰기 권한 비활성화
  • 재시도 3회 초과 시 모델 교체보다 harness 진단을 먼저 수행

3) 권장 최소 하네스 구성

작게 시작할 때는 아래 5개면 충분합니다.

  1. 작업 유형별 권한 티어 분리
  2. 읽기 컨텍스트 allowlist와 stale 경보
  3. 출력 스키마 또는 체크리스트 기반 validator
  4. 민감 경로 변경 시 승인 게이트
  5. 실패 시 즉시 중단할 kill switch

이 조합만 있어도 “에이전트가 잘 썼는가"보다 “에이전트가 안전하게 일했는가"를 볼 수 있습니다. 비용 최적화가 필요한 팀은 Inference Router + Quality-Cost Gateway를 별도 레이어로 붙이는 편이 깔끔합니다.

4) 4주 도입 플랜

1주차: 실패를 분류한다
모델 실패, 컨텍스트 실패, 권한 실패, 검증 실패, 승인 대기 실패를 나눠 기록합니다.

2주차: 작업 유형별 하네스 분리
read-only, 문서 수정, 코드 수정, 배포 연계 작업을 각각 다른 권한과 검증으로 나눕니다.

3주차: validator와 승인 게이트 연결
스키마 검증, 테스트 증거, 민감 경로 차단 규칙을 자동화합니다.

4주차: 관측과 강등 규칙 고정
재시도 상한, 인간 handoff 조건, kill switch 절차를 문서화합니다.

트레이드오프/주의점

  1. 하네스를 너무 두껍게 만들면 속도가 떨어진다
    모든 작업에 동일한 검증과 승인을 붙이면 작은 작업도 과하게 느려집니다. 작업 등급별 차등이 필요합니다.

  2. 프레임이 좋아도 컨텍스트가 낡으면 결과는 계속 흔들린다
    Harness는 모델을 보호하지만, 오래된 코드 정보까지 마법처럼 고쳐 주지는 못합니다.

  3. 검증기가 약하면 하네스가 있어도 데모 수준에 머문다
    출력 형식 검사만 하고 의미 검증을 안 하면, 보기 좋은 오답이 그대로 통과합니다.

  4. 승인 체계를 병목으로 만들면 우회 경로가 생긴다
    승인 SLA, 백업 승인자, 자동 강등 규칙 없이 통제만 강화하면 결국 비공식 사용이 늘어납니다.

체크리스트 또는 연습

체크리스트

  • 작업 유형별로 컨텍스트, 권한, 검증, 복구 규칙이 분리돼 있다.
  • 미허용 도구 호출과 민감 경로 변경은 자동 차단된다.
  • 결과 제출 전 validator 또는 테스트 증거가 필수다.
  • 재시도 상한과 인간 handoff 조건이 숫자로 정의돼 있다.
  • kill switch와 read-only 강등 절차가 문서화돼 있다.

연습 과제

  1. 최근 2주간 에이전트 작업 20건을 골라 실패 원인을 모델/컨텍스트/권한/검증/승인으로 재분류해 보세요.
  2. 가장 자주 반복되는 작업 1개에 대해 read-only 하네스와 write 하네스를 분리했을 때 재작업률이 얼마나 줄어드는지 측정해 보세요.
  3. 첫 시도 머지 가능 비율, 재시도율, 정책 차단율을 1주간 수집해 현재 팀의 하네스 성숙도를 점수화해 보세요.

관련 글