기술서를 다 읽고 나면 보통 두 가지가 남는다. 써먹을 만한 절차 몇 개, 그리고 목차.

『하네스 엔지니어링 with 클로드 코드』¹는 조금 달랐다. 14개 장과 부록 4편을 덮고 나서 남은 건 목차가 아니라 문장 하나와 리듬 하나였다.

목차 쪽 사실부터 적어 두면 이렇다. 다섯 덩어리다. 왜 하네스인가라는 진단, 무엇으로 구성하는가라는 분해, 그 구성을 어떻게 자동화하고 유지하는가, 네 도메인의 실전 적용, 그리고 부록 네 편. 마지막 덩어리까지 번호를 받아 Part 05로 적혀 있다.

그런데 다 읽고 손에 남은 모양은 다섯이 아니라 넷이었다. 명제를 세우고, 분해하고, 접고, 다시 펼친다. 이 글은 책 요약이 아니라 다 읽고 나서야 보이는 배치의 의도, 그리고 목차에 이름 없이 책 전체를 관통하는 규칙들에 대한 기록이다.

이 책은 문장 하나를 두 번 확인한다

“이 책이 반복해서 강조하고 싶은 문장은 단 하나”라고 저자가 먼저 못 박는다.

“모델이 아니라 하네스가 결과를 결정합니다.”

책머리에 두 번(「들어가며」와 「이 책에 대하여」) 나오고, 마지막 「마치며」가 “결과를 결정하는 것은 모델 자체가 아니라 하네스였습니다”로 한 번 더 확인한다. 시작과 끝을 같은 명제가 잠근다.

하네스(harness)는 모델 바깥에 놓이는 모든 구조물이다. 정의는 “AI 에이전트가 일하는 환경 전체를 설계하고 운용하는 구조적 체계”이고, 구체적으로는 권한·도구·검증·상태·관측 다섯 축이다. 다루지 않을 것도 미리 밝힌다. 파인튜닝, RLHF, 모델 아키텍처. 모델 안쪽은 이 책의 영역이 아니다. 범위로 정리하면 하네스 엔지니어링이 컨텍스트 엔지니어링을, 컨텍스트 엔지니어링이 프롬프트 엔지니어링을 품는다.

프롬프트로는 왜 부족한가. 책이 내놓는 답이 태도 전체를 압축한다.

“프롬프트는 설득에 의존하지만, 하네스는 기계적 강제에 의존합니다. 프롬프트는 말로 지시합니다. 하네스는 구조로 강제합니다.”

설득과 강제. 이 대비를 붙잡고 있으면 나머지 전부가 “어떻게 강제할 것인가”의 변주로 읽힌다.

덧붙이면 ‘하네스 엔지니어링’은 저자의 조어가 아니다. OpenAI가 코덱스 도입 회고로 낸 글의 제목이 문자 그대로 “Harness engineering”²이고, 랭체인도 같은 시기에 같은 표현을 썼다³. 책이 인용한 “2025 was agents. 2026 is agent harnesses”라는 진단은 저자 개인의 전망이라기보다, 이미 여러 곳에서 동시에 굳어지던 용어를 한국어로 옮겨온 쪽에 가깝다.

같은 모델, 다른 하네스 — 세 장면

미첼 하시모토는 혼자 일한다. 클로드 세션을 3~4개 열어 두고, 각 세션의 결과물을 직접 읽고 마음에 들지 않으면 되돌린다. 속도를 의식적으로 늦추더라도 결과물의 ‘맛’을 지키는 쪽을 고른다. 피터 스타인버거는 세션 5~10개를 동시에 굴리며 이렇게 말한다.

“I ship code I don’t read(저는 코드를 읽지 않고 배포합니다).”

저자는 이 도발적인 문장의 실제 의미가 오히려 정반대에 가깝다고 읽는다. 아키텍처의 최종 책임자는 어디까지나 본인이고, 에이전트는 그 아키텍처 안에서만 제한적으로 자유를 갖는다는 것.

세 번째 장면은 OpenAI 내부 팀이다. 5개월 동안 약 100만 줄을 생성했고 사람이 직접 쓴 코드는 사실상 0줄이었다².

세 장면이 공유하는 건 두 가지다. 같은 계열의 모델, 그리고 하네스를 갖췄다는 사실. 달라지는 건 그 하네스의 형태뿐이다. 하시모토의 하네스는 CLAUDE.md 한 장과 워크트리 몇 개고, OpenAI의 하네스는 AGENTS.md와 서브에이전트 팀을 비롯해 여러 층으로 쌓인 구조다. 모델을 상수로 두고 하네스만 변수로 놓은 관찰 세 개 — 책의 명제를 가장 직접적으로 떠받치는 배치다.

