AI harness

harness란 무엇인가?

harness = “모델을 ‘말하는 뇌’에서 ‘일하는 시스템’으로 바꾸는 실행 프레임(스캐폴딩)”

AI 에이전트 분야에서 harness는 모델(LLM) 자체가 아니라, 모델이 도구를 쓰고, 작업을 쪼개고, 검증하고, 세션이 끊겨도 이어서 일하도록 만드는 주변 실행 환경 + 운영 규율을 묶어서 부르는 말이다. 처음 이 단어를 들으면 보통 이런 식의 “핵심 의문”이 자연스럽게 생긴다:

• “에이전트 얘기할 때 harness가 왜 갑자기 나오지?”
• “이게 공식 용어인가, 그냥 누가 편하게 쓰는 말인가?” Anthropic 글은 이 혼란을 꽤 잘 정리해준다. 그들이 말하는 harness는 “툴을 붙이는 코드” 수준이 아니라 오래 달리는(long-running) 작업을 끝까지 완주하게 만드는 작업 프레임에 가깝다.

---

“그림에서 Model을 제외한 나머지”가 harness일까?

구글의 agent runtime 그림을 보면 Model 옆/위에 Orchestration, Memory, Tools 같은 구성요소가 붙어 있다.
이 구조를 보는 순간 다음 질문으로 이어진다:

그렇다면 실무에서 말하는 harness는, 저 그림에서 Model을 빼고 나머지(Agent Runtime) 전체를 가리킨다고 이해해도 될까? 대부분의 대화/문맥에서 답은 Yes다. harness에 보통 포함되는 범위는 아래처럼 정리된다.

• Orchestration: 계획 → 실행 → 관찰 → 다음 행동(루프), 재시도/분기, 종료 조건
• Memory / State: short/long-term 저장, 체크포인트, 세션 브리징(다음 세션이 읽을 수 있는 형태)
• Tools: 검색/DB/코드/브라우저 자동화 등 손발 연결, 툴 호출 정책
• Verification: 테스트/수용조건 확인, 실패 시 복구 루프
• Artifacts: 진행 로그, git 히스토리, 환경 스크립트 같은 “실행 흔적” 그런데 여기서 한 번 더 걸리는 포인트가 있다. “Reasoning/Planning”을 어디에 두느냐이다.

reasoning/planning도 harness에 포함되는 걸까, 아니면 모델 쪽일까? 실무적으로는 이렇게 나누면 가장 덜 헷갈린다:

• 생각(추론/계획의 생성) 자체는 모델의 능력
• harness는 그 생각을 반복 실행하고 관리하는 프레임(루프/규율)이다. 즉, 생각을 ‘만드는 것’은 모델, 생각을 ‘굴리고 지속시키는 것’은 harness. 이제 다음 연결 질문이 나온다. “그럼 harness를 더 구체적으로 설명한 신뢰 가능한 레퍼런스가 있나?”

---

“문서에 harness라는 단어가 없던데…” → 어디서 ‘AI 에이전트 harness’ 개념을 잡나?

AI 에이전트 분야에서 harness는 아직 “표준 용어”처럼 딱 고정된 단어라기보단,

• runtime
• orchestration layer
• scaffolding
• agent framework 같은 표현들과 겹치는 의미로 쓰이는 경우가 많다. 그래서 용어만 쫓으면 헷갈리고, “어떤 문제를 해결하려는 설계인가?”를 보면 빠르게 정리된다.
  여기서 Anthropic의 글(Effective harnesses for long-running agents)이 강한 이유는:

harness가 왜 필요한지(실패 모드) → 어떻게 설계해야 하는지(구성/규율)까지 “long-running” 관점에서 매우 구체적으로 적어두었기 때문. 이 글이 던지는 다음 연결 질문은 명확하다. “long-running”에서 harness가 특별히 중요한 이유가 뭘까?

---

Anthropic이 말하는 “long-running agent harness”의 핵심 문제

핵심 문제는 한 문장으로 요약된다:

• 에이전트는 컨텍스트 윈도우 때문에 “세션” 단위로 끊겨 일하고,
• 새 세션은 이전 맥락을 “자동으로” 다 기억하지 못해서,
• 다음 세션이 추측으로 출발하면 진행이 쉽게 무너진다. 즉 long-running에서 harness의 목표는 “툴을 붙이기”를 넘어 이렇게 바뀐다:

세션이 끊겨도 다음 세션이 추측하지 않고 확인하며 이어서 달리게 만들기 여기서 자연스럽게 다음 질문으로 넘어간다. 그럼 “추측을 줄이려면” harness가 구체적으로 뭘 제공해야 할까? Anthropic은 그 답을 “artifact(환경에 남기는 산출물) + 운영 규율”로 풀어낸다.

---

