하네스 엔지니어링 — AI가 일하는
'작업장'을 짓다
하네스(harness)는 AI 모델을 감싸고 실제 일을 하게 만드는 실행 환경 전체예요. 2편에서 확인한 컨텍스트의 한계 — 문서는 스스로를 지키지 못한다 — 를 넘으려면, 규칙을 '부탁'이 아니라 코드로 강제해야 했어요. 세션의 길목마다 자동 개입하는 hook, 작업 유형별 실행 조직, 매 턴 자동 저장되는 안전망, 그리고 틀린 수치를 막는 검증 게이트까지. 몇 달간 직접 지어 굴려온 작업장의 설계도를 공개해요.
하네스란 — 도구가 아니라 작업장
하네스의 원뜻은 말에 채우는 마구(馬具), 또는 몸을 지켜주는 안전벨트예요. 힘 좋은 존재가 그 힘을 엉뚱한 데로 흘리지 않고 일에 쓰도록 잡아주는 장치죠. AI 업계에서는 모델을 감싸는 실행 환경 — 도구 연결, 권한 관리, 작업 흐름 제어, 결과 처리까지 — 전체를 가리키는 말로 자리 잡았어요. Anthropic도 공식 기술 블로그에서 장시간 일하는 에이전트를 위한 '하네스 설계'를 별도 주제로 다루고, Claude Code의 심장부인 Claude Agent SDK를 '범용 에이전트 하네스'라고 소개해요.
출처: Anthropic 엔지니어링 블로그 — Effective harnesses for long-running agents · Building agents with the Claude Agent SDK
제가 좋아하는 비유는 이거예요. 채팅으로 AI를 쓰는 건 똑똑한 신입에게 매번 구두로 부탁하는 것이에요. 컨텍스트 엔지니어링은 그 신입에게 업무 매뉴얼을 쥐여준 거고요. 하네스는 거기서 더 나아가 취업규칙과 결재선과 백업 서버까지 갖춘 사무실을 지어주는 일이에요. 매뉴얼은 안 읽으면 그만이지만, 결재선은 건너뛸 수가 없잖아요. 그 차이예요.
전환점 — 말로 하던 규칙을 코드로
2편의 사고(규칙이 문서에 있었는데 안 지켜진 사건) 이후, 가장 자주 빠뜨리는 규칙부터 hook으로 바꿨어요. hook은 세션의 특정 순간에 자동 실행되는 장치예요. 세션이 시작될 때, 지시가 들어올 때, 작업이 끝날 때 — 이 길목마다 코드가 개입해요.
- 세션 시작 — 어제 어디까지 했는지 브리핑이 자동으로 주입돼요. "인계 파일을 읽어달라"고 부탁할 필요가 없어요. 안 읽는 게 불가능하니까요.
- 지시가 들어올 때 — 작업 유형을 감지해 맞는 전문 에이전트로 자동 라우팅돼요. "디자인 규칙 지켜줘"를 매번 말하지 않아도 돼요.
- 작업이 끝날 때 — 검토 게이트가 돌고, 결과가 자동 백업되고, 인계 기록의 날짜가 강제로 갱신돼요.
이 전환의 의미를 한 줄로 줄이면 이래요. 문서의 규칙은 '지켜달라'는 부탁이고, hook의 규칙은 '빠뜨릴 수 없는' 실행이에요. 규칙이 지켜지느냐가 그날의 컨디션에서 분리된 거예요.
작업장의 설계도 — 4개 층
hook을 시작으로 하나씩 쌓다 보니, 작업장 전체가 네 개 층으로 정리됐어요.
여기서 이 시리즈의 두 번째 결론이 나와요. 컨텍스트 엔지니어링은 하네스의 1층이었어요. 훌륭한 층이지만, 그것만으로는 2편에서 본 세 가지 한계(안 지켜짐·비대해짐·검증 안 됨)를 못 넘어요. 한계 하나마다 답이 하나씩 필요했던 거예요 — 안 지켜지는 문제는 2층(강제)이 막고, 비대해지는 문제는 3층의 분업과 뒤에 나올 지침 다이어트가 덜어내고, 검증 문제는 4층(안전망)이 잡아요.
4층 이야기 — 안전망과 검증 게이트
안전망 층은 두 갈래예요. 하나는 복구. 작업이 한 턴 끝날 때마다 그 시점이 자동 저장돼요(체크포인트). 파일이 꼬여도, 실수로 지워도 어느 시점으로든 되돌아갈 수 있어요. 저장소도 세 겹이에요 — 작업 폴더의 클라우드 동기화, 로컬 이력, 원격 저장소 백업. 2편의 '충돌 사본 100개' 같은 사고가 다시 나도, 이제는 몇 분이면 복구돼요.
다른 하나는 검증이에요. AI는 그럴듯하게 틀려요. 유의하지 않은 걸 유의하다고, 상관을 인과라고 말해요. 그래서 수치·통계가 들어간 산출물은 적대적 검증을 통과해야만 납품되게 했어요. 독립적으로 다시 계산해서 대조하고, 방법론과 과대해석을 비판하는 별도 검수 에이전트를 통과 못 하면 저한테 오기 전에 걸러져요.
그럴듯하니까 그대로 보고서에 실려요. 알고 보니 계절 효과를 뺀 수치가 아니었고, 이미 보고된 뒤에야 발견돼요. 정정 비용과 신뢰 비용을 같이 치러요.
납품 전에 검수 에이전트가 독립 재계산 + 방법론 비판을 강제로 돌려요. "계절 보정 없음, 상관≠인과" 지적이 걸리면 고쳐야 통과돼요. 틀린 숫자는 나가기 전에 죽어요.
작업장은 스스로를 고친다
하네스가 재밌어지는 건 이 지점부터예요. 작업장이 갖춰지니, 작업장이 자기 자신을 진단하고 고치기 시작했어요.
한번은 하네스에게 "이 환경의 약점을 적대적으로 진단해봐"라고 시켰어요. 돌아온 답이 뼈아팠어요 — "좋은 하네스, 약한 토대". 백업이 사실상 한 겹이고, 기억 파일이 두 곳으로 갈라져 있고, 항상 읽는 지침이 비대하다는 거예요. 그 진단대로 백업을 세 겹으로 늘리고, 기억을 한 곳으로 통일하고, 지침을 다이어트해서 매 세션 자동으로 읽히는 분량을 28% 줄였어요. 쌓인 기억 파일들은 서로 링크로 연결해 위키처럼 관리하는데, 끊어진 링크나 고립된 기억을 잡아내는 점검 도구까지 하네스 안에 들어 있어요.
1편에서 "잘하게 될수록 더 피곤해지는 구조"를 얘기했는데, 정확히 반대가 된 거예요. 이제는 쓰면 쓸수록 환경이 좋아지는 구조예요. 사고가 나면 그 사고를 막는 장치가 하네스에 추가되고, 반복되는 작업은 표준이 되어 쌓여요.
이 작업장으로 실제로 한 일들
이론 얘기가 아니라는 걸 보여드리기 위해, 이 환경으로 실제 처리한 일 몇 가지를 소개할게요.
회의 기록에서 출발해 팩트체크, 리서치(적대적 검증 포함), 진단 문서, 발표덱까지. 리서치 에이전트와 검수 에이전트, 디자인 표준이 한 흐름으로 돌았어요.
The Brief의 수집→요약 파이프라인이 이 하네스 위에서 돌아가요. 다만 발행은 사람 몫이에요 — AI가 정리한 초안이 편집자용 어드민으로 전달되면, 편집자가 검토하고 에디터 노트를 얹어 발행을 결정해요. 하네스는 그 과정에서 작성·요약의 오탈자를 검증하고, 같은 오타가 반복되면 원천 차단하는 정규화 장치를 파이프라인에 더하는 식으로 같이 진화해요.
다국가 검색·판매 데이터로 "검색이 판매를 예측하나"를 파고들면서, 분석 절차를 업계 표준(CRISP-DM·MMM·nowcasting·인과추론)에 정렬해 9단계 프로세스로 정리했어요. 표준 방법을 실제로 적용해보니 그럴듯하던 상관 대부분이 다중검정 보정(FDR)과 홀드아웃 검증에서 사라졌고 — 견고하게 남은 건 "검색은 판매의 강한 동행지표일 뿐, 단독 예측·인과 레버는 아니다" 하나였어요. 이렇게 과장을 걷어내는 규율(적대적 검증)이 전담 분석 에이전트로 하네스에 들어가면서, 바로 아래 비정형 텍스트 대량 분석을 3일 만에 소화하는 기반이 됐죠.
대형 클라이언트의 콜센터 상담 원문 — 컬럼 39개에 10만 행에 달하는 상담 데이터(자유기술 원문 포함)를 받아, 프로파일링과 텍스트 마이닝으로 가설을 세우고 하나씩 검증해 인사이트 발표덱까지 3일 안에 끝냈어요. 가설마다 예시가 아닌 실제 케이스 원문과 규모·비중 수치를 붙였고, 수십 개 수치를 독립 재계산으로 대조하는 적대적 검증 게이트를 통과한 결론만 남겼어요.
회의 전사를 붙여넣으면 결정사항 중심의 요약 장표와 코칭 카드로 일관 변환돼요. 민감 정보 익명화 규칙도 하네스에 박혀 있어서 사람이 따로 안 챙겨도 돼요.
이 3부작도 그 하네스가 썼어요. 초안은 콘텐츠 에이전트가, 검수는 적대적 검수 게이트가, 발행 전 오류 점검은 hook이 담당했어요. 글의 주제가 곧 글의 제작 방식이에요.
숫자로 보는 현재 상태
지금 이 작업장의 구성을 숫자로 요약하면 이래요.
※ 위 수치는 이 글을 쓰는 시점의 실측 구성이에요. 시간 절감 효과 같은 정량 성과는 환경마다 달라서 싣지 않았어요 — 핵심은 숫자보다 구조예요.
마무리 — 세 단계를 다시 한 줄씩
이 시리즈를 관통한 진화를 한 줄씩으로 줄이면 이래요.
- 프롬프트 엔지니어링 — 매번 잘 부탁하는 기술. 통하지만, 세션이 끝나면 증발해요.
- 컨텍스트 엔지니어링 — AI가 알아야 할 것을 상주시키는 설계. '매번 다시 설명'은 해결되지만, 문서는 스스로를 지키지 못해요.
- 하네스 엔지니어링 — 아는 것을 넘어서 하게 만드는 환경. 강제·실행·안전망까지 갖춘 작업장이에요.
그리고 몇 달의 운영에서 남은 원칙 네 개를 정리하면 —
반복되는 규칙은 부탁이 아니라 hook과 표준으로 박아요.
맥락과 결정은 인계 파일과 기억으로 남겨요.
이미 있는 자산부터 찾아요. 중복 제작이 가장 조용한 낭비예요.
백업은 여러 겹, 복구점은 매 턴, 검증은 납품 전에요.
3부작을 관통하는 한 문장으로 마칠게요. AI에게 좋은 도구를 쥐여주는 것보다, 좋은 작업장을 지어주는 게 레버리지예요. 모델은 계속 좋아지고, 그건 모두에게 똑같이 주어져요. 차이는 그 모델이 매번 최선으로 일하게 잡아주는 환경에서 나요.
그리고 그 작업장은 한 번에 짓는 게 아니에요. 이 시리즈의 모든 층은 사고와 불편에서 하나씩 나왔어요. 오늘 겪은 그 불편이, 여러분 작업장의 다음 층이에요.
자주 묻는 것
하네스가 정확히 뭔가요?
컨텍스트 엔지니어링과 하네스 엔지니어링은 뭐가 다른가요?
개발자가 아닌데도 하네스를 만들 수 있나요?
- 프롬프트 엔지니어링의 한계
- 컨텍스트 엔지니어링 — AI에게 '기억'을 상주시키다
- 하네스 엔지니어링 — AI가 일하는 '작업장'을 짓다 (지금 읽는 글)