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

TL;DR: Claude Code은 파일 접근 권한이 있는 채팅 상자가 아닙니다. 문서화된 29개의 lifecycle events를 갖춘 프로그래밍 가능한 runtime이며, 각 이벤트는 모델이 건너뛸 수 없는 shell scripts로 hook을 걸 수 있습니다. hooks를 dispatchers로, dispatchers를 skills로, skills를 agents로, agents를 workflows로 쌓으면 제약을 강제하고, 작업을 위임하고, sessions 간 memory를 유지하며, multi-agent deliberation을 오케스트레이션하는 autonomous development harness를 얻을 수 있습니다. Claude Code v2.1.147은 기본적으로 꺼져 있는 Workflow tool(CLAUDE_CODE_WORKFLOWS=1)을 추가해, 결정론적 multi-agent orchestration을 순수 userland scripts에서 first-party runtime primitive 쪽으로 옮겼습니다. v2.1.149는 PowerShell permission-bypass 수정과 git-worktree sandbox allowlist 수정으로 보안 측면에서도 같은 교훈을 강화합니다. Hooks와 evidence gates는 여전히 correctness를 책임집니다.⁵²⁵³ 이 가이드는 단일 hook부터 10-agent consensus system까지, 이 스택의 모든 계층을 다룹니다. Framework는 필요 없습니다. bash와 JSON만 있으면 됩니다.

Andrej Karpathy는 LLM agent 주변에 자라나는 것을 가리키는 용어를 만들었습니다. 바로 claws입니다. agent가 context window 밖의 세계를 붙잡을 수 있게 해주는 hooks, scripts, orchestration을 뜻합니다.¹ 대부분의 개발자는 AI coding agents를 대화형 assistant로 다룹니다. prompt를 입력하고, 파일이 편집되는 것을 보고, 다음으로 넘어갑니다. 이런 프레임은 직접 감독할 수 있는 범위까지만 생산성을 제한합니다.

Infrastructure라는 관점은 다릅니다. AI coding agent는 LLM kernel을 갖춘 프로그래밍 가능한 runtime입니다. 모델이 수행하는 모든 action은 사용자가 제어하는 hooks를 거칩니다. 사용자는 prompts가 아니라 policies를 정의합니다. 모델은 web server가 nginx rules 안에서 동작하는 것과 같은 방식으로 사용자의 infrastructure 안에서 동작합니다. nginx 앞에 앉아 requests를 입력하지는 않습니다. 설정하고, 배포하고, 모니터링합니다.

이 차이는 중요합니다. infrastructure는 누적 효과를 만들기 때문입니다. bash commands에서 credentials를 차단하는 hook 하나는 모든 session, 모든 agent, 모든 autonomous run을 보호합니다. evaluation rubric을 인코딩한 skill은 사용자가 호출하든 agent가 호출하든 일관되게 적용됩니다. security를 검토하는 agent는 사용자가 지켜보고 있든 아니든 같은 checks를 실행합니다.²

핵심 요점

• Hooks는 실행을 보장하지만, prompts는 그렇지 않습니다. linting, formatting, security checks처럼 모델의 behavior와 상관없이 매번 반드시 실행되어야 하는 작업에는 hooks를 사용하세요. Exit code 2는 actions를 차단합니다. Exit code 1은 경고만 표시합니다.³
• Skills는 자동으로 활성화되는 domain expertise를 인코딩합니다. description field가 모든 것을 결정합니다. Claude은 skill을 적용할 시점을 결정할 때 keyword matching이 아니라 LLM reasoning을 사용합니다.⁴
• Subagents는 context bloat를 방지합니다. exploration과 analysis를 위한 분리된 context windows는 main session을 가볍게 유지합니다. 독립적인 subagents를 병렬로 실행하고, workers에 지속적인 coordination이 필요할 때는 agent teams를 사용하세요.⁵
• Memory는 filesystem에 있습니다. Files는 context windows를 넘어 유지됩니다. CLAUDE.md, MEMORY.md, rules directories, handoff documents는 구조화된 external memory system을 이룹니다.⁶
• Multi-agent deliberation은 blind spots를 잡아냅니다. 단일 agents는 자신의 assumptions에 스스로 도전할 수 없습니다. 서로 다른 evaluation priorities를 가진 2개의 독립 agents는 quality gates로는 해결할 수 없는 structural failures를 찾아냅니다.⁷
• harness pattern이 곧 system입니다. CLAUDE.md, hooks, skills, agents, memory는 독립적인 features가 아닙니다. 이들은 사용자와 모델 사이에 자동화에 맞춰 확장되는 deterministic layer로 결합됩니다.

이 가이드를 사용하는 방법

각 section은 이전 section을 기반으로 이어집니다. 끝부분의 Decision Framework는 각 problem type에 맞는 mechanism을 고르는 lookup table을 제공합니다.

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 파일과 규칙 디렉터리는 에이전트가 프로젝트에 대해 알아야 할 내용을 정의합니다. 이들은 세션 시작 시 그리고 매 컴팩션 후에 자동으로 로드됩니다. 이는 에이전트의 장기 아키텍처 메모리 역할을 합니다.

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

Orchestration Layer: 다중 에이전트 패턴은 리서치, 리뷰, 심의를 위해 독립적인 에이전트들을 조율합니다. 스폰 예산은 폭주하는 재귀를 방지합니다. 합의 검증은 품질을 보장합니다.

핵심 통찰은 다음과 같습니다. 대부분의 사용자는 전적으로 Core Layer에서 작업하면서 컨텍스트가 비대해지고 비용이 치솟는 것을 지켜봅니다. 파워 유저는 Instruction 및 Extension 레이어를 구성한 다음, 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일 발표)에 도착했습니다. 즉, default_manifest, 샌드박스 지시사항, 그리고 capabilities를 갖춘 Agent의 SandboxAgent 서브클래스, 신규 워크스페이스 계약(파일, 디렉터리, 로컬 파일, Git 레포, 환경 변수, 사용자, 마운트)을 기술하는 Manifest, 그리고 샌드박스 클라이언트, 라이브 세션 주입, manifest 오버라이드, 스냅샷, 머티리얼라이제이션 동시성 제한 등의 런별 배선을 위한 SandboxRunConfig가 포함되었습니다. 빌트인 capabilities는 셸 액세스, 파일시스템 편집, 이미지 검사, skills, 샌드박스 메모리, 컴팩션을 다룹니다. 샌드박스 메모리는 추출된 교훈을 런 간에 유지하고 점진적으로 노출합니다. 워크스페이스는 로컬 파일, Git 레포 엔트리, 그리고 원격 마운트(S3, R2, GCS, Azure Blob, S3 Files)를 지원합니다. 스냅샷은 프로바이더 간 이식 가능합니다. 백엔드는 UnixLocalSandboxClient, DockerSandboxClient, 그리고 옵션 extras를 통해 Blaxel, Cloudflare, Daytona, E2B, Modal, Runloop, Vercel을 위한 호스팅 클라이언트입니다.²⁴

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).³⁰

하네스에 음성 또는 실시간 레이어가 포함된 경우, openai-agents-python v0.17.0 (2026년 5월 8일)은 RealtimeAgent가 gpt-realtime-2를 기본값으로 사용하도록 업데이트했습니다.⁴¹ 기존 실시간 세션은 새 기본값을 자동으로 채택합니다. 평가를 위해 이전 동작을 유지해야 한다면 이전 모델을 명시적으로 핀(pin)하세요.

이제 아키텍처 분기는 현실이 되었습니다.

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

Skills는 모델이 호출하는 확장 기능이에요. Claude는 사용자가 명시적으로 호출하지 않아도 컨텍스트를 기준으로 자동으로 이를 발견하고 적용해요.⁴ 세션마다 같은 컨텍스트를 반복해서 설명하고 있다는 생각이 드는 순간이 바로 skill을 만들어야 할 때예요.

Skill을 만들어야 할 때

Skills는 Claude가 항상 사용할 수 있는 지식을 위한 것이에요. Slash commands는 사용자가 명시적으로 트리거하는 작업을 위한 것이고요. 둘 중 하나를 고르는 중이라면 이렇게 물어보세요. “Claude가 이것을 자동으로 적용해야 할까, 아니면 내가 실행 시점을 결정해야 할까?”

Skill 만들기

Skills는 범위가 넓은 것부터 좁은 것까지 4가지 위치에 둘 수 있어요.⁴

모든 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는 language model reasoning을 사용해 관련 skill이 있는지 판단해요. Claude Code 소스에 대한 독립 분석에서도 이 메커니즘이 확인돼요. skill description은 system prompt의 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)가 포함돼요.

Context 예산

모든 skill description은 컨텍스트 창의 1%로 동적으로 확장되는 컨텍스트 예산을 공유하며, fallback은 8,000자예요.⁴ skill이 많다면 각 description을 간결하게 유지하고 핵심 사용 사례를 앞에 두세요. SLASH_COMMAND_TOOL_CHAR_BUDGET 환경 변수로 예산을 재정의할 수 있지만,¹¹ 더 나은 해결책은 더 짧고 정확한 description이에요. 세션 중 /context를 실행해 제외되는 skill이 있는지 확인하세요.

지원 파일과 구성

Skills는 같은 디렉터리의 추가 파일을 참조할 수 있어요.

~/.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으로 Skills 공유하기

