에이전트 하네스 설계 3가지 패턴

• 출처: Anthropic 블로그 Agent Harness Design: 3 Patterns for Harnessing Claude’s Intelligence (Lance Martin, 2026-04-02).
• 하네스(harness): 모델을 둘러싼 소프트웨어 뼈대. 루프, 도구, 컨텍스트 관리, 가드레일을 묶어 순수한 지능을 동작하는 에이전트로 바꾸는 층이다.
  • 모델 자체(Claude)와는 구분된다. 같은 모델이라도 하네스를 어떻게 짜느냐에 따라 결과가 달라진다.
• 핵심 메시지: “생성형 AI 시스템은 만들어진다기보다 자라난다.” 하네스에 박아 넣은 “Claude는 이걸 못 하니까 내가 대신해 준다"는 가정은 모델이 좋아지면 그대로 낡은 짐이 된다.
  • 그래서 하네스 설계의 질문은 “무엇을 더 넣을까"가 아니라 “무엇을 그만둘 수 있는가” 다.
• 대신 무한정 걷어낼 수는 없다. 지연 시간·비용·안전 경계는 여전히 하네스가 책임진다. 아래 세 패턴이 그 균형점이다.

1. 하네스가 아니라 모델에 기댄다

• Claude가 이미 잘 아는 도구로 애플리케이션을 만든다. 새 도메인 전용 도구를 발명하는 것보다 학습된 도구를 쓰는 쪽이 강하다.
• 근거: Claude 3.5 Sonnet은 bash 도구와 텍스트 에디터 도구(파일 조회·생성·편집) 두 개만으로 SWE-bench Verified 49%를 기록했다.
  • SWE-bench Verified: 실제 GitHub 이슈를 코드 수정으로 해결하는지 측정하는 벤치마크.
• 고수준 기능들도 결국 이 두 도구의 조합이다.
  • Agent Skills, programmatic tool calling(Claude가 도구 호출을 코드로 표현하는 방식), 메모리 도구 — 셋 다 bash + 텍스트 에디터 위에 얹혀 있다.
  • 즉 하네스에 복잡한 전용 구현을 추가하지 않고도 특수 목적 패턴을 만들 수 있다.

2. 하네스를 걷어낸다

• 모델이 좋아질 때마다 “내 하네스에 인코딩된 가정 중 아직 필요한 게 뭔가"를 다시 평가한다. 재평가 대상은 크게 세 가지다.

Claude가 스스로 행동을 조율하게 한다

• 흔한 안티패턴: 모든 도구 실행 결과를 Claude의 컨텍스트 윈도우로 되돌려 보내는 것.
  • 컨텍스트 윈도우: 모델이 한 번에 볼 수 있는 텍스트 창. 여기에 들어가는 토큰이 그대로 비용과 지연이 된다.
  • 검색 결과 100건을 전부 컨텍스트에 넣고 Claude가 읽어서 3건을 고르는 식이면, 나머지 97건 값을 그대로 낸 셈이다.
• 해법: Claude에게 코드 실행 도구를 주고, 도구 호출과 그 사이의 로직을 코드로 쓰게 한다.
  • 결과를 필터링하거나 다른 도구로 파이프할 때 중간 데이터가 컨텍스트를 거치지 않는다.
• 효과: BrowseComp(웹 탐색 벤치마크)에서 Opus 4.6이 자기 도구 출력을 직접 필터링하게 하자 정확도가 45.3% → 61.6% 로 올랐다.

Claude가 스스로 컨텍스트를 관리하게 한다

• 시스템 프롬프트에 모든 작업 지시를 미리 다 넣지 않는다. 대신 점진적 공개(progressive disclosure) 가 가능한 스킬로 제공한다.
  • 점진적 공개: 목록과 한 줄 설명만 먼저 보여주고, 필요하다고 판단했을 때 Claude가 본문을 읽어 들이는 방식.
