클로드 코드(Claude Code) 하네스(Harness) 구조

Claude Code 하네스(Harness) 구조:
에이전트를 자동화 파이프라인으로 구축하기

1. 하네스(Harness) 아키텍처 개요

Claude Code의 하네스 패턴은 LLM 에이전트를 결정론적인 인프라로 감싸는 혁신적인 설계 방식입니다. 단순한 대화형 인터페이스를 넘어, 시스템이 사전에 정의된 규칙과 도구에 따라 움직이도록 설계되었습니다.

• Core Layer: 모델의 기본 대화 컨텍스트가 위치하는 최하단 계층입니다.
• Instruction Layer: CLAUDE.md 등을 통한 장기 메모리와 규칙을 정의합니다.
• Extension Layer: Skills(스킬), Hooks(훅), 서브에이전트 등 실질적인 도구를 확장합니다.
• Orchestration Layer: 여러 에이전트의 팀 워크와 검증 로직을 관리하는 최상위 계층입니다.

2. 디렉토리 구조 및 설정 범위

하네스는 개인 전역 설정(~/.claude/)과 프로젝트 레벨 설정(.claude/)으로 나뉩니다. Claude Code는 현재 위치에서 상위로 디렉토리를 탐색하며 설정을 공유하므로 효율적인 중앙 관리가 가능합니다.

~/.claude/           # 개인 전역 설정
├── CLAUDE.md        # 전역 지침
├── skills/          # 전문 스킬 모듈
├── agents/          # 커스텀 서브에이전트
└── hooks/           # 자동 실행 스크립트

상위 디렉토리에 .claude/를 두는 하네스 레포 패턴을 사용하면 여러 프로젝트가 동일한 스킬셋을 공유할 수 있습니다.

3. 스킬(Skills)과 훅(Hooks)의 활용

하네스 구조의 핵심은 결정론적 실행입니다. 프롬프트는 확률적으로 작동하지만, 훅(Hooks)은 셸 스크립트 기반으로 100% 실행됩니다.

• Skills: 언어 모델의 추론을 통해 특정 상황(예: 코드 리뷰, 보안 감사)에서 자동 활성화되는 전문 지식 모듈입니다.
• Hooks: PreToolUse, PostToolUse 등 22개 라이프사이클에 연결됩니다. exit 2를 통해 보안상 위험한 명령을 실제 블로킹(Blocking) 할 수 있습니다.

예를 들어, AWS 키나 API 토큰이 포함된 명령어를 사전에 차단하는 보안 훅은 안정적인 개발 환경 구축에 필수적입니다.

4. 멀티 에이전트 패턴

단일 에이전트는 자신의 실수를 스스로 잡기 어렵습니다. 하네스 구조는 멀티 에이전트 오케스트레이션을 통해 결과의 신뢰도를 높입니다.

위험하거나 비가역적인 작업이 감지되면 에이전트 A(찬성 논거)와 에이전트 B(반대 논거)가 독립적으로 평가를 진행하고, 최종 합의를 도출하는 과정을 거칩니다. 실험적 기능인 Agent Teams를 활성화하면 에이전트 간의 소통을 통해 복잡한 과제를 수행할 수 있습니다.

5. 5분 퀵스타트 체크리스트

• 보안 훅 설정: block-secrets.sh를 생성하여 시크릿 유출 방지
• 리뷰 스킬 정의: SKILL.md를 작성하여 특정 도메인 지식 주입
• CLAUDE.md 최적화: 프로젝트의 아키텍처 결정 사항을 기록하여 장기 메모리 활용
• 재귀 방지: 무한 에이전트 생성을 막는 recursion-guard.sh 설정

이제 여러분의 프로젝트에 이 구조를 적용하여 더 지능적이고 안전한 개발 자동화를 경험해 보세요.