Project skills(저장소 루트의 .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을 자동으로 받게 돼요. 설치도, 설정도 필요 없어요. 이는 팀 전체에서 전문 지식을 표준화하는 가장 효과적인 방법이에요.

Prompt Library로서의 Skills

단일 목적 skill을 넘어, 디렉터리 구조는 체계화된 prompt library로도 작동해요.

~/.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가 컨텍스트에 따라 자동으로 끌어오는 지식 기반이 돼요. 주니어 개발자는 따로 요청하지 않아도 시니어 수준의 가이드를 받게 돼요.

Skills와 Hooks의 조합

Skills는 frontmatter에 자체 hooks를 정의할 수 있고, 이 hooks는 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'"
---

Philosophy skills는 SessionStart hooks를 통해 자동 활성화되어, 명시적 호출 없이도 모든 세션에 품질 제약을 주입해요. 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이 많아질수록 더 많은 description이 1% 컨텍스트 예산을 두고 경쟁해요. skill이 활성화되지 않는다고 느껴지면 /context에서 제외된 항목을 확인하세요. 모호한 skill을 많이 두기보다, 적지만 잘 설명된 skill을 우선하세요.

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

SDK Skill Surface(2026년 5월 8일)

claude-agent-sdk-python v0.1.77+의 self-hosted harness는 사용 가능한 skills를 선언할 때 allowed_tools의 기존 "Skill" 값이 아니라 ClaudeAgentOptions의 skills 옵션을 사용해야 해요.³⁷ "Skill" 축약형은 deprecated되었고, 전용 옵션은 어떤 skills를 사용할 수 있는지에 대해 Claude Code에 더 구조화된 정보를 제공해요. v0.1.77에 번들된 CLI는 v2.1.133이에요.

.claude/skills/에서 Plugin과 Skill의 수렴(2026년 5월 29일)

Skills는 항상 프로젝트의 .claude/skills/ 디렉터리에서 로드되어 왔어요. Claude Code v2.1.157은 이 디렉터리를 plugins까지 확장해요. 이제 .claude/skills/에 둔 plugin은 marketplace 등록 없이 자동으로 로드되고, claude plugin init <name>은 manifest와 SKILL.md가 이미 연결된 새 plugin을 그 위치에 scaffold해요.⁵⁸ 이로써 예전에는 서로 다른 위치에 있던 두 가지 프로젝트 도구 형태 사이의 간극이 사라졌어요. 하나는 저장소에 바로 커밋되는 bare skill이고, 다른 하나는 skill과 hooks, MCP server를 묶지만 이전에는 설치를 위해 marketplace가 필요했던 plugin이에요. harness 설계에서의 실질적인 효과는 이렇습니다. project-scoped tooling을 배포하는 데 더 이상 registry 우회로가 필요하지 않아요. 작성하고, 커밋하면, 팀원은 git pull로 같은 surface를 받습니다. Plugins는 여전히 번들 설치형 사용 사례(hooks + skills + MCP servers + agents를 하나의 ZIP에 담는 경우)를 담당해요. 달라진 점은 프로젝트가 자기 트리에서 plugin 하나를 로드하기 위해 marketplace를 세울 필요가 없어졌다는 점이에요.

Governance로 번들 Surface 숨기기(2026년 6월 8일)

Skills는 capability이고, capability는 attack surface예요. Claude Code v2.1.169는 번들 skills, workflows, built-in slash commands를 모델에서 완전히 숨기는 disableBundledSkills 설정과 이에 대응하는 CLAUDE_CODE_DISABLE_BUNDLED_SKILLS 환경 변수를 추가해요.⁶⁰ 강화되었거나 규제 대상인 harness에서는 이것이 의도적인 attack-surface reduction이에요. 특정 project 및 personal skills 집합을 감사하고 승인한 운영자는 Anthropic가 기본 제공하는 모든 것을 억제할 수 있고, 그러면 모델은 운영자가 검토한 surface만을 대상으로 추론하게 돼요. 이를 tool allowlist와 같은 방식으로 다루세요. 기본값은 넓은 capability이고, 그 기본값을 끄는 것은 편의 toggle이 아니라 governance 결정이에요.

중첩 .claude/skills와 Closest-Wins Resolution(2026년 6월 16일)

Claude Code v2.1.178은 project tooling을 location-aware하게 만들었어요. 이제 중첩된 .claude/skills 디렉터리의 skills는 저장소 루트에서만이 아니라 해당 디렉터리 아래 파일로 작업할 때 로드돼요. 이름이 충돌하면 중첩 skill은 <dir>:<name>으로 표시되어 둘 다 접근 가능한 상태로 남아요.⁶³ 같은 릴리스에서는 나머지 project surface도 작업 디렉터리에 가장 가까운 항목으로 해석되도록 바뀌었어요. 중첩된 .claude/ 디렉터리들 사이에서 agent, workflow, output-style 이름이 충돌하면 작업 디렉터리에 가장 가까운 것이 이기고, project-scope workflow 저장은 항상 루트가 아니라 가장 가까운 기존 .claude/workflows/를 대상으로 해요.⁶³ monorepo나 repo-of-repos에서는 이것이 하나의 평평한 global surface와 컨텍스트에 맞게 활성화되는 package별 tooling의 차이를 만들어요. services/api/.claude/skills/는 같은 이름의 services/web/ skill과 충돌하지 않으면서, 해당 트리에서 작업할 때만 표시되는 API 전용 skills를 담을 수 있어요.

Hook Architecture

Hooks는 Claude Code lifecycle events에 의해 실행되는 shell commands입니다.³ Hooks는 모델이 해석하는 prompts가 아니라 일반 scripts로 LLM 바깥에서 실행됩니다. 모델이 rm -rf /를 실행하려고 하나요? 10줄짜리 bash script가 command를 blocklist와 대조해 확인하고, shell이 보기 전에 거부합니다. hook은 모델이 원하든 원하지 않든 실행됩니다.

사용 가능한 Events

이 가이드 업데이트 시점 기준으로 Claude Code는 8개 범주에 걸쳐 문서화된 lifecycle events 29개를 제공합니다. event 목록은 release와 함께 늘어나므로, production hooks를 연결하기 전에는 reference docs를 source of truth로 삼고 cheat sheet에서 현재 전체 표를 확인하세요.¹³

Exit Code 의미

Exit codes는 hooks가 actions를 차단할지 결정합니다.³

중요: 모든 security hook은 exit 1이 아니라 exit 2를 사용해야 합니다. Exit 1은 비차단 경고입니다. 위험한 command는 그대로 실행됩니다. 팀에서 가장 흔히 저지르는 hook 실수가 바로 이것입니다.¹⁴

Hook Configuration

Hooks는 settings files에 있습니다. 공유 hooks는 project-level(.claude/settings.json)에, 개인 hooks는 user-level(~/.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 field는 event별 값을 필터링합니다. tool events의 경우 Bash, Edit, Write, Read, Glob, Grep 같은 tool_name 값, mcp__server__tool 같은 MCP tool names, 또는 모든 tools를 뜻하는 *와 매칭됩니다. 단순 이름과 |로 구분된 목록은 정확히 일치해야 하며, 다른 문자가 포함된 값은 JavaScript regular expressions입니다. 일부 events는 matchers를 지원하지 않으며, 설정되어 있으면 항상 실행됩니다.¹³

Hook Input/Output Protocol

Hooks는 stdin으로 전체 context가 담긴 JSON를 받습니다.

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

고급 제어가 필요하면 PreToolUse hooks가 JSON를 출력해 tool input을 수정하거나, context를 주입하거나, permission decisions를 내릴 수 있습니다. hookSpecificOutput wrapper를 사용하세요. 더 오래된 top-level decision/reason 형식은 PreToolUse에서 deprecated되었습니다.

{
  "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."
  }
}

3가지 보장 유형

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

Formatting guarantees는 사후 일관성을 보장합니다. Write/Edit에 대한 PostToolUse hooks는 파일이 바뀔 때마다 formatter를 실행합니다. formatter가 모든 것을 정규화하므로 모델의 출력은 중요하지 않습니다.

{
  "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'"
          }
        ]
      }
    ]
  }
}

Safety guarantees는 위험한 actions가 실행되기 전에 막습니다. Bash에 대한 PreToolUse hooks는 commands를 검사하고 destructive patterns를 exit code 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

Quality guarantees는 결정 지점의 상태를 검증합니다. git commit commands에 대한 PreToolUse hooks는 linter나 test suite를 실행하고, quality checks가 실패하면 commit을 차단합니다.

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

Shell Commands를 넘어서는 Hook Types

Claude Code는 5가지 hook types를 지원합니다.¹³

Command hooks(type: "command")는 shell scripts를 실행합니다. 빠르고 결정적이며 token cost가 없습니다.

MCP tool hooks(type: "mcp_tool")는 이미 연결된 MCP server의 tool을 호출합니다. validation logic이 이미 MCP 경계 뒤에 있고 별도의 shell script가 필요하지 않을 때 사용하세요.

Prompt hooks(type: "prompt")는 빠른 Claude model에 single-turn prompt를 보냅니다. 모델은 허용하려면 { "ok": true }를, 차단하려면 { "ok": false, "reason": "..." }를 반환합니다. regex로 표현할 수 없는 미묘한 평가에 사용하세요.

Agent hooks(type: "agent")는 tool access(Read, Grep, Glob)가 있는 subagent를 생성해 multi-turn verification을 수행합니다. 이 기능은 experimental입니다. production gates에는 command hooks를 선호하고, 실제 files나 test output 검사가 정말 필요한 checks에만 agent hooks를 남겨 두세요.

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

Claude Code v2.1.140부터 agent hook input에는 subagent_type이 포함되므로, shared hook이 prompt text를 추측하지 않고도 security-reviewer 실행인지 explorer인지 generic worker인지 구분할 수 있습니다.⁴⁹

