에이전트 하네스 아키텍처 2026: 다이어그램 레퍼런스

요약: Claude Code은 파일 접근이 가능한 채팅 상자가 아닙니다. 22개의 라이프사이클 이벤트를 갖춘 프로그래밍 가능한 런타임이며, 각 이벤트는 모델이 건너뛸 수 없는 셸 스크립트로 연결할 수 있습니다. hooks를 dispatchers로, dispatchers를 skills로, skills를 agents로, agents를 워크플로우로 쌓아 올리면, 제약 조건을 강제하고 작업을 위임하며 세션 간 메모리를 유지하고 다중 에이전트 협의를 조율하는 자율 개발 harness를 구축할 수 있습니다. 이 가이드는 단일 hook에서 10개 에이전트 합의 시스템까지, 이 스택의 모든 계층을 다룹니다. 프레임워크가 필요 없으며, 모두 bash와 JSON만으로 구현합니다.

Andrej Karpathy는 LLM 에이전트 주변에 형성되는 것을 claws라는 용어로 표현했습니다. 에이전트가 컨텍스트 윈도우 바깥 세계를 움켜쥘 수 있게 해주는 hooks, 스크립트, 오케스트레이션을 의미합니다.¹ 대부분의 개발자는 AI 코딩 에이전트를 대화형 어시스턴트로 취급합니다. 프롬프트를 입력하고, 파일이 편집되는 것을 지켜보고, 다음으로 넘어갑니다. 이런 관점은 생산성을 직접 감독할 수 있는 범위로 제한합니다.

인프라 관점의 멘탈 모델은 다릅니다. AI 코딩 에이전트는 LLM 커널을 갖춘 프로그래밍 가능한 런타임입니다. 모델이 수행하는 모든 동작은 여러분이 제어하는 hooks를 거칩니다. 프롬프트가 아닌 정책을 정의하는 것입니다. 웹 서버가 nginx 규칙 안에서 동작하듯, 모델도 여러분의 인프라 안에서 동작합니다. nginx 앞에 앉아서 요청을 직접 타이핑하지 않듯이, 설정하고 배포하고 모니터링하면 됩니다.

이 구분이 중요한 이유는 인프라가 복리로 작용하기 때문입니다. bash 명령에서 자격 증명을 차단하는 hook 하나가 모든 세션, 모든 에이전트, 모든 자율 실행을 보호합니다. 평가 기준을 인코딩한 skill은 여러분이 직접 호출하든 에이전트가 호출하든 일관되게 적용됩니다. 보안 코드 리뷰를 수행하는 에이전트는 여러분이 지켜보든 아니든 동일한 검사를 실행합니다.²

핵심 요점

• Hooks는 실행을 보장하지만, 프롬프트는 보장하지 않습니다. 린팅, 포매팅, 보안 검사 등 모델의 동작과 관계없이 매번 반드시 실행되어야 하는 작업에는 hooks를 사용하세요. 종료 코드 2는 동작을 차단하고, 종료 코드 1은 경고만 표시합니다.³
• Skills는 자동 활성화되는 도메인 전문 지식을 인코딩합니다. description 필드가 모든 것을 결정합니다. Claude은 키워드 매칭이 아닌 LLM 추론을 사용하여 skill 적용 여부를 판단합니다.⁴
• Subagents는 컨텍스트 비대화를 방지합니다. 탐색과 분석을 위한 격리된 컨텍스트 윈도우가 메인 세션을 가볍게 유지합니다. 최대 10개까지 병렬 실행이 가능합니다.⁵
• 메모리는 파일 시스템에 존재합니다. 파일은 컨텍스트 윈도우를 넘어 영속됩니다. CLAUDE.md, MEMORY.md, rules 디렉토리, 핸드오프 문서가 구조화된 외부 메모리 시스템을 형성합니다.⁶
• 다중 에이전트 협의는 사각지대를 발견합니다. 단일 에이전트는 자신의 가정에 도전할 수 없습니다. 서로 다른 평가 우선순위를 가진 두 개의 독립 에이전트가 quality gates로는 해결할 수 없는 구조적 결함을 포착합니다.⁷
• harness 패턴이 곧 시스템입니다. CLAUDE.md, hooks, skills, agents, 메모리는 독립된 기능이 아닙니다. 이들은 여러분과 모델 사이에 자동화와 함께 확장되는 결정론적 계층으로 구성됩니다.

이 가이드 활용법

각 섹션은 이전 섹션을 기반으로 합니다. 마지막의 의사결정 프레임워크는 각 문제 유형에 적합한 메커니즘을 선택하기 위한 참조 테이블을 제공합니다.

5분 안에 완성하는 골든 패스

깊이 있는 내용으로 들어가기 전에, 0에서 시작해 작동하는 harness를 구축하는 가장 짧은 경로를 소개합니다. hook 하나, skill 하나, subagent 하나, 그리고 하나의 결과물입니다.

1단계: 보안 hook 만들기 (2분)

.claude/hooks/block-secrets.sh 파일을 생성합니다.

#!/bin/bash
INPUT=$(cat)
CMD=$(echo "$INPUT" | jq -r '.tool_input.command // empty')
if echo "$CMD" | grep -qEi '(AKIA|sk-|ghp_|password=)'; then
    echo "BLOCKED: Potential secret in command" >&2
    exit 2
fi

.claude/settings.json에 연결합니다.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{ "type": "command", "command": ".claude/hooks/block-secrets.sh" }]
      }
    ]
  }
}

결과: 이제 Claude가 실행하는 모든 bash 명령은 유출된 자격 증명이 있는지 검사됩니다. 모델은 이 검사를 건너뛸 수 없습니다.

2단계: 코드 리뷰 skill 만들기 (1분)

.claude/skills/reviewer/SKILL.md 파일을 생성하고 frontmatter(name: reviewer, description: Review code for security issues, bugs, and quality problems. Use when examining changes, reviewing PRs, or auditing code., allowed-tools: Read, Grep, Glob)와 함께 체크리스트를 작성합니다. SQL 인젝션, XSS, 하드코딩된 시크릿, 누락된 에러 처리, 50줄이 넘는 함수.

결과: Claude는 리뷰, 검사, 또는 감사를 언급할 때마다 이 전문성을 자동으로 활성화합니다.

3단계: subagent 생성하기 (30초)

아무 Claude Code 세션에서 Claude에게 별도의 에이전트를 사용하여 최근 커밋 3개를 보안 이슈 관점에서 리뷰해달라고 요청하세요. Claude는 diff를 읽고, 여러분의 리뷰 skill을 적용하고, 요약을 반환하는 Explore 에이전트를 생성합니다. 메인 컨텍스트는 깨끗하게 유지됩니다.

이제 무엇을 얻었는가

3계층 harness를 갖추게 되었습니다. 결정론적 보안 게이트(hook), 자동으로 활성화되는 도메인 전문성(skill), 그리고 컨텍스트를 보호하는 격리된 분석(subagent). 아래의 모든 섹션은 이 세 계층 중 하나를 확장한 내용입니다.

에이전트 아키텍처가 중요한 이유

Simon Willison은 현재의 순간을 하나의 관찰로 규정합니다. 이제 코드를 작성하는 것은 싸졌다는 것입니다.⁸ 맞는 말입니다. 하지만 그 따름정리는 이제 검증이 비싼 부분이 되었다는 것입니다. 검증 인프라 없이 만들어진 저렴한 코드는 대규모로 버그를 양산합니다. 결실을 맺는 투자는 더 나은 프롬프트가 아닙니다. 모델이 놓치는 것을 잡아내는, 모델을 둘러싼 시스템입니다.

에이전트 아키텍처를 필수적으로 만드는 세 가지 힘이 있습니다.

컨텍스트 윈도우는 유한하고 손실이 있습니다. 모든 파일 읽기, 도구 출력, 대화 턴은 토큰을 소비합니다. Microsoft Research와 Salesforce는 200,000개 이상의 시뮬레이션된 대화에서 15개의 LLM를 테스트했고, 단일 턴에서 다중 턴 상호작용으로 넘어갈 때 평균 39%의 성능 저하를 발견했습니다.⁹ 이 저하는 단 두 턴만에 시작되며 예측 가능한 곡선을 따릅니다. 처음 30분 동안의 정밀한 다중 파일 편집이 90분 무렵에는 단일 파일 터널 비전으로 전락합니다. 더 긴 컨텍스트 윈도우로는 이 문제를 해결할 수 없습니다. 동일한 연구의 “Concat” 조건(전체 대화를 단일 프롬프트로 제공)은 같은 내용으로 단일 턴 성능의 95.1%를 달성했습니다. 저하는 토큰 제한이 아니라 턴 경계에서 발생합니다.

모델의 동작은 결정론적이 아니라 확률적입니다. Claude에게 “파일을 편집한 후 항상 Prettier를 실행하라”고 지시하면 대략 80%의 경우에만 작동합니다.³ 모델은 잊어버리거나, 속도를 우선시하거나, 변경이 “너무 작다”고 판단할 수 있습니다. 컴플라이언스, 보안, 팀 표준에서 80%는 허용되지 않습니다. hook은 실행을 보장합니다. 모든 Edit 또는 Write는 예외 없이 매번 여러분의 포매터를 트리거합니다. 결정론은 확률론을 이깁니다.

단일 관점은 다차원적 문제를 놓칩니다. API 엔드포인트를 리뷰한 단일 에이전트는 인증을 확인하고, 입력 정화를 검증하고, CORS 헤더를 확인했습니다. 깨끗한 건강 진단서가 나왔습니다. 별도로 침투 테스터로 프롬프트된 두 번째 에이전트는 해당 엔드포인트가 데이터베이스 쿼리 증폭을 통해 서비스 거부를 유발할 수 있는 무제한 쿼리 매개변수를 받아들인다는 것을 발견했습니다.⁷ 첫 번째 에이전트는 평가 프레임워크에서 쿼리 복잡성을 보안 표면으로 취급하지 않았기 때문에 확인하지 않았습니다. 이 간극은 구조적입니다. 어떤 수준의 프롬프트 엔지니어링으로도 해결되지 않습니다.

에이전트 아키텍처는 이 세 가지 모두를 다룹니다. hook은 결정론적 제약을 강제하고, subagent는 컨텍스트 격리를 관리하며, 다중 에이전트 오케스트레이션은 독립적인 관점을 제공합니다. 이들이 함께 harness를 구성합니다.

