Claude Code 하네스 엔지니어링 – 모델보다 하네스가 먼저다

문제를 받으면 “이렇게 구현하면 되겠다” 싶어 곧장 코드로 넘어가는 경우가 많다. 그런데 Claude Code가 강력한 이유는 모델이 똑똑해서가 아니다. 모델을 둘러싼 하네스(harness) 구조가 강력해서다. 같은 원리를 사람의 문제 설계에도 적용할 수 있다. 이 글은 Claude Code의 코어 루프와 하네스를 분해한 뒤, 그 구조를 설계 방법론으로 옮겨오는 과정을 다룬다. 실행 가능한 방법론이라는 의미로 이 방법론을 코드크래프트(CodeCraft)라고 부르겠다

코어 루프는 의외로 단순하다

Claude Code의 중심에는 단순한 반복문 하나가 있다. 모델을 호출하고, 모델이 도구 사용을 요청하면 도구를 실행하고, 그 결과를 다시 모델에게 넘긴다. 이 과정을 반복한다

모델 호출
  → 모델이 Tool Use 요청
    → 하네스가 요청을 파싱
      → 권한 확인
        → 도구 실행
          → 결과를 다시 모델에게 반환
            → 반복

핵심은 모델이 파일 시스템, 셸, 네트워크에 직접 접근하지 않는다는 점이다. 모델은 “이 도구를 이렇게 쓰겠다”는 요청만 만든다. 그 요청을 파싱하고, 권한을 확인하고, 실제 구현으로 넘기는 일은 전부 하네스가 한다

이 분리가 안전성의 출발점이다. 모델이 잘못 판단하거나 외부 입력에 조작되더라도, 하네스가 샌드박싱과 권한 검사로 실행을 통제할 수 있다. 논문이 꼽은 Claude Code의 다섯 가지 설계 동기 중 하나가 바로 이 통제권, 즉 인간 결정 권한(human decision authority)이다

모델과 하네스의 역할은 다르다

코어 루프 안에서 모델과 하네스가 맡는 일은 명확히 갈린다

주체하는 일
모델판단하고, 다음 액션을 제안하고, Tool Use를 요청한다
하네스요청을 검증하고, 권한을 확인하고, 도구를 실행하고, 결과를 루프에 되돌린다

모델은 제안까지만 한다. 실행은 하네스가 통제한다. 이 구분을 설계에 옮기면 이렇게 된다. “이렇게 구현하면 되겠다”는 판단이 곧 실행은 아니다. 그 설계가 입력 조건을 만족하는지, 출력 규칙을 지키는지, 제약을 위반하지 않는지, 엣지 케이스를 통과하는지 먼저 확인해야 한다. 판단과 실행 사이에 검증 단계를 두는 것이 하네스 엔지니어링의 출발점이다

Context Harness – 맥락은 희소 자원이다

Claude Code가 가진 가장 현실적인 제약은 컨텍스트 윈도우다. 한 번에 볼 수 있는 정보량이 정해져 있다. 그래서 모델을 호출하기 전에 불필요하거나 너무 큰 정보를 줄인다. 논문은 이 과정을 다섯 단계의 컨텍스트 축소 파이프라인으로 설명한다

단계역할
Budget Reduction크기 한계를 넘긴 개별 도구 출력을 참조 포인터로 대체
Snip오래되고 덜 중요한 기록을 잘라냄
Micro-Compact캐시 효율을 지키는 세밀한 압축
Context Collapse매우 긴 대화 기록을 관리
Auto-Compact마지막 수단으로 의미 기반 요약

이 구조가 말하는 바는 분명하다. 맥락은 무한정 넣을 수 없는 희소 자원이고, 무엇을 넣고 무엇을 줄일지가 결과를 가른다

설계로 옮기면 병목은 모델의 컨텍스트 윈도우가 아니라 문제 맥락을 얼마나 정확히 잡았는가다. 예를 들어 “고객 주문의 배송비를 계산하는 서비스를 만들어라”라는 문제를 받았다고 하자. 겉보기엔 배송비 계산기 만들기다. 하지만 이 한 문장만 보고 코드를 짜면 중요한 맥락을 놓친다. 주문 금액이 높으면 무료 배송인가? 비나 눈이 오면 추가 요금이 붙는가? 도시마다 기본 요금이 다른가? 프리미엄 고객은 할인을 받는가? 이 질문이 정리되지 않으면 사람도 코드도 추측으로 움직인다

그래서 코드를 짜기 전에 문제 맥락을 다음처럼 명시한다

모호한 문제: "배달 수수료 계산기를 만들어라"

입력:    주문 금액, 배달 거리, 도시, 고객 타입, 날씨, 주문 상태
출력:    기본 배송비, 추가 요금, 할인 금액, 최종 배송비 (음수 불가)
제약:    음수 거리 금지, 취소 주문 제외, 최종 배송비 음수 금지
변경 가능성: 도시별 요금, 날씨별 추가 요금, 멤버십 할인, 프로모션 정책

Claude Code가 컨텍스트를 관리하지 않으면 엉뚱한 파일을 보거나 중요한 정보를 잃는다. 문제 맥락을 관리하지 않으면 엉뚱한 설계를 한다. 짧은 한 문장짜리 프롬프트만 보고 코드를 만들면 추측 위에 코드가 쌓인다. 요구사항 분석이 곧 사람의 Context Harness다

Tool Harness – 설계 옵션과 디자인 패턴

Claude Code는 MCP, 스킬, 훅, 플러그인 같은 확장 메커니즘으로 능력을 넓힌다. 설계에서 이에 대응하는 것이 디자인 패턴이다. 패턴은 외워서 쓰는 정답이 아니라, 변하는 부분을 갈아 끼울 수 있게 만드는 도구다

변하는 부분쓰는 패턴효과
계산 정책이 자주 바뀐다Strategy정책을 통째로 교체 가능
상황별로 다른 객체를 만든다Factory생성 규칙을 한곳에 모음
데이터 출처가 바뀐다Repository저장소와 로직을 분리
외부 API가 붙는다Adapter외부 인터페이스를 내부 규격으로 변환

배송비 계산기에서 날씨별·도시별 요금처럼 정책으로 바뀔 부분은 Strategy로 분리한다. 고객 타입에 따라 다른 할인 객체를 만들어야 하면 Factory를 쓴다. 모든 문제를 하나의 패턴으로 풀려는 시도가 가장 위험하다. 변하는 지점을 먼저 찾고, 그 지점에 맞는 패턴을 고르는 순서가 맞다

정리

한 줄로 요약하면, Claude Code를 강하게 만드는 것은 모델이 아니라 코어 루프를 둘러싼 하네스다. 설계도 똑같다. “이렇게 구현하면 되겠다”는 판단으로 바로 가지 말고, 그 앞에 맥락을 잡는 Context Harness와 위험을 막는 Permission Harness를 먼저 세워야 한다. 코드를 짜기 전에 입력·출력·제약·변경 가능성 네 가지가 적혀 있는지부터 확인하면 된다

다음 글에서는 책임을 분리하는 서브에이전트, 기록을 이어붙이는 세션 영속성, 생성과 평가를 가르는 검증 하네스를 다룬다

출처와 참고자료