하네스 엔지니어링, 왜 다들 어렵다고 할까요?

하네스의 원래 뜻과 Claude Code, Codex 공식 문서의 설명, 설명을 들어도 어려운 네 가지 이유, 직접 실행한 지침과 훅 실험, 다섯 부품의 차이, 처음 시작하는 순서를 2026년 11월 1일 기준으로 정리했습니다.

홍승협(준이아빠)게시 2026.11.06약 26분

새로 올라온 글이에요. 먼저 읽어 보고 퀴즈도 풀어 보세요

#AI #자동화

유튜브에서 보기 준이아빠유튜브 구독하기영상 길이 15분 47초유튜브 공개 2026.11.06

영상 챕터

시각을 누르면 유튜브에서 해당 장면부터 재생됩니다.

준이아빠AI가 일하는 법AI 친구들의 작업실 구경하기 ↗

하네스가 뭔지 모르겠다는 분들
하네스의 원래 뜻과 AI에서의 뜻
Claude Code와 Codex라는 하네스
하네스 엔지니어링이라는 말
어렵게 느껴지는 네 가지 이유
팀장 OK 비유
실험 1, 지침만으로 글자 수 지키기
대본 검토 반복
Claude Code 하네스의 다섯 부품
부탁과 강제, 그리고 훅의 한계
긴 작업에서 사라지는 지시
자주 하는 오해 네 가지
처음 시작하는 분이 할 일
정리
따라 해 보기
출처와 기준일

세 줄로 먼저 읽기

하네스는 모델이 도구를 쓰게 하고 보여 줄 내용을 정하며 결과를 다시 넘기는 바깥 장치 전부이고, 하네스 엔지니어링은 그 장치를 설계하고 고쳐 나가는 일입니다.
빵집 문구 실험에서 글자 수 규칙은 지침만으로 세 번 모두 지켜졌고, 작업 종료 때 실행한 훅은 결과를 바꾸지 않은 채 검사가 실행됐다는 기록을 남겼습니다.
AI가 같은 실수를 두 번 하면 지침 파일에 한 줄로 적고, 그래도 반복하면 검사를 만들어 훅으로 연결합니다.

하네스 엔지니어링은 AI 모델 바깥에 있는 도구와 규칙, 검사를 설계하고 계속 고쳐 나가는 일입니다. 이 글은 준이아빠AI유튜브 영상 "하네스 엔지니어링, 왜 다들 어렵다고 할까요?"의 내용을 챕터 순서대로 정리했습니다. 단어의 원래 뜻과 공식 문서의 설명, 설명을 들어도 어려운 이유, 직접 해 본 실험, Claude Code의 부품, 처음 시작하는 분이 할 일까지 다룹니다.

하네스가 뭔지 모르겠다는 분들

"하네스가 뭔지 아직도 모르겠다." AI 에이전트 이야기를 나누는 한 단톡방에서 2026년 10월 중순부터 2주 동안 나온 말입니다. 이 기간에 하네스라는 단어가 들어간 메시지는 요약 봇이 올린 글까지 합쳐 75개였고, 올린 계정은 22개였습니다.

설명은 사람마다 달랐습니다. 직접 만들어 쓰면서도 자기 하네스가 어떻게 작동하는지 모르겠다는 분이 있었고, 목줄이나 지휘봉 같은 비유도 제각각이었습니다. 원래 뜻이 말 안장이라는 설명도 나왔는데, 사전을 찾아보면 안장과 하네스는 다른 물건입니다.

하네스의 원래 뜻과 AI에서의 뜻

사전에서 하네스(harness)는 짐을 끄는 동물의 작업용 끈과 띠를 통틀어 가리키는 말입니다. 말이나 소를 수레에 연결하는 장비입니다. 말을 묶어 두려고 쓰는 것이 아니라 말의 힘을 수레에 전하려고 씁니다. 말이 아무리 힘이 세도 하네스가 없으면 수레는 움직이지 않습니다.

