에이전트 하네스: 같은 모델도 다르게 일하게 만드는 층

에이전트 하네스 뜻: 한 줄 정의#

하네스는 모델 자체가 아니라 모델이 실제 작업을 진행하도록 연결하는 환경입니다. 아래 구분은 이 글이 정리한 개념이며 Mirr 문서의 문장을 그대로 옮긴 것이 아닙니다. 관련 설명은 도구와 권한과 컨텍스트와 파일을 참고하세요.

1. 작업 목표와 관련 파일을 지정하고 비밀번호·인증 토큰 등 민감한 내용은 제외합니다.
2. 선택한 모드와 권한을 확인하고, 승인 요청의 경로와 명령이 의도와 맞는지 살핍니다.
3. 변경 내용과 실제 테스트 결과를 검토합니다. 실행하지 않은 테스트는 성공으로 간주하지 않습니다.

Anthropic의 도구 사용 문서는 도구 실행의 경계를 이렇게 설명합니다. 모델은 도구 이름과 JSON 인수를 담은 tool_use 블록을 응답으로 보낼 뿐이고, 애플리케이션이 그 작업을 실행한 뒤 결과를 tool_result 블록으로 다음 요청에 담아 돌려보냅니다. 문서의 표현대로 모델은 스스로 아무것도 실행하지 않습니다. 파일 편집처럼 Anthropic이 스키마를 공개한 도구도 실행은 애플리케이션이 맡습니다(도구 사용 문서, 2026-11-03 확인).

이 왕복은 루프로 반복됩니다. Claude Code 작업 방식 문서는 작업을 맥락 수집, 행동, 결과 검증의 세 단계로 나누고, 도구 호출마다 얻은 정보가 다음 판단으로 되돌아간다고 설명합니다. 같은 문서는 모델 주변에서 도구를 제공하고 모델이 보는 맥락을 관리하는 바깥 계층을 'agentic harness'라고 부릅니다. Anthropic의 장기 작업 글도 Claude Agent SDK를 '범용 에이전트 하네스'라고 부르며, 여러 컨텍스트 창에 걸친 작업에는 압축(compaction)만으로 충분하지 않다고 봅니다(2026-11-03 확인).

API로 직접 루프를 만든다면 응답의 중단 사유(stop_reason)를 기준으로 루프를 돌려야 합니다. 중단 사유가 tool_use인 동안만 도구를 실행하고 계속하며, end_turn, max_tokens, stop_sequence, refusal 중 하나로 끝나면 루프를 빠져나옵니다. 문서는 이 경우를 Claude가 최종 답변을 냈거나, 애플리케이션이 처리해야 할 다른 이유로 멈춘 것으로 설명합니다.

도구 호출에는 비용도 따릅니다. Anthropic 문서는 도구 호출이 최소 한 번의 추가 왕복을 만들며, 가벼운 작업에서는 그 오버헤드가 작업보다 커질 수 있다고 설명합니다. 반대로 텍스트만으로는 할 수 없는 일, 예컨대 파일 쓰기나 현재 데이터 조회에는 도구가 필요합니다.

서버에서 실행되는 도구는 따로 구분해서 봐야 합니다. 웹 검색, 웹 페치, 코드 실행처럼 Anthropic 서버가 실행하는 도구는 애플리케이션이 tool_result를 보낼 필요가 없고, 응답에 담긴 실행 결과를 읽기만 합니다. 같은 '도구'라도 실행 위치에 따라 애플리케이션이 맡는 일이 달라집니다.

왜 중요한가: 한국 개발자 기준#

같은 모델을 쓰더라도 어떤 파일을 전달하고 어떤 명령을 허용하는지에 따라 작업 과정이 달라집니다. 한국어 요구사항과 관련 코드 경로를 함께 주면 작업 범위를 명확히 하는 데 도움이 됩니다. 모델이나 하네스가 결과의 정확성을 보장하지는 않습니다.

컨텍스트도 하네스가 고르는 입력입니다. Claude Code 문서에 따르면 컨텍스트 윈도우에는 대화 기록, 파일 내용, 명령 출력, CLAUDE.md, 자동 메모리, 불러온 스킬, 시스템 지시가 함께 담깁니다. /context 명령으로 무엇이 공간을 쓰는지 확인할 수 있습니다. 컨텍스트가 차면 자동 압축이 대화를 요약하는데, 요약 과정에서 대화 초반의 세부 지시가 빠질 수 있습니다. 그래서 문서는 계속 지켜야 할 규칙을 CLAUDE.md에 두라고 권합니다.

