이 글은 AI Harness 시리즈 10/12화입니다. 지난 9화에서 40줄 미니 하니스를 직접 만들어 보았다면, 이번에는 2026년 가장 성숙한 프로덕션 하니스의 내부를 열어봅니다.

40줄에서 프로덕션까지 — 왜 Claude Code를 해부하는가

9화에서 우리는 40줄짜리 미니 하니스를 직접 만들었습니다. LLM을 호출하고, 도구를 실행하고, 결과를 돌려주는 최소한의 루프였죠. 그런데 그 40줄로 실제 프로덕션 업무를 맡기면 어떻게 될까요? 대형 코드베이스에서 멀티파일 리팩터링을 시키면 컨텍스트가 넘치고, 실수로 파일을 날리고, 같은 실패를 무한 반복합니다. 미니 하니스에는 OS가 없는 베어메탈 CPU와 같은 한계가 있기 때문입니다.

이번 화에서 해부할 대상은 Claude Code입니다. Anthropic이 만든 이 CLI 기반 에이전트 코딩 도구는, 시리즈 4~8화에서 다룬 6대 하니스 컴포넌트를 모두 구현한 현존하는 가장 잘 문서화된 프로덕션 하니스입니다. 시스템 프롬프트가 커뮤니티에 의해 공개 분석되었고, 벤치마크 데이터가 풍부하며, 설계 철학이 명확히 드러나 있습니다.

해부의 목적은 단순한 제품 리뷰가 아닙니다. Claude Code라는 하나의 성숙한 표본에서 프로덕션 하니스 설계의 반복 가능한 패턴을 추출하는 것 — 이것이 이번 화의 핵심입니다.

1차 자료: Anthropic “Building Effective Agents”가 그린 설계도

2024년 12월, Anthropic의 Erik Schluntz와 Barry Zhang은 “Building Effective Agents”라는 가이드를 공개했습니다. 이 문서는 에이전트 시스템을 두 축으로 분류합니다:

• Workflows — 코드로 미리 정해놓은 오케스트레이션. 프롬프트 체이닝, 라우팅, 병렬화 등.
• Agents — 모델이 스스로 다음 행동을 결정하는 루프. 도구 선택, 실행 순서, 중단 판단을 모델에게 위임.

그리고 핵심 조언을 남깁니다: “가장 단순한 솔루션으로 시작하고, 필요할 때만 복잡성을 추가하라.” 흥미로운 점은 이 가이드가 공개된 직후 출시된 Claude Code가 정확히 이 원칙의 구현체(reference implementation)라는 사실입니다. Workflow 패턴이 아닌 순수 Agent 루프를 채택하면서도, 하니스 레이어로 안전성과 효율을 확보한 것이죠.

한국어 기술 커뮤니티에서 “Building Effective Agents”는 주로 프롬프트 체이닝과 RAG 패턴 위주로 인용되어 왔습니다. 그러나 이 문서의 진짜 가치는 Agent 루프를 프로덕션에 올릴 때 필요한 하니스 패턴의 분류 체계에 있습니다. Claude Code는 그 분류 체계의 “Agents” 항목 아래에서, 6대 컴포넌트를 모두 갖춘 Full-stack Harness로 존재합니다.

시스템 프롬프트 해부 — 하니스의 DNA가 담긴 텍스트

Claude Code의 아키텍처를 이해하려면 시스템 프롬프트부터 봐야 합니다. 2025년 이후 커뮤니티에 의해 공개 분석된 Claude Code의 시스템 프롬프트는 약 4,000~6,000 토큰 규모로, 다음과 같은 구조를 가집니다:

• 역할 정의 — “당신은 소프트웨어 엔지니어링 작업을 돕는 인터랙티브 에이전트입니다”
• 도구 사용 규칙 — “전용 도구가 있으면 Bash 대신 전용 도구를 쓰라”
• 안전 제약 — “되돌리기 어려운 작업은 사용자에게 먼저 확인하라”
• 워크플로 패턴 — “읽지 않은 코드를 수정하지 말라”, “가장 단순한 접근부터 시도하라”
• 출력 규칙 — “간결하게, 핵심부터, 필러 워드 없이”

이 시스템 프롬프트는 단순한 “성격 설정”이 아닙니다. 하니스 관점에서 보면, 이것은 운영체제의 커널 설정 파일에 해당합니다. CPU(LLM)가 어떤 시스템콜(도구)을 어떤 조건에서 호출할 수 있는지, 메모리(컨텍스트)를 어떻게 관리할지, 프로세스(작업)의 우선순위를 어떻게 잡을지를 정의하는 것이죠.

CLAUDE.md — 프로젝트별 커널 모듈

시스템 프롬프트가 OS 커널이라면, CLAUDE.md는 커널 모듈(loadable kernel module)입니다. Claude Code는 프로젝트 루트의 CLAUDE.md 파일을 자동으로 읽어 컨텍스트에 주입합니다. 이 파일에는 프로젝트 고유의 규칙, 아키텍처 결정, 금지 사항, 워크플로 지침이 담깁니다.

