Claude Code 유출로 본 에이전틱 하네스 설계 패턴 12가지 정리

이 글은 Claude Code 소스 유출을 통해 드러난 실제 프로덕션용 코딩 에이전트의 내부 설계 방식을 바탕으로, 에이전틱 애플리케이션을 설계할 때 참고할 수 있는 12가지 핵심 하네스 디자인 패턴을 정리한 글입니다.
단순한 기능 나열이 아니라, 왜 이런 구조가 필요했고 어떤 문제를 해결하기 위해 등장했는지를 중심으로 설명합니다. 에이전트 기반 시스템을 설계하거나, LLM을 실제 서비스 환경에서 운영하고자 하는 분들에게 구조적인 인사이트를 제공하는 것이 목적입니다.

반응형

---

에이전틱 하네스란 무엇인가

에이전틱 하네스(agentic harness)는 LLM 자체가 아니라, LLM이 안정적으로 일하도록 감싸는 실행 구조를 의미합니다.
여기에는 다음과 같은 요소들이 포함됩니다.

• 어떤 정보를 언제, 얼마나 제공할 것인가
• 어떤 도구를 언제 사용할 수 있는가
• 어떤 작업 흐름을 강제할 것인가
• 기억과 컨텍스트를 어떻게 관리할 것인가

Claude Code 유출은 이 하네스가 실제로 어떻게 구성되는지를 드물게 보여준 사례였습니다.

---

전체 구조 개요

12가지 패턴은 다음 네 가지 범주로 나뉩니다.

1. Memory & Context (기억과 문맥)
2. Workflow & Orchestration (작업 흐름과 오케스트레이션)
3. Tools & Permissions (도구와 권한)
4. Automation (자동화)

이제 각 범주별로 핵심 패턴을 정리합니다.

---

1. Memory & Context 패턴

1) Persistent Instruction File Pattern

에이전트가 매 세션마다 같은 규칙을 다시 배우지 않도록, 프로젝트 단위의 지속적인 지침 파일을 자동 로드하는 방식입니다.

• 빌드 명령
• 테스트 규칙
• 네이밍 컨벤션
• 아키텍처 제약

을 코드 저장소에 포함시켜 관리합니다.

장점

• 세션이 바뀌어도 일관성 유지

트레이드오프

• 지침 파일이 오래되면 오히려 잘못된 행동을 학습시킬 수 있음

---

2) Scoped Context Assembly Pattern

단일 지침 파일이 아닌, 디렉터리별로 다른 규칙을 로딩하는 패턴입니다.

• 조직 레벨
• 프로젝트 루트
• 상위 / 하위 디렉터리

에 따라 서로 다른 규칙을 적용합니다.

적합한 경우

• 모노레포
• 멀티 언어 프로젝트

트레이드오프

• 에이전트가 실제로 어떤 규칙을 보고 있는지 파악하기 어려움

---

3) Tiered Memory Pattern

모든 기억을 동일하게 취급하지 않고, 계층화된 메모리 구조로 관리합니다.

• 항상 로드되는 소형 인덱스
• 필요 시 로드되는 주제별 메모리
• 디스크에 저장된 전체 세션 로그

장점

• 토큰 낭비 방지
• 중요한 정보가 묻히지 않음

트레이드오프

• 어떤 정보를 어느 계층에 둘지 판단 로직이 복잡해짐

---

4) Dream Consolidation Pattern

시간이 지나며 쌓인 기억을 백그라운드에서 정리·중복 제거·압축하는 패턴입니다.

• 중복 제거
• 모순 제거
• 인덱스 크기 유지

사람의 수면 중 기억 정리와 유사한 개념입니다.

트레이드오프

• 자동 정리가 잘못되면 필요한 정보가 삭제될 위험

---

5) Progressive Context Compaction Pattern

긴 대화로 컨텍스트 한계를 넘지 않도록, 대화의 나이에 따라 단계별로 압축합니다.

• 최신 대화: 원문 유지
• 과거 대화: 요약
• 아주 오래된 대화: 강한 압축

문제 해결 포인트

• 장기 추론 작업이 중간에 끊기지 않음

---

2. Workflow & Orchestration 패턴

6) Explore–Plan–Act Loop Pattern

에이전트가 곧바로 수정하지 못하도록 탐색 → 계획 → 실행 단계를 강제합니다.

• Explore: 읽기 전용
• Plan: 사용자와 접근 방식 논의
• Act: 수정 권한 부여

효과

• 잘못된 파일 수정
• 구조 무시 문제 감소

트레이드오프

• 단순 작업에는 느리게 느껴질 수 있음

---

7) Context-Isolated Subagents Pattern

작업 단계별로 서로 다른 컨텍스트를 가진 하위 에이전트를 분리 실행합니다.

• 조사 전용
• 계획 전용
• 실행 전용

장점

• 컨텍스트 오염 방지

단점

• 단계 간 정보 전달에서 뉘앙스 손실 가능

---

8) Fork–Join Parallelism Pattern

독립적인 작업을 병렬 에이전트로 분기 실행하고 결과를 병합합니다.

• 각 에이전트는 독립된 작업 공간 사용
• 병렬 처리로 속도 개선

트레이드오프

• 병합 시 충돌 해결이 더 어려울 수 있음

---

3. Tools & Permissions 패턴

9) Progressive Tool Expansion Pattern

처음부터 모든 도구를 보여주지 않고, 필요할 때만 도구를 확장합니다.

• 기본 도구 세트는 최소화
• 추가 도구는 상황에 따라 활성화

효과

• 도구 선택 혼란 감소

---

10) Command Risk Classification Pattern

쉘 명령을 실행하기 전, 위험도를 자동 분류합니다.

• 저위험: 자동 승인
• 고위험: 사용자 확인 또는 차단

장점

• 보안과 편의성의 균형

트레이드오프

• 규칙 기반 분류는 지속적인 튜닝 필요

---

11) Single-Purpose Tool Design Pattern

범용 쉘 대신, 목적별 전용 도구를 제공합니다.

• 파일 읽기
• 파일 수정
• 검색

각각 명확한 입력과 권한 범위를 가집니다.

효과

• 리뷰와 권한 관리가 쉬워짐

---

4. Automation 패턴

12) Deterministic Lifecycle Hooks Pattern

절대 빠지면 안 되는 작업을 프롬프트가 아닌 생명주기 훅으로 자동 실행합니다.

• 포맷터 실행
• 설정 재로드
• 명령 검증

핵심 메시지

• “항상 해야 하는 일”은 모델의 기억에 맡기지 않는다

트레이드오프

• 훅 내부 문제는 디버깅이 어려움

---

728x90

Claude Code 유출이 보여준 것은 단순한 구현 디테일이 아니라, 에이전틱 시스템을 안정적으로 운영하기 위한 구조적 원칙이었습니다.

• 기억은 계층화되어야 하고
• 컨텍스트는 관리되어야 하며
• 권한은 단계적으로 열려야 하고
• 반복 규칙은 자동화되어야 합니다

이 패턴들은 특정 제품에 종속된 요령이 아니라, 앞으로도 계속 유효할 에이전트 설계의 기본 단위에 가깝습니다.
모델이 발전하더라도, 이 하네스 설계 원칙은 에이전틱 애플리케이션의 핵심 기반으로 남을 가능성이 큽니다.

300x250

https://generativeprogrammer.com/p/12-agentic-harness-patterns-from

12 Agentic Harness Patterns from Claude Code