HTTP hooks(type: "http")는 event의 JSON input을 POST request로 URL에 보내고 JSON를 다시 받습니다. webhooks, 외부 notification services, 또는 API 기반 validation(v2.1.63+)에 사용하세요. SessionStart events에서는 지원되지 않습니다.

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

Async Hooks

Hooks는 실행을 차단하지 않고 background에서 실행될 수 있습니다. notifications와 logging 같은 중요하지 않은 작업에는 async: true를 추가하세요.¹³

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

notifications, telemetry, backups에는 async를 사용하세요. formatting, validation 또는 다음 action 전에 완료되어야 하는 어떤 작업에도 async를 사용하지 마세요.

독립 Hooks보다 Dispatchers

같은 event에서 hooks 7개가 모두 실행되고 각자 stdin을 독립적으로 읽으면 race conditions가 생깁니다. 같은 JSON state file에 두 hooks가 동시에 쓰면 JSON가 잘립니다. 그 파일을 파싱하는 모든 downstream hook이 깨집니다.²

해결책은 cached stdin에서 hooks를 순차 실행하는 event당 dispatcher 1개입니다.

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

Hooks Debugging

조용히 실패하는 hooks를 debugging하는 5가지 기법입니다.¹⁴

1. Scripts를 독립적으로 테스트하세요. sample JSON를 pipe하세요. echo '{"tool_input":{"command":"git commit -m test"}}' | bash your-hook.sh
2. Debug output에는 stderr를 사용하세요. Exit code 2의 stderr는 error message로 Claude에 다시 전달됩니다. 비차단 stderr(exit 1, 3 등)는 verbose mode(Ctrl+O)에서만 나타납니다.
3. jq failures를 주의하세요. 잘못된 JSON paths는 조용히 null을 반환합니다. 실제 tool input으로 jq expressions를 테스트하세요.
4. Exit codes를 검증하세요. exit 1을 사용하는 PreToolUse hook은 작동하는 것처럼 보이지만 아무 enforcement도 하지 않습니다.
5. Hooks를 빠르게 유지하세요. Hooks는 동기적으로 실행됩니다. 모든 hooks를 2초 미만, 가능하면 500ms 미만으로 유지하세요.

SDK 측 Hook Event Streaming

claude-agent-sdk-python(v0.1.74+, 2026년 5월 6일) 기반 self-hosted harnesses는 shell-script callbacks를 거치지 않고 message stream에서 직접 hook events를 구독할 수 있습니다.³⁶ ClaudeAgentOptions에 include_hook_events=True를 설정하면 HookEventMessage objects(PreToolUse, PostToolUse, Stop 등)가 assistant messages와 tool results와 같은 iterator에서 yield됩니다. 이는 TypeScript SDK의 includeHookEvents option과 대응하며, bundled CLI도 같은 release에서 v2.1.129로 올라갔습니다.

event-stream pattern은 harness가 이미 Python에 있고 hook signals를 model output과 같은 control flow에서 다루고 싶을 때 잘 맞습니다. shell-script hook contract(exit codes, stdin JSON, dispatchers)는 여러 tools를 조합하거나, Claude Code와 Codex 사이에서 hooks를 공유하거나, 차단을 위해 exit-code semantics가 필요한 harnesses에 여전히 맞는 답입니다.

Effort와 Session Provenance(2026년 5월 7-8일)

Claude Code v2.1.132와 v2.1.133의 두 가지 추가 사항은 hooks와 subprocesses가 실행 context를 더 잘 파악하게 해 줍니다.³⁸³⁹

• hook input의 effort.level. Hooks는 이제 tool_input과 session_id를 담는 같은 input에서 effort.level JSON field를 받습니다. 같은 값이 $CLAUDE_EFFORT env var로 export되므로 Bash commands는 JSON를 파싱하지 않고도 이를 읽을 수 있습니다. hook cost를 effort tier에 맞춰 조절하는 데 사용하세요. low에서는 비싼 validation을 건너뛰고, xhigh나 max에서는 전체 security gate를 실행하세요.
• Bash subprocesses의 CLAUDE_CODE_SESSION_ID env var. Bash tool subprocesses는 이제 hooks가 보는 것과 같은 session_id 값을 CLAUDE_CODE_SESSION_ID로 봅니다. 이는 per-session state를 logging하지만 이전에는 subprocess events와 hook events를 연결할 수 없었던 tools의 provenance gap을 닫습니다.

두 signals는 code changes 없이 사용할 수 있습니다. 새 fields를 무시하는 기존 hooks는 계속 작동합니다.

autoMode.hard_deny와 v2.1.136 Hook/Plugin Fixes(2026년 5월 8일)

Claude Code v2.1.136은 auto mode에 새로운 hard-deny tier를 추가하고 long-running harnesses에 영향을 주던 plugin 및 MCP 문제 묶음을 수정했습니다.⁴⁰

• settings.autoMode.hard_deny. 사용자 의도나 allow exceptions와 관계없이 무조건 차단하는 auto mode classifier rules입니다. 이는 기존 allow/deny matchers 위에 놓이는 협상 불가능한 governance lever입니다. operator가 personal settings에서 더 넓은 범주를 승인했더라도 절대 override되면 안 되는 rules(force-push to main, secret-bearing files, production database access)에 사용하세요.
• MCP servers가 /clear 후 더 이상 사라지지 않습니다. .mcp.json, plugins, claude.ai connectors에 설정된 servers가 VS Code extension, JetBrains plugin, Agent SDK에서 /clear 후 active set에서 조용히 빠지던 문제가 있었습니다. 수정은 v2.1.136에 포함되었습니다. “MCP server X went missing mid-session”을 봤다면 이것이 원인이었습니다.
• 동시 refresh 중 MCP OAuth refresh-token 손실. 여러 remote MCP servers를 사용하는 users는 더 이상 매일 재인증할 필요가 없어야 합니다. 동시 refresh writes가 서로를 덮어쓰고 있었습니다.
• Plan mode가 이제 file writes를 올바르게 차단합니다. matching Edit(...) allow rule이 plan-mode write protection을 우회하고 있었습니다. 이제 plan mode는 allow rules와 관계없이 강제됩니다.
• Plugin Stop 및 UserPromptSubmit hooks가 더 이상 mid-session에 실패하지 않습니다. cache cleanup이 실행 중인 session에서 아직 사용하는 plugin-version files를 삭제해, 이 두 hook events가 특히 깨졌습니다. 수정 후에는 사용 중인 versions가 pinned 상태로 유지됩니다.
• plugin.json의 skills entry. skills 설정이 plugin의 기본 skills/ directory를 숨기고 있었습니다. 이제 entry가 올바르게 compose되며, file path를 가리키면 조용히 실패하는 대신 명시적인 error가 발생합니다.
• CLAUDE_ENV_FILE SessionStart hook env vars가 stale해지던 문제. SessionStart hooks가 CLAUDE_ENV_FILE을 통해 export한 vars가 /resume 또는 /clear 후 stale해졌습니다. v2.1.136에서 수정되었습니다. 이제 sessions는 이 events에서 env file을 다시 source합니다.

governance harnesses에서 운영상 흥미로운 항목은 autoMode.hard_deny(새 lever)와 MCP disappearing fix(long sessions를 깨뜨리던 silent failure)입니다. 나머지는 quality-of-life cleanup입니다.

Structured Hook Arguments와 Block Continuation(2026년 5월 11일)

Claude Code v2.1.139는 production harnesses에 중요한 hook 세부사항 2가지를 추가했습니다. command hooks용 args: string[] exec form과 PostToolUse hooks용 continueOnBlock입니다.⁴²⁴⁴ hook에 dynamic values나 path placeholders가 필요하면 args를 선호하세요. shell 없이 command를 직접 spawn하므로 quoting과 injection 실수 한 범주가 통째로 사라집니다.

PostToolUse hook이 rejection reason을 Claude에 다시 전달하고 flow를 끝내지 않은 채 turn을 계속해야 할 때 continueOnBlock을 사용하세요. 이를 security bypass가 아니라 operator-experience 기능으로 다루세요. blocking gate는 여전히 unsafe outcome을 차단해야 합니다.

같은 release는 CLAUDE_PROJECT_DIR을 MCP stdio servers에 전달하고 plugin configs가 commands에서 ${CLAUDE_PROJECT_DIR}을 참조할 수 있게 합니다.⁴² MCP tools는 server를 시작한 process working directory가 무엇이었는지에 의존하지 말고, 이 값에서 project-relative paths를 resolve해야 합니다.

Claude Code v2.1.140은 대부분 harness operators를 위한 reliability release입니다. settings 변경 시 ConfigChange hooks가 실행되지 않던 문제를 고치고, disableAllHooks와 allowManagedHooksOnly가 settings levels 전반에서 올바르게 compose되지 않던 edge cases를 닫으며, permission dialogs가 hook results에서 반환된 의도치 않은 environment variables를 노출하지 않게 합니다.⁴⁹ 이 변경으로 이 섹션의 기존 governance patterns가 더 신뢰할 수 있게 됩니다. 새로운 hook architecture가 필요하지는 않습니다.

Claude Code v2.1.141은 controlling terminal 없이 desktop notifications, window titles, bells를 처리하기 위한 hook-output terminalSequence field를 추가합니다.⁵⁰ 이는 enforcement가 아니라 operator signaling으로 다루세요. Security와 quality gates는 여전히 일반적인 blocking contract, 즉 structured hook output과 unsafe action을 막는 exit behavior를 통해 failures를 전달해야 합니다. 같은 release는 Agent View를 한 directory로 제한하는 claude agents --cwd <path>, GitHub SSH keys가 없는 environments에서 plugin installs를 위한 CLAUDE_CODE_PLUGIN_PREFER_HTTPS, 여러 workspace를 포함하는 workload-identity federation rules를 위한 ANTHROPIC_WORKSPACE_ID도 추가합니다.⁵⁰ 이들은 team harnesses를 위한 architecture details입니다. 더 좁은 operational views, 줄어든 plugin-install assumptions, 명시적인 enterprise token scoping입니다.

