Chapter 4: 하네스 엔지니어링 빠른 정복 — 개념과 핵심 패턴

4.1 에이전트 프레임워크의 역설

Lance Martin(Anthropic)은 이렇게 말했다: "에이전트 프레임워크는 Claude의 현재 한계에 대한 가정들을 코드로 인코딩한다. 하지만 모델이 진화하면서 그 가정들이 병목이 된다 [Martin and Anthropic, 2026]."

이게 하네스 엔지니어링의 역설이다. 모델의 한계를 보완하기 위해 만든 코드가, 모델이 발전하면서 모델의 발목을 잡는다. 좋은 하네스는 모델 발전에 맞춰 계속 진화한다.

하지만 더 근본적인 질문이 있다: 하네스가 도대체 무엇인가?

4.2 하네스의 정체 — 마법을 벗기다

AI engineer인 Alex Fulton이 Claude Code와 Codex 모두를 분석한 후 내린 결론 [Fulton, 2026]: "두 도구 모두 기본적으로 while True 루프에 도구를 붙인 것이다. 마법은 컨텍스트 관리, 샌드박싱, 구조화된 출력에 있지, LLM 호출 자체에 있지 않다."

# 하네스의 본질 (의사 코드)
while True:
    context = load_context()  # CLAUDE.md / AGENTS.md 읽기
    response = llm_call(context + user_input)
    result = execute_tools(response.tool_calls)
    save_context(result)  # 메모리 업데이트
    if response.is_done:
        break

이게 전부다. 차이를 만드는 것은:

1. load_context()가 무엇을 읽는가 — 메모리 모델
2. execute_tools()가 무엇을 허용하는가 — 권한 모델
3. save_context()가 무엇을 저장하는가 — 지속성 모델

하네스 엔지니어링은 이 세 함수를 잘 설계하는 것이다.

4.3 세 가지 패턴

Anthropic의 "Harnessing Claude's Intelligence" [Martin and Anthropic, 2026]는 세 가지 설계 패턴으로 정리한다.

패턴 1: 모델이 이미 아는 도구를 써라

Claude(그리고 GPT-5.5도)는 bash와 텍스트 에디터를 인터넷 학습 데이터에서 깊이 이해한다. 복잡한 전용 도구를 만드는 것보다, 모델이 이미 잘 아는 범용 도구 위에서 고수준 기능을 구성하는 것이 더 효과적이다.

실제 증거: Claude 3.5 Sonnet이 bash + 텍스트 에디터만으로 SWE-bench Verified 49%를 달성했다 (2024년 말 SOTA). Sonnet 4.6에서는 같은 패턴으로 76.3%까지 올랐다 [Martin and Anthropic, 2026].

이 두 도구 위에서 programmatic tool calling, skills, memory 같은 고수준 기능이 나온다.

패턴 2: "내가 하지 않아도 되는 것은 무엇인가?"를 계속 물어라

하네스에 인코딩된 가정들을 계속 검토하고, 불필요해진 구조는 제거한다. 세 가지 확장 방향:

A. 자기 오케스트레이션: 모든 도구 결과를 컨텍스트 창에 로드하는 전통적 패턴 대신, 코드 실행 도구를 주고 모델이 도구 호출을 연쇄적으로 처리하게 한다. BrowseComp에서 Opus 4.6이 45.3% → 61.6%로 상승했다 [Martin and Anthropic, 2026].

B. 점진적 컨텍스트: 시스템 프롬프트에 모든 지시를 미리 로드하면 어텐션 예산이 소진된다. Skill YAML frontmatter로 간략한 개요만 제공하고, 에이전트가 필요할 때 전체 내용을 읽도록 한다. Subagents(격리된 컨텍스트 창)를 활용하면 Opus 4.6이 BrowseComp에서 +2.8%p 향상된다.

C. 메모리 지속성: 장기 에이전트는 단일 컨텍스트 창 한계를 넘는다. 두 가지 해결책:

• Compaction: 과거 컨텍스트 요약. Opus 4.6 BrowseComp 84%
• Memory folder: 파일에 컨텍스트 쓰고 읽기. Sonnet 4.5의 BrowseComp-Plus 60.4% → 67.2%

패턴 3: 경계를 신중하게 설정하라

모델은 기본적으로 앱의 보안 경계나 UX 표면을 모른다. 명시적 경계를 설정한다:

A. 캐시 히트 극대화: Prompt caching으로 캐시된 토큰 비용을 기본 입력 토큰의 10%로 낮춘다. 정적 컨텐츠 먼저, 동적 컨텐츠 마지막 [Martin and Anthropic, 2026].

B. 선언적 도구: 보안 경계가 필요한 액션, 되돌리기 어려운 액션에 전용 도구를 만든다.

C. 관찰 가능성: 로깅/트레이싱/재현을 위한 구조적 레이어.

4.4 패턴별 Claude → Codex 매핑

세 패턴은 도구 독립적이다. Codex에서도, Claude Code에서도 적용된다. 5장에서는 이 패턴들을 Codex에 구체적으로 구현한다.

4.5 반론: 프레임워크가 가정을 코드화한다

Lance Martin의 주장은 맞다. 하지만 이것이 하네스를 쓰지 말라는 뜻이 아니다. 하네스를 진화 가능하게 설계하라는 뜻이다.

4개월간 Claude Code를 매일 쓴 Okhlopkov의 회고 [Okhlopkov, 2026]: "처음 한 달은 도구를 배우는 데 썼다. 그다음 석 달은 하네스를 최적화하는 데 썼다." 하네스를 코드처럼 리팩터링하는 것이 그 최적화의 핵심이다. 마지막으로 하네스를 점검한 것이 모델 업데이트 이전이라면 — 이제 더 이상 존재하지 않는 한계를 보완하고 있는 것일 수 있다.

참고문헌

1. Anthropic, "Harnessing Claude's Intelligence: Three Patterns for Agent Harness Design," 2026. [Martin and Anthropic, 2026]
2. Anthropic, "Claude Code: Best practices for agentic coding," 2026. [Anthropic, 2026]
3. Fulton, Alex, "Inside the agent harness," 2026. [Fulton, 2026]
4. Promptshelf, "10 Claude Code hook examples," 2026. [Shelf, 2026]
5. Okhlopkov, "Claude Code setup — 4-month retrospective," 2026. [Okhlopkov, 2026]
6. Korean Developer, "하네스 엔지니어링 40분 정복," 2026. [Korean Dev Blog, 2026]
7. HesReallyHim, "Awesome Claude Code — community catalog," 2026. [GitHub, 2026]