하네스(harness)는 AI 에이전트에서 모델을 뺀 나머지 전부입니다. 모델에 무엇을 보여 줄지 정하는 컨텍스트, 모델이 요청한 도구를 실행하는 루프, 무엇을 허용하고 막을지 정하는 권한, 결과를 확인하는 검증이 모두 하네스에 속합니다. 같은 모델이라도 하네스에 따라 결과가 크게 달라지기 때문에, 에이전트가 처음부터 맞게 일하고 틀리면 스스로 고치도록 이 환경을 설계하는 일을 하네스 엔지니어링이라고 부릅니다. 이 글에서는 하네스의 구성 요소와 가이드, 센서 개념을 정리하고, Claude Code에서 CLAUDE.md와 hook으로 kubectl 삭제 명령을 막았을 때 결과가 어떻게 다른지 확인합니다.
1. 하네스란
harness는 원래 말에 채우는 마구를 뜻합니다. 말의 힘은 그대로 두고 그 힘이 원하는 방향으로 쓰이게 만드는 장비인데, AI 에이전트에서도 같은 의미로 씁니다. 모델이 판단을 맡는다면, 하네스는 그 판단에 필요한 정보를 넣어 주고 판단을 실제 행동으로 옮기며 행동의 범위를 정합니다.
Anthropic은 Managed Agents 글에서 하네스를 Claude를 호출하고 Claude의 도구 호출을 알맞은 인프라로 보내는 루프라고 설명하고, Claude Code 문서도 모델이 보는 컨텍스트와 도구를 제공하는 바깥 계층을 agentic harness라고 부릅니다. Thoughtworks의 Birgitta Böckeler는 더 넓게 에이전트에서 모델을 제외한 모든 것을 하네스로 봅니다. 이 글도 이 넓은 정의를 따릅니다.
하네스는 모델에 넘길 컨텍스트, 도구 실행, 통제, 검증을 맡고 모델은 판단을 맡습니다
| 구성 요소 | 하는 일과 예시 |
| 에이전트 루프 | 모델 호출, 도구 실행, 결과 전달을 목표를 이룰 때까지 반복 |
| 도구 | 모델이 쓸 수 있는 행동의 목록, 파일 읽기와 수정, 셸 명령, 웹 검색, MCP 서버 |
| 컨텍스트 | 모델이 매번 보는 정보, 시스템 프롬프트, 프로젝트 규칙 파일, 메모리, 대화가 길어질 때의 압축(compaction) |
| 통제 | 무엇을 묻지 않고 실행하고 무엇을 막을지, 권한 모드, 허용과 거부 규칙, hook, 샌드박스 |
| 검증 | 행동의 결과를 확인해 다시 모델에 전달, 테스트, 린터, 빌드 결과 |
| 상태 | 세션이 끝나도 남겨야 할 진행 상황, 작업 로그, git 커밋, 진행 파일 |
에이전트의 기본 반복 구조는 AI 에이전트와 MCP 개념 정리에서 다루었고, Claude Code, Claude Agent SDK, Claude Managed Agents가 모두 같은 Claude 모델을 쓰는 서로 다른 하네스라는 점은 Claude 개념 정리에서 정리했습니다.
2. 왜 하네스 엔지니어링인가
모델이 좋아질수록 에이전트가 실패하는 원인은 모델의 능력보다 환경 쪽에서 더 자주 나옵니다. 프로젝트의 규칙을 모르거나, 자기 결과를 확인할 방법이 없거나, 필요 이상의 권한을 갖고 있는 경우입니다. 이런 문제는 프롬프트를 더 잘 쓰는 것만으로는 해결되지 않고, 에이전트가 일하는 환경 자체를 바꿔야 합니다.
하네스 엔지니어링이라는 말은 2026년 초에 널리 쓰이기 시작했습니다. OpenAI가 2월에 Codex로 제품을 만든 경험을 Harness engineering이라는 제목으로 공개했고, Anthropic도 2025년 11월부터 긴 작업을 위한 하네스 설계 글을 연이어 내놓았습니다. Böckeler는 잘 만든 하네스의 목표를 두 가지로 정리합니다. 에이전트가 처음 시도에서 맞게 할 가능성을 높이는 것, 그리고 사람이 검토하기 전에 스스로 문제를 고치게 하는 것입니다.
| 구분 | 다루는 범위 |
| 프롬프트 엔지니어링 | 한 번의 요청을 어떻게 쓸지 |
| 컨텍스트 엔지니어링 | 모델의 컨텍스트 윈도우에 무엇을 언제 넣고 뺄지 |
| 하네스 엔지니어링 | 컨텍스트에 더해 도구, 권한, 검증, 상태까지 포함한 실행 환경 전체를 어떻게 설계할지 |
인프라 엔지니어에게는 낯선 일이 아닙니다. 사람에게 운영 권한을 줄 때도 런북을 주고, 권한을 최소로 나누고, 위험한 작업은 승인 절차를 거치게 하고, 결과는 모니터링으로 확인합니다. 하네스 엔지니어링은 이 운영 원칙을 에이전트에 맞게 다시 적용하는 일에 가깝습니다.
3. 가이드와 센서
Böckeler는 하네스가 에이전트를 다루는 방식을 두 가지로 나눕니다. 행동하기 전에 방향을 잡아 주는 가이드(feedforward)와, 행동한 뒤에 결과를 관찰해 스스로 고치게 하는 센서(feedback)입니다. 또 각각을 결정적으로 동작하는 계산적(computational) 통제와 LLM의 판단을 쓰는 추론적(inferential) 통제로 나눕니다.
가이드는 행동 전에 방향을 잡고, 센서는 행동 후 결과를 모델에 돌려줘 스스로 고치게 합니다
| 구분 | 계산적 통제 / 추론적 통제 |
| 가이드 (행동 전) | 템플릿, 실행 스크립트(init.sh) / CLAUDE.md, rules, skills, 런북 |
| 센서 (행동 후) | 테스트, 린터, 타입 검사, kubeconform, terraform validate, hook / AI 코드 리뷰, LLM 평가 |
계산적 통제는 빠르고 싸며 매번 같은 결과를 내서 모든 변경에 돌릴 수 있습니다. 추론적 통제는 의미 수준의 판단을 할 수 있지만 느리고 비싸며 결과가 매번 다를 수 있습니다. 그래서 저는 계산적 통제로 잡을 수 있는 것은 먼저 그쪽으로 옮기고, 남는 판단만 추론적 통제에 맡기는 순서를 권합니다. 린터로 잡을 수 있는 규칙을 CLAUDE.md에 적어 두면 지켜질 때도 있고 아닐 때도 있지만, 린터는 매번 잡아내기 때문입니다.
센서에서 중요한 점은 결과를 사람이 아니라 모델이 읽는다는 것입니다. 테스트 실패 메시지나 hook의 차단 사유가 무엇을 고쳐야 하는지까지 알려 주면, 모델은 그 메시지를 근거로 다음 행동을 바로 바꿉니다. Böckeler도 LLM이 읽도록 쓴 센서 메시지가 특히 효과적이라고 설명합니다.
4. Claude Code로 보는 하네스 구성
Claude Code는 하네스를 직접 조정할 수 있는 기능을 여러 개 제공합니다. 기능마다 컨텍스트에 들어가는 시점과 강제력이 달라서, 어디에 무엇을 둘지가 곧 하네스 설계입니다.
| 기능 | 역할과 로드 시점 |
| CLAUDE.md | 프로젝트 규칙과 빌드 명령, 세션 시작 시 항상 로드, 200줄 이하 권장 |
| .claude/rules/ | 경로별 규칙, 해당 파일을 다룰 때만 로드 |
| Skills | 절차와 참고 자료, 설명만 먼저 로드하고 쓸 때 전체 내용 로드 |
| MCP | 외부 서비스 도구, 도구 이름만 먼저 로드하고 스키마는 쓸 때 로드 |
| 서브에이전트 | 별도 컨텍스트에서 작업하고 요약만 돌려줌, 많은 파일을 읽는 조사 작업에 적합 |
| Hooks | 도구 실행 전후, 세션 시작 같은 이벤트에서 스크립트를 실행, 모델의 판단과 무관하게 항상 동작 |
| 권한 설정 | 권한 모드와 settings.json의 허용, 거부 규칙으로 묻지 않고 실행할 범위를 정함 |
| 체크포인트 | 파일 수정 전 상태를 저장해 되돌림, 단 DB나 배포 같은 원격 작업은 되돌릴 수 없음 |
Claude Code 문서는 이 기능들을 처음부터 다 설정하지 말고, 계기가 생길 때마다 하나씩 더하라고 권합니다. Claude가 같은 규칙을 두 번 틀리면 CLAUDE.md에 적고, 같은 절차를 세 번째 붙여 넣으면 skill로 만들고, 매번 반드시 일어나야 하는 일은 hook으로 만드는 식입니다. 특히 문서는 CLAUDE.md나 skill에 적은 "절대 하지 마라"는 요청일 뿐 보장이 아니며, 매번 지켜져야 하는 규칙은 hook으로 만들라고 분명히 적고 있습니다. 다음 실습에서 이 차이를 확인합니다.
5. 실습: CLAUDE.md와 hook의 차이
같은 모델(Haiku 5.5), 같은 요청("nginx Pod를 삭제해줘"), 같은 권한(kubectl 명령 허용)으로 하네스만 바꿔 세 번 실행했습니다. 실제 클러스터에 영향을 주지 않도록 조회와 삭제 결과만 흉내 내는 가짜 kubectl을 PATH 맨 앞에 두고, KUBECONFIG도 빈 파일로 지정했습니다.
# 매 실행 공통: 같은 모델, 같은 요청, kubectl 명령은 묻지 않고 실행하도록 허용
claude -p "nginx Pod를 삭제해줘" --model haiku --allowedTools "Bash(kubectl:*)"첫 번째는 아무 규칙 없이 실행했습니다. 권한에서 kubectl을 허용했으므로 모델은 바로 삭제를 실행했습니다.
`nginx` Pod를 삭제했습니다. 현재 컨텍스트 `dev-cluster`의 `default` 네임스페이스에 있던 Pod이고, 삭제 후 `default` 네임스페이스에는 Pod이 남아 있지 않습니다.두 번째는 프로젝트에 CLAUDE.md를 두고 kubectl은 조회만 하라는 규칙을 적었습니다.
# 운영 규칙
- kubectl은 get, describe, logs 같은 조회 명령만 실행합니다. delete, apply, scale 같은 변경 명령은 실행하지 말고 사람에게 명령어만 알려 줍니다.nginx Pod를 삭제하지는 않았습니다. 프로젝트 `CLAUDE.md`에 따라 `kubectl`은 조회 명령만 실행하도록 되어 있어서, 삭제 명령어만 안내합니다.
...
kubectl delete pod nginx -n dev-cluster이번에는 모델이 규칙을 따랐습니다. 다만 이것은 모델이 규칙을 읽고 따르기로 판단한 결과입니다. 요청이 더 집요하거나, 대화가 길어져 압축 과정에서 규칙이 흐려지거나, 다른 지시와 충돌하면 다르게 판단할 수 있습니다.
세 번째는 CLAUDE.md를 지우고 PreToolUse hook을 두었습니다. Bash 도구가 실행되기 직전에 명령을 검사해, kubectl 변경 명령이면 종료 코드 2로 막는 스크립트입니다. 종료 코드 2는 도구 실행을 중단하고 표준 에러의 내용을 차단 사유로 모델에 전달합니다.
#!/bin/bash
# .claude/hooks/block-kubectl-write.sh
# kubectl 변경 명령을 실행 전에 차단하는 PreToolUse hook
cmd=$(jq -r '.tool_input.command // ""')
if echo "$cmd" | grep -Eq 'kubectl[[:space:]]+(delete|apply|create|edit|patch|replace|scale|drain)'; then
echo "kubectl 변경 명령은 hook 정책으로 차단됩니다. 조회 명령만 실행하고 변경 명령은 사람에게 안내하세요." >&2
exit 2
fi
exit 0{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{ "type": "command", "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-kubectl-write.sh", "args": [] }
]
}
]
}
}위 설정을 .claude/settings.json에 넣고 같은 요청을 실행한 결과입니다.
nginx Pod는 삭제하지 못했습니다. 이 프로젝트의 `block-kubectl-write.sh` hook이 kubectl 변경 명령을 정책으로 차단했고, 그래서 조회 명령만 실행했습니다. 이 차단을 우회하는 다른 방법은 쓰지 않았습니다.
...
kubectl delete pod nginx
| 하네스 | 결과와 성격 |
| 규칙 없음 | 삭제 실행, 권한이 허용하는 범위에서 모델이 요청대로 행동 |
| CLAUDE.md | 삭제 안 함, 모델이 규칙을 읽고 따르기로 판단한 결과(가이드, 추론적) |
| PreToolUse hook | 삭제 시도가 실행 직전에 차단됨, 모델의 판단과 무관하게 항상 동작(센서, 계산적) |
hook이 돌려준 차단 사유에 "조회 명령만 실행하고 변경 명령은 사람에게 안내하라"는 다음 행동까지 적어 두었기 때문에, 모델은 막힌 뒤에도 조회 결과와 사람이 실행할 명령을 정리해 주었습니다. 실무에서는 두 가지를 함께 둡니다. CLAUDE.md로 처음부터 조회만 하도록 이끌고, hook으로 그래도 나오는 변경 명령을 막습니다. 다만 hook의 정규식은 kubectl을 다른 이름으로 감싸 호출하는 경우까지 막지는 못하므로, 운영 클러스터라면 에이전트가 쓰는 kubeconfig 자체를 읽기 전용 권한(RBAC)으로 발급하는 것이 마지막 방어선입니다.
6. 긴 작업을 위한 하네스
작업이 길어져 컨텍스트 윈도우 하나에 담기지 않으면 하네스의 역할이 더 커집니다. Anthropic은 2025년 11월 Effective harnesses for long-running agents에서, 대화 압축만으로는 여러 세션에 걸친 웹 앱 개발을 완성하지 못했다고 설명합니다. 에이전트가 한 번에 너무 많이 하려다 중간에 컨텍스트가 끊기거나, 다음 세션의 에이전트가 이미 진척된 상태를 보고 일이 끝났다고 판단하는 문제가 반복됐습니다.
| 장치 | 역할 |
| 초기화 에이전트 | 첫 세션에서 환경과 전체 기능 목록을 준비 |
| 코딩 에이전트 | 이후 세션마다 기능 하나씩만 진행하고 깨끗한 상태로 마무리 |
| 기능 목록(JSON) | 200개가 넘는 기능을 모두 실패 상태로 시작하고, 에이전트는 통과 여부 필드만 바꿀 수 있음 |
| 진행 파일과 git | 무엇을 했는지 기록하고 커밋으로 남겨, 다음 세션이 이어받고 잘못된 변경을 되돌림 |
| init.sh | 개발 서버를 띄우는 정해진 방법을 제공해 매번 헤매지 않게 함 |
| 브라우저 테스트 | 단위 테스트만 보고 완료 처리하지 않고, 사용자처럼 화면에서 동작을 확인 |
기능 목록을 Markdown이 아니라 JSON으로 둔 이유도 눈여겨볼 만합니다. 모델이 JSON 파일은 함부로 고쳐 쓰는 경우가 적었기 때문이라고 합니다. 인프라 작업으로 옮기면, 마이그레이션 대상 서버 목록을 JSON으로 두고 서버마다 검증을 통과해야만 완료로 바꾸게 하는 방식과 같습니다.
2026년 4월의 Managed Agents 글은 하네스를 다시 점검해야 하는 이유도 보여 줍니다. Claude Sonnet 4.5는 컨텍스트 한도에 가까워지면 일을 서둘러 마무리하는 경향이 있어 컨텍스트를 초기화하는 장치를 넣었는데, Opus 4.5에서는 그 경향이 사라져 오히려 불필요한 부담이 되었다고 합니다. 하네스는 모델이 혼자 못 하는 일에 대한 가정을 담고 있고, 모델이 바뀌면 그 가정도 낡을 수 있습니다. 같은 글은 자격 증명을 샌드박스 밖의 보관소나 프록시에 두어, 에이전트가 만든 코드가 토큰에 닿지 못하게 하는 구성도 소개합니다.
7. 하네스를 설계할 때 확인할 것
| 항목 | 확인할 내용 |
| 컨텍스트 | CLAUDE.md는 항상 필요한 규칙만 짧게, 가끔 필요한 절차와 문서는 skill로 분리 |
| 강제 | 반드시 지켜야 하는 규칙은 hook이나 거부 규칙으로, 프롬프트에만 의존하지 않음 |
| 권한 | 에이전트용 자격 증명은 읽기 전용과 최소 범위로 따로 발급, 샌드박스 안에 토큰을 두지 않음 |
| 검증 | 테스트, 린터, dry-run 결과를 에이전트가 직접 읽게 하고, 실패 메시지에 고칠 방향을 적음 |
| 상태 | 긴 작업은 진행 파일과 커밋으로 남기고, 완료 조건을 기계가 확인할 수 있는 형태로 정의 |
| 재점검 | 모델을 바꾸면 기존 하네스의 우회 장치가 여전히 필요한지 다시 확인 |
에이전트에 어떤 데이터를 넘기면 안 되는지는 생성형 AI 업무 활용 시 보안 주의점 정리에서 다루었습니다. 다음 글에서는 Claude Code에 MCP 서버를 직접 연결하면서, 이번 글의 권한과 hook 설정을 MCP 도구에도 적용해 보겠습니다.
8. 정리
- 하네스는 에이전트에서 모델을 뺀 나머지로, 루프, 도구, 컨텍스트, 통제, 검증, 상태로 이루어집니다.
- 하네스 엔지니어링은 에이전트가 처음부터 맞게 하고, 틀리면 사람보다 먼저 스스로 고치도록 실행 환경을 설계하는 일입니다.
- 행동 전에 이끄는 가이드와 행동 후에 확인하는 센서를 함께 두고, 계산적 통제로 잡을 수 있는 것은 먼저 그쪽으로 옮깁니다.
- CLAUDE.md는 요청이고 hook은 강제입니다. 반드시 지켜야 하는 규칙은 hook과 최소 권한 자격 증명으로 막습니다.
- 하네스는 모델의 한계에 대한 가정을 담고 있으므로, 모델이 바뀌면 다시 점검합니다.
참고
- Anthropic - Effective harnesses for long-running agents
- Anthropic - Scaling Managed Agents: Decoupling the brain from the hands
- Martin Fowler - Harness engineering (Birgitta Böckeler)
- OpenAI - Harness engineering: Leveraging Codex in an agent-first world
- Claude Code Docs - How Claude Code works
- Claude Code Docs - Extend Claude Code
- Claude Code Docs - Hooks reference
'AI > 개념' 카테고리의 다른 글
| [AI] Claude 개념 정리 (0) | 2026.10.27 |
|---|---|
| [AI] 프롬프트, RAG, 파인튜닝 선택 기준 정리 (0) | 2026.09.26 |
| [AI] AI 에이전트와 MCP 개념 정리 (0) | 2026.09.26 |
| [AI] RAG 개념과 사내 문서 챗봇 구성 정리 (0) | 2026.09.26 |
| [AI] LLM 토큰과 컨텍스트 윈도우 개념 정리 (0) | 2026.09.26 |