Claude Code v2.1.142는 hook semantics보다 background-session orchestration에 더 중요합니다.⁵¹ claude agents는 이제 wrapper state에 의존하지 않고 명시적인 directory, settings, MCP, plugin, permission, model, effort flags로 background sessions를 dispatch할 수 있습니다. Fast mode는 이제 기본값이 Opus 4.7입니다. harness가 Opus 4.6 behavior에 의존한다는 측정된 근거가 있을 때만 CLAUDE_CODE_OPUS_4_6_FAST_MODE_OVERRIDE=1을 pin하세요. Root-level plugin SKILL.md discovery와 plugin-provided LSP visibility는 packaging ambiguity를 줄입니다. MCP_TOOL_TIMEOUT, 이미 존재하던 background-session worktrees, daemon sleep/wake 및 post-upgrade cleanup, plugin cache cleanup에 대한 fixes는 orchestration bugs처럼 보일 수 있는 reliability gaps를 닫습니다.

Stop-hook steering, cross-session authority, multi-agent v2(2026년 6월)

6월 초의 4가지 변경은 harness와 multi-agent design에 중요합니다.⁵⁹

Stop/SubagentStop hooks에 steering channel이 생겼습니다. Claude Code v2.1.163부터 Stop 또는 SubagentStop hook은 hookSpecificOutput.additionalContext를 반환해 Claude에 feedback을 전달하고, 응답이 hook error로 표시되지 않은 채 turn을 계속할 수 있습니다. 이전에는 Stop hook의 실질적 lever가 exit-2 block뿐이었고, 이는 error처럼 읽히며 consecutive-block cap에 포함되었습니다. quality-gate harness에는 이것이 더 깔끔한 primitive입니다. “done이라고 했지만 tests가 red입니다”를 감지한 Stop hook은 이제 hard-blocking 대신 “아직 실패하는 항목은 이것이니 계속하세요”를 주입할 수 있습니다. 진짜 stop conditions에는 block을, “아직 끝나지 않았고 이유는 이것입니다”에는 additionalContext를 사용하세요.

Cross-session messaging은 더 이상 borrowed authority를 전달하지 않습니다. v2.1.166은 multi-session case를 강화했습니다. 다른 Claude session에서 SendMessage를 통해 relayed된 messages는 더 이상 originating user의 authority를 전달하지 않으므로, receiving session은 relayed permission requests를 거부하고 auto mode가 이를 차단합니다. orchestration에서 agents가 서로 message하게 한다면 inbound message를 authenticated instruction이 아니라 untrusted data로 다루세요. 이는 security section이 tool output에 적용하는 원칙을 inter-agent messaging으로 확장한 것입니다.

Model resilience가 first-class setting이 되었습니다. fallbackModel setting은 이제 최대 3개의 backup models를 순서대로 연결하며, primary가 overloaded 또는 unavailable일 때 차례로 시도합니다. 또한 unexpected non-retryable API errors가 발생하면 turn이 fallback에서 한 번 auto-retry됩니다. long-running autonomous harness에서는 transient primary-model outage가 dropped run이 아니라 graceful degradation이 됩니다. claude agents --json도 v2.1.162에서 waitingFor field를 추가해, blocked background session이 permission prompt처럼 무엇을 기다리는지 드러냅니다. agents fleet를 polling하는 coordinator에게는 observability 측면의 이점입니다.

Clean-room governance와 troubleshooting을 위한 safe mode. Claude Code v2.1.169는 모든 customization을 한 번에 비활성화한 session을 시작하는 --safe-mode flag와 대응하는 CLAUDE_CODE_SAFE_MODE environment variable을 추가합니다. CLAUDE.md, plugins, skills, hooks, MCP servers가 모두 꺼집니다.⁶⁰ 이는 harness의 반대편에 있는 의도적인 clean-room입니다. 모든 operator가 결국 묻게 되는 질문, “이 동작은 model에서 나온 것인가, 아니면 내가 설정한 것에서 나온 것인가?”에 답할 때 사용하세요. hook이 잘못 발화하거나, skill이 원치 않을 때 활성화되거나, MCP server가 context를 오염시킬 때 --safe-mode는 diff할 수 있는 known-empty baseline을 제공합니다. 이는 governance primitive이기도 합니다. harness가 보통 부여하는 persistent authority 없이 bare model을 실행하는 방법이며, operator-defined scaffolding의 영향 없이 결과를 재현해야 할 때 중요합니다.

Model tiers에 대한 참고. 이 가이드는 Opus 4.8을 Claude Code의 agentic default, 즉 달리 선택하지 않는 한 autonomous harnesses를 실행하는 model로 다룹니다. 2026년 6월 9일 기준, Anthropic는 Opus보다 위의 새 tier인 Claude Fable 5(claude-fable-5)를 출시했습니다. 이는 가장 강력한 모델, 즉 general use에 맞게 안전화된 “Mythos-class” system으로 설명되며, Claude Code v2.1.170에서 /model claude-fable-5로 선택할 수 있습니다.⁶⁰ Opus 4.8은 agentic default로 남아 있습니다. 더 높은 tier는 fleet의 blanket setting이 아니라 raw reasoning depth가 cost를 정당화하는 decision에 의도적으로 사용하세요.

Codex가 multi-agent v2를 출시했습니다. Codex CLI v0.137.0은 runtime choice를 각 thread에 유지하고, spawned agents의 follow-up 및 metadata defaults를 더 깔끔하게 노출하며(hide_spawn_agent_metadata는 이제 기본값이 true), raw parent events를 child listeners로 전파합니다. subagent model은 명시적으로 유지됩니다. built-in default/worker/explorer agent types, TOML-defined custom agents, concurrency controls(agents.max_threads 기본값 6, agents.max_depth 기본값 1)입니다. 같은 release는 per-turn skill-catalog resolution과 새로운 thread-start/turn-error lifecycle contributor events가 있는 v1 skills extension을 추가해, kernel-sandbox posture를 기본 경계로 유지하면서 Claude Code의 hook/skill surface와의 격차를 좁혔습니다. 이어서 Codex v0.138.0-v0.139.0은 production을 위해 multi-agent v2를 강화했습니다. inter-agent message payloads는 이제 encrypted되며, v2 agent config catalog와 agent-residency LRU가 어떤 agents를 resident로 유지할지 관리하고, concurrency는 spawned threads가 아니라 active execution 기준으로 계산되므로 idle agents는 더 이상 slot을 소비하지 않습니다.⁶¹ lifecycle API도 성숙했습니다. close_agent는 단순히 handle을 닫는 것이 아니라 running agent를 interrupt한다는 점을 반영해 interrupt_agent(v0.139.0)로 이름이 바뀌었습니다. 또한 subagent가 올린 MCP startup warnings는 이제 parent transcript로 중복 전파되지 않고 owning thread에만 scope됩니다.⁶¹ Codex 측 orchestration을 구축하는 사람에게 이것들은 demo와 fleet를 가르는 차이입니다. encrypted message transport, bounded residency, execution-counted concurrency, thread boundary를 넘지 않는 warnings입니다. 이어서 Codex v0.140.0은 cross-tool seam을 열었습니다. /import는 Claude Code에서 setup, project config, recent chats를 선택적으로 Codex로 가져오며, sessions는 영구 삭제 가능해졌습니다(codex delete / /delete, confirmation safeguards 포함).⁶⁴ /import는 operators가 harnesses 사이를 이동한다는 첫 공식 인정입니다. 하나를 위해 만든 configuration이 더 이상 그 안에 갇혀 있지 않습니다.

Memory와 Context

모든 AI 대화는 제한된 context window 안에서 작동합니다. 대화가 길어지면 시스템은 새 내용을 위한 공간을 만들기 위해 이전 턴을 압축합니다. 이 압축은 손실이 있습니다. 3번째 턴에 문서화한 아키텍처 결정이 15번째 턴까지 살아남지 못할 수 있습니다.⁹

Multi-Turn Collapse의 3가지 메커니즘

MSR/Salesforce 연구는 각각 다른 개입이 필요한 3가지 독립 메커니즘을 확인했습니다.⁹

전략 1: Memory로서의 파일시스템

context 경계를 넘어 가장 신뢰할 수 있는 memory는 파일시스템에 있습니다. Claude Code는 모든 session 시작 시와 모든 compaction 이후에 CLAUDE.md와 memory 파일을 읽습니다.⁶

~/.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 파일은 session을 가로질러 오류, 결정, 패턴을 기록합니다. bash에서 VAR가 0일 때 set -e와 함께 ((VAR++))가 실패한다는 사실을 발견하면 이를 기록합니다. 3번의 session이 지난 뒤 Python에서 비슷한 integer edge case를 만나면, MEMORY.md 항목이 그 패턴을 드러냅니다.¹⁵

Auto Memory (v2.1.32+): Claude Code는 project context를 자동으로 기록하고 다시 불러옵니다. 작업하는 동안 Claude는 관찰 내용을 ~/.claude/projects/{project-path}/memory/MEMORY.md에 씁니다. Auto memory는 session 시작 시 처음 200줄을 system prompt에 로드합니다. 간결하게 유지하고, 자세한 메모는 별도의 topic 파일로 링크하세요.⁶