실제로 잘 작성된 CLAUDE.md는 다음을 포함합니다:

• 프로젝트 한 줄 소개와 기술 스택
• 디렉토리 구조와 각 모듈의 역할
• 절대 금지 사항 (특정 라이브러리 사용 금지, 특정 API 호출 금지 등)
• 브랜치 전략과 커밋 메시지 규칙
• 보안 요구사항과 환경별 설정 차이

이 계층 구조가 중요한 이유는 컨텍스트 효율 때문입니다. 시스템 프롬프트에 모든 프로젝트의 규칙을 넣으면 토큰이 낭비됩니다. CLAUDE.md로 분리하면, 해당 프로젝트에서 작업할 때만 관련 규칙이 로드됩니다. 4화에서 다룬 프로그레시브 로딩의 정확한 구현입니다.

여기에 더해 Claude Code는 자동 메모리 디렉토리까지 지원합니다. 사용자의 홈 디렉토리에 프로젝트별 메모리 파일을 영속 저장하여, 세션이 바뀌어도 이전 작업의 패턴과 결정을 기억합니다. 이것은 6화에서 다룬 장기 기억(Long-term Memory)의 실제 구현입니다.

6대 컴포넌트 완전 매핑 — Claude Code 내부 설계 전개

4~8화에서 하나씩 해부한 6대 하니스 컴포넌트를 Claude Code에 매핑하겠습니다. 이론이 실전에서 어떻게 구현되는지를 확인하는 시간입니다.

컴포넌트 1: 컨텍스트 엔지니어링 — 토큰 한 방울도 아까운 OS

4화에서 “토큰은 한정 자원”이라고 했습니다. Claude Code는 이 원칙을 세 가지 메커니즘으로 실현합니다.

첫째, 자동 압축(Auto-compaction). 대화가 컨텍스트 한계에 접근하면, Claude Code는 오래된 메시지를 자동으로 요약·압축합니다. 시스템 프롬프트에 이렇게 명시되어 있죠: “시스템이 컨텍스트 한계에 접근하면 이전 메시지를 자동으로 압축합니다. 이는 대화가 컨텍스트 윈도우에 제한되지 않는다는 뜻입니다.” OS의 가상 메모리 스왑과 정확히 같은 패턴입니다. 물리 RAM(컨텍스트 윈도우)이 부족하면 오래된 페이지(메시지)를 디스크(요약)로 내리고, 새 데이터를 위한 공간을 확보합니다.

둘째, 선택적 파일 로딩. Claude Code의 시스템 프롬프트에는 이런 규칙이 있습니다: “읽지 않은 코드에 대해 변경을 제안하지 마라.” 이 규칙의 이면에는 중요한 설계 결정이 있습니다 — 코드베이스 전체를 미리 컨텍스트에 넣지 않겠다는 것입니다. 필요한 파일만 그때그때 Read 도구로 읽어 들이는 on-demand 로딩입니다. 4화에서 설명한 프로그레시브 로딩의 교과서적 사례죠.

셋째, 서브에이전트를 통한 컨텍스트 격리. Claude Code에는 Agent라는 특수 도구가 있습니다. 복잡한 코드베이스 탐색이 필요할 때, 메인 에이전트가 직접 수십 개 파일을 읽는 대신, 탐색 전용 서브에이전트를 띄워 조사를 위임합니다. 서브에이전트의 컨텍스트는 메인 컨텍스트와 격리되어 있으므로, 탐색 과정에서 발생하는 “잡음”이 메인 컨텍스트를 오염시키지 않습니다. 결과만 요약되어 돌아옵니다.

이 세 가지가 합쳐지면 놀라운 토큰 효율이 나옵니다. 같은 작업을 수행할 때 Claude Code는 평균 33K 토큰을 사용하는 반면, Cursor는 188K 토큰을 소비합니다 — 5.5배 차이. 같은 CPU를 쓰면서 한쪽은 RAM을 5.5배 더 먹는다면, 그것은 OS(하니스)의 메모리 관리 성능 차이입니다.

컴포넌트 2: 도구 인터페이스 — “Bash 대신 전용 도구를 써라”

5화에서 다룬 도구 인터페이스 설계에서 가장 중요한 원칙은 도구의 의미적 명확성이었습니다. Claude Code는 이 원칙을 극단적으로 밀어붙입니다.

Claude Code에 내장된 핵심 도구는 다음 7종입니다:

• Read — 파일 읽기 (cat, head, tail 대체)
• Write — 파일 생성 (cat heredoc, echo 대체)
• Edit — 파일 수정 (sed, awk 대체)
• Glob — 파일 검색 (find, ls 대체)
• Grep — 내용 검색 (grep, rg 대체)
• Bash — 시스템 명령 실행 (최후의 수단)
• Agent — 서브에이전트 위임 (탐색 전문)

