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

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

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

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

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

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

AI engineer인 Alex Fulton이 Claude Code와 Codex 모두를 분석한 후 내린 결론 ^[3]: "두 도구 모두 기본적으로 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" ^[1]는 세 가지 설계 패턴으로 정리한다.

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

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

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

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

2026년 5~6월의 Codex 업데이트는 이 원칙을 더 넓혔다. 이제 "모델이 이미 아는 도구"는 bash와 텍스트 에디터만이 아니다. 로그인된 웹앱을 다루는 Chrome extension, 로컬 앱을 조작하는 Computer Use, 웹앱 초안을 띄우는 Sites, 원격 host에 붙는 mobile/remote surface까지 공식 도구 표면에 들어왔다 ^[10]. 하네스 설계자는 이것을 한데 섞으면 안 된다. shell 작업, 브라우저 작업, desktop 작업, 배포 preview 작업을 별도 wrapper와 권한 경계로 나눠야 한다.

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

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

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

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: 경계를 신중하게 설정하라

여기서 말하는 "경계"는 모델에게 맡길 일과 사람이 직접 통제해야 할 일을 나누는 선이다. 모델은 코드를 읽고 고치는 데 능숙하지만, 이 repo에서 어떤 파일이 위험한지, 어떤 명령이 배포를 일으키는지, 어떤 UI 변경이 사용자를 혼란스럽게 만드는지 처음부터 알지 못한다. 따라서 하네스는 모델에게 "여기까지는 자유롭게 해도 된다"와 "여기부터는 반드시 멈추고 확인해야 한다"를 알려줘야 한다.

가장 쉬운 예는 파일 권한이다. 문서와 테스트는 모델이 자유롭게 고쳐도 되지만, 결제 로직, 인증 설정, 배포 스크립트는 수정 전에 사람의 승인을 받아야 할 수 있다. 또 다른 예는 실행 명령이다. npm test는 허용해도 되지만, npm publish, terraform apply, production DB migration은 자동 실행하면 안 된다. 좋은 하네스는 이런 차이를 프롬프트가 아니라 구조로 표현한다.

이 패턴은 세 가지로 구현된다.

A. 안정적인 정보와 변하는 정보를 분리한다. 프로젝트 규칙, 코드 스타일, 테스트 명령처럼 자주 바뀌지 않는 정보는 AGENTS.md나 skill 설명처럼 앞쪽에 둔다. 오늘의 태스크, 현재 diff, 방금 실패한 테스트처럼 매번 바뀌는 정보는 뒤쪽에 둔다. 이렇게 하면 모델이 매번 같은 규칙을 안정적으로 보고, prompt caching도 더 잘 작동한다 ^[1].

B. 위험한 행동은 선언적 도구나 wrapper로 감싼다. "배포해줘"처럼 넓은 지시를 모델에게 바로 맡기지 말고, bin/deploy-preview, bin/check-release, make verify처럼 사람이 정한 안전한 입구를 만든다. 도구는 내부에서 어떤 명령을 실행할지, 어떤 환경에서는 멈출지, 어떤 로그를 남길지 결정한다. 모델은 그 도구를 호출할 뿐이다.

C. 나중에 재현할 수 있게 기록한다. 에이전트가 무엇을 읽고, 어떤 명령을 실행했고, 어떤 diff를 만들었는지 남겨야 한다. 로그, trace, HANDOFF.md, 테스트 결과가 여기에 해당한다. 경계를 설정한다는 것은 단순히 금지 목록을 만드는 일이 아니다. 문제가 생겼을 때 어디서 잘못됐는지 되짚을 수 있게 만드는 일이다.

4.4 패턴별 Claude → Codex 매핑

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

특히 hooks는 "보안 경계"가 아니라 "운영 guardrail"로 다뤄야 한다. Codex 공식 문서는 hooks와 plugin-bundled hooks가 trust review를 거친다고 설명하지만, 모든 shell/WebSearch 경로를 완전히 가로채는 완전한 enforcement layer로 보장하지 않는다 ^[10]. 그래서 위험한 동작은 hook 하나에 맡기지 말고 permission profile, .rules, wrapper command, /review, git diff를 함께 써야 한다.

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

이 장의 시작에서 본 Lance Martin의 문제 제기는 이렇다. 에이전트 프레임워크와 하네스는 모델의 현재 약점을 보완하기 위해 만들어진다. 그런데 모델이 좋아지면, 예전에 필요했던 보완 장치가 오히려 모델의 능력을 제한할 수 있다. 예를 들어 예전에는 모델이 긴 절차를 스스로 관리하지 못한다고 생각해서 모든 단계를 코드로 고정했을 수 있다. 하지만 새 모델이 더 긴 계획과 도구 호출을 스스로 처리할 수 있다면, 그 고정된 절차는 도움이 아니라 병목이 된다.

이 반론은 "하네스를 만들지 말라"는 뜻이 아니다. 반대로 하네스가 중요하기 때문에, 하네스를 고정된 설정 묶음이 아니라 계속 리팩터링하는 코드처럼 다뤄야 한다는 뜻이다. 이 책에서 말하는 "진화 가능한 하네스"는 다음 네 가지 성질을 가진다.

1. 규칙과 실행을 분리한다. 프로젝트 규칙은 AGENTS.md처럼 사람이 읽는 파일에 두고, 실제 실행은 make verify, bin/deploy-preview 같은 명령으로 둔다. 규칙을 바꿀 때 실행 코드를 뒤엎지 않아도 되고, 실행 방식을 바꿀 때 모델 지시 전체를 다시 쓰지 않아도 된다.
2. 범용 지식과 도구 전용 지식을 분리한다. 코드 스타일, 테스트 명령, 금지 파일은 Claude Code와 Codex가 모두 읽을 수 있는 곳에 둔다. Claude 전용 hook이나 Codex 전용 subagent 설정은 각 도구의 디렉토리에 둔다. 그래야 한 도구를 바꿔도 프로젝트 지식이 함께 사라지지 않는다.
3. 실패 패턴을 문서에 반영한다. 에이전트가 같은 실수를 반복하면 프롬프트로 매번 고치지 말고 AGENTS.md의 "Common Mistakes"나 skill에 넣는다. 하네스는 처음부터 완성되는 것이 아니라, 실패를 흡수하면서 좋아진다.
4. 삭제보다 비활성화를 우선한다. 오래된 hook, skill, subagent가 의심스러워도 바로 지우지 말고 언제, 왜, 어떤 실험 뒤에 제거할지 기록한다. 특히 Claude Code에서 Codex로 넘어가는 동안에는 되돌아갈 수 있는 경로가 하네스의 일부다.

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

다음 장에서는 이 원칙을 Codex에서 구체적인 파일 구조로 옮긴다. AGENTS.md에는 무엇을 쓰고, ~/.codex/config.toml에는 무엇을 두며, .codex/agents/와 skills는 언제 필요한지 살펴본다. 즉 4장은 하네스를 보는 법이고, 5장은 그 하네스를 Codex에서 실제로 짓는 법이다.

참고문헌

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]
8. OpenAI, "Codex hooks," Codex manual, 2026. [OpenAI, 2026]
9. OpenAI, "Codex plugins," Codex manual, 2026. [OpenAI, 2026]
10. OpenAI, "Codex app automations," Codex manual, 2026. [OpenAI, 2026]