책이 덧붙이는 관찰 하나가 특히 걸린다. OpenAI 팀은 3인에서 7인으로 늘었는데 1인당 처리량이 오히려 증가했고, 원인은 “하네스 아키텍처가 온보딩 비용을 흡수했다”는 것이다. 인원이 늘수록 1인당 생산성이 떨어진다는 브룩스 법칙의 반례에 해당한다. 그렇다면 하네스는 개인의 생산성 도구가 아니라 조직의 온보딩 비용을 옮겨 놓는 구조물이라는 뜻이 된다. 새 팀원이 사람에게 물어야 알 수 있던 규칙이 파일에 적혀 있으면, 그 파일을 읽는 건 사람이 아니라 에이전트다.

혼자 쓴 PR을 혼자 머지하는 구조

하네스가 변수라면, 그 변수를 비웠을 때는 무엇이 무너지는가. 책의 진단은 사고에서 출발한다. 에이전트가 프로덕션 DB를 지웠고, 곧바로 복구가 불가능하다고 보고했다. 그 보고도 사실이 아니었다. 저자는 원인을 한 문장으로 압축한다. 단일 에이전트는 자신의 실수를 잘 보지 못한다. 계획하고, 코드를 쓰고, 검증하고, 스스로 고치는 네 단계가 전부 같은 박스 안에서 돌기 때문이다. 개발자 언어로 옮기면 이렇게 된다.

“혼자 쓴 PR을 혼자 머지하는 구조입니다.”

인간 팀에서 리뷰어 없는 머지는 사고지만, 에이전트에게는 그게 기본 구성이라는 지적이 뼈아프다.

진단 옆에는 환경만 바꾼 실험 세 개가 놓이는데, 층위를 구분해서 읽는 게 좋다. 편집 도구 인터페이스 한 줄을 바꿔 성공률이 뒤집힌 Hashline 벤치마크⁴, 그리고 모델을 고정한 채 미들웨어·프롬프트 구조만 바꿔 순위를 끌어올린 랭체인의 Terminal Bench 실험³은 외부에 공개된 자료로 확인된다. 반면 가장 인상적인 숫자, .claude/ 구성 전체를 바꿔 49.5점에서 79.3점으로 올렸다는 실험은 저자의 내부 A/B다. 채점 기준과 과제 목록이 공개돼 있지 않아 재현할 수 없다. 세 개를 같은 무게로 읽으면 곤란하다.

특이한 건 진단 다음에 처방이 곧바로 오지 않는다는 점이다. 권한·도구·검증·상태·관측 다섯 축을 열거한 뒤 저자는 이렇게 적는다. “이 다섯 축이 실제로 어떻게 구성되는지는 2부에서 따로 다룹니다.” 그 사이에 끼어드는 건 실습이다. 독자는 30분 안에 굴러가는 최소 하네스를 만드는데, 그 결과물이 파일 다섯 개다(에이전트 2 + 스킬 1 + CLAUDE.md 1 + 작업 디렉터리 1). 손으로 먼저 만들고 이름은 나중에 붙이는 순서다.

파일은 다섯 개인데 개념은 셋이다

실습으로 만든 파일 다섯 개는 개념 셋으로 묶인다. 하네스는 누가(Agent), 어떻게(Skill), 언제·누구와(Orchestrator)로 나뉘고, 셋은 독립적으로 설계되다가 실행 시점에만 맞물린다. 이 경계선은 방금 손으로 만든 것을 그대로 해부하는 방식으로 그어진다 — “이 장은 그 다섯 파일을 세 덩어리로 나눠 봅니다”.

책의 편집 방식이 드러나는 장면이 하나 있다. 에이전트 정의 파일의 표준 섹션 일곱 개를 제시하면서 ‘팀 통신 프로토콜’ 한 칸만 비워둔 채 넘어간다. 그 빈칸은 한참 뒤 오케스트레이터를 설명하면서 채워진다. 한 번에 다 넣지 않고 미뤄 뒀다가 회수하는 이 방식 자체가, 책임을 나누되 실행 시점에만 맞물린다는 앞의 경계선을 실연하는 것처럼 읽힌다.

분해를 통과하고 나면 각 기둥에 한 줄씩 남는다. 에이전트 정의 파일은 설정이 아니라 역할 계약서이고, 스킬에서 호출 여부를 결정하는 건 본문이 아니라 description이며, 오케스트레이터는 지시자가 아니라 지휘자다. 다만 이 세 줄만 옮겨 적으면 밀도가 사라진다. 각 줄에 도달하려고 붙여 둔 계산이 이 책에서 가장 실용적인 부분이다.

계약서 쪽 계산부터 보자. 왜 설정 파일이 아니라 계약서인가.

“설정 파일은 값을 저장하지만 계약서는 약속을 저장합니다.”

그 약속의 실체는 프론트매터 한두 줄이다. 어떤 도구를 쥐여줄지(tools)를 파일에 적는 순간, 그 에이전트가 할 수 없는 일이 프롬프트가 아니라 파일 수준에서 정해진다. 본문에 “Write 금지”라고 써 두는 건 프롬프트일 뿐이고, 확률적으로 판단하는 시스템에서 판단은 언젠가 흔들린다. 책은 tools 필드를 파일 수준 가드레일이라 부른다. 어떤 모델로 돌릴지(model)는 권한이 아니라 비용과 추론 등급을 가르는 별개의 축인데, 결론은 둘을 함께 묶는다.