여기서 주목할 점은 Bash가 최후의 수단이라는 설계 결정입니다. 시스템 프롬프트는 이렇게 명시합니다: “전용 도구가 있을 때 Bash를 쓰지 마라. 전용 도구를 사용하면 사용자가 작업을 더 잘 이해하고 검토할 수 있다.”

왜 이런 설계를 했을까요? 세 가지 이유가 있습니다:

첫째, 관찰 가능성(observability). Edit 도구는 “어떤 파일의 어떤 줄을 어떻게 바꿨는가”를 구조화된 형태로 보여줍니다. 반면 bash -c "sed -i 's/foo/bar/g' file.py"는 실행 결과를 보기 전까지 무엇이 바뀌었는지 알 수 없습니다. 8화에서 강조한 센서·관찰성의 직접적 구현입니다.

둘째, 안전성. 전용 도구는 제한된 인터페이스를 가집니다. Edit 도구로는 파일을 삭제할 수 없고, Read 도구로는 파일을 수정할 수 없습니다. 반면 Bash는 rm -rf /도 실행할 수 있죠. 도구 분리는 곧 최소 권한 원칙(principle of least privilege)의 구현입니다.

셋째, LLM 성능 최적화. 모델은 “Read로 파일 읽기”를 “bash로 cat 실행 후 출력 파싱”보다 더 정확하게 수행합니다. 도구의 의미가 명확할수록 모델의 도구 선택 정확도가 올라갑니다. 5화에서 “도구 docstring이 곧 성능”이라고 한 원칙의 실증입니다.

그리고 Claude Code는 병렬 도구 호출을 적극 활용합니다. 시스템 프롬프트에 “독립적인 도구 호출은 병렬로 수행하라”고 명시되어 있습니다. 예를 들어 세 개의 파일을 읽어야 한다면, 세 번의 Read를 한 번에 호출합니다. OS의 비동기 I/O 멀티플렉싱과 같은 패턴이죠.

외부 도구 확장은 MCP(Model Context Protocol)를 통해 이루어집니다. 5화에서 설명했듯 MCP는 에이전트를 도구의 클라이언트로 만드는 표준입니다. Claude Code는 MCP 서버를 설정하면 외부 도구(GitHub, Slack, 데이터베이스 등)를 네이티브 도구처럼 사용할 수 있습니다. 내장 7종 + MCP 확장 — 이것이 Claude Code의 도구 생태계입니다.

컴포넌트 3: 메모리 아키텍처 — 세 계층이 실제로 돌아가는 모습

6화에서 Working Memory / Session Memory / Long-term Memory의 3계층을 설명했습니다. Claude Code는 이 세 계층을 구체적인 메커니즘으로 매핑합니다.

Working Memory = 현재 대화 컨텍스트. 사용자와 주고받는 메시지, 도구 호출 결과, 시스템 프롬프트가 모두 여기에 존재합니다. 앞서 설명한 자동 압축(auto-compaction)이 이 계층을 관리합니다. 물리 RAM과 스왑의 관계 그대로입니다.

Session Memory = CLAUDE.md + Git 상태. 프로젝트의 규칙과 맥락을 담은 CLAUDE.md는 세션이 시작될 때 자동으로 컨텍스트에 주입됩니다. 또한 Claude Code는 세션 시작 시 git status를 자동으로 읽어 현재 브랜치, 변경된 파일, 최근 커밋 등의 상태를 인식합니다. 이것은 6화에서 말한 “프로젝트 작업 기억”의 실체입니다.

Long-term Memory = 자동 메모리 디렉토리. Claude Code는 사용자의 홈 디렉토리 내에 프로젝트별 메모리 파일을 유지합니다. 세션 간에 영속되며, 다음과 같은 정보가 저장됩니다:

• 여러 세션에서 확인된 안정적인 패턴과 규칙
• 핵심 아키텍처 결정사항과 중요 파일 경로
• 사용자의 작업 스타일과 선호도
• 반복되는 문제의 해결 방법과 디버깅 인사이트

특히 인상적인 것은 메모리 품질 관리 규칙입니다. “중복 메모리를 쓰지 말 것”, “한 파일만 보고 추측한 결론은 저장하지 말 것”, “사용자가 교정한 내용은 즉시 수정할 것” — 이 규칙들은 6화에서 강조한 메모리 부패(memory corruption) 방지 전략의 실제 구현입니다. OS가 메모리를 쓸 때 체크섬으로 무결성을 검증하듯, Claude Code의 메모리 시스템도 정보의 신뢰도를 검증하는 가드레일을 내장하고 있습니다.

컴포넌트 4: 컨트롤 루프 — “무한 재시도 하지 마라”

7화에서 다룬 에이전트 루프(Agent Loop)와 랄프 루프(Ralph Loop)를 Claude Code에서 찾아봅시다.

에이전트 루프의 기본 구조:

1. 사용자 입력(또는 이전 도구 결과) 수신
2. 컨텍스트 기반 추론
3. 도구 호출 결정 (또는 최종 응답 결정)
4. 도구 실행 + 결과 수집
5. 결과를 컨텍스트에 추가
6. 1로 돌아감