AI에서는 모델이 말에 해당합니다. 모델은 AI에서 글을 읽고 다음에 쓸 글을 정하는 부분입니다. 모델 혼자서는 파일을 열지도, 검색을 하지도 못하므로 모델 바깥에 따로 프로그램이 있어야 합니다. 이 프로그램이 하는 일은 세 가지입니다.

모델이 도구를 쓸 수 있게 합니다.
모델에게 무엇을 보여 줄지 정합니다.
도구가 낸 결과를 다시 모델에게 넘깁니다.

모델 바깥에서 이런 일을 하는 장치 전부를 하네스라고 부릅니다. 이렇게 모델이 도구를 써 가며 스스로 일을 이어 가는 AI가 에이전트입니다.

Claude Code와 Codex라는 하네스

Anthropic이 만든 코딩용 AI 도구 Claude Code의 공식 문서는 Claude Code를 모델에게 도구를 주고 모델이 보는 내용을 관리하는 바깥 층으로 설명하고, 이 층을 에이전트 하네스(agentic harness)라고 부릅니다.

OpenAI의 Codex도 비슷한 도구입니다. OpenAI는 Codex에서 모델을 감싸고 작동하는 에이전트 반복 구조와 로직을 Codex 하네스(Codex harness)라고 부릅니다. Claude Code나 Codex를 쓰고 있다면 이미 하네스를 쓰고 있는 것입니다.

AI 개발 도구를 만드는 LangChain은 2026년 3월 글에서 이를 더 짧게 정리했습니다. "Agent = Model + Harness", 그리고 "If you're not the model, you're the harness."라는 문장입니다. 에이전트는 모델과 하네스를 합친 것이고, 모델이 아닌 것은 전부 하네스라는 뜻입니다.

하네스 엔지니어링이라는 말

이 표현은 2026년 2월에 널리 퍼졌습니다. 이 표현이 들어간 글 가운데 확인한 가장 이른 글은 여러 개발 도구를 만들어 온 개발자 미첼 하시모토(Mitchell Hashimoto)의 2월 5일 블로그 글입니다. 하시모토는 업계에 정해진 이름이 있는지는 모르겠지만 자기는 하네스 엔지니어링이라고 부르게 됐다고 적었습니다. 그가 말한 뜻은 에이전트가 실수할 때마다 시간을 들여서라도 같은 실수를 다시는 못 하게 만드는 해결책을 마련하는 것입니다.

같은 달 OpenAI는 하네스 엔지니어링을 제목으로 내건 글을 냈습니다. 약 다섯 달 동안 사람이 코드를 한 줄도 직접 쓰지 않고 제품을 만든 실험을 다룬 글입니다. 이 실험에서는 규칙을 문서에 적어 두는 데서 끝내지 않고, 자동 검사와 구조 테스트로 규칙을 지키게 했습니다.

정리하면 다음과 같습니다.

말	뜻
하네스	모델 바깥에 있는 장치 전부
하네스 엔지니어링	그 장치를 설계하고 계속 고쳐 나가는 일

어렵게 느껴지는 네 가지 이유

단톡방 대화를 읽고 제가 정리한 이유는 네 가지입니다.

첫째, 같은 단어를 서로 다른 뜻으로 씁니다. Claude Code 같은 제품을 하네스라고 하는 사람, 제품에 직접 더한 자기 설정을 하네스라고 하는 사람, 계획과 실행과 평가를 나누는 구조를 하네스라고 하는 사람이 있었습니다. 이 대화에서만 다섯 가지 뜻이 섞여 나왔습니다. 앞의 정의대로라면 제품과 내 설정은 모두 모델 바깥의 장치이므로 하네스에 들어갑니다. 계획, 실행, 평가를 나누는 구조는 그 장치를 짜는 방법 가운데 하나입니다.

둘째, 무슨 문제를 풀려는지보다 도구 이름이 먼저 나옵니다. 어떤 문제를 푸는 도구인지 모르면 외울 이름만 늘어납니다.