“model·tools는 거버넌스 결정이지 성능 최적화가 아닙니다.”

값을 고르는 문제처럼 보이던 자리가 권한을 나누는 문제로 바뀐다.

호출되지 않는 스킬은 없는 것과 같다

공들여 만든 스킬이 한 번도 호출되지 않는 일은 왜 생기나. Vercel 벤치마크에서는 평가 사례의 56%가 그랬다. 본문이 부족해서가 아니라, 본문이 열리기도 전에 막힌 것이다. 클로드는 호출 여부를 판단할 때 본문을 읽지 않고 name과 description만 본다. 공간 제약도 겹친다. 세션이 열릴 때 스킬 목록에 쓰이는 건 전체 컨텍스트 윈도의 약 1%다.

그래서 책이 내놓는 description 3단계 공식은 문장 작법이 아니라 이 제약에 대한 대응이다.

세 번째 단계가 반직관적이다. 적합하지 않은 경우를 함께 적으라는 것. 이유는 명확하다. 경계가 없으면 여러 스킬이 같은 요청을 두고 겹치고, 그러면 클로드는 어느 쪽도 확신하지 못해 결국 아무 스킬도 호출하지 않을 수 있다. 호출률을 높이는 방법은 “이것도 할 수 있다”를 늘리는 쪽이 아니라 “이건 내 일이 아니다”를 적는 쪽이다.

본문 쪽 원칙인 Progressive Disclosure도 같은 계산에서 나온다. 세 층에 각각 다른 생명주기를 준다. 프론트매터는 항상 보이고(호출할 것인가), SKILL.md 본문은 호출한 뒤 열리고(어떻게 수행하는가), references는 필요할 때만 열린다(무엇을 추가로 참고하는가). 이 구조에 붙은 근거가 핵심 문장을 만든다.

“컨텍스트는 내 것이 아니라 공공재입니다.”

숫자로 옮기면 이렇다. 세션에 스킬이 30개 등록돼 있고 각자 description을 500자씩만 써도 매 요청마다 15,000자가 고정비로 붙는다. 내 스킬의 description 한 줄이 길어지면 같은 세션의 다른 스킬이 그만큼 자리를 잃는다. Progressive Disclosure는 파일 정리 관례가 아니라 공유 자원 배분 규칙이라는 뜻이다.

팀 크기의 상한은 통신 경로에서 나온다

팀원이 4명이면 잠재 통신 채널은 6개다. 10명이면 45개가 된다. N×(N-1)/2개다.

이 숫자가 생기는 건 설계 선택 하나 때문이다. 리더 중심 구조에서는 모든 메시지가 중앙을 지나는 star topology지만, 팀원끼리 직접 메시지를 보내는 순간 full mesh가 된다. 리더를 거치지 않는 통신을 택하는 이유는 성능이 아니라 병렬성인데, 그 선택에는 대가가 딸려 온다.

채널이 늘어난다는 건 팀원 한 명이 상대해야 할 대화 상대도 함께 늘어난다는 뜻이다. 10명 팀이라면 각자 나머지 아홉 명의 메시지를 읽고 반응해야 한다. 자기 컨텍스트의 상당 부분을 메시지에 내주고, 그만큼 실제 작업에 쓸 몫이 줄어든다. 책은 이걸 이론으로 두지 않고 사고 기록 한 줄을 붙인다.

“세션 9a990de8이 2분 내 292개 에이전트를 생성하여 36.8GB RSS에 도달했습니다. 이 사례 이후 팀원 한 명이 받을 수 있는 메시지 수가 최대 50개로 제한되었습니다.”

인용 끝에는 출처가 “클로드 코드 내부 사고 사례, 오케스트레이션 패턴 가이드”로 붙어 있다. 이 표기대로라면 저자가 돌린 실험이 아니라 인용해 온 사고 기록이다.

앞서 스킬을 두고 한 말이 팀 규모에서 그대로 다시 나온다. 컨텍스트는 공공재이고, 팀원을 한 명 늘리는 건 나머지 전원의 몫에서 조금씩 떼어내는 일이다. 그래서 이 문장이 성립한다.

“3명의 집중된 팀원이 5명의 산만한 팀원보다 낫습니다.”

앞의 절차 전체가 폴더 하나로 접힌다

코드 리뷰 팀을 만들고, 다음 주에 풀스택 팀을 만들고, 그다음 주에 마이그레이션 팀을 만든다. 도메인만 바뀌었을 뿐 하는 일은 거의 같다. 도메인 분석, 역할 쪼개기, 에이전트, 스킬, 포인터, 검증. 그리고 “여섯 번째 팀을 만들던 날” 엔지니어는 같은 패턴이 반복되고 있음을 깨닫는다.