하니스 패턴

하니스는 프레임워크가 아닙니다. 이는 하나의 패턴입니다. AI 코딩 에이전트를 결정론적 인프라로 감싸는, 조합 가능한 파일, 스크립트, 관례의 집합입니다. 구성 요소는 다음과 같습니다:

┌──────────────────────────────────────────────────────────────┐
│                      THE HARNESS PATTERN                      │
├──────────────────────────────────────────────────────────────┤
│  ORCHESTRATION                                                │
│  ┌────────────┐  ┌────────────┐  ┌────────────┐             │
│  │   Agent     │  │   Agent    │  │  Consensus │             │
│  │   Teams     │  │  Spawning  │  │  Validation│             │
│  └────────────┘  └────────────┘  └────────────┘             │
│  Multi-agent deliberation, parallel research, voting          │
├──────────────────────────────────────────────────────────────┤
│  EXTENSION LAYER                                              │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐    │
│  │  Skills   │  │  Hooks   │  │  Memory  │  │  Agents  │    │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘    │
│  Domain expertise, deterministic gates, persistent state,     │
│  specialized subagents                                        │
├──────────────────────────────────────────────────────────────┤
│  INSTRUCTION LAYER                                            │
│  ┌──────────────────────────────────────────────────────┐    │
│  │     CLAUDE.md  +  .claude/rules/  +  MEMORY.md       │    │
│  └──────────────────────────────────────────────────────┘    │
│  Project context, operational policy, cross-session memory    │
├──────────────────────────────────────────────────────────────┤
│  CORE LAYER                                                   │
│  ┌──────────────────────────────────────────────────────┐    │
│  │           Main Conversation Context (LLM)             │    │
│  └──────────────────────────────────────────────────────┘    │
│  Your primary interaction; finite context; costs money        │
└──────────────────────────────────────────────────────────────┘

지시 계층(Instruction Layer): CLAUDE.md 파일과 rules 디렉터리는 에이전트가 프로젝트에 대해 무엇을 알고 있는지 정의합니다. 세션 시작 시와 모든 컴팩션 이후에 자동으로 로드됩니다. 이는 에이전트의 장기 아키텍처 메모리입니다.

확장 계층(Extension Layer): skills는 컨텍스트에 따라 자동으로 활성화되는 도메인 전문성을 제공합니다. hooks는 매칭되는 모든 tool call에서 실행되는 결정론적 게이트를 제공합니다. Memory 파일은 세션 간 상태를 유지합니다. 커스텀 agents는 특화된 subagents 구성을 제공합니다.

오케스트레이션 계층(Orchestration Layer): 다중 에이전트 패턴은 독립적인 에이전트를 조정하여 연구, 검토, 심의를 수행합니다. 스폰 예산(spawn budget)은 무한 재귀를 방지합니다. 합의 검증(consensus validation)은 품질을 보장합니다.

핵심 통찰은 이것입니다. 대부분의 사용자는 Core Layer에서만 작업하며, 컨텍스트가 부풀어 오르고 비용이 치솟는 것을 지켜봅니다. 파워 유저는 Instruction과 Extension 계층을 구성한 다음, Core Layer는 오케스트레이션과 최종 결정에만 사용합니다.²

관리형 vs 자체 호스팅 하니스 (2026년 4월)

2026년 초 내내, “자신의 하니스를 직접 만드는” 경로가 유일한 실질적 선택지였습니다. 2026년 4월, 그것이 바뀌었습니다. Anthropic는 Claude Managed Agents를 퍼블릭 베타로 출시했습니다(4월 8일). 하니스 루프 + tool 실행 + 샌드박스 컨테이너 + 상태 지속성을 REST API로 제공하며, 표준 토큰 요금에 세션-시간당 $0.08가 추가로 청구됩니다. OpenAI의 Agents SDK 업데이트(4월 16일)는 동일한 분리를 공식화했습니다. 하니스와 컴퓨트를 별개의 계층으로, 네이티브 샌드박스 제공자(Blaxel, Cloudflare, Daytona, E2B, Modal, Runloop, Vercel)와 컨테이너 손실에서 살아남기 위한 스냅샷/리하이드레이트 기능을 포함합니다.²³²⁴

아키텍처 분기가 이제 현실이 되었습니다:

어느 쪽을 선택할 것인가: 자체 호스팅은 이미 인프라 역량을 갖추고 있거나, 직접 제어하는 skills/hooks를 원하거나, 특정 워크플로를 깊이 최적화하는 팀에 적합합니다. 관리형은 전담 플랫폼 엔지니어가 없는 팀, 커스터마이징보다 가치 실현 속도가 더 중요한 경우, 또는 에이전트 실행이 직접 지속성 계층을 구축하지 않고도 노트북을 닫아도 안정적으로 살아남아야 하는 경우에 적합합니다. 둘은 호환됩니다. 자체 호스팅 하니스를 운영하면서 특정 장시간 실행 작업은 REST API를 통해 Managed Agents에 위임할 수 있습니다.

디스크상의 하니스 모습

~/.claude/
├── CLAUDE.md                    # Personal global instructions
├── settings.json                # User-level hooks and permissions
├── skills/                      # Personal skills (44+)
│   ├── code-reviewer/SKILL.md
│   ├── security-auditor/SKILL.md
│   └── api-designer/SKILL.md
├── agents/                      # Custom subagent definitions
│   ├── security-reviewer.md
│   └── code-explorer.md
├── rules/                       # Categorized rule files
│   ├── security.md
│   ├── testing.md
│   └── git-workflow.md
├── hooks/                       # Hook scripts
│   ├── validate-bash.sh
│   ├── auto-format.sh
│   └── recursion-guard.sh
├── configs/                     # JSON configuration
│   ├── recursion-limits.json
│   └── deliberation-config.json
├── state/                       # Runtime state
│   ├── recursion-depth.json
│   └── agent-lineage.json
├── handoffs/                    # Session handoff documents
│   └── deliberation-prd-7.md
└── projects/                    # Per-project memory
    └── {project}/memory/MEMORY.md

.claude/                         # Project-level (in repo)
├── CLAUDE.md                    # Project instructions
├── settings.json                # Project hooks
├── skills/                      # Team-shared skills
├── agents/                      # Team-shared agents
└── rules/                       # Project rules

이 구조의 모든 파일은 목적이 있습니다. ~/.claude/ 트리는 모든 프로젝트에 적용되는 개인 인프라입니다. 각 저장소의 .claude/ 트리는 프로젝트별이며 git을 통해 공유됩니다. 이 둘이 함께 완전한 하니스를 구성합니다.

Skills 시스템

skills는 모델이 호출하는(model-invoked) 확장입니다. Claude는 명시적으로 호출하지 않아도 컨텍스트에 따라 자동으로 skills를 발견하고 적용합니다.⁴ 세션마다 같은 컨텍스트를 반복해서 설명하고 있는 자신을 발견하는 순간이, 바로 skill을 만들어야 할 순간입니다.

Skill을 만들어야 할 때

skills는 Claude가 항상 사용할 수 있는 지식을 위한 것입니다. slash commands는 명시적으로 트리거하는 액션을 위한 것입니다. 둘 사이에서 고민하고 있다면, “이것을 Claude가 자동으로 적용해야 하는가, 아니면 내가 언제 실행할지 결정해야 하는가?”라고 자문하세요.

Skill 만들기

skills는 범위가 가장 넓은 것부터 가장 좁은 것까지 네 곳에 위치할 수 있습니다:⁴

모든 skill은 YAML 프론트매터가 있는 SKILL.md 파일을 필요로 합니다:

---
name: code-reviewer
description: Review code for security vulnerabilities, performance issues,
  and best practice violations. Use when examining code changes, reviewing
  PRs, analyzing code quality, or when asked to review, audit, or check code.
allowed-tools: Read, Grep, Glob
---

# Code Review Expertise

## 보안 점검
코드를 검토할 때 다음을 확인하세요.

### 입력 검증
- 데이터베이스 작업 전에 모든 사용자 입력이 살균(sanitize)되었는지
- 매개변수화된 쿼리 사용 여부 (SQL에 문자열 보간 없음)
- 렌더링되는 HTML 콘텐츠에 대한 출력 인코딩

### 인증
- 보호된 모든 엔드포인트에서 세션 토큰 검증
- 데이터 변경 전 권한 확인
- 소스에 하드코딩된 자격 증명이나 API 키가 없는지

Frontmatter 참조

Description 필드가 전부입니다

세션 시작 시 Claude Code는 모든 스킬의 name과 description을 추출하여 Claude의 컨텍스트에 주입합니다. 메시지를 전송하면 Claude는 언어 모델 추론을 사용하여 관련된 스킬이 있는지 판단합니다. Claude Code 소스에 대한 독립적인 분석에서도 이 메커니즘이 확인되었습니다. 스킬 설명은 시스템 프롬프트의 available_skills 섹션에 주입되며, 모델은 표준적인 언어 이해 능력을 사용하여 관련 스킬을 선택합니다.¹⁰

나쁜 description:

description: Helps with code

효과적인 description:

description: Review code for security vulnerabilities, performance issues,
  and best practice violations. Use when examining code changes, reviewing
  PRs, analyzing code quality, or when asked to review, audit, or check code.

효과적인 description에는 다음이 포함됩니다. 무엇을 하는지 (특정 이슈 유형에 대한 코드 검토), 언제 사용하는지 (변경 사항 검토, PR 검토, 품질 분석), 그리고 사용자가 자연스럽게 입력하는 트리거 구문 (review, audit, check)입니다.

컨텍스트 예산

모든 스킬 description은 컨텍스트 윈도우의 2%로 동적으로 조정되는 컨텍스트 예산을 공유하며, 기본 폴백은 16,000자입니다.⁴ 스킬이 많다면 각 description을 간결하게 유지하세요. SLASH_COMMAND_TOOL_CHAR_BUDGET 환경 변수를 통해 예산을 재정의할 수 있지만,¹¹ 더 나은 해결책은 더 짧고 정확한 description입니다. 세션 중 /context를 실행하여 제외된 스킬이 있는지 확인하세요.

지원 파일 및 구성

스킬은 같은 디렉토리의 추가 파일을 참조할 수 있습니다.

