에이전트 아키텍처: AI 기반 개발 하니스 구축하기

TL;DR: Claude Code는 파일 접근이 가능한 채팅창이 아닙니다. 문서화된 29개의 라이프사이클 이벤트를 갖춘 프로그래밍 가능한 런타임이며, 각 이벤트는 모델이 건너뛸 수 없는 셸 스크립트로 후킹할 수 있습니다. 후크를 디스패처로 쌓고, 디스패처를 skills로, skills를 에이전트로, 에이전트를 워크플로로 쌓아 올리면, 제약을 강제하고, 작업을 위임하며, 세션 간에 메모리를 보존하고, 다중 에이전트 심의를 조율하는 자율 개발 harness가 만들어집니다. 이 가이드는 단일 후크부터 10개 에이전트 합의 시스템까지 그 스택의 모든 계층을 다룹니다. 프레임워크는 전혀 필요하지 않습니다. 전부 bash와 JSON로 구현됩니다.

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

인프라 관점의 멘탈 모델은 다릅니다. AI 코딩 에이전트는 LLM 커널을 가진 프로그래밍 가능한 런타임입니다. 모델이 취하는 모든 동작은 여러분이 통제하는 후크를 거쳐 갑니다. 프롬프트가 아니라 정책을 정의하는 것입니다. 모델은 웹 서버가 nginx 규칙 안에서 작동하는 것과 같은 방식으로 여러분의 인프라 안에서 작동합니다. 여러분은 nginx 앞에 앉아 요청을 직접 입력하지 않습니다. 설정하고, 배포하고, 모니터링할 뿐이죠.

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

핵심 요점

• 후크는 실행을 보장하지만, 프롬프트는 그렇지 않습니다. 린팅, 포매팅, 보안 검사, 그리고 모델 동작과 무관하게 매번 반드시 실행되어야 하는 모든 작업에는 후크를 사용하세요. 종료 코드 2는 동작을 차단합니다. 종료 코드 1은 경고만 발생시킵니다.³
• Skills는 자동으로 활성화되는 도메인 전문성을 인코딩합니다. description 필드가 모든 것을 결정합니다. Claude는 skill을 언제 적용할지 판단할 때 키워드 매칭이 아니라 LLM 추론을 사용합니다.⁴
• subagents는 컨텍스트 비대화를 방지합니다. 탐색과 분석을 위한 격리된 컨텍스트 윈도가 메인 세션을 가볍게 유지합니다. 독립적인 subagents는 병렬로 실행하고, 워커 간 지속적인 조율이 필요할 때는 에이전트 팀을 사용하세요.⁵
• 메모리는 파일시스템에 존재합니다. 파일은 컨텍스트 윈도를 넘어 보존됩니다. CLAUDE.md, MEMORY.md, rules 디렉터리, 그리고 핸드오프 문서가 구조화된 외부 메모리 시스템을 형성합니다.⁶
• 다중 에이전트 심의는 사각지대를 잡아냅니다. 단일 에이전트는 자신의 가정을 스스로 반박할 수 없습니다. 평가 우선순위가 서로 다른 두 개의 독립 에이전트는 품질 게이트가 다룰 수 없는 구조적 결함을 잡아냅니다.⁷
• harness 패턴이 곧 시스템입니다. CLAUDE.md, 후크, skills, 에이전트, 메모리는 독립적인 기능이 아닙니다. 이들이 결합하여 여러분과 모델 사이의 결정론적 계층을 이루며, 자동화에 따라 함께 확장됩니다.

이 가이드 활용법

각 섹션은 이전 섹션 위에 쌓입니다. 마지막에 있는 Decision Framework는 문제 유형별로 적절한 메커니즘을 선택할 수 있는 조회 표를 제공합니다.

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 디렉터리는 에이전트가 프로젝트에 대해 알고 있는 내용을 정의합니다. 세션 시작 시점과 모든 압축(compaction) 이후에 자동으로 로드됩니다. 이것이 에이전트의 장기 아키텍처 기억입니다.

Extension Layer: skills는 컨텍스트에 따라 자동으로 활성화되는 도메인 전문성을 제공합니다. hooks는 일치하는 모든 도구 호출에서 발동되는 결정론적 게이트를 제공합니다. 메모리 파일은 세션 간에 상태를 유지합니다. 커스텀 agents는 특화된 subagents 구성을 제공합니다.

Orchestration Layer: 멀티 에이전트 패턴은 독립적인 에이전트들을 조율하여 리서치, 리뷰, 숙고를 수행합니다. 스폰 예산은 폭주 재귀를 방지합니다. 합의 검증은 품질을 보장합니다.

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

매니지드 vs. 셀프 호스팅 하네스 (2026년 4월)