셋째, 해 보면 안다는 답이 많았습니다. 열 번 만들어 보면 저절로 이해된다는 답에는 무엇을 열 번 만들지가 빠져 있어서, 처음 시작하는 분은 무엇부터 해야 할지 알 수 없습니다.

넷째, 비유에 나오는 물건이 대부분 무언가를 붙잡거나 통제하는 데 쓰입니다. 목줄, 가슴줄, 지휘봉 같은 비유만 들으면 하네스가 붙잡아 두는 장치라고 생각하기 쉽습니다. 하네스는 막는 일 말고도 결과를 검사하고 다시 시켜서 품질을 끌어올리는 일을 합니다.

팀장 OK 비유

단톡방에 나온 설명 가운데 처음 듣는 분이 이해하기 가장 쉬운 것은 이 비유라고 보는 편입니다. 하네스는 팀장이 OK할 때까지 보고서를 계속 고치는 것과 같다는 설명입니다.

이 비유에는 보고서를 쓰는 사람, 통과인지 판정하는 사람, 언제 멈출지 정하는 기준이 들어 있습니다. AI 작업에 적용하면 일하는 AI와 검사하는 장치를 따로 두고, 검사를 통과할 때까지 다시 시키는 구조가 됩니다.

소프트웨어 개발 분야에서 잘 알려진 마틴 파울러의 사이트에 실린 글은 하네스의 부품을 두 종류로 나눕니다.

부품	하는 일	팀장 비유
지침(guides)	일하기 전에 방향을 알려 줍니다	팀장의 업무 지시
검사(sensors)	일한 뒤 결과를 확인해 고치게 합니다	팀장의 OK

실험 1, 지침만으로 글자 수 지키기

지침만 적어 두면 AI가 지킬지 직접 확인했습니다. 2026년 11월 1일 Claude Code 2.1.316에게 동네 빵집 스무 곳의 소개 문구를 쓰게 했습니다. 지침 파일에는 문구 한 줄을 번호를 빼고 공백 포함 28자에서 30자 사이로 쓰라고 적었습니다. 글자 수는 사람이 아니라 검사 코드로 확인했습니다.

조건	실행 횟수	결과
지침 파일만	3회	3회 모두 스무 줄 전부 글자 수를 지킴
지침 파일과 작업 종료 때 글자 수를 검사하는 훅	3회	검사가 매번 실행되고 매번 통과, 막은 적 없음

이 실험에서는 단순하고 확인하기 쉬운 규칙이 지침만으로 지켜졌고, 훅은 결과를 바꾸지 않은 채 검사가 실행됐다는 기록을 남겼습니다. 실행 횟수가 세 번씩이라 이 결과를 일반화하지는 않습니다. 사람이 읽고 판단해야 하는 규칙에는 다른 방법이 필요합니다.

대본 검토 반복

이 채널의 대본도 AI가 씁니다. 대본 지침에는 무엇을 하는지 분명하지 않은 말을 쓰지 말라거나, 조사와 주어가 꼬인 문장은 고쳐 쓰라는 규칙이 자세히 적혀 있습니다.

이런 규칙은 글자 수처럼 코드로 판정하기 어렵습니다. 그래서 AI가 이 지침을 읽고 대본을 쓰면, 같은 지침을 준 다른 AI가 문장을 하나씩 검토합니다. 지적을 반영해 고친 뒤 다시 검토받고, 사소한 지적만 남을 때까지 되풀이합니다. 끝없이 이어지지 않게 검토는 12번까지만 하기로 정했습니다. 쓰는 AI와 검토하는 AI를 나누고 OK가 나올 때까지 고치게 했으니, 앞의 팀장 비유를 그대로 적용한 구조입니다.

Claude Code 하네스의 다섯 부품

Claude Code의 하네스를 부품별로 나누면 다음과 같습니다. 내용은 공식 문서 기준입니다.