그다음이 이 책에서 가장 결정적인 전환이다. 저자는 앞에서 가르친 원칙을 그 가르침 자체에 적용한다. 반복되는 절차가 스킬의 재료다. “2부에서 본 여섯 단계 자체가 스킬이 되지 못할 이유가 없습니다.” 스킬과 에이전트를 만드는 스킬, 즉 메타스킬이 여기서 나온다.

그 자각의 결과가 이 문장이다.

“2부 전체가 메타스킬의 references/에 모듈로 접혀 있는 셈입니다.”

이걸 비유로 읽으면 절반만 읽은 것이다. 책은 메타스킬의 실제 파일 크기를 함께 공개한다. SKILL.md 본문 443라인(책이 앞서 정한 500라인 상한 이내), references 6개 파일 합계 1,706라인. 본문의 약 4배 분량이 필요할 때만 컨텍스트에 올라온다. 손으로 익힌 구성 절차가 실제로 파일로 접혀 있다는 사실 진술이다. 그래서 이어지는 문장이 성립한다.

“메타스킬은 자신이 정의한 규칙을 자기가 따릅니다.”

잘 접어 두고도 마지막에 걸리는 관문이 하나 남는다. 등록이다. CLAUDE.md에 등록되지 않은 하네스는 첫 세션 이후 호출되지 않는다. 설계를 아무리 잘해도 등록에서 끊기면 0이다.

도메인은 패턴을 태워 나르는 수레다

리뷰, 풀스택, 마이그레이션, 디버깅. 접은 것을 다시 펼치는 자리에 실린 네 도메인은 왜 하필 이 넷이고 이 순서인가. 난이도순도 규모순도 아니다. 패턴 커버리지 순이다. 가장 익숙한 문제(리뷰)에서 팬아웃·팬인을, 경계면이 많은 문제(풀스택)에서 계층적 위임과 파이프라인이 겹친 복합 패턴을, 규모 문제(마이그레이션)에서 감독자를, 사후 대응(디버깅)에서 생성-검증과 결정론 게이트를 보여준다. 저자의 표현이 이 배치의 성격을 정확히 요약한다.

“8장은 패턴의 ‘지도’를 살펴봤습니다. 실제 ‘지형’은 4부에서 보여줍니다.”

도메인은 패턴을 태워 나르는 수레에 가깝다.

그 성격이 가장 잘 드러나는 게 마이그레이션에 실린 에어비앤비 이야기⁵다. 리액트 테스트 파일 약 3,500개를 6주 만에 옮기고 97%를 자동 처리한 작업이다. 저자는 이걸 “얼핏 프롬프트 엔지니어링처럼 보이지만, 자세히 보면 에이전트 팀의 역할 분업 + 감독자 패턴 + 생성-검증 루프를 실제로 구현한 사례”라고 재해석한다. 소개가 목적이 아니라, 앞에서 쌓아 둔 패턴 어휘로 다시 읽어내는 게 목적이다.

펼치기는 닫힌 고리로 끝난다. 디버깅 팀이 찾은 근본 원인 패턴이 새 코드 리뷰 규칙이 되고, 코드 리뷰가 놓친 케이스가 다시 디버깅 팀의 입력이 된다. 처음 펼친 도메인과 마지막 도메인이 서로를 먹인다.

이 책의 유일한 공리는 “파일이 없으면 존재하지 않는다”이다

여기까지가 배치의 의도라면, 지금부터는 목차에 이름이 없는 것들이다. 파트 구분과 무관하게 책 전체를 관통하는 규칙 몇 개.

그 첫 번째 규칙은 실습 대목에서 한 문장으로 처음 등장한다. 표어가 아니라 공리다. 저자는 reviewer 에이전트 파일의 확장자를 .bak으로 바꿔 워크플로가 끊기는 것을 직접 확인시킨다. 이 공리에서 뒤의 규칙 대부분이 파생된다.

왜 역할을 프롬프트가 아니라 파일에 쓰는가. 왜 스킬은 단일 파일이 아니라 디렉터리와 SKILL.md여야 하는가. 왜 팀을 지운 뒤에도 작업 디렉터리는 남기는가. 왜 CLAUDE.md에 포인터를 등록해야 하는가. 왜 작업 목록을 마크다운 체크리스트가 아니라 JSON으로 쓰는가. 전부 같은 뿌리다. 마지막 항목에는 근거가 붙어 있다. “JSON을 택한 이유는 실수로 변경될 가능성이 적기 때문”이고, 마크다운 체크리스트로 두면 세션이 길어졌을 때 모델이 다 완료했다고 판단해 지워버리는 일이 생긴다.

영속성이 곧 존재다. 이 한 줄로 책의 상당 부분이 재구성된다. 책이 지적하는 HTML 주석 함정도 마찬가지다. <!-- -->로 감싼 순간 그 규칙은 컨텍스트에서 사라지고, 그러면 애초에 존재하지 않았던 것과 같다.

검증자에게서 쓰기 권한을 빼앗는다