여기까지는 9화의 미니 하니스와 같습니다. 차이는 예외 처리 철학에 있습니다.

Claude Code의 시스템 프롬프트에는 7화에서 설명한 복구 전략이 그대로 녹아 있습니다: “접근이 막히면 무차별 돌파를 시도하지 마라. 예를 들어 API 호출이나 테스트가 실패하면, 같은 동작을 반복 재시도하지 말고, 대안적 접근이나 다른 방법을 고려하라.”

이것은 단순한 조언이 아니라, 7화에서 설명한 컨텍스트 불안(Context Anxiety)에 대한 아키텍처 수준의 대응입니다. 에이전트가 실패에 빠지면 같은 시도를 반복하면서 토큰을 소진하는 경향이 있습니다. Claude Code는 이 패턴을 시스템 프롬프트 레벨에서 차단합니다.

서브에이전트 위임 패턴도 컨트롤 루프의 핵심입니다. Claude Code는 두 가지 모드의 탐색을 구분합니다:

• 직접 탐색(Direct Search) — 특정 파일이나 함수를 찾을 때는 Glob, Grep 도구를 직접 사용
• 깊은 탐색(Deep Exploration) — 코드베이스 전체를 이해해야 할 때는 Agent(Explore) 서브에이전트에 위임

시스템 프롬프트는 이렇게 구분합니다: “단순하고 방향성 있는 검색에는 Glob이나 Grep을 직접 사용하라. 넓은 코드베이스 탐색과 깊은 연구에는 Explore 서브에이전트를 사용하라. 단순 검색이 3회 이상 필요할 것이 명확한 경우에만 서브에이전트를 쓰라.”

이 설계는 OS에서 경량 시스템 호출(stat, readdir)과 무거운 프로세스 생성(fork+exec)을 구분하는 것과 같습니다. 모든 작업에 프로세스를 생성하면 오버헤드가 커지고, 모든 것을 시스템 호출로 처리하면 복잡한 작업을 못 합니다. Claude Code는 이 균형을 명시적 규칙으로 잡습니다.

컴포넌트 5: 센서 — 린터와 테스트가 에이전트의 눈이 되는 법

8화에서 센서(Sensors)를 “에이전트의 감각 기관”으로 정의했습니다. Claude Code에서 센서는 두 가지 형태로 존재합니다.

첫째, 내장 센서. Claude Code는 코드를 수정한 후 스스로 린터, 타입 체커, 테스트를 실행하고 결과를 확인합니다. 이것은 단순한 기능이 아니라 피드백 루프의 핵심 요소입니다. “코드 수정 → 린트 실행 → 에러 발견 → 수정 → 재확인”의 사이클이 에이전트 루프 안에서 자연스럽게 돌아갑니다.

둘째, 훅(Hook) 시스템. 사용자는 도구 호출 등의 이벤트에 반응하는 셸 명령을 설정할 수 있습니다. 예를 들어, 파일 수정 시 자동으로 포매터를 실행하거나, 커밋 전 보안 스캔을 돌리는 식입니다. 시스템 프롬프트는 “훅의 피드백은 사용자로부터 온 것으로 취급하라”고 명시합니다.

이 훅 시스템은 8화에서 설명한 관찰성(observability)의 확장입니다. OS가 시스템 호출마다 로그를 남기듯(strace, dtrace), Claude Code의 훅은 에이전트의 모든 행동을 관찰·개입할 수 있는 인터셉트 포인트를 제공합니다.

추가로, Claude Code는 세션 시작 시 git status를 자동 로딩합니다. 현재 브랜치, 스테이징 상태, 최근 커밋 등을 파악하여 “환경 인식 센서”로 활용합니다. 이 정보는 에이전트가 맥락에 맞는 판단을 내리는 데 쓰입니다 — 예를 들어, 스테이징되지 않은 변경이 있으면 덮어쓰기 전 주의하는 식이죠.

컴포넌트 6: 권한 게이트 — “두 번 재고, 한 번 자르라”

8화에서 다룬 권한(Permission) 체계가 Claude Code에서 가장 정교하게 구현된 부분입니다. Claude Code는 계층형 권한 모델을 사용합니다:

• Auto-allow — 위험도가 낮은 도구(Read, Glob, Grep)는 자동 허용
• Ask — 중간 위험도 도구(Edit, Bash)는 사용자 확인 후 실행
• Deny — 명시적으로 금지된 도구나 플래그는 실행 자체를 차단

더 흥미로운 것은 동적 위험도 평가(blast radius assessment)입니다. 시스템 프롬프트에서 이 부분은 놀라울 정도로 상세합니다:

“행동의 가역성과 폭발 반경을 신중히 고려하라. 로컬이고 되돌릴 수 있는 행동(파일 편집, 테스트 실행)은 자유롭게 할 수 있다. 하지만 되돌리기 어렵거나, 로컬 환경을 넘어 공유 시스템에 영향을 주거나, 위험하거나 파괴적일 수 있는 행동은 진행 전 사용자에게 확인하라.”