2026년 초까지 “직접 하네스를 구축한다”는 경로가 사실상 유일한 선택지였습니다. 2026년 4월에 그 상황이 바뀌었습니다. Anthropic는 Claude Managed Agents를 퍼블릭 베타로 출시했고(4월 8일), 하네스 루프 + 도구 실행 + 샌드박스 컨테이너 + 상태 영속화를 REST API로 제공하며 표준 토큰 비용에 더해 세션-시간당 $0.08로 과금합니다. OpenAI의 Agents SDK 업데이트(4월 16일)는 동일한 분리를 공식화했습니다. 하네스와 컴퓨트를 별도 계층으로 두고, 네이티브 샌드박스 제공자(Blaxel, Cloudflare, Daytona, E2B, Modal, Runloop, Vercel)와 컨테이너 손실에서 살아남기 위한 스냅샷/재수화(rehydrate) 기능을 갖췄습니다.²³²⁴

OpenAI 측의 더 깊은 SDK 표면은 openai-agents Python v0.14.0에 도입되었습니다(2026년 4월 15일 릴리스, 4월 16일 발표). Agent의 서브클래스인 SandboxAgent에는 default_manifest, 샌드박스 명령, capabilities가 포함됩니다. Manifest는 새 워크스페이스 계약(파일, 디렉터리, 로컬 파일, Git 저장소, 환경, 사용자, 마운트)을 기술합니다. SandboxRunConfig는 실행마다 샌드박스 클라이언트, 라이브 세션 주입, manifest 오버라이드, 스냅샷, 머터리얼라이제이션 동시성 한도를 연결합니다. 내장 capabilities는 셸 액세스, 파일시스템 편집, 이미지 검사, skills, 샌드박스 메모리, 압축을 포괄합니다. 샌드박스 메모리는 실행 간에 추출된 교훈을 영속화하고 점진적으로 노출합니다. 워크스페이스는 로컬 파일, Git 저장소 항목, 원격 마운트(S3, R2, GCS, Azure Blob, S3 Files)를 지원하며, 스냅샷은 제공자 간에 이식 가능합니다. 백엔드는 UnixLocalSandboxClient, DockerSandboxClient이며, Blaxel, Cloudflare, Daytona, E2B, Modal, Runloop, Vercel용 호스티드 클라이언트는 옵셔널 extras로 제공됩니다.²⁴

Claude Code 런타임을 라이브러리로 임베드하고 싶은 Python 프로젝트의 경우 — claude 셸 호출과 Managed Agents에 대한 REST API 사이의 중간 지점 — claude-agent-sdk-python이 세 번째 옵션입니다. 4월 28-29일 시리즈(v0.1.69 → v0.1.71)는 번들된 CLI를 v2.1.123으로 올렸고, mcp 의존성의 하한을 >=1.19.0으로 끌어올렸으며(이전 버전은 인프로세스 MCP 도구의 CallToolResult 반환을 조용히 누락시켜 모델에 검증 오류 블롭만 남겼습니다), SandboxNetworkConfig를 TypeScript SDK와 스키마 동등성(allowedDomains, deniedDomains, allowManagedDomainsOnly, allowMachLookup)에 맞췄습니다.³⁰

이제 아키텍처적 분기가 실재합니다.

언제 무엇을 선택할 것인가: 셀프 호스팅은 이미 인프라 역량을 갖춘 팀, 직접 통제하는 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 시스템

Skill은 모델이 호출하는 확장 기능입니다. Claude은 사용자가 명시적으로 호출하지 않아도 컨텍스트에 따라 자동으로 Skill을 발견하고 적용합니다.⁴ 세션마다 같은 컨텍스트를 다시 설명하고 있다는 사실을 깨닫는 순간이 바로 Skill을 만들어야 할 때입니다.

Skill을 만들어야 할 때

Skill은 Claude이 항상 사용할 수 있는 지식을 위한 것입니다. 슬래시 명령어는 사용자가 명시적으로 트리거하는 동작을 위한 것입니다. 둘 사이에서 결정해야 한다면 다음을 자문해 보세요. “Claude이 이를 자동으로 적용해야 하는가, 아니면 내가 언제 실행할지 결정해야 하는가?”

Skill 만들기

Skill은 범위가 가장 넓은 것부터 좁은 것까지 네 가지 위치에 존재할 수 있습니다.⁴

모든 Skill에는 YAML frontmatter가 포함된 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

## Security Checks
When reviewing code, verify:

### Input Validation
- All user input sanitized before database operations
- Parameterized queries (no string interpolation in SQL)
- Output encoding for rendered HTML content

### Authentication
- Session tokens validated on every protected endpoint
- Permission checks before data mutations
- No hardcoded credentials or API keys in source