Claude Code는 사용자가 쓰지 않은 문장도 컨텍스트에 더합니다. Claude Code 문서는 CLAUDE.md 파일, 출력 스타일 지시, 읽은 파일이 디스크에서 바뀌었다는 알림, 커밋과 PR의 속성 줄을 예로 듭니다. 압축에서 무엇을 남길지는 CLAUDE.md에 'Compact Instructions' 섹션을 두거나 /compact 뒤에 초점을 적어 조정할 수 있습니다. 한 파일이나 도구 출력이 너무 커서 요약 직후 컨텍스트가 다시 차면, Claude Code는 몇 번 시도한 뒤 오류를 띄우고 멈춥니다.

컨텍스트 관리는 도구 정의에도 적용됩니다. 같은 문서에 따르면 MCP 도구 정의는 기본적으로 지연 로딩되어 도구 검색으로 필요할 때만 불러오므로, Claude가 특정 도구를 쓰기 전까지는 도구 이름과 서버 지시만 컨텍스트를 차지합니다. 스킬도 시작할 때는 설명만 보이고 전체 내용은 호출될 때 들어옵니다.

권한 규칙도 모델이 아니라 Claude Code가 집행합니다. Claude Code 권한 문서는 프롬프트나 CLAUDE.md의 지시가 모델이 무엇을 시도할지는 바꾸지만 Claude Code가 허용하는 범위는 바꾸지 못한다고 설명합니다. '파일을 고치지 마세요'라는 문장만으로는 편집 도구가 막히지 않으며, 거부·질문·허용 규칙과 권한 모드가 그 역할을 맡습니다.

예제: 코드나 터미널로 보기#

예를 들어 “로그인 오류와 관련 테스트를 먼저 찾아 설명하고, 파일 수정이나 명령 실행 전에는 물어봐 주세요”라고 요청할 수 있습니다. 이는 요청 예시이지 실행 기록이 아닙니다. 실제 승인은 선택한 모드와 권한 설정에 따라 달라집니다.

이는 위 Mirr 문서의 기능을 점검하는 질문지입니다. 실제 도구 호출 로그와 제품별 기능 비교·검증 기록은 아직 없습니다.

실행 경계와 컨텍스트#

아래 절차는 실행하지 않은 제안입니다. 프로젝트의 .claude/settings.json에 허용 규칙 Bash(npm test)와 거부 규칙 Bash(git push *)를 둔다고 가정하겠습니다. Claude Code 권한 문서에 따르면 *가 없는 규칙은 명령 하나와 정확히 맞고, 규칙은 거부, 질문, 허용의 순서로 평가되며 먼저 맞는 규칙이 결과를 정합니다. 그러니 Bash(aws *) 같은 넓은 거부 규칙은 더 구체적인 허용 규칙 Bash(aws s3 ls)까지 막습니다. 이 설정이라면 npm test는 질문 없이 실행되고, git push로 시작하는 명령은 차단됩니다. 같은 문서는 git -C . push처럼 다르게 쓴 푸시는 이 규칙에 걸리지 않는다고 적습니다.

점검은 모델의 보고가 아니라 도구 호출 기록에서 시작합니다. 어떤 명령이 어떤 인수로 실행됐고 종료 결과가 무엇이었는지 대조하면, 보고된 단계가 실제로 일어났는지 알 수 있습니다.

Anthropic의 장기 작업 실험은 여러 세션에 걸쳐 상태를 남기는 절차를 보여 줍니다. 초기화 세션은 개발 서버를 띄우는 init.sh, 진행 기록 파일인 claude-progress.txt, 첫 git 커밋을 만들었습니다. claude.ai 복제 예에서는 기능 목록이 200개가 넘었고, 이 목록은 JSON으로 두었습니다. 코딩 에이전트가 바꿀 수 있는 것은 각 항목의 passes 필드뿐이었습니다. 글은 모델이 Markdown 파일보다 JSON 파일을 부적절하게 고치거나 덮어쓰는 일이 적었다고 설명합니다. 이후 세션은 pwd로 작업 위치를 확인합니다. 프롬프트는 그 디렉터리 안의 파일만 편집할 수 있다고 알려 주며, 이어서 git 로그와 진행 기록을 읽고, 미완료 기능 가운데 우선순위가 높은 것을 골라 시작했습니다(Anthropic 장기 작업 하네스 글, 2026-11-03 확인).

Anthropic 글은 두 가지 실패도 보고합니다. 에이전트가 한 번에 너무 많은 일을 하려다 컨텍스트가 바닥나고, 기능이 절반만 구현된 채 문서화되지 않은 상태로 다음 세션에 넘어가는 경우가 하나입니다. 다른 하나는 기능이 쌓인 뒤 나중 세션이 진행 상황만 보고 작업이 끝났다고 선언하는 경우입니다.