실전 사례 넷에서 가장 선명하게 남은 건 개별 팀 구성이 아니라, 네 도메인에서 똑같은 수가 네 번 반복된다는 사실이었다.

• 코드 리뷰 팀: 리뷰어 세 명에게 Edit 권한 없음. 수정은 refactorer만, 그것도 패치 파일로만. 리뷰어가 코드를 직접 고치면 검증 과정에서 나온 거짓 양성이 그대로 커밋되기 때문이다
• 풀스택 팀: 경계면 검증자는 검증만. 직접 고치면 구현 에이전트가 실수를 학습하지 못하고 책임 경계가 무너진다
• 마이그레이션 팀: 검증자에게 Edit 없음. “스스로 고쳐서 통과 처리”하는 문제를 구조적으로 차단한다
• 디버깅 팀: Edit는 오직 수정 제안자에게만. 관찰 → 가설 검증 → 수정 순서로 정렬해 확증 편향을 차단

도메인은 리뷰, 구현, 이관, 디버깅으로 전부 다른데 처방은 하나다. 앞에서 본 tools 한 줄의 가드레일이 네 번 회수된다. 이건 첫 진단(혼자 쓴 PR을 혼자 머지)에 대한 유일한 구조적 답이기도 하다. 자기 검토를 막는 방법은 설득이 아니라 권한 회수다.

저자도 같은 관찰을 부록에 적어 둔다.

“코드 리뷰 팀과 풀스택 팀, 레거시 마이그레이션과 RCA 팀은 서로 다른 도메인을 다루지만 실패 모드는 놀랍도록 비슷합니다.”

네 도메인을 세로로 훑은 뒤 그 넷을 가로로 자르는 시선이다. 교차 안티패턴 네 종(Trigger Miss, Cross-Reference Drift, Verify-Generate Deadlock, Over-Orchestration)은 어느 한 도메인의 문제가 아니라 여러 원칙이 동시에 어긋날 때 생긴다.

그런데 검증자를 따로 세우는 비용을 정당화하려면 먼저 답할 게 있다. 이미 있는 도구로는 왜 안 되는가. 풀스택 사례가 표 하나로 보여준다. 로그인 기능 하나에 경계면이 다섯 개(폼 ↔ 입력 유효성 검증 ↔ API ↔ JWT 서명 ↔ DB)라고 세어 둔 다음, SatangSlide라는 Next.js 기반 서비스에서 실제로 드러난 런타임 버그 일곱 종을 싣는다. API가 객체를 반환하는데 훅이 배열을 기대해 projects?.filter is not a function이 나는 것, thumbnailUrl과 thumbnail_url의 네이밍 불일치로 이미지가 안 보이는 것, 상태 전이 코드가 빠져 생성 페이지가 영원히 대기하는 것. 그리고 이 문장이 붙는다.

“이 버그들 중 어느 하나도 TypeScript 컴파일러가 잡지 못했습니다.”

한 줄이지만 실전 사례 전체의 전제다. 타입 시스템은 모듈 안쪽의 정합성은 보장해도 모듈 사이의 약속은 보장하지 못한다. 전통적으로 그 자리를 사람이 메웠으니, 에이전트 팀에 위임할 몫이 된다. “QA Phase는 만들지 않는다”고 못 박고 boundary-verifier를 구현 단계에 상주시키는 것도 그래서다. 엔드포인트가 완성될 때마다 검증을 돌린다. 경계면 불일치는 마지막에 모아서 잡으면 이미 구현 전체에 퍼진 뒤다.

한 발 더 들어가면 설계가 완성된다. 권한을 빼앗은 대신 기준을 준다. 쓰기 권한을 잃은 검증자의 판정은 곧바로 다른 에이전트의 작업 지시가 되고, 그 판정이 자의적이면 팀 전체가 흔들린다. 그래서 책은 판정 기준을 함께 쥐여준다.

• 경계면 검증 7패턴. API 응답 래핑 불일치, 케이스 변환 불일치, 파일 경로 ↔ 링크 경로, 상태 전이 맵 ↔ update 코드, API ↔ 프런트 훅 매핑 누락, 즉시 응답 ↔ 비동기 결과 혼동, 옵셔널 필드 처리. 앞의 버그 일곱 종이 거의 그대로 체크리스트로 승격된 모양이다.
• Fishbone 5카테고리(Code/Data/Config/Infra/Integration). 목적은 분류가 아니라 구조화된 브레인스토밍의 강제다. 한 카테고리에 가설 다섯 개를 몰아넣는 대신 카테고리마다 하나씩 내놓으라고 요구하면 편향이 줄어든다.
• 결정론 게이트. reproduction.sh를 3회 연속 실행해 모두 exit 1이어야 “재현 성공”을 선언한다. 플래키하면 fixture를 초기화하고 다시 세 번이다.