~/.claude/skills/code-reviewer/
├── SKILL.md                    # Required: frontmatter + core expertise
├── SECURITY_PATTERNS.md        # Referenced: detailed vulnerability patterns
└── PERFORMANCE_CHECKLIST.md    # Referenced: optimization guidelines

SKILL.md에서 상대 링크로 이들을 참조하세요. Claude는 스킬이 활성화되면 이 파일들을 필요할 때 읽습니다. SKILL.md는 500줄 미만으로 유지하고 상세한 참조 자료는 지원 파일로 옮기세요.¹²

Git을 통한 스킬 공유

프로젝트 스킬 (저장소 루트의 .claude/skills/)은 버전 관리를 통해 공유됩니다.⁴

mkdir -p .claude/skills/domain-expert
# ... write SKILL.md ...
git add .claude/skills/
git commit -m "feat: add domain-expert skill for payment processing rules"
git push

팀원이 pull하면 스킬을 자동으로 받게 됩니다. 설치도, 구성도 필요 없습니다. 이는 팀 전반에 걸쳐 전문성을 표준화하는 가장 효과적인 방법입니다.

프롬프트 라이브러리로서의 스킬

단일 목적 스킬을 넘어, 디렉토리 구조는 체계화된 프롬프트 라이브러리로 작동합니다.

~/.claude/skills/
├── code-reviewer/          # Activates on: review, audit, check
├── api-designer/           # Activates on: design API, endpoint, schema
├── sql-analyst/            # Activates on: query, database, migration
├── deploy-checker/         # Activates on: deploy, release, production
└── incident-responder/     # Activates on: error, failure, outage, debug

각 스킬은 당신의 전문성의 서로 다른 측면을 부호화합니다. 이들이 모이면 Claude가 컨텍스트에 따라 자동으로 참조하는 지식 베이스를 형성합니다. 주니어 개발자는 요청하지 않아도 시니어 수준의 가이드를 받을 수 있습니다.

스킬은 Hooks와 결합됩니다

스킬은 frontmatter에서 자체 hooks를 정의할 수 있으며, 이는 해당 스킬이 실행되는 동안에만 활성화됩니다. 이를 통해 다른 세션을 오염시키지 않는 도메인 특화 동작을 만들 수 있습니다.²

---
name: deploy-checker
description: Verify deployment readiness. Use when preparing to deploy,
  release, or push to production.
hooks:
  PreToolUse:
    - matcher: Bash
      hooks:
        - type: command
          command: "bash -c 'INPUT=$(cat); CMD=$(echo \"$INPUT\" | jq -r \".tool_input.command\"); if echo \"$CMD\" | grep -qE \"deploy|release|publish\"; then echo \"DEPLOYMENT COMMAND DETECTED. Running pre-flight checks.\" >&2; fi'"
---

철학 스킬은 SessionStart hooks를 통해 자동 활성화되어, 명시적 호출 없이도 모든 세션에 품질 제약을 주입합니다. 스킬 자체는 지식입니다. Hook은 집행입니다. 이 둘이 함께 정책 계층을 형성합니다.

일반적인 스킬 실수

너무 광범위한 description. git 관련 프롬프트(rebase, merge, cherry-pick, 심지어 git status까지)에 모두 활성화되는 git-rebase-helper 스킬은 80%의 세션에서 컨텍스트를 오염시킵니다. 해결책은 description을 더 엄격하게 하거나, disable-model-invocation: true를 추가하여 명시적인 /skill-name 호출을 요구하는 것입니다.⁴

예산을 두고 경쟁하는 너무 많은 스킬. 스킬이 많아질수록 더 많은 description이 2% 컨텍스트 예산을 두고 경쟁합니다. 스킬이 활성화되지 않는 것이 눈에 띈다면 /context에서 제외된 항목을 확인하세요. 모호한 스킬을 많이 두기보다 잘 설명된 소수의 스킬을 우선하세요.

중요 정보가 지원 파일에 묻혀 있음. Claude는 SKILL.md는 즉시 읽지만 지원 파일은 필요할 때만 접근합니다. 중요한 정보가 지원 파일에 있다면 Claude가 찾지 못할 수 있습니다. 필수 정보는 SKILL.md에 직접 넣으세요.⁴

Hook 아키텍처

Hook은 Claude Code 라이프사이클 이벤트에 의해 트리거되는 셸 명령입니다.³ 모델이 해석하는 프롬프트가 아니라 LLM 외부에서 일반 스크립트로 실행됩니다. 모델이 rm -rf /를 실행하려 한다면? 10줄짜리 bash 스크립트가 차단 목록에 대해 명령을 확인하고 셸이 그것을 보기도 전에 거부합니다. Hook은 모델의 의도와 관계없이 실행됩니다.

사용 가능한 이벤트

Claude Code은 7개 카테고리에 걸쳐 26개 이상의 라이프사이클 이벤트를 제공합니다(이벤트 목록은 릴리스마다 늘어나므로 최신 전체 표는 cheat sheet를 참조하세요):¹³

종료 코드 의미

종료 코드는 hook이 동작을 차단할지 여부를 결정합니다:³

중요: 모든 보안 hook은 exit 1이 아닌 exit 2를 사용해야 합니다. Exit 1은 비차단 경고입니다. 위험한 명령은 여전히 실행됩니다. 이는 팀에서 가장 흔히 발생하는 hook 실수입니다.¹⁴

Hook 설정

Hook은 설정 파일에 정의됩니다. 공유 hook에는 프로젝트 레벨(.claude/settings.json)을, 개인 hook에는 사용자 레벨(~/.claude/settings.json)을 사용합니다:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/validate-bash.sh"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'if [[ \"$FILE_PATH\" == *.py ]]; then black --quiet \"$FILE_PATH\" 2>/dev/null; fi'"
          }
        ]
      }
    ]
  }
}

matcher 필드는 도구 이름과 일치하는 정규식입니다: Bash, Write, Edit, Read, Glob, Grep, Agent 또는 모든 도구에 대해 *를 사용합니다. UserPromptSubmit처럼 도구가 없는 이벤트에는 ""(빈 문자열)를 사용하세요.

Hook 입출력 프로토콜

Hook은 전체 컨텍스트가 포함된 JSON을 stdin으로 받습니다:

{
  "tool_name": "Bash",
  "tool_input": {
    "command": "npm test",
    "description": "Run test suite"
  },
  "session_id": "abc-123",
  "agent_id": "main",
  "agent_type": "main"
}

고급 제어를 위해 PreToolUse hook은 JSON을 출력하여 도구 입력을 수정하거나, 컨텍스트를 주입하거나, 권한 결정을 내릴 수 있습니다. hookSpecificOutput 래퍼를 사용하세요 — 이전의 최상위 decision/reason 형식은 PreToolUse에서 더 이상 사용되지 않습니다:

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "allow",
    "permissionDecisionReason": "Command validated and modified",
    "updatedInput": {
      "command": "npm test -- --coverage --ci"
    },
    "additionalContext": "Note: This database has a 5-second query timeout."
  }
}

세 가지 유형의 보장

어떤 hook을 작성하기 전에 먼저 물어보세요: 어떤 종류의 보장이 필요한가?¹⁴

포매팅 보장은 사후적으로 일관성을 확보합니다. Write/Edit에 대한 PostToolUse hook은 모든 파일 변경 후에 포매터를 실행합니다. 포매터가 모든 것을 정규화하기 때문에 모델의 출력은 중요하지 않습니다.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'if [[ \"$FILE_PATH\" == *.py ]]; then black --quiet \"$FILE_PATH\" 2>/dev/null; elif [[ \"$FILE_PATH\" == *.js ]] || [[ \"$FILE_PATH\" == *.ts ]]; then npx prettier --write \"$FILE_PATH\" 2>/dev/null; fi'"
          }
        ]
      }
    ]
  }
}

안전 보장은 위험한 동작이 실행되기 전에 이를 방지합니다. Bash에 대한 PreToolUse hook은 명령을 검사하고 파괴적인 패턴을 종료 코드 2로 차단합니다:

#!/bin/bash
# validate-bash.sh — block dangerous commands
INPUT=$(cat)
CMD=$(echo "$INPUT" | jq -r '.tool_input.command')

if echo "$CMD" | grep -qE "rm\s+-rf\s+/|git\s+push\s+(-f|--force)\s+(origin\s+)?main|git\s+reset\s+--hard|DROP\s+TABLE"; then
    echo "BLOCKED: Dangerous command detected: $CMD" >&2
    exit 2
fi

품질 보장은 결정 지점에서 상태를 검증합니다. git commit 명령에 대한 PreToolUse hook은 린터 또는 테스트 스위트를 실행하고 품질 검사가 실패하면 커밋을 차단합니다:

#!/bin/bash
# quality-gate.sh — lint before commit
INPUT=$(cat)
CMD=$(echo "$INPUT" | jq -r '.tool_input.command')

if echo "$CMD" | grep -qE "^git\s+commit"; then
    if ! LINT_OUTPUT=$(ruff check . --select E,F,W 2>&1); then
        echo "LINT FAILED -- fix before committing:" >&2
        echo "$LINT_OUTPUT" >&2
        exit 2
    fi
fi

셸 명령을 넘어선 Hook 유형

Claude Code은 네 가지 hook 유형을 지원합니다:¹³

Command hook(type: "command")은 셸 스크립트를 실행합니다. 빠르고, 결정적이며, 토큰 비용이 없습니다.

Prompt hook(type: "prompt")은 빠른 Claude 모델에 단일 턴 프롬프트를 보냅니다. 모델은 허용하려면 { "ok": true }를, 차단하려면 { "ok": false, "reason": "..." }를 반환합니다. 정규식으로 표현할 수 없는 미묘한 평가에 사용하세요.

Agent hook(type: "agent")은 다중 턴 검증을 위해 도구 접근(Read, Grep, Glob)이 가능한 subagent를 생성합니다. 검사하기 위해 실제 파일이나 테스트 출력을 확인해야 할 때 사용하세요:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "agent",
            "prompt": "Verify all unit tests pass. Run the test suite and check results. $ARGUMENTS",
            "timeout": 120
          }
        ]
      }
    ]
  }
}