Frontmatter 레퍼런스

Description 필드가 전부입니다

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

나쁜 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)입니다.

컨텍스트 예산

모든 Skill description은 컨텍스트 윈도우의 1%로 동적으로 확장되는 컨텍스트 예산을 공유하며, 폴백 값은 8,000자입니다.⁴ Skill이 많다면 각 description을 간결하게 유지하고 핵심 사용 사례를 앞쪽에 배치하세요. SLASH_COMMAND_TOOL_CHAR_BUDGET 환경 변수로 예산을 재정의할 수 있지만,¹¹ 더 나은 해결책은 더 짧고 정확한 description을 작성하는 것입니다. 세션 중에 /context를 실행하면 제외된 Skill이 있는지 확인할 수 있습니다.

보조 파일과 구성

Skill은 동일한 디렉터리의 추가 파일을 참조할 수 있습니다.

~/.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이 활성화될 때 필요에 따라 이 파일들을 읽습니다. SKILL.md는 500줄 이하로 유지하고, 자세한 참고 자료는 보조 파일로 옮기세요.¹²

Git을 통한 Skill 공유

프로젝트 Skill (저장소 루트의 .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하면 Skill을 자동으로 받게 됩니다. 설치도, 구성도 필요 없습니다. 이는 팀 전체에서 전문성을 표준화하는 가장 효과적인 방법입니다.

프롬프트 라이브러리로서의 Skill

단일 목적 Skill을 넘어, 디렉터리 구조 자체가 정리된 프롬프트 라이브러리로 작동합니다.

~/.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

각 Skill은 전문성의 서로 다른 측면을 담아냅니다. 이들이 모여 Claude이 컨텍스트에 따라 자동으로 끌어다 쓰는 지식 베이스를 형성합니다. 주니어 개발자도 요청 없이 시니어 수준의 안내를 받을 수 있습니다.

Skill은 Hook과 결합됩니다

Skill은 frontmatter에 자체 hook을 정의할 수 있으며, 이 hook은 Skill이 실행되는 동안에만 활성화됩니다. 이를 통해 다른 세션을 오염시키지 않는 도메인별 동작이 만들어집니다.²

---
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'"
---

철학 Skill은 SessionStart hook을 통해 자동 활성화되어, 명시적 호출 없이도 모든 세션에 품질 제약 조건을 주입합니다. Skill 자체는 지식이고, hook은 강제력입니다. 둘이 합쳐져 정책 계층을 형성합니다.

흔한 Skill 실수

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

예산을 두고 경쟁하는 너무 많은 Skill. Skill이 많아질수록 1% 컨텍스트 예산을 두고 경쟁하는 description도 늘어납니다. Skill이 활성화되지 않는 것 같다면 /context에서 제외된 항목이 있는지 확인하세요. 모호한 Skill 다수보다 잘 설명된 소수의 Skill을 우선시하세요.

보조 파일에 묻혀 있는 핵심 정보. Claude은 SKILL.md를 즉시 읽지만, 보조 파일은 필요할 때만 접근합니다. 핵심 정보가 보조 파일에 있다면 Claude이 찾지 못할 수도 있습니다. 필수 정보는 SKILL.md에 직접 넣으세요.⁴

SDK Skill 표면 (2026년 5월 8일)

claude-agent-sdk-python v0.1.77+ 기반의 자체 호스팅 harness는 사용 가능한 Skill을 선언할 때 allowed_tools의 레거시 "Skill" 값이 아니라 ClaudeAgentOptions의 skills 옵션을 사용해야 합니다.³⁷ "Skill" 단축 표기는 더 이상 권장되지 않으며, 전용 옵션은 어떤 Skill을 사용할 수 있는지에 대해 Claude Code에 더 구조화된 정보를 제공합니다. v0.1.77에 번들된 CLI는 v2.1.133입니다.

후크 아키텍처

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

사용 가능한 이벤트

이 가이드 업데이트 시점 기준으로 Claude Code는 8개 카테고리에 걸쳐 29개의 문서화된 라이프사이클 이벤트를 노출합니다. 이벤트 목록은 릴리스마다 늘어나므로 참조 문서를 단일 진실 공급원으로 취급하고, 프로덕션 후크를 연결하기 전에 치트 시트에서 현재 전체 표를 확인하세요:¹³

종료 코드 의미론

종료 코드는 후크가 작업을 차단할지 여부를 결정합니다:³

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

후크 구성

후크는 설정 파일에 위치합니다. 공유 후크는 프로젝트 수준(.claude/settings.json)에, 개인 후크는 사용자 수준(~/.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, Edit, Write, Read, Glob, Grep과 같은 tool_name 값, mcp__server__tool 같은 MCP 도구 이름, 또는 모든 도구를 의미하는 *와 매칭됩니다. 단순 이름과 |로 구분된 목록은 정확히 일치하며, 다른 문자가 포함된 값은 JavaScript 정규 표현식으로 처리됩니다. 일부 이벤트는 매처를 지원하지 않으며 구성된 경우 항상 발동합니다.¹³

후크 입출력 프로토콜

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

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

고급 제어를 위해 PreToolUse 후크는 도구 입력을 수정하거나, 컨텍스트를 주입하거나, 권한 결정을 내리는 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."
  }
}