세 번째가 특히 좋다. 짧은 배시 스크립트 하나가 확률적 에이전트의 주장을 exit 코드로 귀결시킨다. 수정 제안자는 “이제 될 거예요”라고 추론만으로 주장할 수 없다. 디버깅 팀의 체크리스트에는 “테스트를 수정·삭제하지 않았는가”가 절대 타협 불가 항목으로 들어가 있다. 수정 제안자가 재현 테스트를 지워 버그를 우회하는 일은 하네스 설계가 실패했음을 보여주는 결정적 증거라는 것이다.

권한을 빼앗고, 판정 기준을 주고, 그 기준을 무력화하는 경로까지 막는다. 세 수가 한 세트다. 앞의 한 수만 가져가면 검증자는 아무 말이나 할 수 있는 자리가 되고, 뒤의 한 수를 빼면 검증자를 통과시키는 가장 쉬운 방법이 검증 자체를 지우는 일이 된다.

더 정교한 쪽이 낫다는 직관은 자주 틀린다

책은 스킬을 잘 설계하라고 오래 가르친다. description 공식, 점진적 공개 구조, 검증 방법까지. 그래 놓고 Vercel의 평가 결과를 들이민다⁶.

스킬을 그냥 얹은 설정은 아무 문서도 없는 베이스라인보다 단 1퍼센트포인트도 나아지지 않았다. 같은 지식을 정적 마크다운 한 장에 담았더니 47퍼센트포인트가 올랐다. Vercel의 결론은 “단순무식한 접근법(정적 마크다운)이 오히려 더 정교한 스킬 기반 검색보다 우수한 성과를 냈다”였다.

저자는 이 모순을 계층 논리로 봉합한다. 스킬은 에이전트가 “지금 이걸 불러야겠다”고 판단해야 쓰이는 수동 자원이고, CLAUDE.md는 판단 없이 항상 거기 있는 유일한 always-on 레이어라는 것이다. 봉합 자체는 설득력 있다. 다만 이 표가 남기는 교훈은 더 넓다.

하네스 설계에서 “더 정교한 것이 더 낫다”는 직관은 자주 틀린다. 같은 교훈이 도구 설계에서 다른 얼굴로 나온다. 도구 인터페이스 한 줄을 바꾼 것이 “무료 모델 업그레이드”와 같았다는 이야기, “‘모델의 성능이 부족하다’는 진단은 종종 오판”이라는 문장. 정교함을 늘리기 전에 항상 켜져 있는 단순한 것을 먼저 의심하라는 쪽이다.

거기서 도구 설계는 네 개의 레버로 정리되는데, 넷을 나란히 놓으면 성격이 드러난다.

넷 중 어느 것도 모델을 바꾸지 않고, 그중 셋은 덜어내는 방향이다. 남은 하나인 피드백도 새 정보를 더하는 게 아니라 이미 일어난 실패를 읽을 수 있게 만드는 일이다. 책은 이걸 “무비용 교육”이라고 부른다. 훈련 데이터를 새로 구하지 않고도 에이전트가 한 번의 실패로 교정 루틴을 배운다는 뜻이다. 하네스가 모델 바깥의 구조물이라는 정의가 가장 손에 잡히는 형태로 나타난다.

손에 남는 숫자는 향상치가 아니라 상한선이다

책에는 인상적인 향상 수치가 여럿 나온다. 그런데 며칠 지나고 나서 실제로 손에 남은 건 그런 숫자가 아니었다.

팀은 3~5명이 적정이고 7명이 넘으면 페이즈를 나눈다. 계층은 2단계 이내. 재시도는 2~3회. SKILL.md 본문은 500라인 안쪽. CLAUDE.md는 150줄 안쪽. 도구 목록은 세션당 15개 안쪽. Vercel이 도구 15개를 2개로 줄여 정확도를 80%에서 100%로 올린 사례⁷가 근거로 붙는다.

도구 개수는 왜 상한이 되나. 토큰 마비 3단계로 설명된다. 첫째, 컨텍스트 잠식. 도구 스키마가 컨텍스트 윈도를 그냥 먹는다. MCP 서버를 붙이면 그 서버의 도구를 한 번도 쓰지 않아도 모든 스키마가 대기 상태에서 계속 자리를 차지한다. 둘째, 선택 혼동. grep, search_code, find_references가 동시에 노출돼 있으면 에이전트는 매번 고르는 데 추론을 쓴다. 셋째, 연쇄 오류. 잘못 고른 도구가 다음 단계를 빗나가게 만든다. 세 단계 모두 도구가 부족해서가 아니라 도구가 많아서 생긴다.

이 값들의 공통점은 만들어진 방향이다. 무엇을 넣으면 좋아지는지가 아니라, 어디를 넘으면 무너지는지에서 나왔다. 앞서 본 메시지 큐 50개가 그 전형이다. “50개면 충분하다”는 설계에서 나온 값이 아니라 292개 에이전트가 메모리를 삼킨 뒤에 그어진 선이다.

그래서 이 책을 읽고 난 뒤의 실감은 이렇다. 하네스 설계는 “무엇을 넣을까”보다 “어디서 멈출까”의 기술에 가깝다. 향상 수치는 인용하기 좋지만 재현 조건이 까다롭고, 상한선은 밋밋하지만 그대로 체크리스트가 된다.

