🔥 Harness Books, 코딩 에이전트의 제어 구조를 해부한 두 권의 책

GitHub 트렌딩을 훑다가 별 1,600개짜리 리포지토리 하나에 멈췄다. 이름이 harness-books. README를 열었더니 코드가 아니라 책 두 권이 들어 있었다. Claude Code와 Codex의 내부 구조를 뜯어본 기술 서적이다. "하네스 엔지니어링"이라는 단어가 눈에 꽂혔다. 2026년 들어서 이 용어가 급격히 퍼지고 있긴 한데, 이걸 책 두 권 분량으로 파고든 사람이 있다니.

하네스 엔지니어링이 뭔데

먼저 용어부터 정리하자. Martin Fowler 블로그에서 Birgitta Böckeler가 정의한 공식이 가장 깔끔하다. Agent = Model + Harness. 모델을 뺀 나머지 전부가 하네스다. 프롬프트 레이어, 도구 호출, 권한 체계, 컨텍스트 관리, 오류 복구, 검증 루프. 이것들이 모여서 하나의 제어 구조를 이룬다.

이 책의 저자(GitHub ID: wquguru)는 여기서 한 발 더 나간다. 하네스는 단순한 부품 목록이 아니라 "의도적인 권력 분배 시스템"이라고 말한다. 모델에게 얼마나 권한을 줄 것인가, 어디서 인간이 개입할 것인가, 실패했을 때 누가 수습할 것인가. 이런 설계 판단들이 하네스의 실체라는 거다.

두 권이 각각 다루는 것

Book 1: Harness Engineering: A Design Guide to Claude Code는 Claude Code 하나를 깊이 파고든다. 9개 챕터에 부록 3개. 제어 평면(Control Plane), 쿼리 루프, 도구 권한, 컨텍스트 거버넌스, 오류 복구, 멀티 에이전트 검증, 팀 도입까지 순서대로 올라간다. 마지막 9장에서 하네스 엔지니어링 10원칙을 정리한다.

인상 깊었던 건 2장의 관점이다. "프롬프트는 성격이 아니라 제어 평면이다." Claude Code의 시스템 프롬프트가 정적인 텍스트 블록이 아니라 계층적으로 조립되는 동적 구조라는 걸 소스 코드 레벨에서 추적한다. 프롬프트를 채팅창에 들어가는 안내문 정도로 생각했다면, 이 챕터가 인식을 바꿔줄 것이다.

Book 2: The Harness Design Philosophies of Claude Code and Codex는 비교 해부학이다. Claude Code와 Codex를 나란히 놓고, 같은 문제를 각각 어떻게 풀었는지 본다. 8개 챕터에 부록 2개. 제어 평면의 차이, 세션과 상태 관리의 차이, 실행 정책의 차이, 로컬 거버넌스의 차이를 하나씩 짚는다.

두 시스템의 근본적 분기점이 뭐냐고? 책의 표현을 빌리면 이렇다. Claude Code는 "운영 경험에서 자라난" 하네스고, Codex는 "명시적인 정책과 제어 레이어에서 태어난" 하네스다. 하나는 런타임 규율에서 출발하고, 다른 하나는 구조화된 제어에서 출발한다. 둘 다 작동하지만, 권한을 분배하는 방식이 다르다.

이 책의 핵심 아이디어 세 가지

첫째, 모델의 실수는 예외가 아니라 런타임의 기본값이다. 모델이 가끔 틀리는 게 문제가 아니다. 시스템이 그 결과를 처리할 구조가 없는 게 문제다. 하네스 엔지니어링은 "모델이 완벽해질 때까지 기다리자"가 아니라 "모델이 틀렸을 때 시스템이 어떻게 수습하는가"를 설계하는 일이다.

둘째, 기능 체크리스트가 아니라 질서의 위치가 비교의 기준이다. Claude Code vs Codex를 비교할 때 "어느 쪽이 도구를 더 많이 지원하느냐"는 틀린 질문이다. 올바른 질문은 "제어가 어디에 놓여 있느냐"다. 프롬프트 안에? 별도의 정책 파일에? 샌드박스 경계에? 이 위치 차이가 시스템의 성격을 결정한다.