부품	무엇인가요	언제 작동하나요	누가 정하나요
지침 파일(CLAUDE.md)	대화마다 읽는 참고 내용. 강제 설정이 아닙니다	대화를 시작할 때	따를지는 모델이 정함
스킬	특정 작업을 하는 방법을 적은 설명서	이름과 설명은 평소에 알고, 본문은 필요할 때 읽음	따를지는 모델이 정함
훅	정해진 순간마다 실행되는 명령	파일을 저장할 때, 작업을 끝내려 할 때 등	실행 여부를 모델이 고르지 않음
권한 설정	어떤 도구를 써도 되는지 정한 목록	도구를 쓸 때마다	Claude Code 프로그램이 적용
서브에이전트	일을 따로 맡는 AI. 따로 떨어진 대화에서 일하고 결과 요약만 돌려줌. 사용량은 메인 대화와 같은 한도를 나눠 씀	일을 맡길 때	모델이 맡기거나 사용자가 부름

여러 코딩 도구가 함께 쓰는 지침 파일로 AGENTS.md도 있습니다. Claude Code는 기본 설정에서 CLAUDE.md가 없을 때만 AGENTS.md를 대신 읽습니다.

부탁과 강제, 그리고 훅의 한계

다섯 부품 가운데 네 가지는 두 종류로 나뉩니다. 지침 파일과 스킬은 모델에게 하는 부탁이고, 훅과 권한 설정은 모델의 선택과 상관없이 작동하는 장치입니다. 서브에이전트는 일을 나눠 맡기는 방법입니다. Claude Code 문서도 지침 파일에 어떤 파일을 고치지 말라고 적는 것은 부탁이고, 고치려는 순간 막는 훅이 강제라고 설명합니다.

제가 쓰는 훅 가운데 문장을 검사하는 훅이 있습니다. 이 훅 파일 맨 위에는 만든 이유가 적혀 있습니다. 지침을 읽으라는 지시는 이미 여러 곳에 적혀 있었지만 지켜지지 않았고, 그래서 지시 대신 자동 실행으로 바꾼다는 내용입니다. 지금은 AI가 마크다운 문서(이름이 md로 끝나는 글 파일)를 저장할 때마다 이 훅이 실행되고, 금지한 표현이 나오면 검사 결과를 AI에게 돌려보내 바로 고치게 합니다. 길고 신경 쓸 것이 많은 작업을 하다 보면 단순한 규칙도 빠뜨릴 수 있어서 반드시 실행되는 검사가 필요합니다.

훅에도 한계가 있습니다. 작업을 끝내려는 순간에 검사하는 훅(Stop 훅)은 검사를 통과하지 못하면 이유를 알려 주고 다시 일하게 합니다. 그런데 Claude Code 문서에 따르면, 그사이 도구를 쓰지 않은 채 여덟 번 연속으로 막히면 Claude Code가 훅을 무시합니다.

실제로 작업 종료를 매번 막는 훅을 만들어 확인했습니다. AI는 연속 여덟 번 막힌 뒤 아홉 번째에 작업을 끝냈습니다. 반대로 AI가 중간에 파일을 읽거나 고치면 횟수는 처음부터 다시 계산됩니다. 그러면 여덟 번 제한에 걸리지 않으므로 검사에 계속 떨어질 때 AI가 끝없이 고치기만 할 수 있습니다. 몇 번까지 다시 시킬지는 검사를 만드는 사람이 직접 정해 두는 것이 좋습니다.

훅의 종류도 함께 봐야 합니다. 명령을 실행하는 command 훅과 달리 prompt 훅과 agent 훅은 판정에 모델을 씁니다. 판정이 항상 같게 나오는 검사가 필요하면 command 훅으로 만듭니다.

긴 작업에서 사라지는 지시

대화 내용이 AI가 한 번에 기억할 수 있는 양을 넘으면 앞부분이 요약됩니다. 공식 문서도 이때 대화 초반에 준 자세한 지시가 사라질 수 있다고 적고, 꼭 지켜야 할 규칙은 대화 기록에 맡기지 말고 CLAUDE.md에 적으라고 안내합니다.