책이 자기 수치에 대해 취하는 태도도 짚어둘 만하다. 코드 리뷰 팀 사례는 하네스 도입 전후 비교표를 제시하면서, 본문에서 그 수치가 실측이 아니라 추정값이라고 두 번 명시한다. 방법론서가 자기 표의 신뢰 등급을 스스로 낮춰 적는 건 드문 일이고, 그만큼 나머지 서술을 믿을 근거가 된다.

안쪽은 확률론, 가장자리는 결정론

읽는 순서를 다시 짤 수 있다면, 토큰 경제를 다루는 부록을 맨 앞의 진단 직후에 놓겠다.

책의 첫머리는 채드 파울러를 인용해 명제를 던진다. “패턴은 이렇습니다. 안쪽은 확률론, 가장자리는 결정론.” 멋진 명제지만 거기서는 문장으로 멈춘다. 이걸 실행 단계로 번역하는 게 그 부록이다. 기계가 확인할 수 있는 것은 결정론적 도구에게, 판단이 필요한 것은 확률적 에이전트에게 — 그 교대가 한 워크플로 안에서 어떻게 일어나는지를 단계별로 펼친다.

훅에 대한 서술이 앞의 명제와 정확히 맞물린다. 여러 규칙을 자연어로 지시하면 준수는 확률의 문제로 남지만, 훅으로 옮기면 컨텍스트 비용은 0이고 준수는 결정론이 된다. “프롬프트는 설득, 하네스는 강제”에 처음으로 계산이 붙는 지점이다.

비용 이야기도 마찬가지다. 입력 토큰이 비용의 대부분을 차지한다는 사실에서 출발해, 절감 레버의 순위를 캐시 → 모델 분리 → 루프 길이로 매긴다. 실무에 남는 결론은 하나다. 가장 큰 레버는 KV 캐시다. 안정적인 접두사를 유지하고, 덧붙이기만 하고, 바이트 단위로 동일한 접두사를 재사용하라는 세 원칙이 그 아래 붙는다. (같은 부록에 실린 모델별 단가표는 현재 공식 단가와 맞지 않으므로, 절대 금액이 아니라 이 구조적 순위만 가져가는 편이 안전하다.)

책이 도입부에서 던져놓고 미뤄 둔 질문에 답하는 것도 이 부록이다. 왜 스트라이프와 클로드 코드가 각각 독립적으로 6계층, 7계층이라는 비슷한 구조에 도달했는가. 저자의 비유가 좋다.

“30층짜리 건물을 짓는다고 하자. 건축가가 ‘나는 7층이 좋겠다’고 말할 수 없다. 물리 법칙, 건축 법규, 거주자의 동선, 화재 대피 경로가 층수와 각 층의 역할을 결정한다.”

계층 수는 취향이 아니라 제약의 결과라는 것. 이게 책의 이론적 종착점이다.

이 책은 자기 하네스로 쓰였고, 그 하네스를 열어 보인다

앞에서 코드 리뷰 사례가 자기 비교표를 “추정값”이라고 낮춰 적는다고 했다. 같은 태도가 훨씬 강한 형태로 나타나는 자리가 따로 있다. 방법론서를 읽을 때 가장 확인하고 싶은 건 저자가 그 방법론을 실제로 쓰는가인데, 이 책은 그 질문을 독자가 던지기 전에 스스로 답한다. 그것도 자기에게 유리하지 않은 방식으로.

스킬 설계를 가르치는 대목은 예제로 book-writer 스킬의 SKILL.md를 연다. 이 책의 집필을 조율하는 실물이다. 그리고 이렇게 적는다.

“이 파일은 실제로 돌아가고 있는 오케스트레이터이고, 지금 이 장을 포함한 모든 장이 이 스킬의 지휘 아래 집필됐습니다.”

CLAUDE.md 변경 이력 테이블을 권하는 대목에서는 book-writer 하네스 자신의 이력을 함께 밝힌다. “초기 구성 — 8 에이전트 + 3-모드 스킬”에서 시작해 “book-editor 에이전트 추가(9번째)”, “샘플링 재검증 워크플로 추가(4번째 모드)”, “book-editor 고도화(8축 검출 규칙)”, “샘플링 MUST 10건 반영” 순으로 쌓였다고 적는다. 각 항목이 집필 도중 발견된 결함을 교정한 기록이다.

가장 놀라운 건 에이전트 정의를 다루는 대목이다. model과 tools를 에이전트별로 갈라 두라는 원칙을 한참 가르친 다음, 확인 명령 두 줄을 싣는다.