harness를 구체화하는 ‘artifact’ 4종 세트(Anthropic식)

1) feature list: “완성”을 파일로 고정

Initializer가 사용자 요구를 확장해 수백 개 수준의 end-to-end 요구사항 목록을 만든다.
그리고 이후 작업 에이전트는 이 파일을 삭제/수정하지 말고, 오직 passes만 바꾸게 제한한다.

{
  "category": "functional",
  "description": "New chat button creates a fresh conversation",
  "steps": [
    "Navigate to main interface",
    "Click the 'New Chat' button",
    "Verify a new conversation is created"
  ],
  "passes": false
}

이게 효과적인 이유는 간단하다: “됐다/안 됐다”를 말로 합의하는 게 아니라, 수용조건을 고정해버리기 때문이다.

2) claude-progress.txt: 세션 간 이어달리기 로그

세션이 끝날 때마다 “무엇을 했는지 / 무엇을 결정했는지 / 다음에 뭘 하면 되는지”를 짧게 남긴다.
다음 세션은 이 파일부터 읽고 출발한다.

3) init.sh: 매 세션을 동일한 방식으로 기동시키는 스위치

서버 띄우기, 초기 설정, smoke test 같은 “매번 해야 하지만 자주 까먹는 것”을 스크립트로 고정한다.

4) git history: 상태 파악/복구의 공용 언어

long-running에서는 “현재 상태가 뭔지”를 빠르게 합의하는 게 중요하고, git이 그 역할을 한다.
다음 세션은 git log를 보고 “어디까지 했는지”를 바로 파악한다. 이제 다음 질문으로 자연스럽게 이어진다.

artifact를 준비했으면 끝일까? 실제로는 ‘어떻게 굴리느냐(규율)’가 더 중요하지 않을까? 맞다. 그래서 Anthropic은 harness를 “운영 규칙”으로도 정의한다.

---

harness 운영 규칙 4개(“오래 달리기”에 맞춘 규율)

규칙 1) “완성”은 주장하지 말고, feature list로 증명

‘다 됐습니다’가 아니라 passes가 true가 된 항목의 합으로 완성을 정의한다.

규칙 2) 한 세션에 하나씩: incremental progress

“크게 한 방에”보다 “작게 완주를 반복”하는 방식이 세션 단절에 강하다.
세션이 끊겨도 다음 세션이 바로 이어받을 수 있게 만든다.

규칙 3) 세션 종료는 clean state(merge-ready)

세션을 끝낼 때는 “다음 세션이 청소부터 하지 않도록” 정리된 상태여야 한다.
(코드 정돈, 큰 버그 없음, 최소한의 문서화 등)

규칙 4) passes는 E2E 검증 후에만 바꾼다

핵심은 “테스트를 했는가”가 아니라 현실적인 검증 루프가 harness에 고정돼 있는가다.
브라우저 자동화 같은 도구가 여기에 들어오면, 사람이 하듯 end-to-end 검증을 수행하기가 쉬워진다. 이제 마지막 연결 질문이 남는다.

규칙을 ‘알고’ 있는 것과, 매 세션마다 ‘실제로’ 적용하는 건 다르지 않을까? 그래서 harness는 “체크리스트(프로토콜)”까지 제공하는 쪽으로 구체화된다.

---

매 세션 시작 루틴(= harness가 제공하는 기본 프로토콜)

세션이 바뀌면 에이전트는 기억이 없다. 그래서 시작은 늘 “상태 복구”부터다. 1) pwd 2) read claude-progress.txt 3) read feature_list.json 4) git log --oneline -20 5) init.sh 로 서버 기동 6) 기본 E2E smoke test 7) 다음으로 고칠 feature 1개 선택 → 구현/검증 8) git commit + progress 파일 업데이트 이 루틴의 목적은 한 가지다:

세션이 끊겨도 다음 세션이 추측 대신 확인으로 출발하게 만들기

---

최종 요약(7줄)

1. harness는 모델이 아니라 모델을 ‘일하는 시스템’으로 만드는 런타임/스캐폴딩이다.
2. (그림 기준) Model을 제외한 Orchestration/Memory/Tools 덩어리를 harness로 보면 대부분 맞다.
3. long-running에서는 harness의 목표가 세션 간 단절을 메우기로 확장된다.
4. feature_list.json로 완성 기준선을 고정해 조기 완료 선언을 막는다.
5. 매 세션은 하나씩 완주하고, 반쯤 만든 채 넘기지 않는다.
6. 세션 종료는 clean state + git commit + progress 기록이 기본이다.
7. passes는 “했다고 주장”이 아니라 E2E 검증 후에만 바꾼다.

---

참고 문서

• Effective harnesses for long-running agents
• Building agents with the Claude Agent SDK
• Claude platform docs