요약 직후에 규칙을 대화에 다시 넣어 주는 훅도 만들 수 있습니다. 다만 다시 넣은 내용을 모델이 읽는다고 해서 지킨다는 보장은 없습니다. 그래서 작업이 끝날 때 결과를 한 번 더 확인하는 검사가 필요합니다. 어떤 규칙을 지침에 적고 어떤 규칙을 검사나 훅으로 확인할지 정하는 것도 하네스 설계의 일부입니다.

자주 하는 오해 네 가지

하네스와 워크플로는 같은 말일까요? 워크플로는 미리 정해 둔 작업 순서입니다. 하네스는 순서뿐 아니라 모델에게 주는 도구, 보여 줄 내용, 결과 검사까지 포함합니다. 순서가 미리 정해져 있지 않은 에이전트에도 하네스는 있습니다.

하네스는 오케스트레이션과 에이전트 사이의 단계일까요? 오케스트레이션은 여러 AI에게 일을 나눠 맡기고 지휘하는 일입니다. 하네스는 위아래로 쌓인 단계가 아니라 모델을 감싸는 바깥 장치이므로, 에이전트가 하나뿐이어도 있습니다.

하네스는 복잡할수록 좋을까요? Anthropic은 가장 단순한 방법부터 찾고 필요할 때만 복잡도를 높이라고 조언합니다.

한 번 만들면 끝일까요? 단톡방에서도 새 모델이 나온 뒤 그동안 만들어 둔 규칙과 장치를 많이 없앴다는 경험담이 나왔습니다. 하네스를 만드는 일에는 필요 없어진 장치를 빼는 일도 들어갑니다.

처음 시작하는 분이 할 일

광고 점검 에이전트를 만든 글이 좋은 예입니다. 지시문 한 장에 목표와 작업을 끝낼 기준, 하지 말아야 할 일을 적고, 허용 목록과 금지 목록으로 쓸 수 있는 도구를 정했으며, 실행 기록을 읽고 막힌 곳을 고쳐 다시 실행했습니다. 이 과정이 이미 작은 하네스 엔지니어링입니다.

시작은 두 가지면 됩니다. 첫째, AI가 같은 실수를 두 번 하면 그 실수를 지침 파일에 한 줄로 적습니다. 그래도 또 하면 그때 검사를 하나 만듭니다. 둘째, 내 컴퓨터에 쌓인 지침 파일, 스킬, 훅을 하나씩 적고 각각 언제 쓰이는지 옆에 적어 봅니다. 적지 못한 설정은 아직 내가 파악하지 못한 하네스입니다.

정리

하네스는 AI 모델의 힘이 실제 일이 되게 해 주는 바깥 장치 전부이고, 하네스 엔지니어링은 그 장치를 설계하고 AI가 같은 실수를 다시 하지 않게 고쳐 나가는 일입니다. 지침은 부탁이고, 검사는 그 부탁이 지켜졌는지 확인하는 일이며, 훅은 그 검사를 정해진 순간마다 빠짐없이 실행하게 만드는 방법입니다. AI에게 같은 지적을 두 번 이상 한 적이 있다면, 그 지적이 내 하네스의 첫 번째 부품이 될 수 있습니다.

따라 해 보기

Claude Code를 설치했다는 전제로, 첫 부품 하나와 검사 하나를 만들어 봅니다.

1. 같은 실수를 지침 파일에 적기

작업 폴더의 CLAUDE.md를 엽니다. 없으면 새로 만듭니다.
AI가 두 번 한 실수를 한 줄로 적습니다. "문구는 번호를 빼고 공백 포함 30자 이하로 쓴다"처럼 확인할 수 있는 문장으로 씁니다.
같은 작업을 다시 시켜 지켜지는지 확인합니다.

2. 작업을 끝낼 때 실행되는 검사 연결하기