관련 용어#

컨텍스트 윈도우는 한 요청에서 다룰 수 있는 토큰의 한도이고, 서브에이전트는 별도 하위 작업을 맡는 에이전트입니다. 도구와 에이전트는 같은 뜻이 아닙니다.

체크포인트는 Claude가 파일을 고치기 전에 현재 내용을 스냅샷으로 남기는 기능입니다. Claude Code 문서에 따르면 Esc를 두 번 눌러 이전 상태로 되돌릴 수 있으며, Git 커밋과는 별개로 파일 변경만 다룹니다. 대화를 다시 열어도 체크포인트는 남아 있습니다. 데이터베이스, API, 배포처럼 원격 시스템에 미치는 행동은 체크포인트로 되돌릴 수 없으므로 권한 모드와 규칙으로 통제해야 합니다.

훅(hook)은 도구 호출 전후의 정해진 지점에서 사용자가 정한 명령을 실행하는 장치입니다. 설정 파일에 등록한 훅은 서브에이전트 안의 도구 호출에도 같이 실행됩니다. PreToolUse 훅은 도구 호출 앞에, PostToolUse 훅은 도구가 성공한 뒤에 실행됩니다. 종료 코드 2로 끝난 PreToolUse 훅은 권한 규칙을 평가하기 전에 호출을 막습니다. 종료 코드 0으로 끝난 훅의 표준 오류는 Claude에게 보이지 않으며, 사람이 보려면 디버그 로그를 켜야 합니다.

권한 모드는 Claude가 승인 질문을 얼마나 띄울지 정하는 설정입니다. plan 모드에서 Claude는 파일을 읽고 읽기 전용 셸 명령으로 탐색하지만 소스 파일은 고치지 않습니다. Claude Code 권한 문서는 default(CLI에서는 Manual로 표시), acceptEdits, plan, auto, dontAsk, bypassPermissions를 나열합니다. dontAsk는 승인이 필요한 호출을 자동으로 거부합니다. auto 모드에서는 셸 명령이나 네트워크 요청 같은 행동이 실행되기 전에 백그라운드 분류기가 요청과 맞는지 확인합니다. bypassPermissions는 .git과 .claude 같은 보호 경로에 쓰는 경우에도 질문을 건너뛰므로, 문서는 컨테이너나 가상 머신처럼 격리된 환경에서만 쓰라고 경고합니다.

'다시 묻지 않음'을 고를 때 저장되는 범위도 다릅니다. 같은 권한 문서의 표에 따르면 Bash 명령 승인은 저장소와 명령 단위로 계속 유지되고, 파일 수정 승인은 세션이 끝날 때까지만 유지되며, WebFetch 도메인 승인은 저장소와 도메인 단위로 저장됩니다. 파일 읽기와 검색은 작업 디렉터리 안에서 승인 없이 실행되고, Bash 명령도 내장된 읽기 전용 명령 집합은 질문 없이 실행됩니다.

작업 디렉터리는 Claude가 기본으로 접근할 수 있는 범위입니다. 파일 수정은 Manual 모드에서 승인을 묻고, 다른 모드는 어떤 도구가 질문하는지를 바꿉니다(권한 문서의 도구별 표). Claude Code를 실행한 디렉터리가 기본값이고, --add-dir이나 additionalDirectories 설정으로 넓힐 수 있습니다. permissions.blockWritesOutsideWorkingDirectories를 켜면 Write, Edit, NotebookEdit 도구는 작업 디렉터리 밖에 쓰지 못하지만, 이 설정은 셸 명령과 MCP 도구, 훅이 실행하는 프로그램에는 적용되지 않습니다.

샌드박스는 셸 명령이 파일과 네트워크에 접근하는 범위를 운영체제 수준에서 제한하는 장치입니다. Claude Code 문서는 권한과 샌드박스를 서로 보완하는 두 계층으로 설명합니다. 프롬프트 인젝션으로 Claude의 판단이 우회되더라도 샌드박스 제한은 적용되므로, 두 가지를 함께 쓰라고 권합니다. 셸 명령이 어디에 쓰는지는 샌드박스로 제한해야 한다는 점도 같은 문서에 있습니다.

