하네스(harness)
가 믿을 만하게 일할 환경을 설계하는 일. 무엇인지, 어떻게 돌아가고 어떻게 쓰는지, 조심할 점까지 그림과 예로 풀어 봅니다.
한 문장으로
·에 보내는 모든 일반 는 를 사용해요. 없이 바로 답해도 마찬가지예요. 프롬프트는 하네스의 실행을 시작하는 입력이며, 실행 시스템 전체와 같은 것은 아니에요. 의 넓은 정의에서는 도 하네스의 구성 요소에 포함해요.
- 이렇게 생각해 보세요
- 주방을 떠올려 보세요. 작은 주문 하나도 주방의 작업 환경을 이용해요.
- 예시
- Codex에 인사를 보내요. 입력 → → 답변만으로도 하네스의 를 거친 거예요.
- 자주 하는 실수
- 도구를 하거나 여러 번 재시도해야만 하네스를 쓰는 것은 아니에요. 사용자 프롬프트와 그 입력을 처리하는 하네스는 역할이 달라요.
세 곳이 말하는 하네스
1. Codex: 프롬프트가 하네스의 에이전트 루프를 시작해요
the Codex harness, which provides the core agent loop and execution logic that underlies all Codex experiences
OpenAI — Unrolling the Codex agent loop
는 Codex 하네스가 모든 Codex 사용 환경의 기반인 핵심 에이전트 루프와 실행 을 제공한다고 설명해요. 간단한 입력도 이 루프를 시작해요. 그림의 USER INPUT(사용자 입력) → MODEL INFERENCE(모델 추론) 다음에는 RESPONSE(답변)로 끝나거나, (도구 호출)의 결과를 받아 다시 추론해요. 바로 답하는 경우도 이 루프를 거쳐요. 따라서 Codex의 모든 일반 프롬프트는 하네스를 사용하며, 프롬프트는 그 실행을 시작하는 입력이에요.
"hello" 한 단어도 하네스(harness)를 거쳐요
Codex 에 hello 한 단어만 쳐 보세요. 모델은 도구를 하나도 쓰지 않고 짧게 인사한 뒤 끝내요. 그래서 "이번에는 하네스를 안 썼다"고 생각하기 쉬워요. 하지만 아래 네 단계를 따라가 보면, 그 짧은 대화도 이미 에이전트 루프를 한 바퀴 돈 거예요.
-
hello 입력 나
-
프롬프트 만들기 하네스
-
모델 추론 모델
-
답 보이고 끝 하네스
도구 호출이 있으면 실행 결과를 붙여 3단계로 — hello 는 한 바퀴로 끝나요
-
hello 입력나
에 hello 를 쳐요. 이것은 사용자 입력일 뿐이고, 아직 아무것도 실행되지 않았어요.
-
프롬프트 만들기하네스
하네스는 hello 만 달랑 보내지 않아요. 시스템 지시문, (있으면), 모델이 부를 수 있는 도구 목록, 지금까지의 대화를 붙여 하나의 프롬프트로 만들어 모델에 보내요.
-
모델 추론모델
모델은 프롬프트를 읽고 "인사에는 도구가 필요 없다"고 판단해요. 그래서 "안녕하세요! 무엇을 도와드릴까요?" 같은 답만 써요. 도구 호출은 없어요.
-
답 보이고 끝하네스
하네스는 모델의 출력에 도구 호출이 있는지 살펴요. 없으니 답을 화면에 보여 주고 이번 차례(turn)를 끝내요. 도구 호출이 있었다면 하네스가 도구를 실행하고 결과를 프롬프트에 붙여 3단계로 돌아갔을 거예요.
2. 클로드 코드: 행동에 필요한 기능을 하네스가 제공해요
The tools, context management, and execution environment that turn a language model into a capable coding agent. Claude Code is the harness; Claude is the model inside it. The harness supplies file access, shell execution, permission gating, memory loading, and the loop that chains actions together.
Claude Code — Glossary: Agentic harness
은 을 로 만드는 도구··을 하네스라고 정의해요. 클로드 코드는 하네스이고 는 그 안의 모델이에요. 파일 접근, 실행, 확인, , 여러 행동을 이어 주는 루프는 하네스에서 와요. 짧은 요청도 필요에 따라 이 기능들을 사용할 수 있으므로, 간단한 프롬프트도 하네스를 사용한다고 설명할 수 있어요.
3. LangChain: 모델을 제외한 주변 시스템 전체예요
If you're not the model, you're the harness.
A harness is every piece of code, configuration, and execution logic that isn't the model itself. A raw model is not an agent. But it becomes one when a harness gives it things like state, tool execution, feedback loops, and enforceable constraints.
LangChain — The Anatomy of an Agent Harness
이 글의 넓은 정의에서는 에이전트 시스템에서 모델 자체를 제외한 ·설정·실행 로직 모두가 하네스예요. 모델에 상태, 도구 실행, 피드백, 실제로 강제하는 제약을 제공하면 에이전트가 돼요. 글은 다음을 포함해요.
- 시스템 프롬프트.
- 도구··와 그 설명.
- ·· 같은 실행 기반.
- 생성··모델 선택을 조정하는 로직.
- ·작업 이어가기·를 수행하는 과 .
이 관점은 모델의 지능을 둘러싼 시스템을 설계하는 데 초점을 맞춰요. 시스템 프롬프트는 그 설계의 구성 요소이고, 사용자 프롬프트는 시스템이 처리하는 입력이에요.
모델과 하네스는 함께 자라요
모델 과 하네스 설계는 함께 발전해요. LangChain은 Codex·클로드 코드 같은 제품이 모델과 하네스를 함께 사용하는 을 통해 파일 작업·bash 실행·계획·서브 에이전트 작업을 더 잘하게 된다고 설명해요. 유용한 기능을 하네스에 추가하고 다음 모델의 학습에 반영하는 순환이에요. 그 환경에서 능력이 좋아지지만 도구 로직을 바꾸면 성능이 낮아질 수도 있어요. 이 글은 이를 모델과 하네스의 공동 발전으로 설명해요.
하네스의 세 가지 모습
코딩 에이전트 안에 들어 있는 하네스, 프로젝트가 직접 만드는 하네스, 하네스를 잘 짓는 일 — 셋을 탭에서 하나씩 봅니다.
AI 과정에서 함께 배우기
무엇인가요
기본 내장 하네스는 나 같은 안에서 을 감싸고 있는 입니다. 모델은 글을 읽고 쓸 뿐이고, 가 파일 읽기· 수정· 명령 같은 도구를 주고, AGENTS.md 나 CLAUDE.md 같은 지침을 넣고, 을 묻고, 반복(루프)을 돌립니다. 한 단계마다 모델은 답을 하거나 을 요청합니다. 도구 호출이면 하네스가 그 도구를 실행해 결과를 에 붙이고 모델에게 다시 묻기를, 모델이 마지막 답을 낼 때까지 되풀이합니다. 대화가 길어지면 하네스가 대화를 짧게 요약(압축)해 도 관리합니다.
쉽게 말하면 혼자 요리하고, 맛보고, "맛있어요"라고 말하는 요리사예요.
어떻게 돌아가나요
-
사람이 요청을 보냅니다
-
모델이 도구 호출을 요청합니다
-
하네스가 실행하고 결과를 돌려줍니다
-
마지막 답이 나올 때까지 되풀이합니다
이렇게 씁니다
-
AGENTS.md·CLAUDE.md하네스가 이 프로젝트 지침을 알아서 프롬프트에 넣습니다. Codex 는
AGENTS.md를, Claude Code 는CLAUDE.md를 읽고AGENTS.md도 읽을 수 있습니다. -
/compact대화가 너무 길어지면 하네스가 대화를 요약해 일을 이어 가게 합니다.
-
권한과 샌드박스 — Claude Code 에서는
Shift+Tab으로 가 묻지 않고 할 수 있는 일을 바꾸고, Codex 에서는 샌드박스가 셸 도구가 닿을 수 있는 범위를 정합니다. -
EscClaude Code 에서 루프를 언제든 멈추고 에게 다른 방향을 알려 줍니다.
주의할 점
일하는 프로그램과 일이 끝났다고 판단하는 프로그램이 같으므로, git diff 를 읽고 테스트를 직접 다시 돌려 확인합니다. Codex 의 샌드박스는 Codex 가 주는 shell 도구에만 걸리고, 가 주는 도구는 스스로 안전을 지켜야 합니다. 프로젝트가 에이전트를 바깥에서 부르려고 직접 만드는 와는 다릅니다.
예
-
codex켜고 요청 — Codex 가 직접 쓰고 테스트 -
~/.codex/sessions/Codex 가 남기는 세션 기록
함께 보면 좋은 용어
원문과 공식 문서
이 페이지는 용어를 쉬운 말로 풀어 쓴 것입니다. 기준은 원문이니, 다르면 원문을 따르세요.
- 원문에서 이 용어 보기Unrolling the Codex agent loop OpenAI · 2026-10-24 확인
- Anthropic — Claude Code docs: How Claude Code works — The agentic loop(새 창에서 열림)
- Anthropic — Claude Code docs: Glossary — Agentic harness(새 창에서 열림)
- OpenAI — Unlocking the Codex harness(새 창에서 열림)
- Anthropic — How Claude Code works(새 창에서 열림)
무엇인가요
프로젝트 전용 하네스는 한 프로젝트가 스스로 만든 작은 실행기 입니다(예: 스크립트, 스크립트). 사람이 채팅 창에 입력하는 대신, 이 실행기가 나 를 비대화형 모드인 codex exec 나 claude -p 로 불러 일 하나를 맡깁니다. 는 작업자처럼 일하고 답을 돌려주며, 실행기는 그 결과를 프로젝트의 자기 테스트로 검사하고 기록을 남깁니다. 그래서 일은 에이전트가 하지만, 합격인지는 에이전트가 아니라 프로젝트가 정합니다. 작업자 안에서는 가 평소처럼 돌아갑니다.
쉽게 말하면 요리사가 내놓는 접시마다 맛보고, 무게를 달고, 장부에 적는 검수 담당자예요.
어떻게 돌아가나요
-
실행기가 다음 할 일을 고릅니다
-
나 claude -p 를 부릅니다
-
프로젝트 테스트로 결과를 검사합니다
-
기록을 남기고 다음 일로 갑니다
이렇게 씁니다
-
codex exec "<task>"진행 상황은 stderr 로, 마지막 답만 stdout 으로 나와서 실행기가 저장하기 쉽습니다.
--json을 붙이면 이벤트가 로 나옵니다. -
codex exec --sandbox workspace-writecodex exec는 기본으로 샌드박스에서 돕니다. 작업자가 작업 폴더의 파일을 고치게 하려면 이 옵션을 씁니다. -
claude -p "<task>" --output-format json결과·세션 ·비용을 으로 돌려주고, 성공하면 종료 0, 실패하면 0이 아닌 값을 냅니다.
--bare를 더하면 그 컴퓨터의 훅··CLAUDE.md 를 읽지 않아 어디서나 같은 실행이 됩니다. -
harness/build-log.mdCookbook 예제는 단계마다 계획 파일을
harness/build/에 두고, 각 단계의 검사 결과를 이 기록에 적습니다.
주의할 점
실행기는 에이전트에게 실제 을 주므로 꼭 필요한 만큼만 주고, danger-full-access 는 된 나 에서만 씁니다. claude -p 실행에는 신뢰 창이 뜨지 않고, 수동(Manual) 모드에서는 허락이 필요한 을 아무것도 허락하지 않으면 거절되므로 쓸 도구를 --allowedTools 로 미리 적어 둡니다. 프로젝트 전용 하네스는 기본 내장 하네스를 대신하지 않고 바깥에서 감쌀 뿐입니다.
예
-
bash harness.sh "<request>"어떤 요청이든 실행기에 넘기기 -
codex exec --json --sandbox read-only실행기가 부르는 작업자 -
bash harness.sh verify증거와 결과를 다시 검사
함께 보면 좋은 용어
원문과 공식 문서
이 페이지는 용어를 쉬운 말로 풀어 쓴 것입니다. 기준은 원문이니, 다르면 원문을 따르세요.
- 원문에서 이 용어 보기Codex Docs — Non-interactive mode OpenAI · 2026-10-20 확인
- OpenAI — Codex non-interactive mode — Basic usage(새 창에서 열림)
- Anthropic — Claude Code docs: Run Claude Code programmatically — Get structured output(새 창에서 열림)
- OpenAI — Iterating development workflows with Codex — Create harness and build phase files(새 창에서 열림)
- OpenAI — Harness engineering: leveraging Codex in an agent-first world(새 창에서 열림)
- Anthropic — Claude Code non-interactive mode (claude -p)(새 창에서 열림)
무엇인가요
하네스 엔지니어링은 가 로 제품을 만든 경험을 적은 글에서 붙인, 새로운 엔지니어링 일의 이름입니다. 한 팀이 다섯 달 동안 손으로 쓴 한 줄 없이 내부 베타 제품을 내놓았는데, 코드는 약 100만 줄, 병합된 은 약 1,500개였고 처음에는 엔지니어 세 명뿐이었습니다. 원칙은 "사람은 방향을 잡고, 가 실행한다"입니다. 엔지니어의 일은 코드를 쓰는 것에서 환경을 설계하고, 의도를 밝히고, Codex 에이전트가 믿을 만하게 일하도록 을 만드는 것으로 바뀌었습니다. 에이전트가 막히면 더 열심히 하라고 하지 않고, 어떤 능력이 빠졌는지, 그것을 에이전트가 읽고 지킬 수 있게 하려면 어떻게 할지를 물었습니다.
쉽게 말하면 직접 요리하는 대신 주방과 레시피와 검사 방법을 설계하는 일이에요.
어떻게 돌아가나요
-
에이전트에게 짧은 지도를 줍니다
-
모든 지식을 안에 둡니다
-
와 테스트로 규칙을 지킵니다
-
어긋남을 꾸준히 청소합니다
이렇게 씁니다
-
AGENTS.md1,000쪽 설명서가 아니라 약 100줄짜리 목차로 짧게 두고, 자세한 내용은 정리된
docs/폴더를 가리킵니다. -
맞춤 린터와 구조 테스트 — 정해진 계층과 의존 방향 같은 설계 규칙을 기계로 지키게 하고, 린트 에 고치는 방법을 적어 에이전트에게 알려 줍니다.
-
에이전트가 읽을 수 있는 앱 — 마다 앱을 따로 띄우고, Codex 가 로 화면을, 로그와 지표로 상태를 보며 를 하고 고친 것을 확인합니다.
-
황금 원칙과 청소 작업 — 배경에서 도는 Codex 작업이 어긋난 곳을 찾아 작은 리팩터링 PR 을 엽니다. 쓰레기 수거(garbage collection)처럼 기술 부채를 조금씩 꾸준히 갚습니다.
주의할 점
OpenAI 는 이 방식이 그 저장소의 구조와 도구에 크게 기대고 있어서, 비슷한 투자 없이 다른 곳에서도 된다고 여기면 안 된다고 말합니다. 에이전트가 모두 만든 코드가 몇 년 뒤에도 구조를 잘 지킬지는 아직 모른다고도 합니다. 막는 검사를 적게 두고 빨리 병합하는 방식은 이 적은 팀에서는 무책임할 수 있다고 글 스스로 밝힙니다.
예
-
AGENTS.md문서로 가는 길만 적은 짧은 지도 -
docs/설계·계획·품질 문서를 저장소 안에
함께 보면 좋은 용어
원문과 공식 문서
이 페이지는 용어를 쉬운 말로 풀어 쓴 것입니다. 기준은 원문이니, 다르면 원문을 따르세요.