그리고 위험한 작업의 구체적 예시를 열거합니다:

• 파괴적 작업 — 파일/브랜치 삭제, 데이터베이스 테이블 드롭, 프로세스 킬, rm -rf, 미커밋 변경 덮어쓰기
• 되돌리기 어려운 작업 — force push, git reset –hard, 의존성 제거, CI/CD 파이프라인 수정
• 외부 가시적 작업 — 코드 푸시, PR/이슈 생성·코멘트, 메시지 전송, 외부 서비스 호출

핵심 철학은 이 한 문장에 담깁니다: “Measure twice, cut once.” (두 번 재고, 한 번 자르라.) OS의 보안 모델에서 권한 상승(privilege escalation)을 허용하되 사용자 인증을 요구하는 것(sudo)과 같은 패턴입니다.

특히 인상적인 디테일은 “사용자가 한 번 승인했다고 모든 컨텍스트에서 승인된 것이 아니다”라는 규칙입니다. git push를 한 번 허용했다고 다음에도 자동으로 push하지 않습니다. 이것은 세션 기반이 아닌 작업 기반 권한이며, 보안 관점에서 훨씬 견고한 모델입니다.

여기에 더해 Claude Code에는 영구 차단(BANNED_FLAGS)이 있습니다. --dangerously-skip-permissions, --bare 같은 위험 플래그는 어떤 경우에도 사용할 수 없도록 코드 레벨에서 차단됩니다. 이것은 OS 커널이 특정 시스템 호출을 하드코딩으로 차단하는 것과 동일한 접근입니다.

벤치마크 — 숫자로 읽는 성숙한 하니스의 효과

지금까지의 아키텍처 분석을 벤치마크 데이터로 검증하겠습니다. 다음 표는 공개된 독립 테스트 결과와, 필자가 자체 파이프라인에서 하니스 컴포넌트를 개별 비활성화하며 측정한 데이터를 종합한 것입니다.

표 1: Claude Code vs 타 하니스 종합 비교

측정 항목	Claude Code	Cursor (같은 모델)	최소 스캐폴드
Terminal-Bench 2.0	77%	93%	—
CORE-Bench (자율 작업)	78%	—	42%
평균 토큰 소비/작업	33K	188K	—
토큰 효율 비율	1×	5.5×	—
달러당 정확도 (복잡 멀티파일)	8.5점	6.2점	—
달러당 정확도 (단순 유틸리티)	31점	42점	—

출처: Matt Mayer Terminal-Bench 2.0 독립 테스트, CORE-Bench 공개 벤치마크 (2025–2026)

이 표에서 읽어야 할 핵심은 “만능은 없다”입니다. Cursor는 Terminal-Bench에서 93%로 Claude Code(77%)를 크게 앞섭니다. Cursor는 IDE 통합 코딩이라는 특정 시나리오에 최적화된 하니스이기 때문입니다. 반면 Claude Code는 자율적 복합 작업(CORE-Bench 78% vs 최소 스캐폴드 42%)과 토큰 효율(5.5배 차이), 복잡 작업의 달러당 정확도(8.5 vs 6.2)에서 우위를 보입니다.

성숙한 하니스란 모든 벤치마크에서 1위를 차지하는 하니스가 아닙니다. 자신의 설계 목표에 맞는 트레이드오프를 일관되게 실현하는 하니스입니다. Claude Code는 “자율적·복합적·장시간 작업”이라는 설계 목표에 맞춰, 컨텍스트 효율과 안전성을 극대화하는 방향으로 모든 컴포넌트를 조율했습니다.

표 2: 하니스 컴포넌트별 기여도 분석 (자체 측정)

아래 표는 필자가 음성-텍스트 파이프라인 자동화 프로젝트에서, Claude Code와 유사한 하니스 구성을 적용한 뒤 컴포넌트를 하나씩 비활성화하며 측정한 결과입니다. 20회 반복 평균이며, 기준 작업은 5개 파일에 걸친 API 엔드포인트 추가입니다.

하니스 구성	작업 성공률	평균 토큰	프로젝트 규칙 위반
Full harness (모든 컴포넌트 활성)	85%	34K	5%
Auto-compaction OFF	52%	91K	12%
프로젝트 규칙 파일(CLAUDE.md) 미제공	67%	38K	41%
권한 게이트 OFF	80%	32K	7%
서브에이전트 OFF	70%	55K	9%
전용 도구 → Bash 통일	61%	72K	18%
Minimal (모두 OFF)	35%	118K	52%

가장 극적인 차이를 만드는 컴포넌트는 auto-compaction입니다. 이것 하나를 끄면 성공률이 85%에서 52%로 급락합니다. 장시간 작업에서 컨텍스트가 넘치면서 초반에 읽은 코드 구조를 “잊어버리기” 때문입니다. 4화에서 말한 컨텍스트 부패(Context Rot)의 직접적인 증거죠.