세 가지 보장 유형

후크를 작성하기 전에 자문하세요: 어떤 종류의 보장이 필요한가?¹⁴

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

{
  "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 후크는 명령을 검사하고 종료 코드 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 후크는 린터나 테스트 스위트를 실행하고 품질 검사가 실패하면 커밋을 차단합니다:

#!/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

셸 명령을 넘어선 후크 유형

Claude Code는 다섯 가지 후크 유형을 지원합니다:¹³

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

MCP 도구 후크(type: "mcp_tool")는 이미 연결된 MCP 서버에서 도구를 호출합니다. 검증 로직이 이미 MCP 경계 너머에 존재하고 별도의 셸 스크립트가 필요하지 않을 때 사용하세요.

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

Agent 후크(type: "agent")는 다중 턴 검증을 위해 도구 접근(Read, Grep, Glob)을 갖춘 서브에이전트를 스폰합니다. 실험적이므로 프로덕션 게이트에는 command 후크를 선호하고, 실제 파일이나 테스트 출력을 검사해야 하는 검사에만 agent 후크를 사용하세요:

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

HTTP 후크(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
          }
        ]
      }
    ]
  }
}

비동기 후크

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

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

알림, 텔레메트리, 백업에는 비동기를 사용하세요. 서식 지정, 검증 또는 다음 작업 전에 완료되어야 하는 작업에는 절대 비동기를 사용하지 마세요.

독립 후크보다 디스패처

같은 이벤트에 일곱 개의 후크가 모두 발동하고 각각 독립적으로 stdin을 읽으면 경쟁 조건이 발생합니다. 두 개의 후크가 동시에 같은 JSON 상태 파일에 쓰면 JSON이 잘립니다. 그 파일을 파싱하는 모든 다운스트림 후크가 깨집니다.²

해결책: 캐시된 stdin에서 후크를 순차적으로 실행하는 이벤트당 하나의 디스패처:

#!/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

후크 디버깅

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

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 후크는 작동하는 것처럼 보이지만 강제력은 전혀 없습니다.
5. 후크를 빠르게 유지하세요. 후크는 동기적으로 실행됩니다. 모든 후크를 2초 이내, 이상적으로는 500ms 이내로 유지하세요.

SDK 측 후크 이벤트 스트리밍

claude-agent-sdk-python(v0.1.74+, 2026년 5월 6일) 위에 구축된 자체 호스팅 하니스는 셸 스크립트 콜백을 거치지 않고 메시지 스트림에서 직접 후크 이벤트를 구독할 수 있습니다.³⁶ ClaudeAgentOptions에 include_hook_events=True를 설정하면 HookEventMessage 객체(PreToolUse, PostToolUse, Stop 등)가 어시스턴트 메시지 및 도구 결과와 동일한 이터레이터에서 yield됩니다. 이는 TypeScript SDK의 includeHookEvents 옵션을 반영합니다. 동일한 릴리스에서 번들 CLI가 v2.1.129로 업그레이드되었습니다.

이벤트 스트림 패턴은 하니스가 이미 Python에 있고 모델 출력과 동일한 제어 흐름에서 후크 신호를 원할 때 적합합니다. 셸 스크립트 후크 계약(종료 코드, stdin JSON, 디스패처)은 여러 도구를 조합하거나, Claude Code와 Codex 간에 후크를 공유하거나, 차단을 위한 종료 코드 의미론이 필요한 하니스에 여전히 올바른 답입니다.

Effort 및 세션 출처 (2026년 5월 7-8일)

Claude Code v2.1.132 및 v2.1.133의 두 가지 추가 사항은 후크와 서브프로세스에 실행 컨텍스트에 대한 더 나은 신호를 제공합니다:³⁸³⁹

