에이전트 하네스

https://code.claude.com/docs/ko/how-claude-code-works

Claude Code의 작동 방식 - Claude Code Docs

 

 

클로드 코드(Claude Code)를 설명할 때 등장하는 '에이전트 하네스(Agent Harness)'라는 표현은 공학적 비유가 담긴 아주 핵심적인 용어입니다. 쉽게 풀이해 드릴게요! 🛠️

 

1. '하네스(Harness)'의 본래 의미 🐕🏎️

보통 하네스라고 하면 여러 개의 전선(케이블)을 하나로 묶어 정리 하는 작업을 의미합니다.

공학적으로는 '어떤 핵심 부품이 외부 환경과 잘 연결되어 제 기능을 발휘하도록 감싸는 연결 장치나 골격'을 의미합니다.

 

2. 에이전트 하네스란? (Claude Code의 관점) 🤖🔗

Claude라는 강력한 '두뇌(모델)'가 실제 개발 환경(터미널, 파일 시스템)이라는 '현장'에서 직접 팔다리를 휘두를 수 있도록 입혀준 '슈트'라고 이해하시면 됩니다.

구체적으로 다음과 같은 역할을 수행하기 때문에 하네스라고 부릅니다.

✅ 연결 통로 (Interface)

AI 모델은 원래 텍스트만 주고받을 수 있는 존재입니다. 하네스(Claude Code)는 이 모델이 실제 PC의 파일을 읽고, 명령어를 실행하고, 네트워크에 접속할 수 있도록 길을 열어주는 인터페이스 역할을 합니다.

✅ 제어 및 안전 (Control & Safety)

모델이 멋대로 시스템을 파괴하지 않도록 통제합니다. 사용자의 승인을 확인하거나, 위험한 명령을 필터링하는 등의 '안전 고리' 역할을 수행합니다.

✅ 도구 장착 (Tooling)

Claude에게 ls, grep, vi 같은 도구를 쥐여주고 사용하는 법을 가르칩니다. 모델이 "파일 목록 좀 보여줘"라고 하면, 하네스가 실제로 터미널 명령을 수행해 그 결과를 다시 모델의 눈(입력창) 앞에 가져다줍니다.

 

3. 왜 ClaudeCode를 Claude '주변'의 하네스라고 하나요? 🌐

Claude라는 엔진은 클라우드(Anthropic 서버)에서 실행되고 있습니다. 하지만 Claude Code는 여러분의 로컬 터미널에 설치되죠.

즉, 중앙의 두뇌(Claude)가 내 로컬 PC라는 실제 세상에 손을 뻗어 작업을 수행할 수 있도록, 그 주변을 감싸서 연결해 주는 '현장 요원용 장비'가 바로 Claude Code인 것입니다.

 

💡 요약하자면!

"Claude(두뇌)가 개발 현장(로컬 환경)에서 직접 도구를 휘두르며 일할 수 있도록 연결하고 보조하는 강화 슈트"

라고 이해하시면 가장 정확합니다. Claude Code가 이 하네스 역할을 하기 때문에, 우리는 단순히 채팅만 하는 게 아니라 실무적인 '대리인(Agent)'으로서 Claude를 부릴 수 있게 되는 것이죠! 😎✨