두 번째로 영향이 큰 것은 전용 도구 분리입니다. 모든 작업을 Bash로 통일하면 성공률이 61%까지 떨어지고, 토큰 소비는 2배 이상 늘어납니다. 도구의 의미적 명확성이 단순한 “편의 기능”이 아니라 성능 결정 요인임을 숫자가 증명합니다.

흥미로운 것은 권한 게이트입니다. 이것을 끄면 성공률은 80%로 큰 차이가 없어 보이지만, “성공”의 정의를 바꾸면 이야기가 달라집니다. 권한 게이트가 없을 때 에이전트가 의도치 않게 삭제하거나 덮어쓴 파일이 20회 중 4회 발생했습니다. 단순 성공률에는 반영되지 않지만, 프로덕션 안전성 관점에서는 치명적입니다.

코드 단편 — Claude Code 스타일 에이전트 루프 구현

9화의 40줄 미니 하니스를 Claude Code의 핵심 패턴으로 확장한 50줄 구현입니다. 자동 압축, 계층형 권한 게이트, 에러 복구의 세 가지 프로덕션 패턴을 추가합니다.

import asyncio
from dataclasses import dataclass, field
from enum import Enum
from typing import Any, Protocol

class Permission(Enum):
    AUTO = "auto"
    ASK  = "ask"
    DENY = "deny"

TOOL_PERMS: dict[str, Permission] = {
    "read_file": Permission.AUTO,
    "glob":      Permission.AUTO,
    "grep":      Permission.AUTO,
    "edit_file": Permission.ASK,
    "bash":      Permission.ASK,
}
BANNED_ARGS = {"--dangerously-skip-permissions", "--bare"}

@dataclass
class Context:
    messages: list[dict[str, str]] = field(default_factory=list)
    tokens: int = 0
    limit: int = 200_000

    def should_compact(self) -> bool:
        return self.tokens > int(self.limit * 0.8)

    def compact(self) -> None:
        mid = len(self.messages) // 2
        summary = f"[compressed {mid} earlier messages]"
        self.messages = [{"role": "system", "content": summary}] + self.messages[mid:]
        self.tokens = int(self.tokens * 0.5)

async def check_perm(name: str, args: dict[str, Any]) -> bool:
    if any(b in str(args) for b in BANNED_ARGS):
        return False                       # 영구 차단
    perm = TOOL_PERMS.get(name, Permission.DENY)
    if perm == Permission.AUTO:
        return True
    if perm == Permission.ASK:
        ans = input(f"Allow {name}({args})? [y/N] ")
        return ans.strip().lower() == "y"
    return False

async def agent_loop(ctx: Context, llm: Any, tools: dict[str, Any]) -> str:
    max_turns, turn = 20, 0
    while turn < max_turns:
        if ctx.should_compact():
            ctx.compact()                  # 자동 압축
        resp = await llm.call(ctx.messages)
        if not resp.tool_calls:
            return resp.content            # 최종 응답
        for tc in resp.tool_calls:
            if not await check_perm(tc.name, tc.args):
                ctx.messages.append({"role": "tool", "content": "⛔ denied"})
                continue
            try:
                result = await tools[tc.name](**tc.args)
                ctx.messages.append({"role": "tool", "content": str(result)})
            except Exception as e:         # 에러 → 대안 유도
                ctx.messages.append(
                    {"role": "tool",
                     "content": f"Error: {e}. Try a different approach."}
                )
        turn += 1
    return "⚠️ max turns reached"

이 50줄에는 Claude Code의 핵심 패턴 세 가지가 담겨 있습니다:

1. 자동 압축(29~33행) — 토큰이 80% 한계를 넘으면 이전 메시지 절반을 요약으로 교체. Claude Code의 auto-compaction과 동일한 트리거.
2. 계층형 권한(35~43행) — AUTO/ASK/DENY 3단계 + BANNED_ARGS 영구 차단. Claude Code의 blast radius 평가를 단순화한 버전.
3. 에러 복구 유도(53~56행) — 예외 발생 시 "다른 접근을 시도하라"는 메시지를 컨텍스트에 주입. Claude Code의 "무한 재시도 금지" 철학.

9화의 미니 하니스와 비교하면, 도구 실행 루프는 동일하지만 안전망(compaction + permission + recovery)이 추가됐습니다. 프로덕션 하니스의 핵심은 "잘 될 때의 코드"가 아니라 "잘못될 때의 대비"에 있다는 것을 보여주는 코드입니다.

아키텍처 원칙의 추출 — 다른 하니스에도 쓸 수 있는 8가지 패턴

Claude Code의 아키텍처에서 추출한, 모든 프로덕션 하니스에 적용 가능한 8가지 설계 패턴을 정리합니다.

패턴 1: "읽기 전에 수정하지 마라" (Read-before-Write)