그래도 또 틀리면 검사를 하나 연결합니다. 아래는 실험 1에서 쓴 구성에서 로그를 남기는 줄만 뺀 것입니다. check.py는 out.md를 읽어 규칙을 어기면 이유를 출력하고 실패 코드로 끝나는 짧은 프로그램이고, AI에게 만들어 달라고 해도 됩니다.

.claude/settings.json

{
  "hooks": {
    "Stop": [
      { "hooks": [ { "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/check-hook.sh" } ] }
    ]
  }
}

.claude/check-hook.sh

#!/bin/bash
cd "$(dirname "$0")/.."
out=$(python3 .claude/check.py out.md)
if [ $? -ne 0 ]; then
  echo "검사 실패. 고쳐서 out.md를 다시 쓰세요: $out" >&2
  exit 2
fi
exit 0

위 두 파일과 .claude/check.py를 작업 폴더에 넣고 chmod +x .claude/check-hook.sh를 실행합니다.
일부러 규칙을 어긴 out.md로 훅 스크립트를 직접 실행해 실패 메시지가 나오는지 봅니다.
Claude Code에 작업을 맡기고, 어긴 결과가 나오면 이유를 받아 다시 일하는지 확인합니다.

막혔을 때는 이렇게 확인합니다.

훅이 실행되지 않는 것 같으면 스크립트 경로를 봅니다. 실험 1의 첫 묶음도 경로가 틀려서 다시 실행했습니다. 실행 때마다 로그 파일에 한 줄씩 남기면 실행 여부를 바로 알 수 있습니다.
막혔는데도 작업이 끝났다면 도구 사용 없이 연속 여덟 번 막힌 경우인지 봅니다.
AI가 끝없이 고치면 다시 시킬 횟수의 상한을 검사에 넣습니다.

3. 내 하네스 목록 적기

작업 폴더의 CLAUDE.md, .claude/settings.json의 훅과 권한 설정, 스킬을 한 줄씩 적습니다.
항목마다 언제 쓰이는지, 부탁인지 강제인지 옆에 적습니다.
설명하지 못하는 항목은 지금도 필요한지 확인하고, 필요 없으면 뺍니다.

출처와 기준일

아래 문서는 2026년 11월 1일에 확인했습니다. 실험은 같은 날 Claude Code 2.1.316으로 실행했습니다. 기능과 동작은 이후 바뀔 수 있습니다.

직접 실행: Claude Code 2.1.316, 빵집 소개 문구 스무 줄, 지침만 3회, 지침과 Stop 훅 3회, 종료를 매번 막는 훅 1회
Dictionary.com, harness
Claude Code 문서, How Claude Code works, Memory, Skills, Hooks, Hooks guide, Permissions, Subagents, Features overview
OpenAI, Harness engineering: leveraging Codex in an agent-first world, Unlocking the Codex harness
Mitchell Hashimoto, My AI Adoption Journey (2026-02-05)
LangChain, The Anatomy of an Agent Harness (2026-03-10)
Birgitta Böckeler, Harness engineering for coding agent users (2026-04-02)
Anthropic, Building effective agents (2024-12-19)

이 글이 도움이 되었나요?

이 글 다음 배우기AI 에이전트 중급: 원리와 설계중급 코스 · 5편

도구에 상관없이 통하는 에이전트 원리와 설계 규칙을 정리했습니다

코스 전체 보기 →

이어서 읽기 좋은 글AI 에이전트란 무엇이고, 어떻게 써야 할까요? →

챗봇과 AI 에이전트는 어디서 달라질까요? 제주 여행 부탁을 네 단계로 바꿔 보며 에이전트인지 가리는 질문 하나를 세우고, Claude Code에 카페 매출 분석을 맡긴 실행 기록, 닷츠와 듀엣, 나만의 에이전트를 만드는 여섯 가지 재료, 맡길 때 사람이 정할 것을 2026년 10월 30일 기준으로 정리했습니다.