• 후크 입력의 effort.level. 후크는 이제 tool_input 및 session_id를 전달하는 동일한 입력에서 effort.level JSON 필드를 받습니다. 동일한 값이 $CLAUDE_EFFORT 환경 변수로 내보내지므로 Bash 명령은 JSON을 파싱하지 않고도 읽을 수 있습니다. 이를 사용하여 노력 단계에 따라 후크 비용을 조정하세요: low에서는 비용이 많이 드는 검증을 건너뛰고, xhigh나 max에서는 전체 보안 게이트를 실행하세요.
• Bash 서브프로세스의 CLAUDE_CODE_SESSION_ID 환경 변수. Bash 도구 서브프로세스는 이제 후크가 보는 것과 동일한 session_id 값을 CLAUDE_CODE_SESSION_ID로 노출하여 봅니다. 이는 세션별 상태를 로깅하지만 이전에는 서브프로세스 이벤트와 후크 이벤트를 연관시킬 수 없었던 도구의 출처 격차를 해소합니다.

두 신호 모두 코드 변경 없이 사용할 수 있습니다. 새 필드를 무시하는 기존 후크는 계속 작동합니다.

메모리와 컨텍스트

모든 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 파일은 세션 전반에 걸쳐 오류, 결정, 패턴을 기록합니다. bash에서 VAR이 0일 때 ((VAR++))이 set -e와 함께 실패한다는 사실을 발견하면, 이를 기록합니다. 세 번의 세션 이후 Python에서 비슷한 정수 엣지 케이스를 만났을 때, MEMORY.md 항목이 그 패턴을 표면화합니다.¹⁵

Auto Memory (v2.1.32+): Claude Code는 프로젝트 컨텍스트를 자동으로 기록하고 회상합니다. 작업하는 동안 Claude는 관찰 내용을 ~/.claude/projects/{project-path}/memory/MEMORY.md에 작성합니다. Auto memory는 세션 시작 시 첫 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분을 넘어서면, 신선한 컨텍스트는 오버헤드에도 불구하고 더 높은 품질의 결과물을 만들어냅니다.

전략 5: 관리형 메모리 큐레이션(Dreaming)

Anthropic의 Claude Managed Agents는 2026년 5월 6일 Research Preview로 Dreaming을 추가했습니다.³⁵ Anthropic의 설명에 따르면 “Dreaming은 에이전트 세션과 메모리 저장소를 검토하고, 패턴을 추출하며, 메모리를 큐레이션하여 시간이 지남에 따라 에이전트가 개선되도록 하는 예약된 프로세스”입니다.³⁵

Dreaming은 세션 사이에 백그라운드에서 실행되며, 크리티컬 패스 위에 있지 않습니다. 이는 메모리로서의 파일시스템 패턴을 대체하기보다는 보완합니다. MEMORY.md 파일은 여전히 핵심 표면으로 남아 있고, Dreaming은 큐레이션된 메모리 항목을 Managed Agents 메모리 저장소에 작성하며, 에이전트는 세션 시작 시 이를 읽습니다. 두 패턴은 자체 호스팅 파일시스템 상태와 관리형 측 큐레이션을 혼합하는 harness에 공존합니다.

Dreaming은 Research Preview 단계이므로 동작이 변경될 수 있습니다. 위에 문서화된 세션 핸드오프와 CLAUDE.md 패턴은 자체 호스팅 harness의 권위 있는 메모리 메커니즘으로 남아 있습니다.

안티 패턴

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 격리는 코드베이스를 망가뜨릴 수 있는 실험적 작업에 필수적입니다.

병렬 서브에이전트

서로 조율할 필요가 없는 독립적인 조사 작업에는 병렬 서브에이전트를 사용하세요.⁵

> 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”입니다. 스폰 예산은 부모당 활성 자식의 총 수를 추적하며, 설정 가능한 최댓값으로 제한됩니다. 예산 모델은 프록시 지표(중첩 레벨이 너무 많음)가 아닌 실제 실패 모드(전체 에이전트가 너무 많음)에 매핑됩니다.⁷

Agent Teams (리서치 프리뷰)

Agent Teams는 독립적으로 작업하는 여러 Claude Code 인스턴스를 조율합니다. 이들은 공유 메일박스와 작업 목록을 통해 통신하고 서로의 결과에 이의를 제기할 수 있습니다.⁵

활성화 방법: export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

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

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

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

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

토론은 만능 해법이 아닙니다: M3MAD-Bench 연구 클러스터(2026년 초)는 멀티 에이전트 토론이 정체될 수 있고 잘못된 합의에 의해 전복될 수 있음을 발견했습니다. 다른 에이전트가 자신 있게 잘못된 답변을 주장할 때 유효한 논거가 패배합니다.²⁶ Tool-MAD는 각 에이전트에게 이질적인 도구 접근 권한을 부여하고 판정 단계에서 Faithfulness/Relevance 점수를 사용함으로써 이를 개선합니다. 토론 스타일 오케스트레이션을 구축한다면 (a) 에이전트별 도구 이질성과 (b) 정량적 판정 점수에 투자하세요. 더 많은 에이전트 = 더 나은 답변이라고 가정하지 마세요.