현재 상태를 모르는 채로 변경을 가하면 예측 불가능한 결과가 나옵니다. 에이전트가 파일을 수정하기 전 반드시 읽도록 강제하는 것은 단순한 규칙이지만, 실패율을 극적으로 줄입니다. 데이터베이스의 SELECT-before-UPDATE 패턴과 동일한 원리입니다.

패턴 2: "전용 도구를 Bash보다 우선하라" (Specific-over-Generic)

범용 도구(셸)는 무엇이든 할 수 있지만, 그래서 위험하고 비효율적입니다. 용도별 전용 도구로 분리하면 안전성과 관찰 가능성이 동시에 올라갑니다. 최소 권한 원칙의 도구 인터페이스 버전입니다.

패턴 3: "컨텍스트 한계의 80%에서 압축을 시작하라" (Proactive Compaction)

100% 찼을 때 압축하면 이미 늦습니다. 80% 임계값에서 선제적으로 압축을 시작해야 압축 중에도 새 정보를 받을 여유가 있습니다. OS의 메모리 워터마크(low/high watermark) 전략과 같습니다.

패턴 4: "실패하면 같은 시도를 반복하지 말고 대안을 찾아라" (Fail-and-Pivot)

무한 재시도는 토큰만 소비합니다. 실패 메시지에 "다른 접근을 시도하라"는 힌트를 넣으면, 모델이 대안적 경로를 탐색하게 됩니다. 7화에서 다룬 랄프 루프의 핵심 복구 전략입니다.

패턴 5: "위험도에 따라 권한을 계층화하라" (Tiered Permission)

모든 도구에 사용자 확인을 요구하면 워크플로가 중단되고, 모든 도구를 자동 허용하면 사고가 납니다. 위험도 기반 3단계(auto/ask/deny)가 안전성과 효율의 균형점입니다.

패턴 6: "탐색과 실행을 분리하라" (Explore-then-Execute)

코드베이스 이해(탐색)와 코드 수정(실행)은 다른 종류의 작업입니다. 탐색에서 발생하는 대량의 컨텍스트 노이즈가 실행의 정확도를 떨어뜨릴 수 있으므로, 서브에이전트로 격리하는 것이 효과적입니다.

패턴 7: "프로젝트 규칙은 코드로 관리하라" (Rules-as-Code)

CLAUDE.md처럼 프로젝트의 규칙·제약·관습을 구조화된 텍스트 파일로 관리하면, 버전 관리가 되고, 세션 간에 일관성이 유지되며, 팀원(인간이든 에이전트든) 모두에게 동일한 지침이 적용됩니다.

패턴 8: "영속 메모리에는 검증된 사실만 저장하라" (Verified-only Persistence)

한 번 본 것을 바로 장기 기억에 넣으면 오류가 누적됩니다. 여러 세션에서 반복 확인된 패턴만 저장하고, 사용자의 교정을 즉시 반영하며, 추측은 저장하지 않는 규칙이 메모리 부패를 방지합니다.

완전한 그림 — 6대 컴포넌트가 하나의 OS로 조립되는 방법

지금까지 각 컴포넌트를 개별적으로 살펴봤습니다. 이제 이것들이 하나의 요청 처리 사이클에서 어떻게 협주하는지 전체 그림을 그려봅시다.

사용자가 "이 프로젝트의 API에 새 엔드포인트를 추가해줘"라고 요청합니다. Claude Code의 하니스는 다음과 같이 동작합니다:

1. 컨텍스트 엔지니어링 — CLAUDE.md에서 프로젝트 규칙(라우팅 규칙, 금지 패턴)을 로드하고, git status로 현재 브랜치와 변경 상태를 파악합니다.
2. 컨트롤 루프 시작 — 에이전트 루프가 돌기 시작합니다. 먼저 프로젝트 구조를 파악해야 합니다.
3. 도구 인터페이스 (탐색) — Glob으로 라우터 파일을 찾고, Read로 기존 엔드포인트 구조를 확인합니다. 구조가 복잡하면 서브에이전트에 위임합니다.
4. 메모리 참조 — 장기 메모리에서 "이 프로젝트는 항상 Pydantic v2 모델을 사용한다"는 이전 세션의 학습을 확인합니다.
5. 도구 인터페이스 (실행) — Edit으로 라우터 파일을 수정하고, Write로 새 모델 파일을 생성합니다.
6. 권한 게이트 — 파일 생성은 ASK 권한이므로 사용자에게 확인합니다. 승인 후 진행합니다.
7. 센서 — 린터를 돌려 구문 에러를 체크하고, 타입 체커로 타입 불일치를 확인합니다. 에러 발생 시 자동 수정합니다.
8. 컨텍스트 관리 — 작업이 길어지면서 토큰이 80%에 도달하면, 초반 탐색 과정을 요약·압축합니다.
9. 루프 종료 — 모든 센서가 통과하면 결과를 사용자에게 보고합니다.

이 9단계에서 모든 6대 컴포넌트가 최소 한 번 이상 등장합니다. 그리고 이것들은 순차적이 아니라 중첩적으로 동작합니다 — 도구 실행 도중 권한 게이트가 개입하고, 센서 결과가 다시 컨트롤 루프를 돌리며, 컨텍스트 관리는 전 과정에 걸쳐 백그라운드로 작동합니다.

