Harness Books: Claude Code와 Codex의 하네스 설계 철학을 다룬 온라인/PDF 도서 (영문/중문)

9bow · 6월 16, 2026, 3:30오전

Harness Books 소개

코드를 작성하는 모델을 터미널과 저장소, 권한 시스템, 팀 워크플로 안에 집어넣는 순간, 문제의 성격이 바뀝니다. 모델이 좋은 답을 내놓느냐보다, 그 모델이 만들어 내는 행동이 어떤 결과로 이어지고 누가 그 결과를 책임지느냐가 더 중요해집니다. Harness Books는 바로 이 지점을 다루는 두 권의 책으로, 코딩 에이전트를 둘러싼 제약 구조(constraint structure)가 어떻게 실행을 조직하는지를 설명합니다.

저자는 하네스(harness)를 모델 주변에 덧붙인 액세서리가 아니라 하나의 제어 구조로 봅니다. 프롬프트, 도구, 권한, 상태, 복구, 검증, 제도는 시스템 바깥의 부속품이 아니라 같은 제어 구조 안의 장기(organ)라는 것이 핵심 관점입니다. 그래서 책은 소스 코드를 한 줄씩 따라가는 대신, 본질적으로 불안정한 모델을 지속 가능한 엔지니어링 질서 안으로 어떻게 접어 넣을 수 있는지에 집중합니다.

두 권은 같은 질문을 서로 다른 각도에서 다룹니다. 첫 번째 책은 Claude Code를 관찰 대상으로 삼아 런타임 구조 하나를 깊게 들여다보고, 두 번째 책은 Claude Code와 Codex를 나란히 놓고 두 하네스가 질서를 어디에 두는지를 비교합니다. 온라인으로 읽을 수 있고 PDF로도 받을 수 있으며, 원문은 영어와 중국어로 제공됩니다.

Harness Books가 말하는 하네스의 구성요소

저자는 하네스를 "하나의 제어 구조"로 정의하고, 그 안에서 작동하는 구성요소들을 시스템의 장기에 비유합니다. 모델이 가끔 틀린 말을 하는 것 자체가 위험이 아니라, 그 결과를 다룰 구조가 시스템에 없는 것이 진짜 위험이라는 문제의식이 책 전체를 관통합니다.

프롬프트는 채팅 박스가 아니라 제어판(control plane)의 일부이고, 쿼리 루프는 에이전트 시스템의 심장박동에 해당합니다. 도구와 권한은 에이전트가 세상을 직접 건드리지 못하게 막는 장치이며, 컨텍스트 거버넌스는 메모리와 CLAUDE.md, compact를 하나의 예산 운용 방식으로 묶습니다. 여기에 실패 이후에도 계속 작동하게 하는 오류·복구 경로, 그리고 분업을 통해 불안정성을 관리하는 멀티 에이전트 검증이 더해집니다.

Harness Books의 핵심 주장

저자는 책의 출발점이 되는 다섯 가지 주장을 정리해 두었습니다.

하네스 엔지니어링은 제약 구조가 실행을 어떻게 조직하는지에 관한 것입니다.
코드를 작성하는 모델이 실제 엔지니어링 환경에 들어오면, 핵심 문제는 더 이상 답의 품질이 아니라 행동의 결과입니다.
프롬프트, 도구, 권한, 상태, 복구, 검증, 제도는 시스템 주변의 부속품이 아니라 같은 제어 구조 안의 장기입니다.
에이전트 시스템을 비교할 때 중요한 것은 기능 체크리스트가 아니라 질서가 실제로 어디에 놓여 있는가입니다.
팀이 개인의 경험을 재사용 가능한 규칙으로 바꾸지 못하면, 에이전트를 안정적인 시스템으로 만들기 어렵습니다.

저자는 이 주장들을 두고 "The real danger is not that a model occasionally says something wrong, but that the system has no structure for handling consequences." 라고 정리합니다. 모델의 실수를 예외적 사건이 아니라 런타임의 일상으로 다뤄야 한다는 관점입니다.