Memory volume보다 memory curation (2026년 5월): LLM-agent 협력에 관한 최근 arXiv preprint는 확장된 recall을 잠재적 실패 모드로 봅니다. 저자들의 실험에서 더 긴 visible history는 28개의 model-game 설정 중 18개에서 협력을 저하시켰습니다.⁴⁸ 이를 확정된 법칙이 아니라 설계상의 경고로 다루세요. production 규칙은 이미 충분히 분명합니다. MEMORY.md는 짧게 유지하고, 세부 내용은 링크로 분리하며, handoff에는 결정을 내릴 수 있는 요약을 넣으세요. raw transcript dump, tool log, 긴 recall feed는 active prompt에 자동으로 넣을 것이 아니라 검색 가능한 storage에 두어야 합니다.

전략 2: Proactive Compaction

Claude Code의 /compact 명령은 대화를 요약하고 핵심 결정, 파일 내용, task 상태를 보존하면서 context 공간을 비웁니다.¹⁵

compact해야 할 때: - 별도의 subtask를 완료한 뒤(feature 구현, bug 수정) - codebase의 새 영역을 시작하기 전 - Claude가 앞선 context를 반복하거나 잊기 시작할 때 - 집중 session 중 대략 25-30분마다

CLAUDE.md의 custom compaction instructions:

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

Compaction은 대화를 보호하고, /cd 명령(Claude Code v2.1.169)은 prompt cache를 보호합니다. 이 명령은 턴 동안 누적된 cache를 깨뜨리지 않고 session을 진행 중에 새 working directory로 이동합니다.⁶⁰ 이전에는 directory를 바꾸면 새 session과 cold cache가 필요했습니다. 오래 실행 중인 session이 한 repository에서 sibling repository로 전환되는 경우, monorepo와 multi-service 작업에서 흔하듯이, /cd는 비용이 큰 cached prefix를 그대로 유지하면서 filesystem context만 다시 가리키게 합니다.

전략 3: Session Handoffs

여러 session에 걸친 task라면 전체 상태를 담는 handoff 문서를 만드세요.

## 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 구조는 다음 session에 최소 token 비용으로 전체 context를 제공합니다. claude -c(continue)로 새 session을 시작하거나 handoff 문서를 읽으면 바로 구현으로 들어갈 수 있습니다.¹⁵

전략 4: Fresh-Context Iteration (The Ralph Loop)

60-90분을 넘는 session에서는 iteration마다 새로운 Claude instance를 시작하세요. 상태는 대화 memory가 아니라 파일시스템을 통해 유지됩니다. 각 iteration은 전체 context budget을 받습니다.¹⁶

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

하나의 긴 session과 비교해 보세요.

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

iteration마다 fresh context를 사용하는 접근은 orient 단계(상태 파일 읽기, git history scan)에 15-20%의 overhead를 쓰는 대신, iteration마다 전체 cognitive resources를 확보합니다.¹⁶ 비용 대비 효과는 이렇습니다. 60분 미만의 session에서는 하나의 대화가 더 효율적입니다. 90분을 넘기면 overhead가 있어도 fresh-context가 더 높은 품질의 output을 만듭니다.

전략 5: Managed Memory Curation (Dreaming)

Anthropic의 Claude Managed Agents는 2026년 5월 6일 Research Preview로 Dreaming을 추가했습니다.³⁵ Anthropic에 따르면 “Dreaming is a scheduled process that reviews your agent sessions and memory stores, extracts patterns, and curates memories so your agents improve over time.”³⁵

Dreaming은 critical path가 아니라 session 사이의 background에서 실행됩니다. 이는 filesystem-as-memory 패턴을 대체하기보다 보완합니다. MEMORY.md 파일은 계속 load-bearing surface로 남고, Dreaming은 선별된 memory 항목을 Managed Agents memory store에 기록하며 agent는 session 시작 시 이를 읽습니다. self-hosted filesystem state와 managed-side curation을 함께 쓰는 harness에서는 두 패턴이 공존합니다.

Dreaming은 Research Preview이므로 동작이 바뀔 수 있습니다. 위에 문서화한 session-handoff와 CLAUDE.md 패턴은 self-hosted harness를 위한 authoritative memory mechanism으로 남습니다.

Anti-Patterns

10줄만 필요할 때 파일 전체를 읽기. 2,000줄짜리 파일 하나를 읽으면 15,000-20,000 token을 소비합니다. line offset을 사용하세요. Read file.py offset=100 limit=20은 그 비용의 대부분을 절약합니다.¹⁵

장황한 error output을 context에 유지하기. bug를 디버깅한 뒤 context에는 실패한 iteration에서 나온 40개 이상의 stack trace가 남아 있습니다. bug를 고친 뒤 /compact를 한 번 실행하면 이 죽은 무게를 덜어낼 수 있습니다.

모든 session을 모든 파일 읽기로 시작하기. Claude Code의 glob과 grep tools가 필요할 때 관련 파일을 찾게 하세요. 불필요한 pre-loading으로 인한 100,000개 이상의 token 낭비를 줄일 수 있습니다.¹⁵

Subagent 패턴

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

기본 제공 Subagent 유형

Custom Subagents 만들기

.claude/agents/(프로젝트) 또는 ~/.claude/agents/(개인)에 subagents를 정의하세요.

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

Subagent 설정 필드

Worktree 격리

Subagents는 임시 git worktrees에서 작업할 수 있어, repository의 완전히 격리된 복사본을 제공합니다.⁵

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

병렬 Subagents

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

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

각 agent는 자체 context window에서 실행되고, 관련 코드를 찾은 뒤 요약을 반환합니다. 메인 context는 깨끗하게 유지됩니다.

Recursion Guard

생성 제한이 없으면 agents는 agents에게 위임하고, 그 agents가 다시 agents에게 위임하면서 각 단계마다 context를 잃고 토큰을 소모합니다. recursion guard 패턴은 예산을 강제합니다.¹⁶

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

핵심 교훈: 단순한 depth 제한이 아니라 spawn budget을 사용하세요. depth 기반 제한은 부모-자식 체인(depth 3에서 차단)을 추적하지만 폭은 놓칩니다. depth 1에 agents가 23개 있어도 여전히 “depth 1”입니다. spawn budget은 부모별 전체 활성 자식 수를 추적하고, 설정 가능한 최대값으로 제한합니다. 이 budget 모델은 대리 지표(중첩 수준이 너무 많음)가 아니라 실제 실패 모드(전체 agents가 너무 많음)에 대응합니다.⁷

재귀 위임은 이제 first-party depth입니다. Claude Code v2.1.172(2026년 6월 10일) 기준으로 sub-agents는 자체 sub-agents를 생성할 수 있으며, 최대 5단계까지 중첩됩니다. 이전에는 위임이 사실상 1단계였습니다.⁶² 따라서 위의 recursion guard는 덜 중요해진 것이 아니라 더 중요해졌습니다. 이제 플랫폼이 context와 토큰을 태우는 agents-delegating-to-agents 체인을 정확히 허용하므로, 5단계 트리가 수백 개의 활성 agents로 퍼지지 않게 막는 장치가 spawn budget과 depth cap입니다. 5단계는 플랫폼이 허용하는 상한으로 보아야 하며, 기본적으로 목표로 삼을 값이 아닙니다.

Auto mode는 이제 실행 전에 spawn을 검토합니다. Claude Code v2.1.178은 매칭 governance gap을 닫았습니다. auto mode에서 subagent spawns는 subagent가 시작된 뒤 action을 취할 때만 평가되는 것이 아니라, subagent가 시작되기 전에 permission classifier로 평가됩니다.⁶³ 이전에는 부모 세션에서는 차단되었을 action을 요청하도록 subagent를 생성할 수 있었습니다. spawn 자체가 우회로였던 셈입니다. spawn 시점의 검토는 recursion guard와 permission model이 마침내 만난다는 뜻입니다. child는 정책이 금지한 action을 세탁하는 단계로 사용될 수 없습니다.

Agent Teams (Research Preview)

Agent Teams는 독립적으로 작업하고, 공유 mailbox와 task list를 통해 소통하며, 서로의 발견에 이의를 제기할 수 있는 여러 Claude Code 인스턴스를 조율합니다.⁵

활성화: export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

agent teams와 subagents를 구분해 사용할 때:

Agent View와 Goal Loops (2026년 5월)

Claude Code v2.1.139는 claude agents로 시작하는 research-preview 인터페이스인 Agent View를 추가했습니다. 이 화면에서는 실행 중, 차단됨, 완료된 Claude Code 세션을 한곳에서 볼 수 있습니다.⁴²⁴³ 공식 docs는 이를 여러 세션을 dispatch하고 관리하며, 각 세션이 무엇을 하는지 보고, operator input이 필요한 세션을 식별하는 방법으로 설명합니다.⁴³ 덕분에 multi-agent 작업은 최종 요약만으로는 제공할 수 없는 operations view를 갖게 됩니다.

subagent나 team 패턴을 승격할 때 Agent View를 사용하세요. 어떤 세션이 차단되었는지, 어떤 세션이 아직 실행 중인지, 작업 분배가 의도한 architecture와 맞는지 확인하세요. 이것을 품질의 증거로 간주하지는 마세요. 이는 observability입니다. tests, review gates, evidence reports가 여전히 작업이 sound한지 결정합니다.