셋째, 개인의 경험을 팀의 규칙으로 변환하지 못하면 에이전트는 안정된 시스템이 될 수 없다. 8장에서 다루는 "팀 도입" 파트가 이 부분이다. CLAUDE.md 같은 로컬 규칙 파일, 훅, 스킬 같은 장치들이 개인의 삽질 경험을 조직의 재사용 가능한 제약으로 바꾸는 역할을 한다. 멋진 도구를 혼자 잘 쓰는 것과, 팀이 안정적으로 쓰는 건 완전히 다른 문제다.

누가 읽으면 좋을까

코딩 에이전트를 이미 쓰고 있는 개발자라면 누구든. 특히 Claude Code나 Codex를 팀에 도입하려는 엔지니어링 리드라면 거의 필독이다. "왜 이 도구가 가끔 이상한 짓을 하는가"에 대한 구조적인 답을 얻을 수 있다.

자기만의 에이전트 하네스를 만들려는 사람에게도 좋다. Book 2의 8장 "If you are building your own harness, what to study first"가 정확히 그 질문에 답한다.

다만 코딩 에이전트를 한 번도 써본 적 없다면 진입 장벽이 있을 것이다. 이 책은 Claude Code의 CLAUDE.md, 훅 시스템, 서브에이전트 같은 개념을 어느 정도 알고 있다고 전제하고 진행한다.

아쉬운 점

한국어 번역이 없다. 영어와 중국어만 지원한다. 내용이 좋은 만큼 한국어판이 나온다면 국내 개발자 커뮤니티에 꽤 반향이 있을 텐데.

저자에 대한 정보가 거의 없다. GitHub 프로필 외에는 어떤 배경의 사람인지 알 수가 없다. 책의 깊이를 보면 상당한 실무 경험이 있는 사람인 건 분명한데, 이런 익명성이 신뢰 형성에는 걸림돌이 될 수도 있다.

소스 코드를 직접 인용하면서 분석하는 부분이 많은데, Claude Code와 Codex가 업데이트되면 이 분석이 금방 낡을 수 있다. 물론 README에서도 "소스 코드를 한 줄씩 따라가는 책이 아니다"라고 명시하긴 했다. 설계 철학 중심의 서술이라 당장 쓸모없어지진 않겠지만, 구체적인 파일명이나 함수 참조는 유효 기간이 짧을 수밖에 없다.

읽을 수 있는 방법

전문이 무료로 공개되어 있다. 세 가지 방법으로 읽을 수 있다.

• 온라인 리더 — 웹에서 바로 읽기 (데스크톱에서는 두 책 전환도 가능)
• Book 1 PDF / Book 2 PDF — 다운로드
• GitHub 리포지토리 — 소스 마크다운 직접 열람

저자의 추천 읽기 순서도 있다. 전체 프레임을 잡고 싶으면 Book 1을 먼저 읽고 Book 2로 가라. 코딩 에이전트 도구를 이미 잘 알고 아키텍처 비교가 궁금하면 Book 2부터 시작하라. 결론만 빠르게 보고 싶으면 Book 1의 9장과 Book 2의 7장만 읽어라.

읽고 나서 든 생각

이 책을 읽기 전까지 나는 코딩 에이전트를 "똑똑한 자동완성의 확장판" 정도로 생각했다. 잘 되면 좋고, 안 되면 다시 돌리면 그만인 도구. 그런데 이 책이 보여주는 관점은 다르다. 에이전트가 터미널에 접근하고, 파일을 수정하고, git을 조작하는 순간, 그건 더 이상 제안 도구가 아니다. 결과에 책임을 져야 하는 시스템이다. 그리고 그 책임 구조를 설계하는 게 하네스 엔지니어링이다.

솔직히 이런 수준의 기술 서적이 무료로 풀려 있다는 게 좀 놀랍다. 당장 이번 주에 팀에서 쓰고 있는 Claude Code 설정을 이 책의 프레임으로 다시 점검해 볼 생각이다.

참고 자료

• Harness Books GitHub Repository — 원본 리포지토리, 소스 마크다운과 빌드 도구 포함
• Harness Books Online Reader — 전문 무료 공개 온라인 리더
• Harness engineering for coding agent users — Martin Fowler — Birgitta Böckeler의 하네스 엔지니어링 개요, Agent = Model + Harness 공식 제시
• Harness Engineering: The Missing Layer Behind AI Agents — Louis Bouchard — 하네스 엔지니어링 개념 해설
• AgentWay — Harness Books와 연결된 실습 플랫폼