Harness Books의 두 권 구성

Book 1: A Design Guide to Claude Code

첫 번째 책은 Claude Code를 관찰 대상으로 삼아 런타임 구조에 집중합니다. 시스템이 결국 제어판, 쿼리 루프, 도구 권한, 컨텍스트 거버넌스, 복구 경로, 멀티 에이전트 검증, 팀 규칙 같은 구성요소를 왜 키워 나갈 수밖에 없는지를 다룹니다. 하네스 엔지니어링이 단순히 규모를 키운 프롬프트 엔지니어링이 아닌 이유, 프롬프트가 채팅 박스가 아니라 제어판인 이유, 모델 실수를 런타임의 규범으로 취급해야 하는 이유 같은 질문이 차례로 등장합니다. 마지막 장인 Chapter 9 "Ten Principles of Harness Engineering" 은 책의 결론을 열 가지 원칙으로 압축합니다.

Book 2: Comparing Claude Code and Codex

두 번째 책은 Claude Code와 Codex를 나란히 놓고 각 하네스가 질서를 어디에 두는지를 묻습니다. 한쪽은 런타임 규율(runtime discipline)에서 출발하고, 다른 한쪽은 더 구조화된 제어 계층에서 출발합니다. 두 시스템 모두 작동하지만 권한을 분배하는 방식이 다르다는 것이 비교의 핵심입니다. 제어판의 가장 큰 분기점은 어디인지, 쿼리 루프와 스레드·롤아웃·상태의 역할을 어떻게 정렬할지, 권한과 샌드박스, 정책 언어가 어떤 거버넌스 역할을 하는지, 스킬과 훅, 로컬 규칙이 조직의 습관을 시스템에 어떻게 새겨 넣는지를 장별로 비교합니다.

Harness Books 읽는 방법

저자는 독자의 관심사에 따라 세 가지 읽기 경로를 제안합니다. 전체 틀을 먼저 잡고 싶다면 Book 1을 읽고 Book 2로 넘어가고, 코딩 에이전트 도구에 이미 익숙해 아키텍처 차이를 바로 보고 싶다면 Book 2부터 시작합니다. 결론만 빠르게 보고 싶다면 Book 1의 9장과 Book 2의 7장을 함께 읽으면 됩니다.

저장소는 두 책을 Honkit 기반 사이트로 빌드하는 도구를 함께 제공합니다. 로컬에서 직접 빌드하려면 다음 명령으로 두 권의 locale별 사이트를 만든 뒤 통합 Pages 사이트를 조립합니다.

python3 tools/book-kit/build_honkit.py book1-claude-code
python3 tools/book-kit/build_honkit.py book1-claude-code --locale en
python3 tools/book-kit/build_honkit.py book2-comparing
python3 tools/book-kit/build_honkit.py book2-comparing --locale en
python3 tools/book-kit/build_pages_site.py

최종 결과물은 dist/ 에 생성됩니다. 저자는 이 책들과 별개로 AgentWay 라는 연습 플랫폼을 함께 운영하는데, 책이 제어 구조와 설계 판단을 설명하는 자료라면 AgentWay는 그 개념을 훈련 경로와 실습으로 이어 가는 공간이라고 소개합니다.

Harness Books 온라인으로 읽기

Harness Books 프로젝트 GitHub 저장소

더 읽어보기

이 글은 GPT 모델로 정리한 글을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 덧글로 알려주시기를 부탁드립니다.

파이토치 한국 사용자 모임이 정리한 이 글이 유용하셨나요? 회원으로 가입하시면 주요 글들을 이메일로 보내드립니다!
텔레그램(Telegram)이나 Slack/Discord/Teams/Dooray/GoogleChat 등으로도 새 글 알림을 받으실 수 있습니다.

아래쪽에 좋아요를 눌러주시면 새로운 소식들을 정리하고 공유하는데 힘이 됩니다~