같은 릴리스는 /goal도 추가했습니다. /goal은 완료 조건을 설정하고, interactive, -p, Remote Control 사용을 포함해 조건이 충족될 때까지 Claude가 turn을 이어가도록 합니다.⁴² /goal은 deterministic gates를 대체하는 것이 아니라 session-scoped completion loop로 다루세요. agent가 목표에 집중하도록 유지하는 데 유용하지만, 실패 시 차단해야 하는 tests, citation checks, deploy checks, security hooks는 command 또는 script 기반으로 유지해야 합니다.

Workflow Tool (v2.1.147+)

Claude Code v2.1.147은 기본적으로 꺼져 있는 Workflow 도구를 추가해 deterministic multi-agent orchestration을 제공합니다. CLAUDE_CODE_WORKFLOWS=1로 활성화하세요.⁵² architecture 관점에서 이는 중요합니다. 이전에는 custom dispatch scripts, mailbox state, subagent coordination conventions가 필요했던 flows에 대해 Claude Code가 first-party orchestration primitive를 갖게 되었기 때문입니다.

그 주변의 harness를 삭제하지 마세요. Workflow는 실행 구조를 잡을 수 있지만 safety model을 대체하지는 않습니다. PreToolUse와 PostToolUse hooks를 차단 계층으로 유지하고, 폭주하는 폭을 막기 위해 spawn budgets 또는 workflow step budgets를 유지하며, filesystem state를 감사 가능하게 유지하고, 최종 evidence reports는 model의 self-assessment 밖에 두세요. 실제로는 Workflow를 orchestration shape에 사용하고, hooks, tests, review gates를 truth에 사용하세요.

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

단일 에이전트 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 agent를 위한 운영 정책입니다.²¹ agent는 사용자가 왜 conventional commits를 사용하는지 이해할 필요가 없습니다. 실행할 정확한 명령과 “완료”의 기준을 알아야 합니다.

우선순위 계층

Rules 파일은 자동으로 로드되며 CLAUDE.md를 어지럽히지 않고 구조화된 컨텍스트를 제공합니다.⁶

무시되는 항목

다음 패턴은 agent 동작에서 관찰 가능한 변화를 안정적으로 만들어내지 못합니다.²¹

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

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

서로 충돌하는 우선순위. “빠르게 움직이고 빠르게 배포하세요”에 “포괄적인 테스트 커버리지를 보장하세요”, “런타임을 5분 미만으로 유지하세요”, “모든 commit 전에 전체 통합 테스트를 실행하세요”를 더한 경우입니다. agent는 4가지를 동시에 만족할 수 없고 기본적으로 검증을 건너뜁니다.²¹

강제 수단 없는 스타일 가이드. ruff check --select D 없이 “Google Python Style Guide를 따르세요”라고만 하면 agent가 준수 여부를 확인할 방법이 없습니다.

효과적인 방식

명령 우선 지시:

## 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. 빌드 및 테스트 명령 (agent가 유용한 일을 하려면 먼저 필요합니다)
2. 완료의 정의 (거짓 완료를 방지합니다)
3. 에스컬레이션 규칙 (파괴적인 우회책을 방지합니다)
4. 작업별로 구성된 섹션 (관련 없는 지시 파싱을 줄입니다)
5. 디렉터리 범위 지정 (monorepos: 서비스 지시를 분리해 유지합니다)

앞의 4가지가 작동하기 전까지는 스타일 선호도를 건너뛰세요.

파일 Import

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

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

Import 문법: 상대 경로(@docs/file.md), 절대 경로(@/absolute/path.md), 또는 홈 디렉터리(@~/.claude/file.md). 최대 깊이: 5단계 import.⁶

Cross-Tool 지시 호환성

AGENTS.md는 모든 주요 AI coding tool이 인식하는 open standard입니다.²¹ 팀에서 여러 도구를 사용한다면 AGENTS.md를 canonical source로 작성하고 관련 섹션을 도구별 파일에 미러링하세요.

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

Codex 동등성 참고

Codex에는 이제 주요 harness 계층에 대한 일급 동등 기능이 있지만, 마이그레이션은 파일 복사가 아니라 패턴 변환입니다. Codex는 작업이 시작되기 전에 AGENTS.md를 읽고, ~/.codex의 global guidance를 프로젝트 및 중첩 repository 지시와 계층화합니다.³¹ Codex skills는 progressive disclosure와 함께 동일한 SKILL.md mental model을 사용합니다. Codex는 skill 이름, 설명, 파일 경로로 시작한 다음, 해당 skill을 사용하기로 결정했을 때만 전체 skill을 로드합니다.³² Codex에는 native hooks, plugin-bundled hooks, managed hooks, MCP 지원, 명시적인 subagent workflows도 있습니다.³³³⁴

Codex v0.138.0-v0.139.0은 복잡한 workspace를 위해 AGENTS.md discovery를 더 견고하게 만들었습니다. 이제 로딩은 환경의 filesystem abstraction을 통해 라우팅되고 discovery walk 중 logical paths를 보존하므로, workspace가 remote filesystem이거나 symlinked tree여도 올바른 파일이 선택됩니다.⁶¹ 이는 canonical AGENTS.md가 권위 있는 source이고 agent가 mounted, container-materialized, 또는 symlinked checkout 위에서 작동할 때 중요합니다. 이런 경우에는 단순한 path walk가 조용히 잘못된 지시 파일을 선택하거나 아무 파일도 선택하지 않을 수 있습니다. 하나의 권위 있는 AGENTS.md를 여러 서비스에 미러링한다면, agent가 실제로 로드한 파일이 사용자가 작성한 파일이라고 신뢰하기 위한 최소 기준으로 보세요.

그다음 Codex v0.141.0은 remote-execution 경로 자체를 더 견고하게 만들었습니다. remote executors는 이제 인증된 end-to-end encrypted Noise-relay 채널로 연결됩니다(control plane과 executor는 더 이상 그 사이의 relay를 신뢰하지 않습니다). cross-platform remote execution은 executor의 native working directory와 shell을 보존하고, TLS는 enterprise proxies를 위해 P-521 certificate signatures를 허용합니다.⁶⁵ orchestration이 네트워크 경계를 넘어 Codex executors를 구동한다면, 이는 trusted-relay 가정과 end-to-end-encrypted 가정의 차이입니다. 모든 remote-executor topology의 기준선으로 보세요.

실제 매핑은 다음과 같습니다.

중요한 차이점: Claude subagents는 설명을 기반으로 자동 선택될 수 있지만, Codex는 현재 subagent workflows를 명시적인 방식으로 문서화합니다. 따라서 Codex에서 항상 켜져 있는 harness 동작의 기본값은 skills와 hooks가 적합합니다. subagents는 의도적인 병렬 작업, review, exploration에 사용하세요.

지시 테스트하기

agent가 실제로 지시를 읽고 따르는지 확인하세요.

# 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?"

결정적 테스트: agent에게 빌드 명령을 설명해 달라고 요청하세요. agent가 이를 그대로 재현하지 못한다면 지시가 너무 장황해 컨텍스트 밖으로 밀려났거나, 너무 모호해 agent가 실행 가능한 지시를 추출하지 못했거나, 발견되지 않은 것입니다. GitHub가 2,500개 repositories를 분석한 결과 대부분의 실패는 모호함 때문에 발생했습니다.²¹

프로덕션 패턴

Opus 4.7 장기 패턴 (2026년 4월)

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

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

Worktree Base, Sandbox Paths, Admin Settings (2026년 5월 7일)

Claude Code v2.1.133에는 프로덕션 harness에서 알아둘 만한 관리자 단계 설정 4개가 추가됐어요:³⁹

사용자에게 알려야 할 항목은 worktree.baseRef 되돌림이에요. v2.1.128-v2.1.132 동작(worktree가 로컬 HEAD에서 분기)에 의존하던 agents는 다시 옵트인하지 않는 한 새 worktree에서 push되지 않은 작업에 접근할 수 없어요.

엔터프라이즈 Observability를 위한 OTel 피드백 설문 (2026년 5월 8일)

Claude Code v2.1.136에는 OpenTelemetry를 통해 응답을 수집하는 엔터프라이즈가 세션 내 품질 설문을 다시 활성화할 수 있도록 CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL이 추가됐어요.⁴⁰ 조직이 OTel 이벤트를 중앙 observability 스택으로 보내고 있다면, 이 환경 변수는 설문을 데이터 경로에 다시 넣어 품질 신호가 지연 시간 및 오류 지표와 같은 파이프라인을 통과하게 해요. 옵트인으로 다루세요. 기본값은 설문을 억제한 상태로 두며, 이는 OTel을 사용하지 않는 배포에는 맞는 동작이에요.

Quality Loop

사소하지 않은 모든 변경에 필수로 적용하는 리뷰 프로세스예요:

1. 구현 - 코드를 작성해요
2. 리뷰 - 모든 줄을 다시 읽어요. 오타, 로직 오류, 불명확한 부분을 잡아내요
3. 평가 - evidence gate를 실행해요. 패턴, 엣지 케이스, 테스트 커버리지를 확인해요
4. 다듬기 - 모든 문제를 고쳐요. “나중에”로 미루지 마세요
5. 한 걸음 물러나 보기 - 통합 지점, import, 인접 코드에 회귀가 없는지 확인해요
6. 반복 - evidence gate 기준 중 하나라도 실패하면 4단계로 돌아가요
7. 보고 - 무엇이 바뀌었는지, 어떻게 검증했는지 나열하고 구체적인 증거를 인용해요

Evidence Gate

“그럴 것 같습니다”와 “그래야 합니다”는 증거가 아니에요. 파일 경로, 테스트 출력, 구체적인 코드를 인용하세요.

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

Human Merge Authority