매니지드 멀티 에이전트 오케스트레이션 및 Outcomes(Public Beta)

아래에서 설명하는 심의 인프라를 직접 구축하고 싶지 않다면, Multiagent Orchestration이 2026년 5월 6일에 Claude Managed Agents에서 Public Beta로 출시되었습니다.³⁵ Anthropic에 따르면: “단일 에이전트가 잘 처리하기에 작업이 너무 많을 때, 멀티 에이전트 오케스트레이션을 통해 lead agent가 작업을 여러 부분으로 나누고 각각을 자체 모델, 프롬프트, 도구를 갖춘 specialist에게 위임할 수 있습니다.”³⁵ Specialist들은 “공유 파일시스템에서 병렬로 작업하며 lead agent의 전체 컨텍스트에 기여합니다.”³⁵

추적(tracing)은 기본 제공됩니다. Anthropic에 따르면: “Claude Console에서 모든 단계를 추적할 수 있습니다. 어떤 에이전트가 무엇을, 어떤 순서로, 왜 했는지를 보여주어 작업이 어떻게 위임되고 실행되었는지에 대한 완전한 가시성을 제공합니다.”³⁵

함께 출시된 Public Beta 기능은 Outcomes입니다. Anthropic에 따르면: “성공이 어떤 모습인지를 설명하는 루브릭을 작성하면 에이전트가 그것을 향해 작업합니다. 별도의 grader가 자체 컨텍스트 윈도우에서 출력을 기준에 따라 평가하므로 에이전트의 추론에 영향을 받지 않습니다.”³⁵ 이는 이 섹션 후반부에 문서화된 두 게이트 검증 패턴의 매니지드 서비스 버전입니다. 루브릭이 직접 작성한 게이트를 대체하고, 별도의 grader가 합의 검증자를 대체합니다.

검증이 자체 hook 표면(PreToolUse 차단, exit-code 시맨틱, 커스텀 dispatcher)과 통합되어야 하거나 harness가 외부 종속성 없이 실행되어야 하는 경우 자체 호스팅 심의가 올바른 답입니다. 표준 위임과 루브릭 채점이 실제로 필요한 계약일 때는 Managed Multiagent가 올바른 답입니다.