'에이전트'라는 말도 하네스와 구분하세요. Anthropic의 장기 작업 실험에서 초기화 에이전트와 코딩 에이전트는 첫 사용자 프롬프트만 달랐고, 시스템 프롬프트·도구·하네스는 같았다고 각주에 적혀 있습니다. 같은 글의 각주는 두 에이전트를 따로 부르는 까닭이 첫 사용자 프롬프트가 다르기 때문이라고 설명합니다.

네 부품을 이어 보는 개념 도식#

아래는 역할을 이해하기 위한 도식입니다. Mirr 내부 구현을 역설계한 그림이나 실제 호출 화면은 아닙니다.

사용자 목표와 제약
       ↓
하네스: 관련 맥락과 사용 도구 구성
       ↓
모델: 응답 또는 도구 사용 제안
       ↓
권한 판단 → 허용한 도구 실행 → 결과 확인
       ↑                         ↓
       └──── 필요한 다음 판단 ────┘

사람의 검토: 목표·diff·실제 검사·미실행 항목 대조

권한 판단에서 막힌 행동은 모델의 제안만으로 실행된 것이 아닙니다. 반대로 실행됐다고 결과가 맞는 것도 아닙니다. 역할을 나눠 읽으면 어떤 근거가 부족한지 질문할 수 있습니다.

권한 판단 칸은 Claude Code 권한 문서의 규칙 순서와 함께 읽으면 정확해집니다. 거부 규칙에 걸린 호출은 훅이 'allow'를 돌려줘도 막히고, 질문 규칙에 걸린 호출은 훅이 허용해도 질문이 뜹니다. 훅은 거부나 질문 규칙을 뒤집지 못합니다. '훅이 허용했는데 막혔다'거나 '허용했는데 질문이 떴다'는 경우를 이 순서로 설명할 수 있습니다.

허용한 도구 실행 칸에서 편집 같은 도구는 앞서 본 계약대로 애플리케이션이 실행하고 결과를 돌려줍니다. 결과 확인 칸에 PostToolUse 훅을 둘 수 있지만, 문서는 Edit|Write에 맞춘 PostToolUse 훅이 Bash 명령이나 Claude Code 바깥 프로세스가 같은 파일을 고친 경우에는 실행되지 않는다고 명시합니다. 결과 확인을 훅 하나에 맡기면 이런 빈틈이 생깁니다.

결과 확인이 빠지는 문제는 Anthropic의 장기 작업 실험에서도 나타났습니다. 모델은 종단간 테스트 없이 기능을 완료로 표시하는 경향을 보였고, 브라우저 자동화 도구를 주고 사람처럼 테스트하라고 지시한 뒤에야 숨은 버그를 찾았습니다. 같은 글은 그 도구도 브라우저의 기본 경고창(alert)을 보지 못해 관련 기능에 버그가 남기 쉽다고 밝힙니다.

사람이 끼어드는 승인 단계에서도 하네스가 응답의 전달 경로를 정합니다. 권한 질문에서 '아니요'를 고르고 코멘트를 적으면 그 코멘트는 거부 사유로 Claude에게 전달되고 Claude는 계속 작업합니다. 코멘트 없이 '아니요'만 고르면 메인 대화의 턴이 멈춥니다. '예'를 고르고 코멘트를 달면 명령을 실행한 뒤 코멘트가 결과 다음에 전달됩니다(Claude Code 권한 문서).

같은 저장소와 같은 모델이어도 하네스 설정이 바뀌면 허용 범위가 달라집니다. 승인 모드를 바꾸면 명령 실행과 파일 수정이 허용되는 경계가 바뀌고, 훅에 종료 코드를 연결하면 실패를 사람이 확인하는 흐름이 추가됩니다. 그래서 비교를 오래 유지하려면 어떤 하네스 설정으로 그 과제를 돌렸는지를 결과에 함께 남기는 편이 좋습니다. 설정 이름과 실제 허용 범위 사이의 간극이 크면 그 사실도 기록에 적어 두면 다음 점검에서 다시 확인하기 쉽습니다.

다음에 읽을 것#

Mirr Code의 도구와 권한에서 승인 흐름을, 작업 모드에서 모드별 차이를 확인하세요.

승인 흐름은 Claude Code 권한 문서의 규칙 순서와 권한 모드 설명을 함께 읽으면 정리됩니다. 훅의 종류와 종료 코드별 동작은 훅 참고 문서에서 확인할 수 있습니다. 장기 작업의 실패 유형과 진행 기록 방식은 앞에서 소개한 Anthropic 글에 있습니다.

편집 메모 (2026-11-02): 하네스·도구·서브에이전트의 차이와 오류 진단표를 보충했습니다. 문서 설명을 실제 호출 결과나 성능 비교로 제시하지 않습니다.