2026년 5월 arXiv에 발표된 29,585개의 AI-agent pull-request 생애주기 연구는 운영상의 agency와 merge governance를 분리해요.⁴⁷ 여기서 얻을 수 있는 유용한 아키텍처 교훈은 단순해요. agents는 작업을 시작하고, 브랜치를 이어가고, PR을 열고, 작업을 리뷰하고, 위험을 요약할 수 있지만, merge authority는 별도의 governance 경계로 남아야 해요.

harness에서 이 경계를 명확히 하세요. agents가 PR을 준비하고 증거를 수집하게 하되, 조직에 별도로 감사된 자동화 정책이 없는 한 merge, release, 파괴적인 저장소 작업에는 사람의 승인을 요구하세요. 자동화가 merge를 실행하는 경우에는 실행자와 이를 승인한 사람 또는 정책을 구분하는 로그를 보존하세요.

오류 처리 패턴

원자적 파일 쓰기. 여러 agents가 동시에 같은 상태 파일에 쓰면 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 분류

모든 agent 작업을 blast radius에 따라 분류하고 그에 맞게 gate를 적용하세요:²

Remote Control(어떤 브라우저나 모바일 앱에서든 로컬 Claude Code에 연결)은 “External” gate를 대기 차단에서 비동기 알림으로 바꿔요. 사용자가 휴대폰에서 이전 작업을 검토하는 동안 agent는 다음 작업을 계속 진행해요.²

자율 실행을 위한 작업 명세

효과적인 자율 작업에는 목표, 완료 기준, 컨텍스트 포인터라는 3가지 요소가 포함돼요:¹⁶

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

기준은 기계적으로 검증 가능해야 해요. 테스트 통과/실패, linter 출력, HTTP 상태 코드, 파일 존재 확인 같은 것이어야 해요. 초기에 agent에게 “통과하는 테스트를 작성”하라고 요청한 작업에서는 assert True와 assert 1 == 1이 나왔어요. 기술적으로는 맞지만, 실무적으로는 쓸모없어요.¹⁶

주의해야 할 실패 모드

구체적인 세션 추적

5개 스토리가 포함된 PRD을 처리하는 자율 실행의 세션 추적이에요:²

1. SessionStart가 실행돼요. Dispatcher가 현재 날짜, 프로젝트 감지, 철학 제약, 비용 추적 초기화를 주입해요. hooks 5개, 총 180ms예요.

2. Agent가 PRD을 읽고 첫 번째 스토리를 계획해요. UserPromptSubmit이 실행돼요. Dispatcher가 활성 프로젝트 컨텍스트와 세션 드리프트 기준선을 주입해요.

3. Agent가 Bash를 호출해 테스트를 실행해요. PreToolUse:Bash가 실행돼요. 자격 증명 확인, sandbox 검증, 프로젝트 감지가 진행돼요. 90ms예요. 테스트가 실행돼요. PostToolUse:Bash가 실행돼요. 활동 heartbeat가 기록되고 drift check가 수행돼요.

4. Agent가 Write를 호출해 파일을 생성해요. PreToolUse:Write가 실행돼요. 파일 범위 검사가 이뤄져요. PostToolUse:Write가 실행돼요. lint check와 커밋 추적이 수행돼요.

5. Agent가 스토리를 마무리해요. Stop이 실행돼요. Quality gate가 확인해요. agent가 증거를 인용했나요? 얼버무리는 표현이 있나요? diff에 TODO 주석이 있나요? 어떤 검사든 실패하면 exit 2로 종료되고 agent는 계속 진행해요.

6. 독립 검증: 새 agent가 이전 agent의 자체 보고를 신뢰하지 않고 테스트 스위트를 실행해요.

7. 3개의 코드 리뷰 agents가 병렬로 spawn돼요. 각자 독립적으로 diff를 리뷰해요. 어떤 리뷰어라도 CRITICAL을 표시하면 해당 스토리는 큐로 돌아가요.

8. 스토리가 통과해요. 다음 스토리를 로드해요. 이 사이클이 5개 스토리 모두에 반복돼요.

5개 스토리에서 실행된 총 hooks 수는 약 340개예요. hooks에 소요된 총 시간은 약 12초예요. 이 오버헤드는 하룻밤 실행 한 번에서 자격 증명 유출 3건, 파괴적 명령 1건, 불완전한 구현 2건을 막았어요.

사례 연구: 하룻밤 PRD 처리

프로덕션 harness가 하룻밤 세션 8번에 걸쳐 12개의 PRDs(47개 스토리)를 처리했어요. 지표는 처음 4개의 PRDs(최소 harness: CLAUDE.md만 사용)와 마지막 8개(전체 harness: hooks, skills, quality gates, multi-agent review)를 비교해요.

두 건의 자격 증명 유출은 API 키를 교체하고 downstream services를 감사해야 했고, 대략 4시간의 사고 대응이 필요했어요. 그에 상응하는 문제를 막은 harness 오버헤드는 스토리당 bash 2.4초였어요. Stop hook이 agent가 완료를 보고하도록 허용하기 전에 테스트를 독립적으로 실행했기 때문에 거짓 완료율은 35%에서 4%로 떨어졌어요.

보안 고려 사항

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

Anthropic는 2026년 4월 9일에 agent 신뢰성에 대한 공식 프레임워크를 발표했습니다.²⁷ 이 5가지 원칙은 이 가이드의 Evidence Gate 사고방식과 나란히 맞물리며, 그 범위를 확장합니다.

Anthropic는 또한 MCP를 Linux Foundation의 Agentic AI Foundation에 기증했으며, AGENTS.md와 함께 합류했습니다. AGENTS.md는 현재 OpenAI, Google, Cursor, Factory, Sourcegraph가 공동으로 관리합니다. Agent 상호운용성 표준은 이제 vendor-neutral입니다.²⁷

Skill sandbox tooling: skills를 공격 표면으로 취급하는 팀을 위해, Permiso의 SandyClaw(2026년 4월 2일 출시)는 전용 sandbox에서 skills를 실행하고 Sigma/YARA/Nova/Snort detection 기반의 evidence-backed verdicts를 제공합니다. skill-sandbox category의 첫 제품입니다.²⁸

Sandbox

Claude Code는 선택적 sandbox mode를 지원합니다. 이 모드는 settings.json 또는 /sandbox 명령으로 활성화할 수 있으며, OS-level isolation(macOS의 seatbelt, Linux의 bubblewrap)을 사용해 네트워크 접근과 파일 시스템 작업을 제한합니다. 활성화하면 sandbox는 모델이 임의의 네트워크 요청을 하거나 프로젝트 디렉터리 밖의 파일에 접근하지 못하게 막습니다. sandboxing이 없으면 Claude Code는 개별 tool 호출을 승인하거나 거부하는 permission-based model을 사용합니다.¹³

2026년 5월 보안 기준선. Claude Code v2.1.149는 PowerShell working-directory permission bypass, 여러 PowerShell allow-rule 및 stale-variable permission-analysis gap, 그리고 shared git internals만이 아니라 전체 main repository root를 덮던 git-worktree sandbox write-allowlist bug를 수정했습니다.⁵³ harness가 PowerShell 또는 worktree-isolated agents를 허용한다면 v2.1.149+를 기준선으로 삼고 shell rules는 좁게 유지하세요. 광범위한 PowerShell(*)와 all-repo write exceptions는 orchestration shortcuts이지 safety boundaries가 아닙니다.

OpenAI Agents SDK sandbox lockdown(v0.17.0, 2026년 5월 8일). OpenAI 쪽에서는 openai-agents-python v0.17.0이 병렬 경계를 강화했습니다. LocalFile.src와 LocalDir.src는 이제 source가 SandboxPathGrant와 함께 Manifest.extra_path_grants를 통해 명시적으로 허용되지 않는 한, materialization base_dir(manifest가 적용될 때 SDK process current working directory) 안으로 제한됩니다.⁴¹ Relative local sources는 base_dir에서 resolve됩니다. Absolute paths는 이미 그 안에 있거나 grant를 가져야 합니다. 이는 local artifact boundary issue를 닫습니다. 이전 버전에서는 manifests가 임의의 host paths를 sandbox workspace로 가져올 수 있었습니다. Migration: read-only mounts에는 manifest level에서 SandboxPathGrant(path=..., read_only=True)로 trusted host roots를 선언하세요. extra_path_grants는 trusted application configuration으로 취급하세요. model output이나 untrusted manifest input에서 grants를 채우면 안 됩니다.

OpenAI Agents SDK 후속 기준선(v0.17.3). 0.17.1-0.17.3 라인은 더 많은 sandbox 및 session hardening을 추가했습니다. archive extraction limits, GitRepo subpath validation, 더 명확한 sandbox-provider errors, sandbox commands에서 mountpoint credentials 제외, relative sandbox workspace roots 거부, Vercel-sandbox terminal-state handling이 포함됩니다.⁵⁴ Claude Code hooks만 사용하는 것이 아니라 OpenAI-hosted 또는 provider-backed sandboxes를 사용한다면, 이 섹션의 패턴에는 0.17.3을 현재 기준선으로 삼으세요.

권한 경계

permission system은 여러 수준에서 작업을 gate합니다.

Parameter-Level Permission Rules(2026년 6월)

Claude Code v2.1.178은 permission rules를 tool level에서 parameter level까지 확장했습니다. Tool(param:value)는 tool의 input parameters와 match하며, *는 wildcard로 사용됩니다. canonical example은 Agent(model:opus)입니다. 특정 model tier에서 subagents가 spawn되는 것을 차단하는 rule입니다.⁶³ Architecture 관점에서 보면, 이는 위의 4단계 표로는 표현할 수 없던 gap을 닫습니다. 이전에는 tool 전체를 허용하거나 거부할 수는 있었지만, 그 tool이 어떻게 호출되는지는 제한할 수 없었습니다. 이제 governance policy는 prompt-level request가 아니라 deterministic rule로 “subagents는 spawn할 수 있지만 Fable 5 tier에서는 안 된다” 또는 “Bash는 허용하지만 이 flag는 안 된다”라고 말할 수 있습니다.