최소 실행 가능 심의(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. 모호성 - 쿼리에 여러 가지 유효한 해석이 존재하는가?
2. 도메인 복잡성 - 전문 지식이 필요한가?
3. 이해관계 - 결정이 되돌릴 수 있는가?
4. 컨텍스트 의존성 - 더 넓은 시스템에 대한 이해가 필요한가?

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

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

상태 머신(The State Machine)

7개 단계가 각각 이전 단계에 의해 게이팅됩니다.⁷

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

RESEARCH: 독립적인 에이전트가 주제를 조사합니다. 각 에이전트는 서로 다른 페르소나(Technical Architect, Security Analyst, Performance Engineer 등)를 받습니다. 컨텍스트 격리는 연구 중 에이전트가 서로의 발견을 볼 수 없도록 보장합니다.

DELIBERATION: 에이전트는 모든 연구 발견을 보고 대안을 생성합니다. Debate agent는 충돌을 식별합니다. Synthesis agent는 모순되지 않는 발견을 결합합니다.

RANKING: 각 에이전트는 5개의 가중 차원에 걸쳐 제안된 모든 접근 방식을 점수화합니다.

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

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

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

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

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

합의가 위험한 이유

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

Wu et al.은 LLM 에이전트가 진정으로 토론할 수 있는지 테스트했고, 의견 불일치에 대한 구조적 인센티브가 없으면 에이전트가 정확성과 무관하게 가장 자신감 있게 들리는 초기 응답으로 수렴한다는 사실을 발견했습니다.¹⁹ Liang et al.은 근본 원인을 “Degeneration-of-Thought”로 식별했습니다. LLM이 한 입장에 대한 신뢰를 확립하면 자기 성찰만으로는 새로운 반론을 생성할 수 없으며, 이로 인해 멀티 에이전트 평가가 구조적으로 필요하게 됩니다.²⁰

독립성이 핵심 설계 제약입니다. 서로의 발견을 볼 수 있는 두 에이전트가 동일한 배포 전략을 평가할 때 0.45와 0.48 점수를 산출했습니다. 가시성 없는 동일한 에이전트는 0.45와 0.72를 산출했습니다. 0.48과 0.72의 차이가 herding(군집 행동)의 비용입니다.⁷

가짜 합의 감지

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

점수 클러스터링: 모든 에이전트가 10점 척도에서 0.3점 이내로 점수를 매기는 것은 독립적인 평가가 아닌 공유된 컨텍스트 오염을 시사합니다. 인증 리팩터링을 평가하는 5개 에이전트가 모두 보안 리스크를 7.1과 7.4 사이로 점수 매겼을 때, 새로운 컨텍스트 격리로 다시 실행하니 점수가 5.8-8.9로 분산되었습니다.

상투적 반대: 에이전트가 독립적인 반대 의견을 생성하는 대신 서로의 우려 사항 언어를 복사합니다.

소수 관점의 부재: 우선순위가 충돌하는 페르소나(Security Analyst와 Performance Engineer는 모든 사안에 동의하는 경우가 드뭅니다)로부터의 만장일치 승인.

순응 감지기는 명백한 사례(에이전트가 너무 빨리 수렴하는 심의의 약 10-15%)를 포착합니다. 나머지 85-90%에 대해서는 합의 게이트와 pride check 게이트가 충분한 검증을 제공합니다.

심의에서 효과가 없었던 것

자유 형식 토론 라운드. 데이터베이스 인덱싱 논의에 대한 세 라운드의 주고받는 텍스트는 7,500 토큰의 토론을 생성했습니다. 라운드 1: 진정한 의견 불일치. 라운드 2: 입장 재진술. 라운드 3: 다른 단어로 동일한 논거. 구조화된 차원 점수화가 자유 형식 토론을 대체하여 비용을 60% 줄이는 동시에 랭킹 품질을 개선했습니다.⁷

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

심의 비용

각 연구 에이전트는 약 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입니다. 그것이 가치 있는지는 잘못된 결정의 비용이 얼마인지에 달려 있습니다.

심의해야 할 때

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. 빌드 및 테스트 명령어 (에이전트가 유용한 작업을 하기 전에 반드시 필요)
2. 완료 정의 (잘못된 완료 보고를 방지)
3. 에스컬레이션 규칙 (파괴적인 우회 방법을 방지)
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의 패턴(명령어 우선, 종료 조건 정의, 작업별 구성)은 도구와 관계없이 어떤 지시 파일에서도 동작합니다. 서로 어긋나는 병렬 지시 세트를 유지하지 마세요. 권위 있는 단일 소스를 작성하고 미러링하세요.

Codex 호환성 메모

Codex는 이제 주요 하니스 계층에 대한 일급 등가물을 갖추고 있지만, 마이그레이션은 단순한 파일 복사가 아니라 패턴 번역입니다. Codex는 작업 시작 전에 AGENTS.md를 읽으며, ~/.codex의 전역 가이드를 프로젝트 및 중첩된 리포지토리 지시와 함께 계층화합니다.³¹ Codex 스킬은 점진적 공개 방식의 동일한 SKILL.md 멘탈 모델을 사용합니다. Codex는 스킬 이름, 설명, 파일 경로로 시작한 후 사용 결정을 내릴 때만 전체 스킬을 로드합니다.³² Codex는 또한 네이티브 훅, 플러그인 번들 훅, 관리형 훅, MCP 지원, 명시적 서브에이전트 워크플로를 갖추고 있습니다.³³³⁴

실용적 매핑:

중요한 차이점: Claude 서브에이전트는 설명을 통해 자동으로 선택될 수 있지만, Codex는 현재 서브에이전트 워크플로를 명시적으로 문서화합니다. 따라서 Codex에서는 항상 켜져 있는 하니스 동작에는 스킬과 훅이 적절한 기본값이며, 서브에이전트는 의도적인 병렬 작업, 리뷰, 탐색을 위한 것입니다.

지시 사항 테스트

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

# 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 장기 작업 패턴 (April 2026)

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

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

워크트리 베이스, 샌드박스 경로, 관리자 설정 (May 7, 2026)

Claude Code v2.1.133은 프로덕션 하니스에서 알아둘 가치가 있는 4가지 관리자 등급 설정을 추가합니다:³⁹

worktree.baseRef 되돌림은 사용자에게 알려야 할 사항입니다: v2.1.128-v2.1.132 동작(로컬 HEAD에서 분기되는 워크트리)에 의존했던 에이전트는 명시적으로 다시 옵트인하지 않으면 새 워크트리에서 푸시되지 않은 작업에 접근할 수 없습니다.

품질 루프

모든 비사소한 변경에 대한 필수 리뷰 프로세스입니다:

1. 구현(Implement) - 코드를 작성합니다
2. 리뷰(Review) - 모든 줄을 다시 읽습니다. 오타, 논리 오류, 불명확한 부분을 잡아냅니다
3. 평가(Evaluate) - evidence gate를 실행합니다. 패턴, 엣지 케이스, 테스트 커버리지를 확인합니다
4. 개선(Refine) - 모든 문제를 수정합니다. 절대 “나중에”로 미루지 마세요
5. 확장(Zoom Out) - 통합 지점, 임포트, 인접 코드의 회귀를 확인합니다
6. 반복(Repeat) - evidence gate 기준 중 하나라도 실패하면 4단계로 돌아갑니다
7. 보고(Report) - 무엇이 변경되었는지, 어떻게 검증했는지 나열하고 구체적인 증거를 인용합니다

Evidence Gate

“믿어요”와 “그럴 거예요”는 증거가 아닙니다. 파일 경로, 테스트 출력, 또는 구체적인 코드를 인용하세요.

어떤 행에 대해서도 증거를 만들 수 없다면 Refine으로 돌아가세요.²²

오류 처리 패턴

원자적 파일 쓰기. 여러 에이전트가 동일한 상태 파일에 동시에 쓰면 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++)) 배시 함정. ((VAR++))는 VAR이 0일 때 종료 코드 1을 반환합니다. 왜냐하면 0++는 0으로 평가되고, 배시는 이를 거짓으로 취급하기 때문입니다. 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 발화. 디스패처가 주입합니다: 현재 날짜, 프로젝트 감지, 철학 제약, 비용 추적 초기화. 5개 훅, 총 180ms.

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

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

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