• 컨텍스트 편집(context editing): 낡아서 쓸모없어진 정보를 선택적으로 제거한다.
• 서브에이전트: Claude가 새 컨텍스트 윈도우로 갈라져 나가 격리된 작업을 처리한다. 부모 컨텍스트는 결과만 받는다.
  • 서브에이전트를 여러 개 조율하는 구체적 사례는 Claude Code 동적 워크플로우 참고.

Claude가 스스로 컨텍스트를 보존하게 한다

• 오래 도는 에이전트는 컨텍스트 윈도우를 반드시 넘긴다. 이때 무엇을 남길지 하네스가 정하지 말고 Claude가 정하게 한다.
• 컴팩션(compaction): Claude가 지금까지의 대화를 스스로 요약해 새 컨텍스트로 넘긴다.
• 메모리 폴더: Claude가 필요할 때 파일을 쓰고 읽는다. BrowseComp 정확도가 60.4% → 67.2% 로 올랐다.
• 점진적 컴팩션을 적용했을 때 모델별 BrowseComp 정확도 차이가 이 능력의 성장을 그대로 보여준다.

3. 경계는 신중히 긋는다

• 걷어내면 안 되는 부분도 있다. 캐시 효율과 안전·UX 경계는 하네스가 계속 책임진다.

캐시 적중을 극대화하도록 컨텍스트를 배치한다

• Messages API는 무상태(stateless) 다. 매 턴마다 하네스가 전체 컨텍스트를 다시 싸서 보낸다.
• 프롬프트 캐싱: 지정한 중단점(breakpoint)까지의 내용을 캐시에 저장해 두고 재사용한다. 캐시된 토큰은 기본 입력 토큰의 10% 비용이다.
• 캐시 적중률을 지키는 원칙:

• 앞부분이 조금만 바뀌어도 그 뒤 전부가 캐시 미스가 되므로, “정적 → 동적” 순서가 사실상 나머지 원칙의 근거다.

선언적 도구로 경계를 만든다

• bash 하나면 무엇이든 할 수 있지만, bash 호출은 하네스 입장에서 불투명한 문자열일 뿐이다.
• 특정 행동을 전용 도구로 승격하면 하네스가 타입이 있는 인자를 받는다. 이걸 가로채고, 막고, 렌더링하고, 감사할 수 있다.
• 승격할 가치가 있는 세 가지 이유:
  • 보안: 되돌릴 수 있는가(reversibility)가 좋은 기준이다. 외부 API 호출처럼 되돌리기 어려운 행동은 사용자 확인으로 막는다. 쓰기 작업은 최근 수정된 파일을 덮어쓰지 않도록 staleness 검사를 붙인다.
  • UX: 사용자에게 행동을 보여줄 통로가 된다. 질문을 모달로 띄우거나, 선택지를 제시하거나, 피드백을 받을 때까지 에이전트 루프를 멈출 수 있다.
  • 관측 가능성: 구조화된 인자를 로깅·트레이싱·재현할 수 있다.
• 단, 보안 경계를 꼭 전용 도구로만 세울 필요는 없다. Claude Code의 auto 모드는 두 번째 Claude가 명령 문자열을 읽고 안전한지 판정한다. 전체 방향을 신뢰하는 맥락이라면 전용 도구 없이도 경계가 선다.

모델이 자란다는 것: 포켓몬 메모리 사례

• 같은 하네스, 같은 14,000 스텝에서 모델만 바꿨을 때 메모리 사용 방식이 어떻게 달라지는지 보여주는 예.

• Sonnet 3.5의 메모리에는 “캐터피와 뿔충이는 둘 다 애벌레 포켓몬” 같은 중복·잡다한 기록이 쌓였다.
• Opus 4.6은 /gameplay/learnings.md 에 “모다피의 수면가루+감기 콤보: 수면가루가 들어가기 전에 물기로 빨리 KO” 같은 전술 요약, 미로 탐색 결과, 벽 좌표를 정리해 뒀다.
• 요지: 무엇을 기억할지 판단하는 능력이 모델 자체에서 크게 올라왔다. 예전 모델을 위해 하네스에 넣어 둔 메모리 규칙은 이제 방해가 된다.