companion managed setting인 enforceAvailableModels(v2.1.175)는 model selection을 위에서부터 제한합니다. Default model을 고정하고, user- 또는 project-scoped settings가 managed availableModels allowlist를 넓히지 못하게 막습니다.⁶³ 이 둘은 함께 구성됩니다. allowlist는 session에 존재할 수 있는 tiers 자체를 정의하고, parameter-level rules는 subagents가 그 안에서 어떻게 선택하는지를 제한합니다.

Auto-Mode Destructive-Command Guardrails(2026년 6월)

Claude Code v2.1.183은 작업을 조용히 잃게 만들거나 environments를 teardown하는 작업에 대해 auto mode의 blast radius를 좁혔습니다. 이제 auto mode는 session에서 명시적으로 요청하지 않는 한 다음을 hard-block합니다. destructive git operations(git reset --hard, git checkout -- ., git clean -fd, git stash drop), 이번 session에서 agent가 만들지 않은 commit에 대한 git commit --amend, 그리고 특정 stack을 이름으로 지정하지 않은 infrastructure teardown(terraform destroy, pulumi destroy, cdk destroy)입니다.⁶⁵ Architecture 관점에서 이는 위의 spawn-vetting 및 parameter-level rules를 보완합니다. 어떤 tool인지 또는 어떻게 spawn되는지를 gate하는 대신, 의도에 따라 특정한 되돌릴 수 없는 commands의 작은 집합을 gate합니다. agent는 여전히 그것들을 실행할 수 있지만, 스스로의 판단이 아니라 명시적 지시가 있을 때만 가능합니다. autonomous harness에서는 같은 원칙을 자체 PreToolUse hooks에 encode하세요. 상태를 파괴하는 commands에는 explicit operator signal이 있을 때만 해제되는 deny-by-default rule이 필요합니다.

Prompt Injection 방어

Skills와 hooks는 prompt injection에 대한 defense-in-depth를 제공합니다.

Tool restrictions가 있는 skills는 compromised prompt가 write access를 얻지 못하게 막습니다.

allowed-tools: Read, Grep, Glob

PreToolUse hooks는 model이 어떤 prompt를 받았는지와 무관하게 모든 tool 호출을 검증합니다.

# 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 isolation은 blast radius를 제한합니다. permissionMode: plan이 있는 subagent는 prompt가 compromised되더라도 변경을 만들 수 없습니다.

Agent Logs와 Guardrails는 보안 표면입니다

2026년 5월의 두 advisories는 하나의 패턴을 강화합니다. agent infrastructure는 민감한 content와 executable policy가 leak되거나 escape될 수 있는 새로운 장소를 만듭니다. GitHub Advisory GHSA-f3jg-756w-gm35는 Gryph Agents payload-filter issue를 다룹니다. default logging behavior에서는 sensitive tool-payload content가 local SQLite logs에 남을 수 있었습니다.⁴⁵ OSV GHSA-wxxx-gvqv-xp7p는 admin-protected proxy endpoint에서 LiteLLM custom-code guardrail sandbox escape를 다룹니다.⁴⁶

Production rule은 agent transcripts, tool payloads, SQLite logs, guardrail execution을 sensitive infrastructure로 취급하는 것입니다. persistence 전에 redact하고, retention limits를 적용하며, custom guardrail code는 sandboxed하고 reviewable하게 유지하세요. prompt-level의 “secrets를 log하지 말라” rule만으로는 충분하지 않습니다. logging 및 guardrail path에는 deterministic tests가 필요합니다.

Hook 보안

environment variables를 headers에 interpolate하는 HTTP hooks는 임의의 environment variable exfiltration을 막기 위해 명시적인 allowedEnvVars list가 필요합니다.¹³

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

Human-Agent 책임 분리

agent architectures의 보안에는 human responsibilities와 agent responsibilities 사이의 명확한 분리가 필요합니다.¹⁷

패턴은 이렇습니다. 조직적 맥락, 윤리적 판단, 전략적 방향이 필요한 결정은 humans가 소유합니다. 큰 가능성 공간에서 computational search가 필요한 결정은 agents가 소유합니다. Hooks가 그 경계를 enforce합니다.

Recursive Hook Enforcement

Hooks는 subagent actions에도 fire됩니다.¹³ Claude가 Agent tool을 통해 subagent를 spawn하면, subagent가 사용하는 모든 tool에 대해 PreToolUse 및 PostToolUse hooks가 실행됩니다. recursive hook enforcement가 없으면 subagent가 safety gates를 우회할 수 있습니다. SubagentStop event를 사용하면 subagent가 완료될 때 cleanup 또는 validation을 실행할 수 있습니다.

이는 선택 사항이 아닙니다. security hooks 없이 subagent를 spawn하는 agent는 gates가 main conversation에서 아무 일도 일어나지 않는 것을 지켜보는 동안 main에 force-push하거나, credential files를 읽거나, destructive commands를 실행할 수 있는 agent입니다.

비용은 Architecture입니다

Cost는 operational afterthought가 아니라 architectural decision입니다.² 3가지 수준이 있습니다.

Token level. System prompt compression. Tutorial code examples를 제거하세요. 모델은 APIs를 이미 알고 있습니다. files 사이의 duplicate rules를 collapse하고, explanations를 constraints로 바꾸세요. “sensitive paths와 match되는 tool calls를 reject하라”는 credentials를 읽으면 안 되는 이유를 15줄로 설명하는 것과 같은 일을 합니다.

Agent level. 긴 conversations보다 fresh spawns를 우선하세요. autonomous run의 각 story는 clean context를 가진 새 agent를 받습니다. 각 agent가 fresh하게 시작하므로 context가 불어나지 않습니다. memory 대신 briefing을 사용하세요. models는 누적된 context 30단계를 탐색하는 것보다 명확한 briefing을 더 잘 실행합니다.

Architecture level. operation이 stateless라면 MCP보다 CLI-first를 우선하세요. one-shot evaluation을 위한 claude --print call은 비용이 더 적고 connection overhead가 없습니다. tool에 persistent state 또는 streaming이 필요할 때 MCP가 적합합니다.

의사결정 프레임워크

각 메커니즘을 언제 사용할지:

Skills vs Hooks vs Subagents

FAQ

hook이 몇 개면 너무 많은가요?

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

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

네. PreToolUse hooks는 code 2로 종료하여 모든 tool action을 차단합니다. Claude Code는 대기 중인 action을 취소하고 hook의 stderr 출력을 모델에 보여줍니다. Claude는 거부 이유를 보고 더 안전한 대안을 제안합니다. Exit 1은 비차단 경고이며 action은 계속 진행됩니다.³

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

hook 설정은 프로젝트 수준 hook의 경우 .claude/settings.json에 둡니다. 이 파일은 repository에 커밋되어 팀과 공유됩니다. 사용자 수준 hook의 경우 ~/.claude/settings.json에 두며, 개인용으로 모든 프로젝트에 적용됩니다. 둘 다 있으면 프로젝트 수준 hook이 우선합니다. 작업 디렉터리 문제를 피하려면 스크립트 파일에 절대 경로를 사용하세요.¹⁴

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

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

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

성공 경로와 실패 경로를 모두 테스트하세요. 성공: agents가 생산적으로 의견을 달리하고 합의에 도달합니다. 실패: agents가 너무 빨리 수렴하거나, 전혀 수렴하지 않거나, spawn 예산을 초과합니다. End-to-end tests는 결정적 agent 응답으로 각 시나리오를 시뮬레이션하고, 두 validation gates가 문서화된 모든 실패 모드를 잡는지 검증합니다. 프로덕션 deliberation 시스템은 3개 계층에 걸쳐 141개 테스트를 실행합니다. 48개의 bash 통합 테스트, 81개의 Python unit tests, 12개의 end-to-end pipeline simulations입니다.⁷

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

3-agent deliberation은 벽시계 기준 30-60초를 추가합니다(agents는 Agent tool을 통해 순차 실행됨). 10-agent deliberation은 2-4분을 추가합니다. consensus 및 pride check hooks는 각각 200ms 안에 실행됩니다. 주요 병목은 orchestration 오버헤드가 아니라 agent별 LLM inference time입니다.⁷

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

각 섹션은 50줄 미만, 전체 파일은 150줄 미만으로 유지하세요. 긴 파일은 컨텍스트 창에서 잘릴 수 있으므로 가장 중요한 지침을 앞에 두세요. 스타일 선호보다 명령과 종료 정의가 먼저 와야 합니다.²¹

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

아키텍처 원칙(hooks는 결정적 gates, skills는 도메인 전문성, subagents는 격리된 컨텍스트, 파일시스템은 memory)은 개념적으로 모든 agentic system에 적용됩니다. 구체적인 구현은 Claude Code의 lifecycle events, matcher patterns, Agent tool을 사용합니다. AGENTS.md는 같은 패턴을 Codex, Cursor, Copilot, Amp, Windsurf로 가져갑니다.²¹ 구현 세부 사항은 tool별로 다르더라도 harness 패턴 자체는 tool에 구애받지 않습니다.

빠른 참조 카드

Hook 설정

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

Exit Codes

주요 명령

파일 위치

변경 로그

참고 문헌