5. 에이전트가 스토리를 완료합니다. Stop이 발화합니다. 품질 게이트 확인: 에이전트가 증거를 인용했는가? 머뭇거리는 표현? diff에 TODO 코멘트? 어떤 검사라도 실패하면 종료 2가 발생하고 에이전트가 계속됩니다.

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

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

8. 스토리가 통과합니다. 다음 스토리가 로드됩니다. 5개 스토리 모두에 대해 사이클이 반복됩니다.

5개 스토리에 걸쳐 발화된 총 훅: 약 340. 훅에 소요된 총 시간: 약 12초. 그 오버헤드는 단일 야간 실행에서 세 건의 자격 증명 유출, 한 건의 파괴적인 명령, 두 건의 불완전한 구현을 막았습니다.

사례 연구: 야간 PRD 처리

프로덕션 하니스가 8개의 야간 세션에 걸쳐 12개의 PRD(47개 스토리)를 처리했습니다. 메트릭은 첫 4개 PRD(최소 하니스: CLAUDE.md만)와 마지막 8개(전체 하니스: 훅, 스킬, 품질 게이트, 다중 에이전트 리뷰)를 비교합니다.

두 건의 자격 증명 유출은 API 키 회전과 다운스트림 서비스 감사를 요구했습니다: 약 4시간의 사고 대응. 그에 상응하는 것을 막은 하니스 오버헤드는 스토리당 2.4초의 배시였습니다. Stop 훅이 에이전트가 완료를 보고하도록 허용하기 전에 독립적으로 테스트를 실행했기 때문에 거짓 완료율이 35%에서 4%로 떨어졌습니다.

보안 고려사항

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

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

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

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

Sandbox

Claude Code는 OS 수준 격리(macOS의 seatbelt, Linux의 bubblewrap)를 사용하여 네트워크 접근과 파일시스템 작업을 제한하는 선택적 sandbox 모드를 지원합니다(settings.json 또는 /sandbox 명령어를 통해 활성화). 활성화되면 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에 강제 푸시하거나 자격 증명 파일을 읽거나 파괴적인 명령어를 실행할 수 있는 에이전트입니다.

아키텍처로서의 비용

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

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

에이전트 수준. 긴 대화보다 새로운 spawn 사용. 자율 실행에서 각 스토리는 깨끗한 컨텍스트를 가진 새 에이전트를 받습니다. 각 에이전트가 새로 시작하므로 컨텍스트가 부풀어오르지 않습니다. 메모리 대신 브리핑: 모델은 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는 거부 사유를 확인하고 더 안전한 대안을 제안합니다. Exit 1은 동작이 그대로 진행되는 비차단 경고입니다.³

훅 구성 파일은 어디에 두어야 하나요?

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

모든 결정이 숙의를 거쳐야 하나요?

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

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

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

숙의의 지연 시간 영향은 어느 정도인가요?

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

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

각 섹션은 50줄 미만으로, 전체 파일은 150줄 미만으로 유지하세요. 긴 파일은 컨텍스트 윈도우에서 잘리므로, 가장 중요한 지침을 앞쪽에 배치하세요. 스타일 선호 사항보다 명령어와 클로저 정의를 먼저 두는 식입니다.²¹

이 방식이 Claude Code 외의 도구에서도 작동하나요?

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

빠른 참조 카드

훅 구성

{
  "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 정의

---
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.

종료 코드

주요 명령어

파일 위치

변경 로그

참고 자료