HTTP hook(type: "http")은 이벤트의 JSON 입력을 POST 요청으로 URL에 보내고 JSON을 응답으로 받습니다. 웹훅, 외부 알림 서비스 또는 API 기반 검증(v2.1.63+)에 사용하세요. SessionStart 이벤트에서는 지원되지 않습니다:

{
  "hooks": {
    "PostToolUse": [
      {
        "hooks": [
          {
            "type": "http",
            "url": "https://your-webhook.example.com/hook",
            "headers": { "Authorization": "Bearer $WEBHOOK_TOKEN" },
            "allowedEnvVars": ["WEBHOOK_TOKEN"],
            "timeout": 10
          }
        ]
      }
    ]
  }
}

비동기 Hook

Hook은 실행을 차단하지 않고 백그라운드에서 실행될 수 있습니다. 알림 및 로깅과 같은 비중요 작업에는 async: true를 추가하세요:¹³

{
  "type": "command",
  "command": ".claude/hooks/notify-slack.sh",
  "async": true
}

알림, 텔레메트리, 백업에는 async를 사용하세요. 포매팅, 검증, 또는 다음 동작 전에 반드시 완료되어야 하는 작업에는 절대 async를 사용하지 마세요.

독립 Hook보다 Dispatcher

같은 이벤트에서 동시에 실행되는 7개의 hook이 각각 독립적으로 stdin을 읽으면 경쟁 조건이 발생합니다. 같은 JSON 상태 파일에 동시에 쓰는 두 개의 hook은 JSON을 잘라버릴 것입니다. 그 파일을 파싱하는 모든 하위 hook이 깨집니다.²

해결책: 이벤트당 하나의 dispatcher가 캐시된 stdin으로부터 hook을 순차적으로 실행합니다:

#!/bin/bash
# dispatcher.sh — run hooks sequentially with cached stdin
INPUT=$(cat)
HOOK_DIR="$HOME/.claude/hooks/pre-tool-use.d"