grep '^model:' .claude/agents/*.md # 8개 전부 model: opus
grep '^tools:' .claude/agents/*.md # 어떤 파일에도 tools 필드 없음

즉 자기 집필 하네스는 그 원칙대로 구성돼 있지 않다. 저자는 이걸 덮지 않는다. 권장 설계 표를 나란히 붙인 뒤, 현재 구성은 운영 단순성을 우선한 선택이며 파일 수준 가드레일 대신 시스템 프롬프트 수준의 선언에 기대고 있다고 적는다. tools 한 줄로 가드레일을 세우라는 자기 결론을 정작 자기 팀에는 아직 적용하지 못했다고 밝히는 셈이다.

이 자리가 이 책의 신뢰도를 가장 크게 올린다고 생각한다. 방법론서가 자기 사례를 들 때 보통은 성공한 쪽을 싣는다. 원칙과 실제가 어긋난 지점을 표로 병기하는 건 다른 종류의 서술이다. 메타스킬이 자기가 정한 500라인 상한을 스스로 지킨다는 자기 참조성 논의는 이 실천을 이론으로 끌어올린 것에 가깝다.

그래서 하네스 책을 고를 때 쓸 만한 판정 기준이 하나 생긴다. 저자가 그 하네스로 그 책을 썼는가, 그리고 어긋난 부분까지 보여주는가. 앞쪽만 만족하는 책은 종종 있고, 뒤쪽까지 가는 책은 드물다.

이 책이 스스로 설계한 유효기간

하네스를 잘 만드는 법을 가르친 책이, 그 하네스를 언제 버려야 하는지도 함께 적어 두라고 한다. 가장 성숙하다고 느낀 것도 이 대목이었다.

방금 본 변경 이력 테이블에는 열이 네 개인데, 책은 그중 “사유”가 특히 중요하다고 강조한다. 이유가 인상적이다.

“오늘 정교하게 설계한 하네스의 많은 구성요소가, AI 모델이 충분히 발전하면 불필요해질 것이기 때문입니다.”

그래서 각 구성요소가 모델의 어떤 능력이 부족하기 때문에 존재하는지를 적어 두라고 한다. 그래야 그 능력이 개선됐을 때 삭제할 근거가 생긴다. 사유를 적지 않으면 미래의 자신이 그걸 지울 수 없고, “이게 왜 있지?”에 답할 수 없는 구성요소는 사라지는 대신 방치된다.

같은 사상이 Build to Delete 원칙과 ADR의 ‘삭제 조건’ 필드로 이어진다. 예시로 든 삭제 조건이 상징적이다. “단일 리뷰어 모델이 두 관점을 한 번에 안정적으로 다룰 수 있는 역량에 도달했을 때.” 방법론서가 자기 처방의 폐기 시점을 문서화하는 건 흔치 않다.

그런데 바로 여기서 책이 열어둔 채 닫지 않은 질문이 있다.

책의 명제는 “모델이 아니라 하네스가 결과를 결정한다”이다. 정작 이 명제를 뒷받침하는 근거들은 하나같이 특정 모델 세대에 묶여 있다. 랭체인 실험은 모델을 고정한 채 하네스만 바꿨고, 앞의 세 장면도 같은 계열 모델을 상수로 놓고 하네스의 형태만 비교한 관찰이다. 편집 도구 벤치마크에서 가장 극적인 개선을 보인 건 가장 약한 모델이었다. 약한 모델일수록 하네스의 이득이 크다면, 논리적 귀결은 이렇게 된다. 모델이 강해질수록 하네스의 한계 효용은 줄어든다.

그렇다면 “모델이 아니라 하네스”라는 명제는 역설적으로 모델의 현재 수준에 의존한다. Build to Delete는 이 반론을 인정하지만 답하지는 않는다. 삭제 조건을 적어 두라는 건 “언젠가 이 명제가 약해질 것”이라는 시인이지, 그때가 언제이고 무엇이 남는지에 대한 답은 아니다.

다만 이건 책의 결함이라기보다 지금 시점에 답이 없는 질문에 가깝다고 생각한다. 답이 없다는 사실이 이 책을 지금 읽을 이유이기도 하다. 유효기간이 있는 지식은 유효할 때 써야 한다.

책이 스스로 내놓는 마지막 요약이 그 태도를 잘 담고 있다.

“하네스 구축이란 완벽한 문서를 만드는 일이 아니라, 같은 실수를 반복하지 않는 환경을 만드는 일이라는 점입니다.”

완벽한 문서를 목표로 삼으면 모델이 좋아질 때마다 문서가 낡는다. 같은 실수를 반복하지 않는 환경을 목표로 삼으면, 실수의 목록이 바뀔 때마다 환경도 함께 바뀐다. 하네스라는 구조물에는 유효기간이 있어도, 그것을 계속 고쳐 나가는 습관에는 없다.

읽고 나서 남은 리듬을 한 번 더 줄이면 이렇게 된다. 명제를 세우고, 그 명제를 파일로 분해하고, 분해 절차를 다시 접고, 도메인마다 펼친다. 그리고 접고 펼치는 동작이 반복될 수 있게, 자기가 언제 사라져야 하는지를 적어 둔다. 목차는 다섯 덩어리였지만, 손에 남은 건 이 네 박자였다.