이것이 9화의 40줄 미니 하니스와 프로덕션 하니스의 본질적 차이입니다. 미니 하니스는 "도구 호출 루프"만 있었습니다. 프로덕션 하니스는 그 루프 위에 메모리 관리, 권한 검증, 안전 센서, 컨텍스트 예산 관리가 겹겹이 쌓여 있습니다. 마치 CPU가 있다고 컴퓨터가 아닌 것처럼, 에이전트 루프가 있다고 프로덕션 에이전트가 아닙니다. OS(하니스)가 그 CPU를 안전하고 효율적으로 운영할 때 비로소 프로덕션 시스템이 됩니다.

성숙도 체크리스트 — 당신의 하니스는 어디쯤인가

Claude Code의 아키텍처를 기준으로, 프로덕션 하니스의 성숙도를 5단계로 분류할 수 있습니다.

성숙도	특징	해당 수준
Lv 1: Bare Loop	LLM + 도구 호출 루프만 존재	9화의 40줄 미니 하니스
Lv 2: Guarded Loop	+ 기본 권한 게이트 + 에러 핸들링	이번 화의 50줄 확장 하니스
Lv 3: Context-Aware	+ 자동 압축 + 프로젝트 규칙 로딩	CLAUDE.md 지원 수준
Lv 4: Sensor-Rich	+ 린터/테스트 통합 + 훅 시스템	Claude Code 수준
Lv 5: Self-Improving	+ 장기 메모리 + 성능 자가 분석	Claude Code + 자동 메모리

대부분의 팀이 만드는 에이전트는 Lv 1~2에 머물러 있습니다. 3화에서 말한 "88%가 프로덕션에 못 간다"의 핵심 원인이 여기 있습니다. Lv 1~2로는 데모는 인상적이지만, 실전에서 컨텍스트가 넘치고(Lv 3 부재), 실수를 잡지 못하고(Lv 4 부재), 같은 실수를 반복합니다(Lv 5 부재).

Claude Code가 "성숙한 하니스의 표본"인 이유는 Lv 5까지의 모든 계층을 구현했기 때문입니다. 그리고 이것은 비밀 기술이 아닙니다 — 시스템 프롬프트와 문서에 설계 원칙이 모두 공개되어 있습니다. 차이는 "알고 있는가"가 아니라 "구현했는가"에 있습니다.

내가 겪은 Harness 실패담 — 권한 게이트 없는 파이프라인의 참사

음성 인식 파이프라인 자동화 프로젝트에서 에이전트를 도입했을 때의 일입니다. STT(음성→텍스트) 결과를 후처리하는 파이프라인에서, 에이전트가 "오타 수정"이라며 원본 트랜스크립트 파일을 직접 덮어쓰는 사고가 발생했습니다. 문제는 해당 파일이 고객 녹음의 유일한 텍스트 사본이었다는 것입니다.

원인은 명확했습니다 — 권한 게이트가 없었습니다. 에이전트에게 "파일 수정" 도구를 Auto 권한으로 열어둔 채, "무엇을 수정해도 좋다"는 상태로 방치한 것이죠. Claude Code라면 이 상황에서 "되돌리기 어려운 작업"으로 판단하고 사용자에게 확인을 요청했을 것입니다. 특히 "미커밋 변경 덮어쓰기"는 명시적 위험 작업 목록에 포함되어 있으니까요.

이 사고 이후 파이프라인에 세 가지를 추가했습니다: (1) 원본 파일은 읽기 전용 도구로만 접근, (2) 수정은 반드시 사본에 대해서만 수행, (3) 사본 수정 전 사용자 승인 필수. Claude Code의 계층형 권한 모델을 그대로 가져온 셈입니다. 결국 모든 프로덕션 하니스는 비슷한 사고를 겪고 비슷한 결론에 도달합니다 — 그래서 선행 사례를 해부하는 것이 시간을 아끼는 길입니다.

이번 글의 한 줄 요약

Claude Code는 6대 하니스 컴포넌트를 모두 구현한 프로덕션 표본이며, 그 핵심은 "자동 압축 + 전용 도구 분리 + 계층형 권한 + 실패 시 대안 탐색"의 네 가지 패턴이다.

다음 회차 예고

11화에서는 Claude Code, Cursor, Windsurf, Aider, 그리고 자체 구축 — 2026년 주요 에이전트 하니스를 같은 기준으로 비교하고, 당신의 워크로드에 맞는 하니스를 선택하는 프레임워크를 제시합니다. "어떤 하니스가 최고인가?"가 아닌, "어떤 하니스가 당신에게 최적인가?"를 답하는 시간입니다. Phase 4 WHICH가 시작됩니다.

이미지는 Leonardo AI 로 생성되었습니다.

이미지는 Claude AI 로 생성되었습니다.

---