for hook in "$HOOK_DIR"/*.sh; do
    [ -x "$hook" ] || continue
    echo "$INPUT" | "$hook"
    EXIT_CODE=$?
    if [ "$EXIT_CODE" -eq 2 ]; then
        exit 2  # Propagate block
    fi
done

Hook 디버깅

조용히 실패하는 hook을 디버깅하기 위한 다섯 가지 기법:¹⁴

1. 스크립트를 독립적으로 테스트합니다. 샘플 JSON을 파이프하세요: echo '{"tool_input":{"command":"git commit -m test"}}' | bash your-hook.sh
2. 디버그 출력에는 stderr를 사용합니다. 종료 코드 2의 stderr는 오류 메시지로 Claude에 다시 전달됩니다. 비차단 stderr(exit 1, 3 등)는 verbose 모드(Ctrl+O)에서만 나타납니다.
3. jq 실패를 주의하세요. 잘못된 JSON 경로는 조용히 null을 반환합니다. 실제 도구 입력에 대해 jq 표현식을 테스트하세요.
4. 종료 코드를 검증합니다. exit 1을 사용하는 PreToolUse hook은 작동하는 것처럼 보이지만 실제로는 아무런 강제력을 제공하지 않습니다.
5. Hook을 빠르게 유지합니다. Hook은 동기적으로 실행됩니다. 모든 hook은 2초 이내, 이상적으로는 500ms 이내로 유지하세요.

메모리와 컨텍스트

모든 AI 대화는 유한한 컨텍스트 창 안에서 작동합니다. 대화가 길어질수록 시스템은 새로운 내용을 수용하기 위해 이전 턴을 압축합니다. 이 압축은 손실이 발생합니다. 3번째 턴에서 문서화한 아키텍처 결정이 15번째 턴까지 살아남지 못할 수 있습니다.⁹

멀티턴 붕괴의 세 가지 메커니즘

MSR/Salesforce 연구는 세 가지 독립적인 메커니즘을 식별했으며, 각각 다른 개입이 필요합니다.⁹

전략 1: 메모리로서의 파일시스템

컨텍스트 경계를 넘어 가장 안정적인 메모리는 파일시스템에 존재합니다. Claude Code는 모든 세션 시작 시점과 모든 컴팩션 이후에 CLAUDE.md와 메모리 파일을 읽어들입니다.⁶

~/.claude/
├── configs/           # 14 JSON configs (thresholds, rules, budgets)
│   ├── deliberation-config.json
│   ├── recursion-limits.json
│   └── consensus-profiles.json
├── hooks/             # 95 lifecycle event handlers
├── skills/            # 44 reusable knowledge modules
├── state/             # Runtime state (recursion depth, agent lineage)
├── handoffs/          # 49 multi-session context documents
├── docs/              # 40+ system documentation files
└── projects/          # Per-project memory directories
    └── {project}/memory/
        └── MEMORY.md  # Always loaded into context

MEMORY.md 파일은 세션 전반에 걸쳐 오류, 결정, 패턴을 기록합니다. ((VAR++))가 VAR이 0일 때 bash에서 set -e와 함께 실패한다는 사실을 발견하면 이를 기록합니다. 세 세션 이후 Python에서 비슷한 정수 엣지 케이스를 만났을 때, MEMORY.md 항목이 해당 패턴을 수면 위로 끌어올립니다.¹⁵

자동 메모리 (v2.1.32+): Claude Code는 프로젝트 컨텍스트를 자동으로 기록하고 회상합니다. 작업이 진행되는 동안 Claude는 관찰 내용을 ~/.claude/projects/{project-path}/memory/MEMORY.md에 기록합니다. 자동 메모리는 세션 시작 시 처음 200줄을 시스템 프롬프트에 로드합니다. 내용은 간결하게 유지하고, 상세한 메모는 별도의 주제 파일에 연결하세요.⁶

전략 2: 선제적 컴팩션

Claude Code의 /compact 명령은 주요 결정, 파일 내용, 작업 상태를 보존하면서 대화를 요약하고 컨텍스트 공간을 확보합니다.¹⁵

컴팩션 시점: - 별개의 하위 작업을 완료한 후 (기능 구현 완료, 버그 수정 완료) - 코드베이스의 새로운 영역을 시작하기 전 - Claude가 이전 컨텍스트를 반복하거나 잊어버리기 시작할 때 - 집중 세션 중 대략 25-30분마다

CLAUDE.md의 커스텀 컴팩션 지시사항:

# Summary Instructions
When using compact, focus on:
- Recent code changes
- Test results
- Architecture decisions made this session

전략 3: 세션 핸드오프

여러 세션에 걸친 작업의 경우, 전체 상태를 포착하는 핸드오프 문서를 작성하세요.

## Handoff: Deliberation Infrastructure PRD-7
**Status:** Hook wiring complete, 81 Python unit tests passing
**Files changed:** hooks/post-deliberation.sh, hooks/deliberation-pride-check.sh
**Decision:** Placed post-deliberation in PostToolUse:Task, pride-check in Stop
**Blocked:** Spawn budget model needs inheritance instead of depth increment
**Next:** PRD-8 integration tests in tests/test_deliberation_lib.py

Status/Files/Decision/Blocked/Next 구조는 후속 세션에 최소한의 토큰 비용으로 전체 컨텍스트를 제공합니다. claude -c(continue)로 새 세션을 시작하거나 핸드오프 문서를 읽으면 바로 구현 단계로 진입합니다.¹⁵

전략 4: 새로운 컨텍스트 반복 (Ralph 루프)

60-90분을 초과하는 세션의 경우, 반복마다 새로운 Claude 인스턴스를 생성하세요. 상태는 대화 메모리가 아닌 파일시스템을 통해 유지됩니다. 각 반복은 전체 컨텍스트 예산을 확보합니다.¹⁶

Iteration 1: [200K tokens] -> writes code, creates files, updates state
Iteration 2: [200K tokens] -> reads state from disk, continues
Iteration 3: [200K tokens] -> reads updated state, continues
...
Iteration N: [200K tokens] -> reads final state, verifies criteria

단일 장기 세션과 비교해 보세요.

Minute 0:   [200K tokens available] -> productive
Minute 30:  [150K tokens available] -> somewhat productive
Minute 60:  [100K tokens available] -> degraded
Minute 90:  [50K tokens available]  -> significantly degraded
Minute 120: [compressed, lossy]     -> errors accumulate

반복마다 새로운 컨텍스트를 사용하는 접근 방식은 방향 설정 단계(상태 파일 읽기, git 히스토리 스캔)에서 15-20%의 오버헤드를 감수하는 대신 반복마다 온전한 인지 자원을 확보합니다.¹⁶ 비용-편익 계산: 60분 미만 세션에서는 단일 대화가 더 효율적입니다. 90분을 넘어서면 새로운 컨텍스트 방식이 오버헤드에도 불구하고 더 높은 품질의 결과를 생성합니다.

안티 패턴

10줄이 필요한데 파일 전체를 읽는 것. 2,000줄짜리 파일 한 번 읽기는 15,000-20,000 토큰을 소비합니다. 라인 오프셋을 사용하세요. Read file.py offset=100 limit=20은 그 비용의 대부분을 절약합니다.¹⁵

장황한 오류 출력을 컨텍스트에 유지하는 것. 버그를 디버깅한 후에는 실패한 반복에서 나온 40개 이상의 스택 트레이스가 컨텍스트에 남아 있습니다. 버그 수정 후 /compact를 한 번 실행하면 그 잔해가 제거됩니다.

모든 세션을 모든 파일을 읽는 것으로 시작하는 것. Claude Code의 glob과 grep 도구가 필요에 따라 관련 파일을 찾도록 맡기면, 불필요한 사전 로딩에 드는 100,000개 이상의 토큰을 절약할 수 있습니다.¹⁵

서브에이전트 패턴

서브에이전트는 복잡한 작업을 독립적으로 처리하는 특화된 Claude 인스턴스입니다. 깨끗한 컨텍스트(메인 대화로부터의 오염 없음)에서 시작하여 지정된 도구로 작동하고 결과를 요약으로 반환합니다. 탐색 결과가 메인 대화를 부풀리지 않으며 결론만 돌아옵니다.⁵

내장 서브에이전트 유형

커스텀 서브에이전트 생성

.claude/agents/ (프로젝트) 또는 ~/.claude/agents/ (개인)에서 서브에이전트를 정의합니다.

---
name: security-reviewer
description: Expert security code reviewer. Use PROACTIVELY after any code
  changes to authentication, authorization, or data handling.
tools: Read, Grep, Glob, Bash
model: opus
permissionMode: plan
---

You are a senior security engineer reviewing code for vulnerabilities.

When invoked:
1. Identify the files that were recently changed
2. Analyze for OWASP Top 10 vulnerabilities
3. Check for secrets, hardcoded credentials, SQL injection
4. Report findings with severity levels and remediation steps

Focus on actionable security findings, not style issues.

서브에이전트 설정 필드

Worktree 격리

서브에이전트는 임시 git worktree에서 작동할 수 있으며, 저장소의 완전히 격리된 복사본을 제공합니다.⁵

---
name: experimental-refactor
description: Attempt risky refactoring in isolation
isolation: worktree
tools: Read, Write, Edit, Bash, Grep, Glob
---

You have an isolated copy of the repository. Make changes freely.
If the refactoring succeeds, the changes can be merged back.
If it fails, the worktree is discarded with no impact on the main branch.

Worktree 격리는 코드베이스를 망가뜨릴 수 있는 실험적 작업에 필수적입니다.

병렬 서브에이전트

Claude Code는 최대 10개의 병렬 서브에이전트를 지원합니다.⁵ 독립적인 조사 작업에는 병렬 실행을 사용하세요.

> Have three explore agents search in parallel:
> 1. Authentication code
> 2. Database models
> 3. API routes

각 에이전트는 자체 컨텍스트 윈도우에서 실행되며 관련 코드를 찾아 요약을 반환합니다. 메인 컨텍스트는 깨끗하게 유지됩니다.

재귀 가드

생성 한도가 없으면 에이전트는 다른 에이전트에 위임하고 그 에이전트는 또 다른 에이전트에 위임하며, 각자 컨텍스트를 잃고 토큰을 소진합니다. 재귀 가드 패턴은 예산을 강제합니다.¹⁶

#!/bin/bash
# recursion-guard.sh — enforce spawn budget
CONFIG_FILE="${HOME}/.claude/configs/recursion-limits.json"
STATE_FILE="${HOME}/.claude/state/recursion-depth.json"

MAX_DEPTH=2
MAX_CHILDREN=5
DELIB_SPAWN_BUDGET=2
DELIB_MAX_AGENTS=12

# Read current depth
current_depth=$(jq -r '.depth // 0' "$STATE_FILE" 2>/dev/null)

if [[ "$current_depth" -ge "$MAX_DEPTH" ]]; then
    echo "BLOCKED: Maximum recursion depth ($MAX_DEPTH) reached" >&2
    exit 2
fi

# Increment depth using safe arithmetic (not ((VAR++)) with set -e)
new_depth=$((current_depth + 1))
jq --argjson d "$new_depth" '.depth = $d' "$STATE_FILE" > "${STATE_FILE}.tmp"
mv "${STATE_FILE}.tmp" "$STATE_FILE"

핵심 교훈: 깊이 제한뿐 아니라 생성 예산을 사용하세요. 깊이 기반 제한은 부모-자식 체인을 추적하지만(깊이 3에서 차단) 너비는 놓칩니다. 깊이 1에 23개의 에이전트가 있어도 여전히 “깊이 1”입니다. 생성 예산은 부모당 활성 자식의 총 수를 추적하며 설정 가능한 최대값으로 제한합니다. 예산 모델은 프록시 지표(너무 많은 중첩 수준)가 아니라 실제 실패 모드(총 에이전트가 너무 많음)에 대응합니다.⁷

에이전트 팀 (Research Preview)

에이전트 팀은 여러 Claude Code 인스턴스를 조정합니다. 이들은 독립적으로 작업하면서 공유 메일박스와 작업 목록을 통해 소통하고 서로의 결과를 검증할 수 있습니다.⁵

활성화 방법: export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

에이전트 팀 vs 서브에이전트 사용 시점:

멀티 에이전트 오케스트레이션

단일 에이전트 AI 시스템에는 구조적인 사각지대가 있습니다. 자신의 가정을 스스로 검증할 수 없다는 점입니다.⁷ 멀티 에이전트 심의는 결정이 확정되기 전에 여러 관점에서 독립적인 평가를 강제합니다.

교차 툴 오케스트레이션 (2026년 4월): Google은 4월 7일 Scion을 오픈소스로 공개했습니다. Claude Code, Gemini CLI, 그리고 다른 “심층 에이전트”를 동시 프로세스로 실행하는 멀티 에이전트 하이퍼바이저로, 각각 격리된 컨테이너, git worktree, 자격 증명을 갖습니다. 로컬, 허브, 또는 Kubernetes에서 실행됩니다. 명시적인 철학은 “제약보다 격리(isolation over constraints)”입니다. 에이전트는 프롬프트가 아닌 인프라 계층에서 강제되는 경계 안에서 높은 자율성을 가지고 실행됩니다.²⁵ 이는 서브에이전트 격리 논리를 서로 다른 툴 벤더로 확장합니다. 워크플로우가 Claude와 OpenAI 모델을 아우른다면, Scion은 에이전트별 worktree와 자격 증명 격리를 갖춘 교차 툴 서브에이전트의 첫 번째 실질적인 레퍼런스 구현입니다.

토론은 만병통치약이 아닙니다: M3MAD-Bench 연구 클러스터(2026년 초)는 멀티 에이전트 토론이 정체되며, 오도하는 합의에 의해 전복될 수 있음을 발견했습니다. 다른 에이전트들이 자신 있게 틀린 답을 주장하면 타당한 논증이 패배합니다.²⁶ Tool-MAD는 각 에이전트에게 이질적인 툴 접근 권한을 부여하고 판정 단계에서 Faithfulness/Relevance 점수를 사용함으로써 이를 개선합니다. 토론 방식의 오케스트레이션을 구축한다면, (a) 에이전트별 툴 이질성과 (b) 에이전트가 많을수록 더 나은 답이 나온다고 가정하기보다 정량적 판정 점수화에 투자하세요.

최소 실용 심의(Minimum Viable Deliberation)

2개의 에이전트와 1개의 규칙으로 시작하세요. 에이전트는 서로의 작업을 보기 전에 독립적으로 평가해야 합니다.⁷

Decision arrives
  |
  v
Confidence check: is this risky, ambiguous, or irreversible?
  |
  +-- NO  -> Single agent decides (normal flow)
  |
  +-- YES -> Spawn 2 agents with different system prompts
             Agent A: "Argue FOR this approach"
             Agent B: "Argue AGAINST this approach"
             |
             v
             Compare findings
             |
             +-- Agreement with different reasoning -> Proceed
             +-- Genuine disagreement -> Investigate the conflict
             +-- Agreement with same reasoning -> Suspect herding

이 패턴이 가치의 80%를 커버합니다. 그 외의 모든 것은 점진적인 개선을 더할 뿐입니다.

신뢰도 트리거(The Confidence Trigger)

모든 작업에 심의가 필요한 것은 아닙니다. 신뢰도 점수화 모듈은 네 가지 차원을 평가합니다.¹⁷

1. 모호성(Ambiguity) - 질의에 여러 유효한 해석이 있는가?
2. 도메인 복잡도(Domain complexity) - 전문 지식이 필요한가?
3. 중대성(Stakes) - 결정이 되돌릴 수 있는가?
4. 컨텍스트 의존성(Context dependency) - 더 넓은 시스템에 대한 이해가 필요한가?

점수는 세 가지 수준으로 매핑됩니다.

임계값은 작업 유형에 따라 조정됩니다. 보안 결정은 0.85의 합의를 요구합니다. 문서 변경은 0.50만 있으면 됩니다. 이는 위험한 결정이 면밀한 검토를 받도록 보장하면서 단순 작업에 대한 과잉 엔지니어링을 방지합니다.⁷

상태 머신(The State Machine)

일곱 개의 단계가 있으며, 각 단계는 이전 단계를 통과해야만 진입할 수 있습니다.⁷

IDLE -> RESEARCH -> DELIBERATION -> RANKING -> PRD_GENERATION -> COMPLETE
                                                                    |
                                                              (or FAILED)

RESEARCH: 독립적인 에이전트들이 주제를 조사합니다. 각 에이전트는 서로 다른 페르소나(Technical Architect, Security Analyst, Performance Engineer 등)를 부여받습니다. 컨텍스트 격리는 조사 단계에서 에이전트들이 서로의 결과물을 볼 수 없도록 보장합니다.

DELIBERATION: 에이전트들은 모든 조사 결과를 보고 대안을 생성합니다. Debate 에이전트는 충돌을 식별합니다. Synthesis 에이전트는 서로 모순되지 않는 결과를 결합합니다.

RANKING: 각 에이전트는 가중치가 부여된 5가지 차원에 걸쳐 제안된 모든 접근 방식에 점수를 매깁니다.

2단 게이트 검증 아키텍처(The Two-Gate Validation Architecture)

두 개의 검증 게이트가 서로 다른 단계에서 문제를 포착합니다.⁷

Gate 1: 합의 검증(Consensus Validation) (PostToolUse hook). 각 심의 에이전트가 완료된 직후 실행됩니다. 1. 단계가 최소한 RANKING에 도달해야 함 2. 최소 2명의 에이전트가 완료(구성 가능) 3. 합의 점수가 작업별 적응형 임계값을 충족 4. 어떤 에이전트라도 반대 의견을 제시했다면, 그 우려 사항은 문서화되어야 함

Gate 2: 프라이드 체크(Pride Check) (Stop hook). 세션이 종료되기 전에 실행됩니다. 1. 다양한 방법론: 여러 고유한 페르소나가 대표됨 2. 모순 투명성: 반대 의견에 문서화된 근거가 있음 3. 복잡성 처리: 최소 2개의 대안이 생성됨 4. 합의 신뢰도: 강함(0.85 초과) 또는 보통(0.70-0.84)으로 분류됨 5. 개선 증거: 최종 신뢰도가 초기 신뢰도를 상회함

수명 주기의 서로 다른 시점에 있는 두 hook는 실패가 실제로 발생하는 방식과 일치합니다. 어떤 실패는 즉각적이고(낮은 점수), 어떤 실패는 점진적입니다(낮은 다양성, 누락된 반대 의견 문서).⁷

합의가 위험한 이유(Why Agreement Is Dangerous)

Charlan Nemeth는 1986년부터 2018년 저서 In Defense of Troublemakers에 이르기까지 소수 의견의 반대를 연구했습니다. 반대자가 있는 그룹은 빠르게 합의에 도달하는 그룹보다 더 나은 결정을 내립니다. 반대자가 옳을 필요는 없습니다. 반대 행위 자체가 다수가 그렇지 않으면 건너뛸 가정들을 검토하도록 강제합니다.¹⁸

Wu 외 연구진은 LLM 에이전트가 진정으로 토론할 수 있는지를 검증하였고, 불일치에 대한 구조적 유인이 없으면 에이전트들이 정확성과 무관하게 가장 자신감 있게 들리는 초기 응답으로 수렴한다는 사실을 발견했습니다.¹⁹ Liang 외 연구진은 그 근본 원인을 “사고의 퇴행(Degeneration-of-Thought)”으로 규정했습니다. LLM이 어떤 입장에 대한 확신을 한번 확립하면, 자기 반성은 새로운 반대 논거를 생성할 수 없어 멀티 에이전트 평가가 구조적으로 필수적이 됩니다.²⁰

독립성이 핵심적인 설계 제약입니다. 서로의 결과물을 볼 수 있는 상태에서 동일한 배포 전략을 평가한 두 에이전트는 0.45와 0.48의 점수를 냈습니다. 가시성 없이 동일한 에이전트들: 0.45와 0.72. 0.48과 0.72의 격차가 바로 동조(herding)의 비용입니다.⁷

가짜 합의 감지(Detecting Fake Agreement)

동조 감지 모듈은 에이전트들이 진정한 평가 없이 동의하고 있음을 시사하는 패턴을 추적합니다.⁷

점수 군집화(Score clustering): 모든 에이전트가 10점 척도에서 0.3점 이내로 점수를 매긴다는 것은 독립적인 평가가 아니라 공유된 컨텍스트 오염을 시사합니다. 인증 리팩토링을 평가한 다섯 에이전트가 모두 7.1에서 7.4 사이의 보안 위험 점수를 냈을 때, 새로운 컨텍스트 격리로 재실행하자 점수는 5.8-8.9로 퍼졌습니다.

상투적 반대(Boilerplate dissent): 에이전트들이 독립적인 반대 의견을 생성하기보다 서로의 우려 표현을 복제합니다.

부재하는 소수 관점(Absent minority perspectives): 상충되는 우선순위를 가진 페르소나들로부터의 만장일치 승인(Security Analyst와 Performance Engineer가 모든 것에 동의하는 경우는 드뭅니다).

동조 감지기는 명백한 사례들(에이전트들이 너무 빠르게 수렴하는 심의의 대략 10-15%)을 포착합니다. 나머지 85-90%에 대해서는 합의 및 프라이드 체크 게이트가 충분한 검증을 제공합니다.

심의에서 효과가 없었던 것(What Didn’t Work in Deliberation)

자유 형식 토론 라운드. 데이터베이스 인덱싱 논의를 위한 3라운드의 왕복 텍스트 토론은 7,500 토큰의 토론을 생성했습니다. 1라운드: 진정한 불일치. 2라운드: 입장 재진술. 3라운드: 다른 단어로 표현된 동일한 논증. 구조화된 차원 점수화가 자유 형식 토론을 대체하여 비용을 60% 절감하면서도 랭킹 품질을 향상시켰습니다.⁷

단일 검증 게이트. 첫 번째 구현은 세션 종료 시점에 검증 hook 하나를 실행했습니다. 한 에이전트가 0.52의 합의 점수(임계값 미만)로 심의를 완료한 후, 세션 종료 hook가 실패를 플래그하기 전까지 20분 동안 관련 없는 작업을 계속했습니다. 두 개의 게이트(하나는 작업 완료 시, 다른 하나는 세션 종료 시)로 분할함으로써 동일한 문제들을 수명 주기의 서로 다른 시점에 포착했습니다.⁷

심의 비용(Cost of Deliberation)

각 조사 에이전트는 대략 5,000 토큰의 컨텍스트를 처리하고 2,000-3,000 토큰의 결과를 생성합니다. 3개의 에이전트라면, 결정당 추가로 15,000-24,000 토큰입니다. 10개의 에이전트라면, 대략 50,000-80,000 토큰입니다.⁷

현재 Opus 요금 기준으로, 3개 에이전트 심의는 대략 $0.68-0.90입니다. 10개 에이전트 심의는 $2.25-3.00입니다. 시스템은 대략 10%의 결정에 대해 심의를 트리거하므로, 모든 결정에 걸친 분할 상환 비용은 세션당 $0.23-0.30입니다. 이것이 가치 있는지는 잘못된 결정이 어떤 비용을 초래하는지에 달려 있습니다.

언제 심의할 것인가(When to Deliberate)

CLAUDE.md 설계

CLAUDE.md는 사람을 위한 README가 아니라 AI 에이전트를 위한 운영 정책입니다.²¹ 에이전트는 여러분이 왜 conventional commits를 사용하는지 이해할 필요가 없습니다. 실행해야 할 정확한 명령과 “완료”가 어떤 모습인지를 알아야 합니다.

우선순위 계층

규칙 파일은 자동으로 로드되어 CLAUDE.md를 어수선하게 만들지 않으면서 구조화된 컨텍스트를 제공합니다.⁶

무시되는 요소

다음 패턴들은 에이전트 동작에서 관찰 가능한 변화를 일으키지 못하는 것으로 일관되게 확인되었습니다.²¹

명령이 없는 산문 단락. “우리는 깔끔하고 잘 테스트된 코드를 중요시한다”는 문서화일 뿐 운영 지침이 아닙니다. 에이전트는 이를 읽고도 실행 가능한 지시가 없기 때문에 테스트 없이 코드를 작성하게 됩니다.

모호한 지시. “데이터베이스 마이그레이션에 주의하세요”는 제약 조건이 아닙니다. “마이그레이션 적용 전에 alembic check를 실행하세요. 다운그레이드 경로가 없으면 중단하세요.”가 제약 조건입니다.

상충하는 우선순위. “빠르게 움직이고 신속하게 배포한다” + “포괄적인 테스트 커버리지를 보장한다” + “런타임을 5분 이내로 유지한다” + “모든 커밋 전에 전체 통합 테스트를 실행한다.” 에이전트는 이 네 가지를 동시에 만족시킬 수 없고, 결국 검증 단계를 건너뛰는 쪽으로 기울어집니다.²¹

강제 수단 없는 스타일 가이드. ruff check --select D 같은 실제 검증 수단 없이 “Google Python Style Guide를 따르세요”라고 하면 에이전트가 준수 여부를 확인할 수단이 없습니다.

효과적인 방식

명령 우선 지시:

## Build and Test Commands
- Install: `pip install -r requirements.txt`
- Lint: `ruff check . --fix`
- Format: `ruff format .`
- Test: `pytest -v --tb=short`
- Type check: `mypy app/ --strict`
- Full verify: `ruff check . && ruff format --check . && pytest -v`

완료 정의:

## Definition of Done
A task is complete when ALL of the following pass:
1. `ruff check .` exits 0
2. `pytest -v` exits 0 with no failures
3. `mypy app/ --strict` exits 0
4. Changed files have been staged and committed
5. Commit message follows conventional format: `type(scope): description`

작업별로 구성된 섹션:

## When Writing Code
- Run `ruff check .` after every file change
- Add type hints to all new functions

## When Reviewing Code
- Check for security issues: `bandit -r app/`
- Verify test coverage: `pytest --cov=app --cov-fail-under=80`

## When Releasing
- Update version in `pyproject.toml`
- Run full suite: `pytest -v && ruff check . && mypy app/`

에스컬레이션 규칙:

## When Blocked
- If tests fail after 3 attempts: stop and report the failing test with full output
- If a dependency is missing: check `requirements.txt` first, then ask
- Never: delete files to resolve errors, force push, or skip tests

작성 순서

처음부터 시작한다면 다음 우선순위 순서로 섹션을 추가하세요.²¹

1. Build and test commands (에이전트가 유용한 작업을 하려면 이게 먼저 필요합니다)
2. Definition of done (거짓 완료 보고를 방지합니다)
3. Escalation rules (파괴적인 우회 조치를 방지합니다)
4. 작업별로 구성된 섹션 (관련 없는 지시의 파싱을 줄여줍니다)
5. 디렉토리 스코핑 (모노레포의 경우 서비스별 지시를 격리시킵니다)

처음 네 가지가 제대로 작동하기 전까지는 스타일 환경설정은 건너뛰세요.

파일 임포트

CLAUDE.md 안에서 다른 파일을 참조하세요.

See @README.md for project overview
Coding standards: @docs/STYLE_GUIDE.md
API documentation: @docs/API.md
Personal preferences: @~/.claude/preferences.md

임포트 구문: 상대 경로(@docs/file.md), 절대 경로(@/absolute/path.md), 또는 홈 디렉토리(@~/.claude/file.md). 최대 깊이는 임포트 5단계입니다.⁶

도구 간 지시 호환성

AGENTS.md는 주요 AI 코딩 도구 전반에서 인정받는 개방형 표준입니다.²¹ 팀에서 여러 도구를 사용한다면 AGENTS.md를 정식 소스로 작성하고 관련 섹션을 도구별 파일로 미러링하세요.

AGENTS.md의 패턴(명령 우선, 완료 정의, 작업별 구성)은 도구와 관계없이 어떤 지시 파일에서도 동작합니다. 서로 어긋나는 병렬 지시 세트를 유지하지 마세요. 하나의 정식 소스를 작성하고 미러링하세요.

지시 테스트하기

에이전트가 실제로 여러분의 지시를 읽고 따르는지 확인하세요.

# Check active instructions
claude --print "What instructions are you following for this project?"

# Verify specific rules are active
claude --print "What is your definition of done?"

결정적인 검증: 에이전트에게 빌드 명령을 설명해 보라고 해보세요. 그대로 재현하지 못한다면 지시가 너무 장황하거나(내용이 컨텍스트 밖으로 밀려났거나), 너무 모호하거나(에이전트가 실행 가능한 지시를 추출할 수 없거나), 애초에 발견되지 않고 있는 것입니다. GitHub의 2,500개 저장소 분석에서 대부분의 실패 원인은 모호함이었습니다.²¹

프로덕션 패턴

Opus 4.7 장기 호라이즌 패턴 (2026년 4월)

Claude Opus 4.7 (2026년 4월 16일)은 harness가 방어해야 할 대상을 바꾸는 특정 기능들과 함께 출시되었습니다:²⁹

• 도구 실패 복원력: Opus 4.7은 Opus 4.6 세션을 중단시켰던 도구 실패를 계속 처리합니다. 서브에이전트 코드에서 방어적 재시도 래퍼를 줄일 수는 있지만, 완전히 제거할 수는 없습니다. hook 레벨의 가드는 유지하고, 프롬프트 내 “도구가 실패하면 3번 재시도하세요” 같은 스캐폴딩은 정리하세요.
• xhigh 효과 티어 (Opus-4.7 전용): high와 max 사이에 위치합니다. 코딩 및 에이전트 워크로드에 권장되는 기본값입니다. 장기 실행 서브에이전트에서 xhigh는 하위 비례적 토큰 비용으로 high보다 의미 있게 뛰어난 성능을 보입니다. max는 여전히 단발성 고난도 추론에 적합한 선택이며, xhigh는 지속적인 작업에 더 좋습니다.
• 토큰 예산 상한: output_config.task_budget (beta 헤더 task-budgets-2026-03-13)을 통해 에이전트 실행마다 설정 가능합니다. 모델은 진행 중인 카운트다운을 확인하며 예기치 않게 소진되는 대신 작업 범위를 예산에 맞게 우아하게 조정합니다. 짧은 프롬프트의 품질을 희생하지 않으면서 예측 가능한 토큰 지출을 원하는 에이전트 루프에 사용하세요.
• 암묵적 필요 인식: “암묵적 필요” 테스트를 통과한 최초의 Claude 모델로, 사용자의 문자 그대로의 요청이 실제로 필요한 것을 충분히 명시하지 않을 때를 인식합니다. 이로 인해 CLAUDE.md의 “명확화 규칙” 섹션이 덜 필요해집니다. CLAUDE.md가 “사용자가 Y를 요청할 때 X도 고려하라”는 가드레일로 200줄이 되어 있다면, 이제 기본적으로 다루어지는 항목들은 정리하세요.

Quality Loop

모든 중요한 변경에 대한 필수 검토 프로세스입니다:

1. Implement - 코드 작성
2. Review - 모든 줄을 다시 읽습니다. 오타, 로직 오류, 불명확한 섹션 파악
3. Evaluate - evidence gate 실행. 패턴, 엣지 케이스, 테스트 커버리지 확인
4. Refine - 모든 이슈 수정. “나중에”로 미루지 마세요
5. Zoom Out - 통합 지점, import, 인접 코드의 회귀 확인
6. Repeat - evidence gate 기준 중 하나라도 실패하면 4단계로 돌아갑니다
7. Report - 무엇이 바뀌었는지, 어떻게 검증했는지 나열하고 구체적인 증거를 인용합니다

Evidence Gate

“I believe”와 “it should”는 증거가 아닙니다. 파일 경로, 테스트 출력, 또는 구체적인 코드를 인용하세요.

어떤 행에도 증거를 제시할 수 없다면 Refine으로 돌아가세요.²²

오류 처리 패턴

원자적 파일 쓰기(Atomic file writes). 여러 에이전트가 동일한 상태 파일에 동시에 쓰면 JSON가 손상됩니다. .tmp 파일에 쓴 다음 원자적으로 mv하세요. OS는 동일한 파일시스템에서 mv가 원자적임을 보장합니다.¹⁷

# Atomic state update
jq --argjson d "$new_depth" '.depth = $d' "$STATE_FILE" > "${STATE_FILE}.tmp"
mv "${STATE_FILE}.tmp" "$STATE_FILE"

상태 손상 복구. 상태가 손상되면, 복구 패턴은 크래시하는 대신 안전한 기본값에서 재생성합니다:¹⁶

if ! jq -e '.depth' "$RECURSION_STATE_FILE" &>/dev/null; then
    # Corrupted state file, recreate with safe defaults
    echo '{"depth": 0, "agent_id": "root", "parent_id": null}' > "$RECURSION_STATE_FILE"
    echo "- Recursion state recovered (was corrupted)"
fi

((VAR++)) bash 함정. ((VAR++))는 VAR이 0일 때 종료 코드 1을 반환합니다. 0++이 0으로 평가되고, bash는 이를 false로 처리하기 때문입니다. set -e가 활성화된 상태에서 이것은 스크립트를 종료시킵니다. 대신 VAR=$((VAR + 1))를 사용하세요.¹⁶

Blast Radius 분류

모든 에이전트 액션을 blast radius로 분류하고 그에 따라 게이팅하세요:²

Remote Control (모든 브라우저나 모바일 앱에서 로컬 Claude Code에 연결)은 “External” 게이트를 블로킹 대기에서 비동기 알림으로 바꿉니다. 에이전트는 다음 작업에서 계속 작업하고, 당신은 휴대폰에서 이전 작업을 검토합니다.²

자율 실행을 위한 작업 명세

효과적인 자율 작업은 세 가지 요소를 포함합니다: 목표, 완료 기준, 그리고 컨텍스트 포인터:¹⁶

OBJECTIVE: Implement multi-agent deliberation with consensus validation.

COMPLETION CRITERIA:
- All tests in tests/test_deliberation_lib.py pass (81 tests)
- post-deliberation.sh validates consensus above 70% threshold
- recursion-guard.sh enforces spawn budget (max 12 agents)
- No Python type errors (mypy clean)

CONTEXT:
- Follow patterns in lib/deliberation/state_machine.py
- Consensus thresholds in configs/deliberation-config.json
- Spawn budget model: agents inherit budget, not increment depth

기준은 기계 검증 가능해야 합니다: 테스트 통과/실패, 린터 출력, HTTP 상태 코드, 파일 존재 확인. 에이전트에게 “테스트가 통과하는 테스트를 작성하라”고 요청한 초기 작업은 assert True와 assert 1 == 1을 생성했습니다. 기술적으로는 맞습니다. 실질적으로는 쓸모없습니다.¹⁶

주의해야 할 실패 모드

구체적인 세션 트레이스

5개 스토리가 있는 PRD를 처리하는 자율 실행의 세션 트레이스입니다:²

1. SessionStart 발화. Dispatcher가 주입합니다: 현재 날짜, 프로젝트 감지, 철학 제약, 비용 추적 초기화. 5개 hook, 총 180ms.

2. 에이전트가 PRD를 읽고 첫 번째 스토리를 계획합니다. UserPromptSubmit이 발화합니다. Dispatcher가 주입합니다: 활성 프로젝트 컨텍스트, 세션 드리프트 베이스라인.

3. 에이전트가 Bash를 호출하여 테스트를 실행합니다. PreToolUse:Bash가 발화합니다. 자격 증명 확인, 샌드박스 검증, 프로젝트 감지. 90ms. 테스트 실행. PostToolUse:Bash가 발화합니다: 활동 하트비트 로깅, 드리프트 확인.

4. 에이전트가 Write를 호출하여 파일을 생성합니다. PreToolUse:Write가 발화합니다: 파일 범위 확인. PostToolUse:Write가 발화합니다: 린트 확인, 커밋 추적.

5. 에이전트가 스토리를 완료합니다. Stop이 발화합니다. 품질 게이트 확인: 에이전트가 증거를 인용했는가? 헷징 언어? diff에 TODO 주석? 어떤 확인이든 실패하면 exit 2가 반환되고 에이전트는 계속합니다.

6. 독립적 검증: 새로운 에이전트가 이전 에이전트의 자체 보고를 신뢰하지 않고 테스트 스위트를 실행합니다.

7. 세 개의 코드 리뷰 에이전트가 병렬로 생성됩니다. 각자가 diff를 독립적으로 검토합니다. 어떤 리뷰어든 CRITICAL을 표시하면 스토리는 대기열로 돌아갑니다.

8. 스토리 통과. 다음 스토리 로딩. 5개 모든 스토리에 대해 사이클이 반복됩니다.

5개 스토리에 걸쳐 발화한 총 hook: ~340. hook에 소요된 총 시간: ~12초. 그 오버헤드는 단일 밤샘 실행에서 3번의 자격 증명 누출, 1번의 파괴적 명령, 2번의 불완전한 구현을 방지했습니다.

케이스 스터디: 밤샘 PRD 처리

프로덕션 harness가 8번의 밤샘 세션에 걸쳐 12개의 PRD (47개 스토리)를 처리했습니다. 메트릭은 처음 4개 PRD (최소 harness: CLAUDE.md만)를 마지막 8개 (전체 harness: hooks, skills, 품질 게이트, 멀티 에이전트 리뷰)와 비교합니다.

두 건의 자격 증명 누출은 API 키 로테이션과 다운스트림 서비스 감사를 요구했습니다: 대략 4시간의 인시던트 대응. 이를 방지한 harness 오버헤드는 스토리당 2.4초의 bash였습니다. 허위 완료율은 35%에서 4%로 떨어졌는데, Stop hook이 에이전트가 완료를 보고하기 전에 독립적으로 테스트를 실행했기 때문입니다.

보안 고려사항

신뢰할 수 있는 에이전트의 5가지 원칙 (Anthropic, 2026년 4월)

Anthropic는 2026년 4월 9일 에이전트 신뢰성을 위한 공식 프레임워크를 발표했습니다.²⁷ 이 5가지 원칙은 본 가이드의 Evidence Gate 사고방식과 병행하며 이를 확장합니다:

Anthropic는 또한 MCP를 Linux Foundation의 Agentic AI Foundation에 기증하여, AGENTS.md(현재 OpenAI, Google, Cursor, Factory, Sourcegraph와 공동 관리)와 합류했습니다. 에이전트 상호 운용성 표준은 이제 벤더 중립적입니다.²⁷

Skill 샌드박스 도구: skills를 공격 표면으로 취급하는 팀을 위해, Permiso의 SandyClaw(2026년 4월 2일 출시)는 skills를 전용 샌드박스에서 실행하고 Sigma/YARA/Nova/Snort 탐지로부터 근거 기반 판정을 제공합니다. skill 샌드박스 범주의 첫 번째 제품입니다.²⁸

샌드박스

Claude Code는 OS 수준 격리(macOS의 seatbelt, Linux의 bubblewrap)를 사용하여 네트워크 액세스 및 파일 시스템 작업을 제한하는 선택적 샌드박스 모드(settings.json 또는 /sandbox 명령을 통해 활성화)를 지원합니다. 활성화되면 샌드박스는 모델이 임의의 네트워크 요청을 하거나 프로젝트 디렉토리 외부의 파일에 액세스하는 것을 방지합니다. 샌드박싱이 없으면 Claude Code는 개별 도구 호출을 승인하거나 거부하는 권한 기반 모델을 사용합니다.¹³

권한 경계

권한 시스템은 여러 수준에서 작업을 게이트합니다:

프롬프트 인젝션 방어

Skills와 hooks는 프롬프트 인젝션에 대한 심층 방어를 제공합니다:

도구 제한이 있는 Skills는 손상된 프롬프트가 쓰기 액세스를 얻는 것을 방지합니다:

allowed-tools: Read, Grep, Glob

PreToolUse hooks는 모델이 어떻게 프롬프트되었는지와 상관없이 모든 도구 호출을 검증합니다:

# Block credential file access regardless of prompt
if echo "$FILE_PATH" | grep -qE "\.(env|pem|key|credentials)$"; then
    echo "BLOCKED: Sensitive file access" >&2
    exit 2
fi

Subagent 격리는 폭발 반경을 제한합니다. permissionMode: plan을 사용하는 subagent는 프롬프트가 손상되더라도 변경을 할 수 없습니다.

Hook 보안

환경 변수를 헤더에 보간하는 HTTP hooks는 임의의 환경 변수 탈취를 방지하기 위해 명시적인 allowedEnvVars 목록이 필요합니다:¹³

{
  "type": "http",
  "url": "https://api.example.com/notify",
  "headers": {
    "Authorization": "Bearer $MY_TOKEN"
  },
  "allowedEnvVars": ["MY_TOKEN"]
}

인간-에이전트 책임 분담

에이전트 아키텍처의 보안은 인간과 에이전트 책임 간의 명확한 분담이 필요합니다:¹⁷

패턴: 인간은 조직적 맥락, 윤리적 판단 또는 전략적 방향이 필요한 결정을 소유합니다. 에이전트는 넓은 가능성 공간에 대한 계산적 탐색이 필요한 결정을 소유합니다. Hooks는 경계를 집행합니다.

재귀적 Hook 집행

Hooks는 subagent 작업에 대해서도 발동됩니다.¹³ Claude가 Agent 도구를 통해 subagent를 생성하면, PreToolUse 및 PostToolUse hooks가 subagent가 사용하는 모든 도구에 대해 실행됩니다. 재귀적 hook 집행이 없으면 subagent가 안전 게이트를 우회할 수 있습니다. SubagentStop 이벤트를 사용하면 subagent가 완료될 때 정리 또는 검증을 실행할 수 있습니다.

이것은 선택 사항이 아닙니다. 보안 hooks 없이 subagent를 생성하는 에이전트는, 여러분의 게이트가 메인 대화를 감시하며 아무것도 하지 않는 동안 main에 force-push하거나, 자격 증명 파일을 읽거나, 파괴적인 명령을 실행할 수 있는 에이전트입니다.

아키텍처로서의 비용

비용은 운영상의 부차적 고려사항이 아니라 아키텍처 결정입니다.² 세 가지 수준이 있습니다:

토큰 수준. 시스템 프롬프트 압축. 튜토리얼 코드 예제를 제거하고(모델은 API들을 알고 있습니다), 파일 간 중복된 규칙을 축소하며, 설명을 제약 조건으로 대체합니다. “민감한 경로와 일치하는 도구 호출을 거부하라”는 자격 증명을 읽어서는 안 되는 이유에 대한 15줄의 설명과 동일한 작업을 수행합니다.

에이전트 수준. 긴 대화보다는 새로운 스폰. 자율 실행의 각 스토리는 깨끗한 컨텍스트를 가진 새 에이전트를 얻습니다. 각 에이전트가 새로 시작하므로 컨텍스트가 부풀지 않습니다. 메모리 대신 브리핑: 모델은 30단계의 누적된 컨텍스트를 탐색하는 것보다 명확한 브리핑을 더 잘 실행합니다.

아키텍처 수준. 작업이 무상태일 때는 MCP보다 CLI 우선. 일회성 평가를 위한 claude --print 호출은 비용이 적게 들고 연결 오버헤드를 추가하지 않습니다. MCP는 도구가 영구 상태 또는 스트리밍이 필요할 때 의미가 있습니다.

결정 프레임워크

각 메커니즘을 사용할 시기:

Skills vs Hooks vs Subagents

FAQ

훅이 몇 개부터 너무 많은가요?

제약은 개수가 아니라 성능입니다. 각 훅은 동기적으로 실행되므로, 총 훅 실행 시간이 매칭된 모든 도구 호출에 더해집니다. 사용자 수준과 프로젝트 수준 설정에 걸친 95개의 훅도 각 훅이 200ms 미만에 완료된다면 눈에 띄는 지연 없이 실행됩니다. 주의해야 할 임계점은 다음과 같습니다. PostToolUse 훅이 모든 파일 편집에 500ms 이상을 추가한다면 세션이 느리게 느껴집니다. 배포 전에 time으로 훅을 프로파일링하세요.¹⁴

훅이 Claude Code의 명령 실행을 차단할 수 있나요?

네. PreToolUse 훅은 종료 코드 2로 종료하여 모든 도구 동작을 차단할 수 있습니다. Claude Code는 대기 중인 동작을 취소하고 훅의 stderr 출력을 모델에 표시합니다. Claude는 거부 사유를 확인하고 더 안전한 대안을 제안합니다. 종료 코드 1은 동작이 그대로 진행되는 비차단 경고입니다.³

훅 설정 파일은 어디에 두어야 하나요?

훅 설정은 프로젝트 수준 훅의 경우 .claude/settings.json에 (저장소에 커밋되어 팀과 공유), 사용자 수준 훅의 경우 ~/.claude/settings.json에 (개인용, 모든 프로젝트에 적용) 저장합니다. 두 파일이 모두 존재할 때는 프로젝트 수준 훅이 우선합니다. 작업 디렉터리 문제를 피하려면 스크립트 파일에는 절대 경로를 사용하세요.¹⁴

모든 결정에 deliberation이 필요한가요?

아닙니다. 신뢰도 모듈은 네 가지 차원(모호성, 복잡성, 위험도, 컨텍스트 의존성)에 걸쳐 결정을 점수화합니다. 전체 신뢰도가 0.70 미만인 결정만 deliberation을 트리거하며, 이는 전체 결정의 약 10%에 해당합니다. 문서 수정, 변수 이름 변경, 일상적인 편집은 deliberation을 완전히 건너뜁니다. 보안 아키텍처, 데이터베이스 스키마 변경, 되돌릴 수 없는 배포는 일관되게 deliberation을 트리거합니다.⁷

의견 불일치를 만들어내도록 설계된 시스템을 어떻게 테스트하나요?

성공 경로와 실패 경로를 모두 테스트하세요. 성공: 에이전트들이 생산적으로 의견이 갈리고 합의에 도달합니다. 실패: 에이전트들이 너무 빨리 수렴하거나, 결코 수렴하지 않거나, 스폰 예산을 초과합니다. 종단간 테스트는 결정론적인 에이전트 응답으로 각 시나리오를 시뮬레이션하여, 두 검증 게이트가 문서화된 모든 실패 모드를 잡아내는지 확인합니다. 프로덕션 deliberation 시스템은 세 계층에 걸쳐 141개의 테스트를 실행합니다. 48개의 bash 통합 테스트, 81개의 Python 단위 테스트, 12개의 종단간 파이프라인 시뮬레이션입니다.⁷

Deliberation의 지연 영향은 어느 정도인가요?

3-에이전트 deliberation은 30-60초의 실시간을 추가합니다(에이전트는 Agent tool을 통해 순차적으로 실행됩니다). 10-에이전트 deliberation은 2-4분을 추가합니다. consensus와 pride check 훅은 각각 200ms 미만에 실행됩니다. 주된 병목은 오케스트레이션 오버헤드가 아니라 에이전트당 LLM 추론 시간입니다.⁷

CLAUDE.md 파일은 얼마나 길어야 하나요?

각 섹션은 50줄 미만, 전체 파일은 150줄 미만으로 유지하세요. 긴 파일은 컨텍스트 창에 의해 잘리므로, 가장 중요한 지시 사항을 앞쪽에 배치하세요. 스타일 선호 사항보다 명령과 종결 정의를 먼저 두세요.²¹

Claude Code 외의 도구에서도 작동할 수 있나요?

아키텍처 원칙(결정론적 게이트로서의 훅, 도메인 전문성으로서의 skills, 격리된 컨텍스트로서의 subagents, 메모리로서의 파일 시스템)은 어떤 에이전트 시스템에도 개념적으로 적용됩니다. 구체적인 구현은 Claude Code의 라이프사이클 이벤트, 매처 패턴, Agent tool을 사용합니다. AGENTS.md는 동일한 패턴을 Codex, Cursor, Copilot, Amp, Windsurf로 가져갑니다.²¹ harness 패턴은 구현 세부 사항이 도구별로 다르더라도 도구 중립적입니다.

Quick Reference Card

Hook Configuration

{
  "hooks": {
    "PreToolUse": [{"matcher": "Bash", "hooks": [{"type": "command", "command": "script.sh"}]}],
    "PostToolUse": [{"matcher": "Write|Edit", "hooks": [{"type": "command", "command": "format.sh"}]}],
    "Stop": [{"matcher": "", "hooks": [{"type": "agent", "prompt": "Verify tests pass. $ARGUMENTS"}]}],
    "SessionStart": [{"matcher": "", "hooks": [{"type": "command", "command": "setup.sh"}]}]
  }
}

Skill Frontmatter

---
name: my-skill
description: What it does and when to use it. Include trigger phrases.
allowed-tools: Read, Grep, Glob
---

Subagent Definition

---
name: my-agent
description: When to invoke. Include PROACTIVELY for auto-delegation.
tools: Read, Grep, Glob, Bash
model: opus
permissionMode: plan
---

Instructions for the subagent.

종료 코드

주요 명령

파일 위치

Changelog

참고 문헌