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

요약: Claude Code은 파일에 접근할 수 있는 채팅 상자가 아닙니다. 문서화된 30개의 lifecycle events를 갖춘 프로그래밍 가능한 런타임이며, 각 이벤트에는 모델이 건너뛸 수 없는 셸 스크립트 hooks를 연결할 수 있어요. hooks를 dispatcher로, dispatcher를 skills로, skills를 agents로, agents를 workflows로 쌓으면 제약 조건을 강제하고, 작업을 위임하고, 세션 간 memory를 유지하며, multi-agent deliberation을 조율하는 자율 개발 harness를 만들 수 있어요. Claude Code v2.1.147에는 기본적으로 비활성화된 Workflow tool (CLAUDE_CODE_WORKFLOWS=1)이 추가되면서, 결정론적 multi-agent orchestration이 순수한 사용자 영역 스크립트에서 공식 런타임 기본 요소로 발전하기 시작했어요. v2.1.149에서는 PowerShell 권한 우회 수정과 git-worktree sandbox 허용 목록 수정을 통해 보안 측면에서도 같은 교훈을 강조해요. 정확성은 여전히 hooks와 evidence gate가 책임져요.⁵²⁵³ 이 가이드에서는 단일 hook부터 10-agent 합의 시스템까지 이 스택의 모든 계층을 다뤄요. 프레임워크는 전혀 필요하지 않아요. 모두 bash와 JSON만으로 구현해요.

Andrej Karpathy는 LLM agent 주변에서 자라나는 요소를 가리켜 claws라는 용어를 만들었어요. agent가 자신의 context window 밖에 있는 세계를 다룰 수 있게 해주는 hooks, scripts, orchestration을 뜻해요.¹ 대부분의 개발자는 AI coding agents를 대화형 도우미로 여겨요. 프롬프트를 입력하고, agent가 파일을 수정하는 모습을 지켜본 다음, 다음 작업으로 넘어가요. 이런 관점에서는 생산성이 사용자가 직접 감독할 수 있는 범위를 넘어서기 어려워요.

인프라 관점의 사고방식은 달라요. AI coding agent는 LLM kernel을 갖춘 프로그래밍 가능한 런타임이에요. 모델이 수행하는 모든 작업은 사용자가 제어하는 hooks를 거쳐요. 사용자는 프롬프트가 아니라 정책을 정의해요. 모델은 웹 서버가 nginx 규칙 안에서 작동하는 것처럼 사용자의 인프라 안에서 작동해요. nginx 앞에 앉아 요청을 직접 입력하지는 않아요. 설정하고, 배포하고, 모니터링해요.

이 차이가 중요한 이유는 인프라의 효과가 누적되기 때문이에요. bash 명령에서 인증 정보를 차단하는 hook은 모든 세션과 모든 agent, 모든 자율 실행을 보호해요. 평가 기준을 담은 skill은 사용자가 직접 호출하든 agent가 호출하든 일관되게 적용돼요. 보안 관점에서 코드를 검토하는 agent는 사용자가 지켜보는지와 관계없이 항상 같은 검사를 수행해요.²

핵심 요점

• Hooks는 실행을 보장하지만 프롬프트는 그렇지 않아요. 모델의 동작과 관계없이 매번 반드시 실행해야 하는 linting, formatting, security checks 등의 작업에는 hooks를 사용하세요. Exit code 2는 작업을 차단해요. Exit code 1은 경고만 표시해요.³
• Skills는 자동으로 활성화되는 도메인 전문 지식을 담아요. 모든 것은 description field에 의해 결정돼요. Claude은 keyword matching이 아니라 LLM reasoning을 사용해 skill의 적용 시점을 판단해요.⁴
• Subagents는 context bloat를 방지해요. 탐색과 분석에 격리된 context windows를 사용하면 기본 세션을 간결하게 유지할 수 있어요. 서로 독립적인 subagents는 병렬로 실행하고, 작업자 간에 지속적인 조율이 필요할 때는 agent teams를 사용하세요.⁵
• Memory는 filesystem에 저장돼요. 파일은 context windows가 바뀌어도 유지돼요. CLAUDE.md, MEMORY.md, rules directories, handoff documents가 체계적인 외부 memory system을 구성해요.⁶
• Multi-agent deliberation은 놓치기 쉬운 문제를 찾아내요. 단일 agent는 자신의 가정에 스스로 이의를 제기할 수 없어요. 평가 우선순위가 서로 다른 2개의 독립적인 agents는 quality gates만으로는 발견하기 어려운 구조적 결함을 찾아내요.⁷
• Harness pattern 자체가 시스템이에요. CLAUDE.md, hooks, skills, agents, memory는 서로 독립된 기능이 아니에요. 이 요소들은 결합되어 사용자와 모델 사이에 결정론적 계층을 만들고, 자동화 규모에 맞춰 확장돼요.

이 가이드 활용법

각 섹션은 이전 섹션의 내용을 바탕으로 이어져요. 마지막의 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를 구성합니다.

Harness 패턴

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        │
└──────────────────────────────────────────────────────────────┘

지침 계층: CLAUDE.md 파일과 규칙 디렉터리는 에이전트가 프로젝트에 관해 알아야 할 내용을 정의해요. 세션을 시작할 때와 compaction이 실행될 때마다 자동으로 로드돼요. 이는 에이전트의 장기 아키텍처 메모리 역할을 해요.

확장 계층: skills는 맥락에 따라 자동으로 활성화되는 도메인 전문 지식을 제공해요. hooks는 조건에 맞는 도구 호출이 발생할 때마다 실행되는 결정론적 gate를 제공해요. 메모리 파일은 세션이 바뀌어도 상태를 유지해요. 사용자 지정 에이전트는 특화된 subagents 구성을 제공해요.

오케스트레이션 계층: 멀티 에이전트 패턴은 조사, 검토, 숙의를 위해 독립된 에이전트들을 조율해요. 생성 예산은 제어되지 않는 재귀 실행을 방지해요. 합의 검증은 품질을 보장해요.

핵심은 대부분의 사용자가 컨텍스트가 비대해지고 비용이 늘어나는 모습을 지켜보면서 코어 계층에서만 작업한다는 점이에요. 숙련된 사용자는 지침 계층과 확장 계층을 구성한 뒤, 오케스트레이션과 최종 결정에만 코어 계층을 사용해요.²

관리형 harness와 자체 호스팅 harness 비교(2026년 4월)

2026년 초까지는 “직접 harness 구축하기”가 사실상 유일한 선택지였어요. 하지만 2026년 4월에 상황이 달라졌어요. Anthropic는 4월 8일 공개 베타로 Claude Managed Agents를 출시했어요. harness 루프, 도구 실행, sandbox 컨테이너, 상태 지속성을 REST API로 제공하며, 표준 토큰 요금에 세션 시간당 0.08달러가 추가되는 방식이에요. 4월 16일에 업데이트된 OpenAI의 Agents SDK는 이와 같은 분리를 공식화했어요. harness와 컴퓨팅을 별도 계층으로 나누고, 네이티브 sandbox 제공업체(Blaxel, Cloudflare, Daytona, E2B, Modal, Runloop, Vercel) 및 컨테이너 손실 후에도 작업을 이어갈 수 있는 스냅샷과 복원 기능을 지원해요.²³²⁴

OpenAI 측의 더 심층적인 SDK 기능은 2026년 4월 15일에 출시되고 4월 16일에 발표된 openai-agents Python v0.14.0에 도입됐어요. default_manifest, sandbox 지침, capabilities를 갖춘 Agent의 하위 클래스 SandboxAgent, 새 작업 공간의 계약을 설명하는 Manifest(파일, 디렉터리, 로컬 파일, Git 저장소, 환경, 사용자, 마운트), 실행별로 sandbox 클라이언트, 라이브 세션 주입, manifest 재정의, 스냅샷, 구체화 동시 실행 제한을 연결하는 SandboxRunConfig가 포함돼요. 기본 capabilities는 셸 접근, 파일 시스템 편집, 이미지 검사, skills, sandbox 메모리, compaction을 지원해요. sandbox 메모리는 실행 간에 추출한 교훈을 유지하고 단계적으로 공개해요. 작업 공간은 로컬 파일, Git 저장소 항목, 원격 마운트(S3, R2, GCS, Azure Blob, S3 Files)를 지원하며, 스냅샷은 제공업체 간에 이식할 수 있어요. 백엔드로는 UnixLocalSandboxClient, DockerSandboxClient, 그리고 선택적 추가 패키지를 통해 제공되는 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)와 동일해졌어요.³⁰ 2026년 8월 1일 현재 이 패키지는 PyPI에서 v0.2.128이며, Claude CLI v2.1.220을 번들로 제공하고 mcp 최저 버전은 현재 >=1.23.0이에요. TypeScript SDK의 버전은 v0.3.220이에요. 0.2.x 계열은 여기에서 설명한 0.1.x 기능을 점진적으로 개선한 버전으로, 아래에 나오는 include_hook_events, skills, sandbox 구성 옵션은 여전히 유효해요. 최근 릴리스는 하위 프로세스 정리와 NDJSON 스트림의 안정성 개선에 집중했어요.⁸⁶

harness에 음성 또는 실시간 계층이 포함된다면, openai-agents-python v0.17.0(2026년 5월 8일)부터 RealtimeAgent의 기본 모델이 gpt-realtime-2로 변경됐어요.⁴¹ 기존 실시간 세션에도 새로운 기본값이 자동으로 적용돼요. 평가를 위해 이전 동작을 유지해야 한다면 기존 모델을 명시적으로 고정하세요.

2026년 7월에는 OpenAI의 관리형 서비스에도 멀티 에이전트 기능이 추가됐어요. openai-agents-python v0.18.2(7월 11일)와 openai-agents-js v0.13.2(7월 10일)는 베타로 호스팅형 멀티 에이전트 지원을 추가했어요. 이는 여러 에이전트의 오케스트레이션을 OpenAI가 호스팅 서비스로 관리하는 기능으로, 멀티 에이전트 오케스트레이션 섹션에서 다루는 Anthropic의 Managed Multiagent Orchestration 공개 베타에 직접 대응해요.⁷³ 이제 두 업체 모두 멀티 에이전트 계층에서 아래 표가 단일 에이전트에 관해 설명하는 것과 같은 선택지를 제공해요. 업체가 위임 루프를 실행하는 대신 사용자는 hook 기능을 포기하게 돼요.

이제 아키텍처 선택지는 명확히 나뉘어요.

선택 기준: 이미 인프라 역량을 갖추고 있거나, 직접 제어하는 skills와 hooks가 필요하거나, 특정 워크플로를 고도로 최적화하려는 팀에는 자체 호스팅이 여전히 적합해요. 전담 플랫폼 엔지니어가 없는 팀, 사용자 지정 기능보다 빠르게 가치를 얻는 것이 중요한 경우, 또는 지속성 계층을 직접 구축하지 않고도 노트북을 닫은 뒤 에이전트 실행을 안정적으로 이어가야 하는 경우에는 관리형이 적합해요. 두 방식은 함께 사용할 수도 있어요. 자체 호스팅 harness에서 특정 장기 실행 작업을 REST API를 통해 Managed Agents에 위임할 수 있어요.

디스크에서 보는 Harness 구조

~/.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을 통해 공유돼요. 두 트리가 합쳐져 완전한 harness를 구성해요.

Skills 시스템

Skills는 모델이 호출하는 확장 기능이에요. Claude는 사용자가 명시적으로 호출하지 않아도 문맥에 따라 skills를 자동으로 찾아 적용해요.⁴ 세션마다 같은 문맥을 반복해서 설명하고 있다는 사실을 깨달았다면 skill을 만들어야 할 때예요.

Skill을 만들어야 하는 경우

Skills는 Claude가 항상 활용할 수 있는 지식을 위한 기능이에요. 슬래시 명령은 사용자가 명시적으로 실행하는 작업을 위한 기능이에요. 둘 중 하나를 선택해야 한다면 이렇게 질문해 보세요. “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는 언어 모델 추론을 사용해 관련 skill이 있는지 판단해요. Claude Code 소스를 독립적으로 분석한 결과도 이 작동 방식을 뒷받침해요. Skill description은 시스템 프롬프트의 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)가 포함돼요.

자동 활성화는 절대적인 규칙이 아니라 조절할 수 있는 설정이라는 점에 유의하세요. v2.1.215부터 Claude는 기본 제공 /verify 및 /code-review skills를 더 이상 자체적으로 호출하지 않으며, 명시적으로 호출할 때만 실행해요. 프롬프트 없이 실행할 때 얻는 이점보다 비용이 큰 고부하 검토 skills에 대해 description 기반 활성화를 의도적으로 축소한 조치예요.⁷⁴

문맥 예산

모든 skill description은 문맥 창의 1%로 동적으로 조정되는 문맥 예산을 공유하며, 기본 대체 값은 8,000자예요.⁴ Skills가 많다면 각 description을 간결하게 유지하고 핵심 사용 사례를 맨 앞에 배치하세요. SLASH_COMMAND_TOOL_CHAR_BUDGET 환경 변수로 예산을 재정의할 수 있지만,¹¹ description을 더 짧고 정확하게 작성하는 편이 더 나은 해결책이에요. 세션 중에 /context를 실행해 제외되는 skills가 있는지 확인하세요.

지원 파일과 구성

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 공유

프로젝트 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

팀원이 변경 사항을 가져오면 skill도 자동으로 받아요. 설치도, 설정도 필요하지 않아요. 팀 전체의 전문 지식을 표준화하는 가장 효과적인 방법이에요.

프롬프트 라이브러리로 활용하는 Skills

단일 용도의 skills를 넘어, 디렉터리 구조를 체계적인 프롬프트 라이브러리로 활용할 수도 있어요.

~/.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은 사용자의 전문 지식 중 서로 다른 측면을 담아요. 이 skills를 함께 구성하면 Claude가 문맥에 따라 자동으로 활용하는 지식 기반이 돼요. 주니어 개발자도 별도로 요청하지 않고 시니어 수준의 안내를 받을 수 있어요.

Hooks와 조합되는 Skills

Skills는 실행되는 동안에만 활성화되는 자체 hooks를 frontmatter에 정의할 수 있어요. 다른 세션을 오염시키지 않으면서 도메인별 동작을 구현할 수 있어요.²

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

철학 skills는 SessionStart hooks를 통해 자동으로 활성화되며, 명시적으로 호출하지 않아도 모든 세션에 품질 제약 조건을 삽입해요. Skill 자체는 지식이고, hook은 이를 강제하는 장치예요. 둘을 결합하면 정책 계층이 형성돼요.

흔한 Skill 실수

지나치게 광범위한 description. Git과 관련된 모든 프롬프트에서 활성화되는 git-rebase-helper skill은 rebase, merge, cherry-pick은 물론 git status에서도 실행되어 세션의 80%에서 문맥을 오염시켜요. Description의 범위를 좁히거나 disable-model-invocation: true를 추가해 명시적인 /skill-name 호출을 요구하면 해결할 수 있어요.⁴

예산을 두고 경쟁하는 skills가 너무 많음. Skills가 많을수록 더 많은 description이 1%의 문맥 예산을 두고 경쟁해요. Skills가 활성화되지 않는다면 /context에서 제외된 항목을 확인하세요. 모호한 skills를 많이 두기보다 description이 명확한 소수의 skills를 우선하세요.

지원 파일에 묻힌 핵심 정보. Claude는 SKILL.md를 즉시 읽지만 지원 파일은 필요할 때만 열어요. 핵심 정보가 지원 파일에 있으면 Claude가 찾지 못할 수도 있어요. 필수 정보는 SKILL.md에 직접 넣으세요.⁴

SDK Skill 인터페이스 (2026년 5월 8일)

claude-agent-sdk-python v0.1.77 이상을 사용하는 자체 호스팅 harness에서는 기존의 allowed_tools 안에 "Skill" 값을 넣는 방식 대신 ClaudeAgentOptions의 skills 옵션으로 사용 가능한 skills를 선언해야 해요.³⁷ "Skill" 축약 표기는 더 이상 권장되지 않으며, 전용 옵션을 사용하면 어떤 skills를 사용할 수 있는지에 관한 정보를 Claude Code에 더 구조적으로 제공할 수 있어요. v0.1.77에 포함된 CLI 버전은 v2.1.133이에요.

.claude/skills/에서 플러그인과 Skill의 통합 (2026년 5월 29일)

Skills는 원래부터 프로젝트의 .claude/skills/ 디렉터리에서 불러왔어요. Claude Code v2.1.157부터는 이 디렉터리를 플러그인에도 사용할 수 있어요. 이제 .claude/skills/에 배치한 플러그인은 마켓플레이스에 등록하지 않아도 자동으로 불러오며, claude plugin init <name>을 실행하면 manifest와 SKILL.md가 연결된 새 플러그인이 그 위치에 생성돼요.⁵⁸ 이로써 이전에는 서로 다른 위치에 있던 2가지 프로젝트 도구 구성 방식의 간극이 사라졌어요. 하나는 저장소에 바로 커밋하는 기본 skill이고, 다른 하나는 skill과 hooks, MCP 서버를 묶지만 설치하려면 이전까지 마켓플레이스가 필요했던 플러그인이에요. Harness 설계에 미치는 실질적인 효과는 프로젝트 범위 도구를 배포할 때 더 이상 레지스트리를 거칠 필요가 없다는 점이에요. 작성하고 커밋하기만 하면 팀원도 git pull을 통해 같은 인터페이스를 사용할 수 있어요. 플러그인은 여전히 하나의 ZIP에 hooks, skills, MCP servers, agents를 묶어 설치하는 사용 사례를 담당해요. 달라진 점은 프로젝트 자체 트리에서 플러그인을 불러오기 위해 별도의 마켓플레이스를 구축할 필요가 없어졌다는 거예요.

거버넌스를 위한 기본 제공 인터페이스 숨기기 (2026년 6월 8일)

Skills는 기능이며, 기능은 공격 표면이기도 해요. Claude Code v2.1.169에는 기본 제공 skills, workflows, 내장 슬래시 명령을 모델에서 완전히 숨기는 disableBundledSkills 설정과 이에 대응하는 CLAUDE_CODE_DISABLE_BUNDLED_SKILLS 환경 변수가 추가됐어요.⁶⁰ 보안이 강화되었거나 규제를 받는 harness에서는 공격 표면을 의도적으로 줄이는 수단이에요. 특정 프로젝트 및 개인 skills를 감사하고 승인한 운영자는 Anthropic에서 기본 제공하는 모든 항목을 숨겨 모델이 운영자의 검증을 거친 인터페이스만 대상으로 추론하게 할 수 있어요. 도구 허용 목록과 같은 방식으로 다루세요. 기본 설정은 광범위한 기능을 허용하며, 이를 끄는 것은 단순한 편의 설정이 아니라 거버넌스 결정이에요.

중첩된 .claude/skills와 가장 가까운 항목 우선 적용 (2026년 6월 16일)

Claude Code v2.1.178부터 프로젝트 도구는 위치를 인식해요. 이제 저장소 루트뿐만 아니라 중첩된 .claude/skills 디렉터리의 skills도 해당 디렉터리 아래의 파일에서 작업할 때 불러와요. 이름이 충돌하면 중첩된 skill은 <dir>:<name> 형식으로 표시되므로 두 skill에 모두 접근할 수 있어요.⁶³ 같은 릴리스부터 나머지 프로젝트 인터페이스도 작업 디렉터리에 가장 가까운 항목을 기준으로 해석해요. 중첩된 .claude/ 디렉터리에서 agent, workflow 또는 출력 스타일의 이름이 충돌하면 작업 디렉터리에 가장 가까운 항목이 우선 적용돼요. 프로젝트 범위 workflow를 저장할 때도 항상 루트를 대상으로 하지 않고 가장 가까운 기존 .claude/workflows/에 저장해요.⁶³ 모노레포나 저장소로 구성된 저장소에서 이 기능은 하나의 평면적인 전역 인터페이스와 문맥에 따라 활성화되는 패키지별 도구를 구분하는 핵심 차이예요. services/api/.claude/skills/에는 해당 트리에서 작업할 때만 표시되는 API 전용 skills를 둘 수 있으며, 같은 이름을 사용하는 services/web/의 skill과도 충돌하지 않아요.

Hook 아키텍처

Hooks는 Claude Code 수명 주기 이벤트로 실행되는 셸 명령어예요.³ 모델이 해석하는 프롬프트가 아니라 일반 스크립트로 LLM 외부에서 실행돼요. 모델이 rm -rf /를 실행하려고 하나요? 10줄짜리 bash 스크립트가 명령어를 차단 목록과 대조하고, 셸에 도달하기 전에 거부해요. 모델의 의사와 관계없이 hook은 실행돼요.

사용 가능한 이벤트

이 가이드가 업데이트된 시점을 기준으로 Claude Code는 8개 범주에 걸쳐 문서화된 수명 주기 이벤트 30개를 제공해요. 이벤트 목록은 릴리스와 함께 늘어나므로 참조 문서를 정확한 정보의 기준으로 삼고, 프로덕션 hooks를 연결하기 전에 요약표에서 최신 전체 표를 확인하세요.¹³

DirectoryAdded(v2.1.219)는 세션 도중 발생하던 작업 공간의 공백을 해소해요. 이벤트 목록은 v2.1.152에서 MessageDisplay가 추가된 후 계속 안정적으로 유지됐으며, DirectoryAdded는 그 이후 처음 추가된 수명 주기 이벤트예요. /add-dir 또는 SDK의 register_repo_root 제어 요청이 세션 도중 새 작업 디렉터리를 등록한 후 실행돼요.⁸⁴ 이 이벤트가 해소하는 공백은 실질적인 문제였어요. 지금까지는 harness가 SessionStart에서 작업 공간을 철저하게 검증하더라도, 이후 두 번째 저장소가 추가될 때 어떤 hook도 실행되지 않았어요. 시작 시 작업 공간에 적용한 모든 검증은 여기서 다시 실행해야 해요. 여기에는 신뢰도 검사, 비밀 정보 스캔, 디렉터리 구조에서 도출한 경로 범위 규칙, 저장소별 정책 로드가 포함돼요. 이제 세션의 디렉터리 집합은 실행 시점에 고정되지 않기 때문이에요. 이 이벤트는 차단용이 아니라 정보 제공용이므로 gate가 아닌 상태 재도출 및 출처 기록을 위한 트리거로 다루세요. 특정 디렉터리가 절대 추가되면 안 된다면 hook에서 거부하려 하지 말고 설정에서 차단하세요. SDK 지원도 같은 릴리스에 추가됐어요. TypeScript v0.3.219에서 제어 프로토콜의 수명 주기 이벤트에 DirectoryAdded가 추가됐으므로, SDK에서 호스팅되는 harness도 CLI 기반 harness와 같은 방식으로 이 이벤트를 받을 수 있어요.⁸⁵

종료 코드의 의미

종료 코드는 hooks가 작업을 차단할지 결정해요.³

Hook 설정

Hooks는 설정 파일에 저장돼요. 공유 hooks에는 프로젝트 수준 설정(.claude/settings.json)을, 개인 hooks에는 사용자 수준 설정(~/.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, mcp__server__tool 같은 MCP 도구 이름이나 모든 도구를 나타내는 * 등의 tool_name 값과 일치하는지 확인해요. 단순 이름과 |로 구분된 목록에는 정확히 일치하는 값만 적용되며, 그 밖의 문자가 포함된 값은 JavaScript 정규 표현식으로 처리돼요. 일부 이벤트는 matchers를 지원하지 않으며, 설정하면 항상 실행돼요.¹³ Claude Code v2.1.195부터 하이픈이 포함된 식별자(code-reviewer, mcp__brave-search)가 들어간 matchers는 실수로 부분 문자열과 일치하지 않고 정확히 일치해요. 따라서 특정 에이전트나 서버를 대상으로 한 hook이 해당 문자열을 포함하기만 한 모든 이름에 더는 실행되지 않아요. 하이픈이 포함된 MCP 서버의 모든 도구를 대상으로 하려면 명시적인 패턴인 mcp__brave-search__.*를 사용하세요.⁶⁶ v2.1.214에서는 같은 원칙을 경로 패턴에도 적용했어요. 단일 세그먼트 dir/** 패턴을 사용하는 hook의 if: 조건은 이제 트리 어디에나 있는 이름이 dir인 모든 디렉터리가 아니라 <cwd>/dir에만 일치해요. 모든 깊이를 대상으로 하는 것이 맞다면 **/dir/**을 사용하세요.⁷⁴ v2.1.195 변경 사항과 마찬가지로, 이 수정은 의도치 않게 넓은 범위 대신 명시된 의도를 따르도록 해요. 이전의 모든 깊이 동작에 암묵적으로 의존하던 hook 조건이 있는지 점검하세요.

Hook 입력/출력 프로토콜

Hooks는 전체 컨텍스트가 포함된 JSON을 stdin으로 받아요.

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

더 세밀하게 제어하려면 PreToolUse hooks가 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."
  }
}

3가지 보장 유형

Hook을 작성하기 전에 어떤 유형의 보장이 필요한지 먼저 생각해 보세요.¹⁴

형식 보장은 작업이 끝난 후 일관성을 유지해요. Write/Edit의 PostToolUse hooks는 파일이 변경될 때마다 포매터를 실행해요. 포매터가 모든 내용을 정규화하므로 모델이 어떤 출력을 생성했는지는 중요하지 않아요.

{
  "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 hooks는 명령어를 검사하고 종료 코드 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 hooks는 린터나 테스트 모음을 실행하고, 품질 검사를 통과하지 못하면 커밋을 차단해요.

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

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

셸 명령어 이외의 Hook 유형

Claude Code는 5가지 hook 유형을 지원해요.¹³

명령어 hooks(type: "command")는 셸 스크립트를 실행해요. 빠르고 결정론적이며 토큰 비용이 들지 않아요. MCP tool hooks (type: "mcp_tool")는 이미 연결된 MCP 서버의 도구를 호출해요. 검증 로직이 이미 MCP 경계 뒤에 있고 별도의 셸 스크립트가 필요하지 않을 때 사용하세요.

Prompt hooks (type: "prompt")는 빠른 Claude 모델에 단일 턴 프롬프트를 보내요. 모델은 허용할 때 { "ok": true }를 반환하고, 차단할 때 { "ok": false, "reason": "..." }를 반환해요. 정규식으로 표현할 수 없는 정교한 평가에 사용하세요.

Agent hooks (type: "agent")는 도구 접근 권한(Read, Grep, Glob)이 있는 subagent를 생성해 여러 턴에 걸쳐 검증해요. 아직 실험적인 기능이므로 프로덕션 게이트에는 command hooks를 우선 사용하고, 실제 파일이나 테스트 출력을 반드시 살펴봐야 하는 검사에만 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 입력에 subagent_type이 포함돼요. 따라서 공유 hook은 프롬프트 텍스트를 보고 추측하지 않고도 security-reviewer 실행을 explorer나 일반 worker와 구분할 수 있어요.⁴⁹

HTTP hooks (type: "http")는 이벤트의 JSON 입력을 URL에 POST 요청으로 보내고 JSON 응답을 받아요. webhooks, 외부 알림 서비스 또는 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 Hooks

Hooks는 실행을 차단하지 않고 백그라운드에서 동작할 수 있어요. 알림이나 로깅처럼 중요하지 않은 작업에는 async: true를 추가하세요.¹³

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

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

독립적인 Hooks보다 Dispatchers

동일한 이벤트에서 7개의 hooks를 실행하고 각 hook이 stdin을 독립적으로 읽게 하면 경합 상태가 발생해요. 2개의 hooks가 동일한 JSON 상태 파일에 동시에 쓰면 JSON이 잘려 나가요. 그러면 해당 파일을 파싱하는 모든 downstream hook이 중단돼요.²

해결 방법은 이벤트마다 dispatcher를 하나만 두고 캐시된 stdin을 사용해 hooks를 순차적으로 실행하는 거예요.

#!/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 디버깅

아무런 오류도 표시하지 않고 실패하는 hooks를 디버깅하는 5가지 방법이에요.¹⁴

1. 스크립트를 개별적으로 테스트하세요. 샘플 JSON을 파이프로 전달하세요. echo '{"tool_input":{"command":"git commit -m test"}}' | bash your-hook.sh
2. 디버그 출력에는 stderr를 사용하세요. 종료 코드 2의 stderr는 오류 메시지로 Claude에 다시 전달돼요. 차단하지 않는 stderr(종료 코드 1, 3 등)는 상세 모드(Ctrl+O)에서만 표시돼요.
3. jq 실패를 확인하세요. 잘못된 JSON 경로는 아무런 오류 없이 null을 반환해요. 실제 도구 입력으로 jq 표현식을 테스트하세요.
4. 종료 코드를 확인하세요. exit 1을 사용하는 PreToolUse hook은 작동하는 것처럼 보여도 아무것도 강제하지 못해요.
5. Hooks를 빠르게 유지하세요. Hooks는 동기식으로 실행돼요. 모든 hooks가 2초 안에, 가능하면 500ms 안에 끝나도록 하세요.

SDK 측 Hook 이벤트 스트리밍

claude-agent-sdk-python(v0.1.74 이상, 2026년 5월 6일)을 기반으로 구축한 자체 호스팅 harness는 셸 스크립트 콜백을 거치지 않고 메시지 스트림에서 hook 이벤트를 직접 구독할 수 있어요.³⁶ ClaudeAgentOptions에서 include_hook_events=True로 설정하면 HookEventMessage 객체(PreToolUse, PostToolUse, Stop 등)가 어시스턴트 메시지 및 도구 결과와 동일한 이터레이터에서 반환돼요. 이는 TypeScript SDK의 includeHookEvents 옵션과 같은 방식이며, 같은 릴리스에서 번들 CLI도 v2.1.129로 업데이트됐어요.

이벤트 스트림 패턴은 harness가 이미 Python에서 실행되고 있으며 모델 출력과 같은 제어 흐름에서 hook 신호를 처리하려 할 때 적합해요. 여러 도구를 조합하거나, Claude Code과 Codex에서 hooks를 공유하거나, 차단에 종료 코드 의미 체계가 필요한 harness에는 셸 스크립트 hook 규약(종료 코드, stdin JSON, dispatchers)이 여전히 적합해요.

TypeScript SDK의 2026년 7월 릴리스(v0.3.205~v0.3.208)는 스트리밍 프로토콜 자체의 규약도 더욱 명확하게 만들었어요.⁷⁰ 이제 인터럽트는 형식이 지정된 영수증을 반환해요. 인터럽트는 still_queued UUID를 통해 아직 대기열에 있는 메시지를 확인해 주며, 세션은 system/init에서 interrupt_receipt_v1 기능을 알려요. 따라서 코디네이터는 “인터럽트가 적용됨”과 “이미 처리 중인 메시지보다 인터럽트가 늦게 도착함”을 구분할 수 있어요. command_lifecycle 프레임은 메시지별 대기, 시작, 완료, 취소, 폐기 상태를 보고해요. 트랜스크립트에서 추론하지 않고도 “내가 보낸 메시지에 무슨 일이 일어났는가”를 확인할 수 있는 최초의 공식 해답이에요. 더 작은 기능도 추가됐어요. subagent 완료 페이로드를 위한 AgentToolCompletedOutput 타입이 도입됐고, 이제 canUseTool 콜백은 updatedInput 필드 없이 {behavior: 'allow'}를 반환할 수 있어요.

이 릴리스의 한 항목은 기능이 아니라 최소 보안 기준이에요. v0.3.208은 대기 중인 hook이 있을 때 호출자의 중단 요청이 도착하면 이를 hook 성공으로 변환하던 문제를 수정했어요. 이 문제로 인해 PreToolUse hook이 통제하는 도구가 호출자의 중단 요청 이후에도 실행될 수 있었어요.⁷⁰ harness가 SDK 측 hooks를 권한 게이트로 사용하고 중단 요청으로 진행 중인 작업을 취소한다면 v0.3.208을 최소 버전으로 삼으세요. 이보다 낮은 버전에서는 “중단됨”이 항상 “차단됨”을 의미하지 않았어요. Python v0.2.127(2026년 7월 24일)은 한 달 사이에 발생한 두 번째 유사 우회 사례예요. 백그라운드 subagents가 아직 실행 중인데도 query()가 첫 번째 result 프레임에서 stdin을 닫았기 때문에, subagents의 SDK-MCP 도구 호출이 "Stream closed"와 함께 실패했으며 PreToolUse hooks까지 완전히 우회했어요.⁸⁵ 이 패턴을 명확히 인식하고 주의하세요. SDK 측 hook 강제는 hook 판정을 수집하기 전에 전송 계층이 종료되는 수명 주기 경계, 즉 중단, 종료 처리, 스트림 닫기에서 허용 상태로 실패해요. 또한 우회된 hook은 승인한 hook과 겉으로 완전히 같아서 실패가 드러나지 않아요. 두 SDK의 최소 버전을 고정하고, 검증 가능한 강제 수단으로 셸 hook 계층을 유지하세요.

작업 강도와 세션 출처 정보(2026년 5월 7~8일)

Claude Code v2.1.132와 v2.1.133에 추가된 2가지 기능은 hooks와 하위 프로세스에 실행 컨텍스트를 더 잘 파악할 수 있는 신호를 제공해요.³⁸³⁹

• Hook 입력의 effort.level. 이제 Hooks는 tool_input과 session_id가 포함된 동일한 입력에서 effort.level JSON 필드를 받아요. 동일한 값이 $CLAUDE_EFFORT 환경 변수로도 내보내지므로 Bash 명령은 JSON을 파싱하지 않고 읽을 수 있어요. 이 값을 사용해 작업 강도 등급에 따라 hook 비용을 조절하세요. low에서는 비용이 큰 검증을 건너뛰고, xhigh나 max에서는 전체 보안 게이트를 실행하세요.
• Bash 하위 프로세스의 CLAUDE_CODE_SESSION_ID 환경 변수. 이제 Bash 도구의 하위 프로세스는 hooks가 확인하는 것과 동일한 session_id 값을 CLAUDE_CODE_SESSION_ID로 받아요. 이를 통해 세션별 상태를 기록하는 도구가 하위 프로세스 이벤트와 hook 이벤트를 연결하지 못했던 출처 정보의 공백이 해소돼요.

두 신호 모두 코드를 변경하지 않고 사용할 수 있으며, 새 필드를 무시하는 기존 hooks도 계속 작동해요.

autoMode.hard_deny와 v2.1.136 Hook 및 Plugin 수정 사항(2026년 5월 8일)

Claude Code v2.1.136은 자동 모드에 새로운 하드 거부 등급을 추가하고, 장시간 실행되는 harness에 영향을 주던 여러 plugin 및 MCP 문제를 수정했어요.⁴⁰ - settings.autoMode.hard_deny. 사용자의 의도나 허용 예외와 관계없이 무조건 차단하는 auto mode 분류기 규칙입니다. 기존 allow/deny 매처보다 상위에서 작동하는 타협 불가능한 거버넌스 수단입니다. 운영자가 개인 설정에서 더 넓은 범주를 승인했더라도 절대 재정의해서는 안 되는 규칙에 사용하세요. 예를 들면 main으로의 force-push, 비밀 정보가 포함된 파일, 프로덕션 데이터베이스 접근이 있습니다. - autoMode.classifyAllShell (v2.1.193). 기본적으로 auto mode 분류기는 임의 코드 실행 패턴과 일치하는 셸 명령만 검토합니다. 이 설정은 모든 Bash/PowerShell 명령을 분류기로 전달하며, 거버넌스가 적용되는 harness에서 가장 넓은 범위를 검사하는 방식입니다. 같은 릴리스에서는 거부 사유도 대화 기록, 알림, /permissions에 표시하므로 조용히 차단되던 동작을 감사 가능한 결정으로 바꿉니다. Codex는 v0.142.2에서 이에 해당하는 영역을 강화했습니다. 안전 분류기가 검사할 수 없는 실행 가능 AST 영역이 포함된 PowerShell 명령은 이제 조용히 통과하지 않고 승인을 요구합니다.⁶⁶ - Hook ask가 분류기의 최저 결정을 제한합니다(v2.1.211). hook과 auto mode 사이의 우선순위 문제가 이제 정리되었습니다. ask 권한 결정을 반환하는 PreToolUse hook은 최종 결과가 최소한 사용자 확인을 거치도록 제한하므로, auto mode가 샌드박스 밖에서 실행되는 Bash 명령을 다시 허용으로 올릴 수 없습니다.⁶⁹ 거버넌스가 적용되는 harness에 필요했던 보장 단계가 바로 이것입니다. hook의 ask는 완전 자동 권한 방식에서도 유지되는 결정론적인 사람 개입 중단 지점입니다. 거부가 아니라 사람의 판단이 필요한 작업에는 단순한 종료 코드 2 차단 대신 ask를 사용하세요. - 분류기 모델은 세션별로 고정됩니다(v2.1.210). auto mode 분류기는 기본적으로 Sonnet 5를 사용하며 세션 동안 고정되므로, 세션 중간에 모델을 전환해도 권한 분류에 사용하는 모델은 바뀌지 않습니다.⁶⁹ 분류의 일관성은 거버넌스의 핵심 속성이며, 이 변경으로 눈에 띄지 않던 변동 원인 하나가 사라졌습니다. - MCP 서버가 /clear 이후 더 이상 사라지지 않습니다. .mcp.json, plugins, claude.ai connectors에 설정된 서버가 VS Code 확장 프로그램, JetBrains plugin, Agent SDK에서 /clear를 실행한 뒤 활성 목록에서 조용히 사라지는 문제가 있었습니다. 이 문제는 v2.1.136에서 수정되었습니다. “MCP server X가 세션 중간에 사라졌다”는 현상을 겪었다면 이것이 원인이었습니다. - 동시 갱신 시 MCP OAuth 갱신 토큰 손실. 여러 원격 MCP 서버를 사용하는 사용자는 이제 매일 다시 인증하지 않아도 됩니다. 동시에 수행된 갱신 쓰기가 서로를 덮어쓰고 있었습니다. - 이제 Plan mode가 파일 쓰기를 올바르게 차단합니다. 일치하는 Edit(...) 허용 규칙이 Plan mode의 쓰기 보호를 우회하고 있었습니다. 이제 허용 규칙과 관계없이 Plan mode가 적용됩니다. - Plugin Stop 및 UserPromptSubmit hooks가 더 이상 세션 중간에 실패하지 않습니다. 캐시 정리 과정에서 실행 중인 세션이 계속 사용하고 있던 plugin 버전 파일을 삭제하여, 특히 이 두 hook 이벤트가 중단되는 문제가 있었습니다. 수정된 버전에서는 사용 중인 버전을 고정해 유지합니다. - plugin.json의 skills 항목. skills를 설정하면 plugin의 기본 skills/ 디렉터리가 숨겨지고 있었습니다. 이제 이 항목이 올바르게 결합되며, 파일 경로를 지정하면 조용히 실패하는 대신 명시적인 오류가 발생합니다. - CLAUDE_ENV_FILE SessionStart hook 환경 변수가 오래된 상태로 유지되는 문제. SessionStart hooks가 CLAUDE_ENV_FILE을 통해 내보낸 변수가 /resume 또는 /clear 이후 갱신되지 않는 문제가 있었습니다. v2.1.136에서 수정되었습니다. 이제 이러한 이벤트가 발생하면 세션이 환경 파일을 다시 불러옵니다.

거버넌스 harness에서 운영 측면으로 주목할 항목은 새로운 수단인 autoMode.hard_deny와 장시간 세션을 망가뜨리던 조용한 실패인 MCP 사라짐 문제의 수정입니다. 나머지는 모두 사용 편의성을 개선하는 정리 작업입니다.

구조화된 Hook 인수와 차단 후 계속 실행(2026년 5월 11일)

Claude Code v2.1.139에는 프로덕션 harness에 중요한 hook 관련 세부 기능 2가지가 추가되었습니다. command hooks를 위한 args: string[] 실행 형식과 PostToolUse hooks를 위한 continueOnBlock입니다.⁴²⁴⁴ hook에 동적 값이나 경로 자리표시자가 필요하다면 args를 사용하세요. 셸을 거치지 않고 명령을 직접 실행하므로 인용 처리와 삽입 실수 문제를 상당 부분 없앨 수 있습니다.

PostToolUse hook이 흐름을 종료하는 대신 거부 사유를 Claude에 전달하고 턴을 계속해야 한다면 continueOnBlock을 사용하세요. 이것은 보안 우회 수단이 아니라 운영자 경험을 위한 기능으로 다뤄야 합니다. 차단 게이트는 여전히 안전하지 않은 결과를 막아야 합니다.

같은 릴리스에서는 CLAUDE_PROJECT_DIR을 MCP stdio 서버에 전달하고 plugin 설정의 명령에서 ${CLAUDE_PROJECT_DIR}을 참조할 수 있게 되었습니다.⁴² MCP tools는 서버를 실행한 프로세스의 우연한 작업 디렉터리가 아니라 이 값을 기준으로 프로젝트 상대 경로를 해석해야 합니다. 2026년 7월 초 릴리스(v2.1.203~v2.1.206)에서는 같은 원칙을 프로토콜 수준까지 확장했습니다. 이제 MCP roots/list에는 세션의 추가 작업 디렉터리가 포함되며, 디렉터리가 바뀌면 roots/list_changed 알림이 전송됩니다. 따라서 MCP roots를 준수하는 서버는 프로젝트 디렉터리가 하나뿐이라고 가정하지 않고 실제 다중 디렉터리 작업 공간 구조를 추적합니다.⁶⁸

Claude Code v2.1.140은 주로 harness 운영자를 위한 안정성 릴리스입니다. 설정이 변경되어도 ConfigChange hooks가 실행되지 않던 문제를 수정하고, 설정 수준이 여러 단계일 때 disableAllHooks와 allowManagedHooksOnly가 올바르게 조합되지 않던 예외 상황을 해결했으며, 권한 대화 상자에서 hook 결과가 반환한 의도하지 않은 환경 변수가 노출되지 않도록 했습니다.⁴⁹ 이 변경으로 이 섹션의 기존 거버넌스 패턴을 더 안정적으로 적용할 수 있지만 새로운 hook 아키텍처가 필요하지는 않습니다.

Claude Code v2.1.141에는 제어 터미널이 없어도 데스크톱 알림, 창 제목, 알림음을 사용할 수 있는 hook 출력의 terminalSequence 필드가 추가되었습니다.⁵⁰ 이것은 강제 적용이 아니라 운영자에게 신호를 보내는 기능으로 다루세요. 보안 및 품질 게이트는 여전히 일반적인 차단 규약을 통해 실패를 알려야 합니다. 구조화된 hook 출력과 안전하지 않은 작업을 막는 종료 동작을 함께 사용하세요. 같은 릴리스에는 Agent View의 범위를 하나의 디렉터리로 제한하는 claude agents --cwd <path>, GitHub SSH 키가 없는 환경에서 plugin을 설치하기 위한 CLAUDE_CODE_PLUGIN_PREFER_HTTPS, 여러 작업 공간에 적용되는 워크로드 신원 연동 규칙을 위한 ANTHROPIC_WORKSPACE_ID도 추가되었습니다.⁵⁰ 팀 harness 관점에서는 운영 화면의 범위를 좁히고, plugin 설치에 필요한 전제를 줄이며, 기업용 토큰의 범위를 명시하는 아키텍처 세부 사항입니다.

Claude Code v2.1.142는 hook 의미 체계보다 백그라운드 세션 오케스트레이션에 더 중요한 릴리스입니다.⁵¹ 이제 claude agents는 래퍼 상태에 의존하지 않고 명시적인 디렉터리, 설정, MCP, plugin, 권한, 모델, effort 플래그를 사용해 백그라운드 세션을 디스패치할 수 있습니다. 해당 릴리스에서 fast mode의 기본 모델은 Opus 4.7이었으며, Opus 4.6의 동작에 대한 의존성이 측정된 harness는 CLAUDE_CODE_OPUS_4_6_FAST_MODE_OVERRIDE=1로 고정할 수 있었습니다. v2.1.219부터 Opus 4.7은 fast mode에서 완전히 제외되었고 /fast는 Opus 5와 Opus 4.8에 적용됩니다.⁸⁴ 루트 수준의 plugin SKILL.md 탐색과 plugin이 제공하는 LSP 표시 기능은 패키징의 모호성을 줄입니다. MCP_TOOL_TIMEOUT, 기존 백그라운드 세션 작업 트리, 데몬의 잠자기와 깨우기 및 업그레이드 후 정리, plugin 캐시 정리에 관한 수정은 오케스트레이션 버그처럼 보일 수 있는 안정성 문제를 해결합니다.

Stop-hook 유도, 세션 간 권한, multi-agent v2(2026년 6월)

6월 초에 적용된 변경 사항 4가지는 harness와 multi-agent 설계에 중요합니다.⁵⁹

Stop/SubagentStop hooks에 유도 채널이 추가되었습니다. Claude Code v2.1.163부터 Stop 또는 SubagentStop hook은 hookSpecificOutput.additionalContext를 반환하여 응답이 hook 오류로 표시되지 않으면서 Claude에 피드백을 전달하고 턴을 계속할 수 있습니다. 이전에는 Stop hook에서 실질적으로 사용할 수 있는 수단이 종료 코드 2 차단뿐이었는데, 이는 오류로 표시되고 연속 차단 한도에도 포함됩니다. 품질 게이트 harness에는 새 방식이 더 깔끔한 기본 수단입니다. “완료했다고 했지만 테스트가 실패하고 있음”을 감지한 Stop hook은 이제 강제로 차단하는 대신 “아직 실패 중인 항목은 다음과 같으니 계속 진행하세요”라는 내용을 전달할 수 있습니다. 실제로 중단해야 하는 조건에는 차단을 사용하고, “아직 완료되지 않았으며 그 이유는 다음과 같습니다”라는 안내에는 additionalContext를 사용하세요.

세션 간 메시지는 더 이상 빌려온 권한을 전달하지 않습니다. v2.1.166에서는 다중 세션 상황의 보안이 강화되었습니다. 다른 Claude 세션에서 SendMessage를 통해 전달된 메시지는 더 이상 원래 사용자의 권한을 포함하지 않으므로, 수신 세션은 전달된 권한 요청을 거부하고 auto mode는 이를 차단합니다. 오케스트레이션에서 에이전트끼리 메시지를 주고받는다면 수신 메시지를 인증된 지시가 아닌 신뢰할 수 없는 데이터로 다루세요. 이는 보안 섹션에서 도구 출력에 적용한 원칙을 에이전트 간 메시지까지 확장한 것입니다. v2.1.199부터 Claude Code은 이름이 같은 에이전트 2개 때문에 SendMessage가 잘못 전달되는 경우도 감지하여 경고합니다. 이름이 같은 잘못된 에이전트에게 메시지가 도달하는 상황 자체가 별도의 오케스트레이션 버그이므로, 이는 권한 경계를 보완하는 안정성 개선입니다. 모델 복원력이 핵심 설정으로 자리 잡았어요. 이제 fallbackModel 설정은 최대 3개의 예비 모델을 연결하며, 기본 모델이 과부하 상태이거나 사용할 수 없을 때 지정한 순서대로 시도해요. 또한 예상치 못한 재시도 불가 API 오류가 발생하면 해당 턴을 대체 모델에서 한 번 자동으로 재시도해요. 장시간 실행되는 자율 harness에서는 이 기능 덕분에 일시적인 기본 모델 장애로 실행이 중단되는 대신 성능을 낮춰 계속 실행할 수 있어요. claude agents --json에도 차단된 백그라운드 세션이 권한 요청 같은 무엇을 기다리는지 보여 주는 waitingFor 필드가 추가되었어요(v2.1.162). 여러 에이전트를 주기적으로 확인하는 모든 코디네이터에 관찰 가능성을 높여 주는 개선이에요.

클린룸 거버넌스와 문제 해결을 위한 안전 모드. Claude Code v2.1.169에는 모든 사용자 지정 기능을 한꺼번에 비활성화한 상태로 세션을 시작하는 --safe-mode 플래그와 이에 대응하는 CLAUDE_CODE_SAFE_MODE 환경 변수가 추가되었어요. 비활성화되는 항목은 CLAUDE.md, 플러그인, skills, hooks, MCP 서버예요.⁶⁰ 이는 harness의 반대 개념으로, 의도적으로 조성한 클린룸이에요. 모든 운영자가 결국 묻게 되는 “이 동작은 모델에서 비롯된 것인가, 아니면 내가 설정한 무언가에서 비롯된 것인가?”라는 질문에 답할 때 사용하세요. hook이 잘못 실행되거나, 실행되면 안 되는 skill이 활성화되거나, MCP 서버가 컨텍스트를 오염시킬 때 --safe-mode를 사용하면 비교 기준으로 삼을 수 있는, 아무것도 설정되지 않은 기준 상태를 확보할 수 있어요. 이 기능은 거버넌스를 위한 기본 수단이기도 해요. 평소 harness가 부여하는 지속적인 권한을 전혀 적용하지 않은 채 기본 모델만 실행할 수 있기 때문이에요. 운영자가 정의한 어떤 기반 구성에도 영향을 받지 않고 결과를 재현해야 할 때 유용해요.

모델 등급에 관한 참고 사항. Claude Code v2.1.197(2026년 6월 30일)부터 Claude Sonnet 5가 새 세션의 기본 제공 모델이에요. 네이티브 1M 컨텍스트와 8월 31일까지 적용되는 MTok당 $2/$10 프로모션 가격을 제공하며, 초기 기본 선택이었던 Opus 4.8을 대체했어요. 이 가이드에서는 Opus 5(claude-opus-5)를 에이전트 작업의 권장 기본 모델로 다뤄요. 의도적으로 다른 모델을 선택하지 않는 한 자율 harness를 실행할 모델이에요. 장기간에 걸쳐 이루어지는 중요한 에이전트 루프에서는 Opus의 깊이 있는 추론이 비용 이상의 가치를 발휘하기 때문이에요. Opus 5는 2026년 7월 24일 Claude Code v2.1.219에서 새로운 기본 Opus로 출시되었어요. 1M 컨텍스트와 MTok당 $5/$25의 가격을 제공하고, 대체 대상인 Opus 4.8과 가격이 같아요. fast mode는 기본 속도보다 약 2.5배 빠르며 가격은 $10/$50이에요. Anthropic에 따르면 Frontier-Bench v0.1에서 Opus 4.8보다 2배 넘는 성능을 기록했고, 절반의 비용으로 Fable 5의 CursorBench 3.2 점수와 0.5% 이내의 차이를 보였어요.⁸⁴⁸⁷ 가격은 같고 기능은 더 뛰어나며, Anthropic이 “작업을 검증하고 신중하게 반복하는 능력이 훨씬 강하다”고 평가한 모델이에요. harness 작업에서는 비용을 따져 볼 필요조차 거의 없는 드문 업그레이드이며, 4.8에서 이전할 때는 모델 아이디만 변경하면 돼요. 비용에 민감하거나 처리량이 중요한 작업에서는 속도 대비 지능의 효율이 뛰어난 Sonnet 5로 낮추세요. Opus보다 높은 등급에는 2026년 6월 9일 출시된 Claude Fable 5(claude-fable-5)가 있어요. Anthropic의 가장 강력한 모델이자 일반적인 용도로 안전하게 만든 “Mythos급” 시스템으로 소개되었으며, Claude Code v2.1.170에서 /model claude-fable-5로 선택할 수 있어요.⁶⁰ 전체 에이전트에 일괄 적용하지 말고, 비용을 감수할 만큼 최고의 추론 능력이 필요한 의사 결정에만 의도적으로 상위 등급을 사용하세요. Opus 5 전환에 따른 정리 사항도 2가지 있어요. Opus 4.7은 fast mode에서 제외되었고, 이제 /fast는 Opus 5와 Opus 4.8에 적용돼요. 또한 v2.1.176부터 “사용 가능한 최고의 Opus 모델”을 선택해 온 자동 모드 분류기의 Fable-5 대체 모델은 이제 Opus 5로 결정돼요.⁸⁴

Codex가 multi-agent v2를 출시했어요. Codex CLI v0.137.0에서는 각 스레드가 런타임을 직접 선택할 수 있고, 생성된 에이전트의 후속 작업과 메타데이터 기본값이 더 깔끔하게 제공돼요(hide_spawn_agent_metadata의 기본값은 이제 true예요). 원시 부모 이벤트도 자식 리스너로 전파돼요. subagent 모델은 여전히 명시적이에요. 기본 제공되는 default/worker/explorer 에이전트 유형, TOML로 정의한 사용자 지정 에이전트, 동시 실행 제어(agents.max_threads 기본값 6, agents.max_depth 기본값 1)를 지원해요. 같은 릴리스에는 턴마다 skill 카탈로그를 해석하고 새로운 스레드 시작 및 턴 오류 수명 주기 기여자 이벤트를 제공하는 v1 skills 확장 기능도 추가되었어요. 커널 샌드박스를 기본 경계로 유지하면서 Claude Code의 hook 및 skill 기능과의 격차를 줄였어요. 이후 Codex v0.138.0~v0.139.0에서는 프로덕션 환경에 맞게 multi-agent v2를 강화했어요. 이제 에이전트 간 메시지 페이로드가 암호화되며, v2 에이전트 설정 카탈로그와 에이전트 상주 상태를 관리하는 LRU를 통해 어떤 에이전트를 계속 상주시킬지 제어해요. 또한 동시 실행 수를 생성된 스레드 수가 아닌 활성 실행을 기준으로 계산하므로 유휴 에이전트는 더 이상 슬롯을 차지하지 않아요.⁶¹ 수명 주기 API도 성숙해졌어요. close_agent는 실행 중인 에이전트를 단순히 닫는 것이 아니라 중단한다는 동작을 정확히 나타내도록 v0.139.0에서 interrupt_agent로 이름이 변경되었어요. subagent가 발생시킨 MCP 시작 경고도 이제 소유 스레드에만 표시되며 부모의 기록에 중복으로 올라가지 않아요.⁶¹ Codex 기반 오케스트레이션을 구축하는 사람에게는 이러한 기능이 데모와 실제 에이전트군을 가르는 요소예요. 암호화된 메시지 전송, 제한된 상주 상태, 실행 수를 기준으로 한 동시 실행 제어, 스레드 경계를 넘어 유출되지 않는 경고를 제공하기 때문이에요. 이어서 Codex v0.140.0은 도구 간 연동 지점을 열었어요. /import를 사용하면 Claude Code의 설정, 프로젝트 구성, 최근 채팅을 선택적으로 Codex로 가져올 수 있으며, 세션은 확인 절차를 거쳐 영구적으로 삭제할 수 있게 되었어요(codex delete / /delete).⁶⁴ /import는 운영자가 여러 harness 사이를 오간다는 사실을 처음으로 공식 인정한 기능이에요. 이제 하나의 harness를 위해 만든 설정이 그 안에만 갇히지 않아요.

메모리와 컨텍스트

모든 AI 대화는 유한한 컨텍스트 창 안에서 작동해요. 대화가 길어지면 시스템은 새 콘텐츠를 위한 공간을 확보하기 위해 이전 대화 내용을 압축해요. 이 압축 과정에서는 정보가 손실돼요. 3번째 대화에서 기록한 아키텍처 결정이 15번째 대화까지 유지되지 않을 수도 있어요.⁹

여러 대화에 걸친 붕괴를 일으키는 3가지 메커니즘

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

전략 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일 때 set -e와 함께 ((VAR++))를 사용하면 실패한다는 사실을 발견했다면 이를 기록하세요. 3번의 세션이 지난 뒤 Python에서 비슷한 정수 경계 사례를 만나면 MEMORY.md 항목을 통해 해당 패턴을 확인할 수 있어요.¹⁵

자동 메모리(v2.1.32 이상): Claude Code는 프로젝트 컨텍스트를 자동으로 기록하고 불러와요. 작업하는 동안 Claude는 관찰한 내용을 ~/.claude/projects/{project-path}/memory/MEMORY.md에 기록해요. 자동 메모리는 세션을 시작할 때 처음 200줄을 시스템 프롬프트에 불러와요. 내용은 간결하게 유지하고 자세한 메모는 별도의 주제 파일로 연결하세요.⁶ v2.1.210부터 크기 제한을 초과하는 MEMORY.md 쓰기는 아무런 알림 없이 잘리는 대신 오류가 발생해요⁶⁹. 메모리 항목이 조용히 사라지는 것이 아니라 파일을 쓰는 시점에 실패가 드러나요. harness가 메모리 쓰기를 자동화한다면 이 오류를 처리하세요. 플랫폼이 재시도하라는 것이 아니라 파일을 정리해야 한다고 알려 주는 신호예요.

메모리 양보다 메모리 선별 관리(2026년 5월): 최근 발표된 LLM 에이전트 협력 관련 arXiv 사전 논문에서는 더 많은 기억을 불러오는 기능 자체가 실패 요인이 될 수 있다고 설명해요. 저자들의 실험에서는 모델 게임 환경 28개 중 18개에서 표시되는 기록이 길수록 협력 성과가 나빠졌어요.⁴⁸ 이를 확정된 법칙이 아닌 설계상의 경고로 받아들이세요. 프로덕션 환경에 적용할 원칙은 이미 충분히 명확해요. MEMORY.md는 짧게 유지하고, 세부 정보는 링크로 연결하며, 인계 문서에는 결정에 바로 활용할 수 있는 요약을 넣으세요. 원본 대화 기록과 도구 로그, 방대한 기억 데이터는 활성 프롬프트에 자동으로 넣지 말고 검색 가능한 저장소에 보관해야 해요.

전략 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

압축은 대화를 보호하고, /cd 명령(Claude Code v2.1.169)은 프롬프트 캐시를 보호해요. 대화 중 누적된 캐시를 손상하지 않으면서 세션을 새로운 작업 디렉터리로 옮겨요.⁶⁰ 이전에는 디렉터리를 변경하면 새 세션을 시작해야 했고 캐시도 비어 있었어요. 장시간 실행되는 세션이 한 저장소에서 인접한 저장소로 전환할 때가 있어요. 모노레포와 다중 서비스 작업에서 흔한 상황이에요. 이때 /cd를 사용하면 비용이 많이 드는 캐시된 접두부를 그대로 유지하면서 파일 시스템 컨텍스트의 대상을 변경할 수 있어요.

전략 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

상태/파일/결정/차단 요소/다음 작업 구조를 사용하면 최소한의 토큰 비용으로 다음 세션에 전체 컨텍스트를 제공할 수 있어요. 새 세션을 claude -c(계속)로 시작하거나 인계 문서를 읽으면 곧바로 구현 작업에 들어갈 수 있어요.¹⁵

전략 4: 새로운 컨텍스트로 반복 실행(Ralph Loop)

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에서는 이 2가지 패턴이 공존해요.

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개 이상의 토큰을 절약할 수 있어요.¹⁵

Subagent 패턴

subagents는 복잡한 작업을 독립적으로 처리하는 특화된 Claude 인스턴스입니다. 깨끗한 컨텍스트에서 시작해 메인 대화의 영향을 받지 않고, 지정된 도구를 사용하며, 결과를 요약해서 반환해요. 탐색 결과가 메인 대화를 불필요하게 늘리지 않고 결론만 돌아옵니다.⁵

기본 제공 Subagent 유형

사용자 지정 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에서 작업하며 저장소의 완전히 격리된 사본을 사용할 수 있어요.⁵

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

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

코드베이스를 손상할 수 있는 실험 작업에는 worktree 격리가 꼭 필요해요.

격리는 경계가 실제로 지켜질 때만 격리입니다. Claude Code v2.1.210에서는 worktree로 격리된 subagents가 메인 checkout을 변경할 수 있던 버그를 수정했어요. 이는 바로 이 메커니즘이 방지하기 위해 존재하는 문제입니다.⁶⁹ isolation: worktree를 편의 기능이 아닌 안전 경계로 사용한다면 v2.1.210을 최소 버전으로 삼으세요. 함께 도입된 권한 변경은 반대 방향으로 작용합니다. v2.1.211부터 “always allow” 규칙은 여러 worktrees에 걸쳐 저장소 루트에 유지되므로, 한 worktree에서 승인한 규칙이 같은 저장소의 다른 worktrees에도 적용돼요.⁶⁹ 이는 병렬 worktree agents에 알맞은 사용성을 제공하지만, 일회성 실험 중에 부여한 허용 권한도 실험이 끝난 뒤까지 남는다는 뜻입니다. 눈앞의 worktree만이 아니라 저장소 전체를 고려해 권한을 부여하세요.

v2.1.216에서는 이 작업을 마무리해 worktree 격리를 단순한 버그 수정 수준에서 강제 가능한 수준으로 끌어올렸어요.⁷⁴ v2.1.210의 수정은 일반적인 git 호출을 통해 worktree subagents가 메인 checkout을 변경하지 못하게 했지만, git 자체에는 git -C <path>, --git-dir, GIT_DIR/GIT_WORK_TREE 환경 변수처럼 경로를 명시적으로 바꾸는 기능이 있어요. worktree로 격리된 subagent는 여전히 이 기능을 사용해 공유 checkout을 대상으로 지정할 수 있었습니다. 이제 이러한 우회로가 모두 차단됐어요. 같은 릴리스에서는 worktree 세션이 가끔 다른 프로젝트에 남아 있던 worktree로 들어가는 문제를 수정하고, .claude에 심어 둔 심볼릭 링크를 따라 프로젝트 외부 대상에 workflow와 예약 작업이 쓰이지 않도록 했으며, /rewind가 심볼릭 링크와 하드 링크를 통과하지 못하게 했습니다. 이 4가지 수정에는 같은 원칙이 적용돼요. 격리 경계는 기본 동작만 막는 데 그치지 않고 git 환경 재정의나 심볼릭 링크 설치 같은 의도적인 경로 변경에도 유지되어야 합니다. isolation: worktree가 harness의 편의 기능이 아니라 안전 경계라면 이제 v2.1.216을 최소 버전으로 삼으세요.

병렬 Subagents

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

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

각 agent는 자체 컨텍스트 창에서 실행되고 관련 코드를 찾은 뒤 요약을 반환해요. 메인 컨텍스트는 깔끔하게 유지됩니다.

Recursion Guard

생성 제한이 없으면 agents가 다른 agents에 위임하고, 그 agents가 다시 다른 agents에 위임하면서 단계마다 컨텍스트를 잃고 토큰을 소모해요. 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"

핵심 교훈: 깊이 제한만 두지 말고 생성 예산을 사용하세요. 깊이 기반 제한은 부모와 자식의 연결을 추적하므로 깊이 3에서 차단할 수 있지만 너비는 놓쳐요. 깊이 1에 agents가 23개 있어도 여전히 “깊이 1”입니다. 생성 예산은 부모별로 활성화된 전체 자식 수를 추적하고 설정 가능한 최댓값으로 제한해요. 예산 모델은 대리 지표인 과도한 중첩 단계가 아니라 실제 장애 형태인 과도한 전체 agent 수에 직접 대응합니다.⁷

기본 중첩 깊이는 이미 3번 바뀌었으므로 여기에 의존해 설계하지 마세요. Claude Code v2.1.172(2026년 6월 10일)에서는 sub-agents가 자체 sub-agents를 생성하고 최대 5단계까지 중첩할 수 있게 됐어요. 이전에는 위임이 사실상 1단계로 제한됐습니다.⁶² 이 동작은 v2.1.172부터 v2.1.216까지 유지됐어요. v2.1.217(2026년 7월 21일)에서는 깊이가 1로 줄어 기본적으로 중첩 생성이 꺼졌습니다. 이어 v2.1.219(2026년 7월 24일)에서는 중간값으로 정착했어요. “Subagents는 이제 기본적으로 최대 깊이 3까지 중첩된 subagents를 생성할 수 있습니다(기존 1). 중첩을 비활성화하려면 CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=1을 설정하세요.”⁸⁴ 5에서 1로, 다시 3으로 바뀌었으며 마지막 2번의 변경은 3일 안에 일어났어요.

여기서 얻을 결론은 특정 숫자가 옳다는 것이 아니에요. 플랫폼은 여전히 적절한 기본값을 찾는 중이며, 따라서 harness가 “출시된 기본값”을 그대로 상속하는 방식은 적절하지 않습니다. 중첩 깊이를 명시적인 예산 항목으로 다루세요. 대부분의 오케스트레이션에서는 1이나 2면 충분하므로 CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH를 아키텍처에 실제로 필요한 깊이로 설정해 업그레이드가 fleet의 위임 깊이를 조용히 바꾸지 못하게 하세요. 이러한 변화와 관계없이 기존 주장은 그대로 유효합니다. agents가 agents에 위임하는 연결은 결과를 만드는 속도보다 빠르게 컨텍스트와 토큰을 소모하며, 깊이는 적극 활용할 기능이 아니라 예산으로 관리할 위험 요소예요. 위의 recursion guard는 다음 기본값이 어느 방향으로 바뀌더라도 깊은 트리가 수백 개의 활성 agents로 확산하지 않도록 막아 줍니다. 다음 릴리스 후에도 의도한 의미를 그대로 유지하는 깊이 값은 직접 설정한 제한뿐이에요.

이제 auto 모드는 실행 전에 생성 요청을 검토합니다. Claude Code v2.1.178에서는 관련 정책 공백도 해소했어요. auto 모드에서는 subagent가 작업을 수행하기 시작한 뒤에만 검사하는 것이 아니라 실행되기 전에 권한 분류기가 subagent 생성 요청을 평가합니다.⁶³ 이전에는 부모 세션이 수행하지 못하도록 차단된 작업을 요청하기 위해 subagent를 생성할 수 있었고, 생성 자체가 우회 수단이 됐어요. 생성 시점에 검토하면 recursion guard와 권한 모델이 비로소 맞물립니다. 정책에서 금지한 작업을 세탁하기 위한 중간 단계로 자식을 사용할 수 없어요.

이제 플랫폼에서 기본 생성 예산을 제공합니다. Claude Code v2.1.212(2026년 7월)에는 폭주 루프를 막는 기본 guardrails가 추가됐어요. 세션별 subagent 생성은 기본 200회로 제한되며(CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION으로 조정하고 /clear로 카운터 초기화), WebSearch도 세션당 200회로 제한됩니다(CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSION).⁶⁹ 이 섹션에서 v1.0부터 사용자 영역 스크립팅으로 설명해 온 생성 예산 패턴을 이제 플랫폼에서 직접 제공해요. 깊이 모델보다 예산 모델이 적합하다는 점을 입증한 셈입니다. 다만 수치를 살펴보세요. 생성 200회는 위 설정의 agent 12개 예산보다 한 자릿수 더 큽니다. 기본 제한은 아키텍처에 맞춰 조정된 예산이 아니라 실제 폭주 루프를 막기 위한 퓨즈예요. 부모별 예산, 깊이 추적, 오케스트레이션의 실제 동작에 맞춘 제한을 위해 사용자 영역 guard를 계속 사용하고, 이를 빠져나간 문제는 플랫폼 제한으로 잡으세요.

이제 기본 제공 guardrail 세트는 4개 축을 다룹니다. 그중 3개는 이 섹션의 사용자 영역 guard가 추적하는 항목을 그대로 보완해요. 세션별 전체 생성 수(v2.1.212, 제한 200, CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION), 중첩 깊이(CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH, 현재 기본값 3이며 불안정하다는 점이 확인됨), 동시 실행 수(v2.1.217, 기본값 20, CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS로 한 메시지가 무제한의 백그라운드 agents로 확산할 수 없게 됨)입니다.⁷⁸⁸⁴ v2.1.219에서는 사용자 영역 guards에 일반적으로 없던 4번째 축인 오케스트레이션 너비를 추가했어요. 이는 계획된 단일 workflow에 허용되는 agent 수이며, “agents를 15개 미만으로 유지”하라는 기본 가이드라인으로 제공됩니다. 아래 Workflow Tool 섹션에서 다루는 workflowSizeGuideline을 사용하면 모든 설정 파일에서 이 값을 지정할 수 있어요. 이제 생성 예산 패턴은 설계 당시 다루려 했던 모든 축과 당시에는 고려하지 않았던 축 하나까지 기본 기능으로 뒷받침됩니다.

하지만 수치 조정에 관한 주의 사항은 항목마다 다르게 적용돼요. 생성 200회와 동시 agents 20개는 퓨즈입니다. 위 설정의 agent 12개 deliberation 예산보다 한 자릿수 크며, 아키텍처를 형성하기보다 폭주 루프를 잡도록 정해진 값이에요. 너비 가이드라인은 실제 예산과 같은 범위에 들어온 첫 번째 기본 수치입니다. workflow당 agents 15개는 이 가이드의 12개와 매우 가까워서 플랫폼 기본값을 채택해도 부담이 없고, 다른 값을 선택하려면 실제 이유가 있어야 해요. 3개의 퓨즈는 설명할 수 있는 값으로 설정하고, 너비 가이드라인은 의도한 오케스트레이션 구조에 맞게 설정하세요.

Agent Teams(Research Preview)

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

활성화 방법: export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Agent Teams와 subagents를 각각 사용해야 하는 경우:

Agent View와 Goal 루프(2026년 5월)

Claude Code v2.1.139에는 실행 중이거나 차단됐거나 완료된 Claude Code 세션을 한 화면에서 보여 주는 Research Preview 인터페이스인 Agent View가 추가됐으며, claude agents로 시작할 수 있어요.⁴²⁴³ 공식 문서에서는 여러 세션을 배정하고 관리하며, 각 세션의 작업 내용을 확인하고, 운영자의 입력이 필요한 세션을 파악하는 방법으로 설명합니다.⁴³ 덕분에 최종 요약만으로는 제공할 수 없는 운영 현황을 여러 agent 작업에서 확인할 수 있어요.

subagent나 team 패턴을 본격적으로 도입할 때는 Agent View를 사용해 차단된 세션과 아직 실행 중인 세션을 확인하고, 작업 분배가 의도한 아키텍처와 일치하는지 살펴보세요. 이를 품질의 증거로 여기면 안 됩니다. Agent View는 관측 기능일 뿐이며, 작업이 건전한지는 여전히 테스트, review gates, evidence reports로 판단해야 해요.

같은 릴리스에는 완료 조건을 설정하고 조건이 충족될 때까지 여러 턴에 걸쳐 Claude의 작업을 이어 가는 /goal도 추가됐어요. 대화형 모드, -p, Remote Control에서도 사용할 수 있습니다.⁴² /goal은 결정론적 gates를 대신하는 기능이 아니라 세션 범위의 완료 루프로 다루세요. agent가 목표에 집중하도록 유지하는 데는 유용하지만, 실패 시 반드시 차단해야 하는 테스트, 인용 확인, 배포 확인, 보안 hooks는 명령이나 스크립트를 기반으로 유지해야 해요.

Workflow Tool(v2.1.147 이상)

Claude Code v2.1.147에는 결정론적 다중 agent 오케스트레이션을 위한 Workflow 도구가 추가됐으며 기본값은 비활성화예요. CLAUDE_CODE_WORKFLOWS=1로 활성화하세요.⁵² 이 기능은 이전에 사용자 지정 dispatch 스크립트, mailbox 상태, subagent 조율 규칙이 필요했던 흐름에 Claude Code의 기본 오케스트레이션 요소를 제공한다는 점에서 아키텍처상 중요해요.

주변 harness를 삭제하면 안 됩니다. Workflow는 실행 구조를 정의할 수 있지만 안전 모델을 대체하지는 못해요. PreToolUse와 PostToolUse hooks는 차단 계층으로 유지하고, 무제한으로 확장되는 너비를 막기 위해 생성 예산이나 workflow 단계 예산을 유지하며, 파일 시스템 상태를 감사할 수 있게 하고, 최종 evidence reports는 모델의 자체 평가 외부에 두세요. 실무에서는 오케스트레이션 구조에 Workflow를 사용하고, 사실 확인에는 hooks, 테스트, review gates를 사용하세요.

이제 동적 workflows에는 너비에 관한 기본 기준이 있습니다(v2.1.219). 동적 workflows에는 기본적으로 중간 규모 가이드라인인 “agents를 15개 미만으로 유지”가 적용돼요. /config의 Dynamic workflow size에서 다른 크기나 무제한 옵션을 선택할 수 있고, 실행 중인 workflow의 상태 표시줄에는 현재 가이드라인이 나타납니다.⁸⁴ 이 수치는 강제 제한이 아닌 권고 사항이며, 너비가 넓은 계획을 차단하는 대신 planner의 방향을 유도해요. 설정할 가치가 있는 이유는 이 값이 전달되는 방식에 있습니다. 새로운 workflowSizeGuideline 설정 키는 managed settings와 프로젝트 설정을 포함한 모든 설정 파일에서 지정할 수 있고, v0.3.219부터 TypeScript SDK 설정 유형에도 포함돼요. 따라서 각 운영자가 오케스트레이션 너비를 다시 정하는 대신 팀이나 조직 차원에서 표준화할 수 있습니다.⁸⁵ 코드베이스의 작업이 실제로 분해되는 방식을 담을 수 있도록 프로젝트 수준에서 설정하세요. 운영 시 알아 둘 점은 2가지입니다. 설정 파일에서 값을 지정하면 /config 행이 숨겨지는데, 올바른 동작이지만 이유를 모르면 설정이 사라진 것처럼 보일 수 있어요. 또한 가이드라인은 실행을 제한하는 것이 아니라 planner를 유도하므로 안전이 아닌 구조 항목에 속합니다. 폭주하는 너비는 여전히 생성 제한으로 막아야 해요.

여기서 유지해야 할 관점은 오케스트레이션 너비가 생성 수, 중첩 깊이, 동시 실행과 나란히 놓이는 4번째 기본 guardrail 축이며, Anthropic가 폭주 방지용 퓨즈가 아닌 현실적인 작업 규모에 맞춰 조정한 첫 번째 축이라는 점이에요. workflow당 agents 15개는 이 가이드가 v1.0부터 사용한 12개 agent deliberation 예산과 같은 수준입니다. 플랫폼 기본값과 자체 예산이 서로 다른 방향에서 같은 값에 수렴한다면, 이러한 수치에서 얻을 수 있는 가장 확실한 독립적 뒷받침에 가까워요.

세션 Forking과 자동 백그라운드 MCP(2026년 7월)

Claude Code v2.1.212에서는 2개의 오케스트레이션 요소가 재구성됐어요.⁶⁹ 이제 /fork는 현재 대화 상태에서 새 백그라운드 세션을 만듭니다. 분기된 흐름은 독립적으로 실행되고 원래 세션은 작업을 계속해요. 이전의 세션 내부 동작은 /subtask로 이름이 바뀌었습니다. 이 차이는 오케스트레이션 설계에서 중요해요. /subtask는 단일 세션의 수명 주기 안에서 수행하는 제한된 우회 작업이지만, /fork는 전체 컨텍스트를 상속하는 병렬 백그라운드 세션을 저렴하게 생성하는 방법으로서 subagent보다 Ralph 루프 생성에 더 가깝습니다. harness 스크립트에서 /fork가 세션 안에 머문다고 가정했다면 이제 백그라운드 작업을 배정하게 돼요.

같은 릴리스에서는 느린 MCP 호출을 자동으로 백그라운드로 전환해요. 2분 넘게 실행되는 MCP 도구 호출은 자동으로 백그라운드 실행으로 이동하며, CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS로 기준 시간을 조정할 수 있습니다.⁶⁹ 이제 느린 MCP 서버가 agentic 루프를 멈추게 하지는 않아요. 하지만 “도구가 결과를 반환함”과 “턴이 계속됨”이 더 이상 같은 이벤트가 아니므로, MCP의 동기식 완료를 가정한 hooks나 스크립트는 턴 경계가 아니라 도구 결과를 기준으로 동작해야 합니다.

headless 오케스트레이션을 위해 v2.1.211에는 subagent assistant 텍스트를 stream-json 출력으로 전달하는 --forward-subagent-text(환경 변수: CLAUDE_CODE_FORWARD_SUBAGENT_TEXT)가 추가됐어요.⁶⁹ 부모의 스트림을 사용하는 coordinator 프로세스는 이제 transcript를 폴링하거나 최종 요약을 기다리지 않고 subagent의 진행 상황을 직접 관찰할 수 있습니다. 이는 기본적으로 백그라운드에서 실행되는 subagents를 보완하는 관측 기능이에요. v2.1.219에서는 이 기능이 첫 단계를 넘어 확장됐습니다. 이제 깊이 2 이상에서 생성된 subagents도 자신을 생성한 Agent의 tool_use id를 키로 사용해 전달된 스트림에 표시돼요.⁸⁴ 이 키를 중심으로 시스템을 설계하세요. 중첩이 다시 기본으로 활성화된 상태에서는 subagent 텍스트를 평면 스트림으로 보면 모호해요. id를 사용하면 coordinator가 어떤 부모가 어떤 자식을 만들었는지 알 수 있으므로 위임 트리를 추정하지 않고 스트림에서 재구성할 수 있습니다. 스트림 사용자가 subagents 1단계만 처리하도록 작성됐다면 이제 존재조차 몰랐던 agents의 텍스트도 보게 돼요. 전달된 모든 행이 직접 자식에게 속한다고 가정하지 말고, 생성한 tool_use id를 기준으로 묶으세요.

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

단일 에이전트 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를 사용하는 이유를 이해할 필요가 없어요. 실행할 정확한 명령어와 “완료”의 기준을 알아야 해요.

우선순위 계층

규칙 파일은 자동으로 로드되며 CLAUDE.md를 복잡하게 만들지 않고 구조화된 컨텍스트를 제공해요.⁶

무시되는 내용

다음 패턴은 agent 동작에 눈에 띄는 변화를 일으키지 않아요.²¹

명령어가 없는 설명문. “깔끔하고 테스트가 잘된 코드를 중요하게 생각합니다”는 운영 지침이 아니라 문서예요. 실행 가능한 지침이 없으므로 agent는 이를 읽고도 테스트 없이 코드를 작성해요.

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

서로 충돌하는 우선순위. “빠르게 진행하고 배포하세요”, “포괄적인 테스트 커버리지를 확보하세요”, “실행 시간을 5분 이내로 유지하세요”, “커밋할 때마다 전체 통합 테스트를 실행하세요”라는 지침을 함께 두는 경우예요. agent는 4가지 지침을 동시에 충족할 수 없으므로 검증을 건너뛰는 쪽을 기본값으로 선택해요.²¹

강제 수단이 없는 스타일 가이드. ruff check --select D 없이 “Google Python 스타일 가이드를 따르세요”라고만 하면 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. 디렉터리 범위 지정 (모노레포에서 서비스별 지침을 분리해요)

앞의 4가지가 제대로 작동하기 전까지는 스타일 선호 사항을 생략하세요.

이제 플랫폼이 CLAUDE.md를 대신 검사해 줘요. 2026년 7월 초 릴리스인 v2.1.203~v2.1.206부터 /doctor는 CLAUDE.md를 분석하고 모델이 코드베이스에서 직접 파악할 수 있는 내용을 줄이도록 제안해요. 다시 나열한 디렉터리 구조, 코드에 이미 드러난 프레임워크 관례, 패키지 스크립트와 중복되는 명령어 목록 등이 여기에 해당해요.⁶⁸ 이는 이 섹션의 핵심 주장을 제공사가 직접 확인해 준 셈이에요. 지침은 agent가 추론할 수 없는 정책, 임계값, 완료 조건을 담을 때 컨텍스트를 사용할 가치가 있으며, 디스크에서 읽을 수 있는 내용을 담을 때는 그렇지 않아요. CLAUDE.md가 크게 늘어난 뒤에는 /doctor를 실행하고 정리 제안을 출발점으로 활용하세요. 다만 “추론 가능”하다고 표시된 운영 규칙이 단순한 설명이 아니라 반드시 필요한 제약 조건이라면 그대로 유지하세요.

파일 가져오기

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는 주요 harness 계층에 대응하는 기본 기능을 제공하지만, 마이그레이션은 파일 복사가 아니라 패턴 변환이에요. Codex는 작업을 시작하기 전에 AGENTS.md를 읽으며, ~/.codex의 전역 지침 위에 프로젝트 및 중첩된 저장소의 지침을 계층적으로 적용해요.³¹ Codex skills는 점진적 공개 방식과 함께 동일한 SKILL.md 개념 모델을 사용해요. Codex는 먼저 skill 이름, 설명, 파일 경로만 확인한 다음, 사용하기로 결정했을 때만 전체 skill을 로드해요.³² Codex는 기본 hooks, plugin에 포함된 hooks, 관리형 hooks, MCP 지원, 명시적인 subagent 워크플로도 제공해요.³³³⁴

Codex v0.138.0~v0.139.0은 복잡한 워크스페이스에서도 AGENTS.md를 안정적으로 찾도록 개선했어요. 이제 환경의 파일 시스템 추상화 계층을 통해 파일을 로드하고 탐색 과정에서 논리 경로를 보존하므로, 워크스페이스가 원격 파일 시스템이나 심볼릭 링크로 구성된 트리여도 올바른 파일을 선택해요.⁶¹ 기준 AGENTS.md가 권위 있는 소스이고 agent가 마운트된 체크아웃, 컨테이너에서 구체화된 체크아웃 또는 심볼릭 링크로 연결된 체크아웃에서 작업할 때 특히 중요해요. 단순한 경로 탐색 방식은 이런 환경에서 잘못된 지침 파일을 선택하거나 아무 파일도 찾지 못할 수 있어요. 하나의 기준 AGENTS.md를 여러 서비스에 반영한다면, agent가 실제로 로드한 파일과 작성한 파일이 같다고 신뢰할 수 있는 최소 버전으로 이 릴리스를 간주하세요.

이후 Codex v0.141.0은 원격 실행 경로 자체의 보안도 강화했어요. 이제 원격 실행기는 인증되고 종단 간 암호화된 Noise-relay 채널을 통해 연결돼요. 제어 영역과 실행기가 중간 릴레이를 더 이상 신뢰하지 않아도 돼요. 플랫폼 간 원격 실행은 실행기 고유의 작업 디렉터리와 셸을 유지하며, TLS는 엔터프라이즈 프록시를 위한 P-521 인증서 서명을 허용해요.⁶⁵ 오케스트레이션이 네트워크 경계를 넘어 Codex 실행기를 구동한다면, 이는 신뢰할 수 있는 릴레이를 전제로 하는 방식과 종단 간 암호화 방식의 차이를 만들어요. 모든 원격 실행기 구성의 기준으로 삼으세요.

2026년 7월 릴리스 흐름을 보면 두 런타임이 서로 반대 방향에서 출발해 같은 기본 요소로 수렴하고 있어요.⁷² Codex v0.143.0은 MCP 도구를 기본적으로 도구 검색을 통해 로드해요. 도구 스키마를 처음부터 컨텍스트에 넣지 않고 필요할 때 가져와요. 이는 Claude Code이 ToolSearch 인터페이스를 통해 제공하는 지연된 도구 로딩 패턴과 같으며, 두 런타임 모두에서 MCP 도구 수가 많아질 때 발생하는 컨텍스트 비대화 문제에 적합한 해결책이에요. Codex v0.144.0에는 writes 앱 승인 모드가 추가됐어요. 읽기 전용 작업은 확인 없이 실행되고 쓰기 작업에는 승인이 필요해요. 읽기 전용과 자동 승인 사이에 위치하는 완전히 새로운 권한 모드이며, Claude Code의 모드 목록에는 이에 정확히 대응하는 방식이 없어요. 가장 유사한 plan 모드는 쓰기마다 승인을 요청하는 대신 쓰기 자체를 차단해요. 같은 릴리스에서 MCP 대화형 인증이 정식 출시됐어요. 또한 v0.144.5는 위험한 명령어 감지 범위를 확대해 Claude Code이 v2.1.183과 v2.1.208에서 출시한 파괴적 명령어 guardrails와 비슷한 기능을 제공해요. 여러 런타임에 걸친 harness 설계에서는 이러한 수렴이 핵심이에요. 지연된 도구 로딩, 단계별 쓰기 승인, 의도 수준의 위험한 명령어 차단은 제공사를 구분하는 기능이 아니라 기본 요건이 되고 있어요.

Codex v0.145.0은 2가지 측면에서 이러한 수렴을 더 확장했어요.⁷⁶ 선택적으로 사용할 수 있는 multi-agent V2 인터페이스가 안정화됐어요. 이제 sub-agent 모델, 추론 수준, 동시 실행 수를 설정할 수 있으며, 이전에 제거된 agent 역할도 복원됐어요. 이는 .claude/agents/ frontmatter에서 subagent별 모델과 작업 강도를 설정하는 기능에 대응하는 Codex의 방식이에요. 또한 /import가 완전한 harness 간 마이그레이션 기능으로 확장됐어요. v0.140.0에서 출시된 Claude Code 설정 가져오기를 넘어, 이제 Claude Code과 Cursor의 설정을 모두 마이그레이션해요. MCP 서버, plugins, 세션, 명령어, 프로젝트 범위의 메모리도 포함돼요. 두 런타임을 모두 사용하는 팀은 한 방향으로 마이그레이션하는 비용이 계속 낮아지고 있어요. Claude Code에서 구축한 서버, 명령어로 사용하는 skills, 메모리 등의 harness 계층은 종속 요소가 아니라 점점 더 이식 가능한 상태가 되고 있어요.

실제 대응 관계는 다음과 같아요.

중요한 차이점이 있어요. Claude subagents는 설명을 바탕으로 자동 선택될 수 있지만, 현재 Codex 문서에서는 subagent 워크플로를 명시적으로 사용하도록 안내해요. 따라서 Codex에서 항상 활성화되어야 하는 harness 동작에는 skills와 hooks를 기본으로 사용하고, 의도적인 병렬 작업, 검토, 탐색에는 subagents를 사용하세요.

지침 테스트하기

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가 실행 가능한 지침을 추출하지 못했거나, 지침 파일을 찾지 못한 거예요. GitHub이 2,500개 저장소를 분석한 결과에 따르면 대부분의 실패 원인은 모호한 지침이에요.²¹

프로덕션 패턴

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

Claude Opus 4.7은 2026년 4월 16일에 출시되었으며, harness에서 방어 방식을 바꿔야 하는 다음과 같은 기능이 추가되었습니다.²⁹

• 도구 실패 복원력: Opus 4.7은 Opus 4.6 세션을 중단시켰던 도구 실패가 발생해도 작업을 계속합니다. subagents 코드의 방어적 재시도 래퍼를 줄일 수는 있지만 완전히 제거할 수는 없습니다. hook 수준의 보호 장치는 유지하고, 프롬프트 안의 “도구가 실패하면 세 번 다시 시도하세요” 같은 보조 지침은 줄이세요.
• xhigh 작업 수준 (Opus-4.7 전용): high와 max 사이에 위치합니다. 코딩 및 에이전트 워크로드의 기본값으로 권장됩니다. 장시간 실행되는 subagents에서는 xhigh가 토큰 비용의 증가 폭보다 훨씬 큰 성능 향상을 high 대비 제공합니다. 한 번의 고난도 추론에는 여전히 max가 적합하지만, 지속적인 작업에는 xhigh가 더 좋습니다.
• 토큰 예산 상한: 각 에이전트 실행에서 output_config.task_budget으로 설정할 수 있습니다. 베타 헤더는 task-budgets-2026-03-13입니다. 모델은 남은 예산이 줄어드는 것을 확인하면서 작업 범위를 조정하므로 예기치 않게 토큰을 모두 소진하지 않습니다. 짧은 프롬프트의 품질을 희생하지 않으면서 토큰 사용량을 예측 가능하게 유지하려는 에이전트 루프에 사용하세요.
• 암묵적 요구 파악: 사용자의 문자 그대로의 요청이 실제 요구 사항을 충분히 설명하지 못한 상황을 인식하는 “암묵적 요구” 테스트를 통과한 최초의 Claude 모델입니다. 이에 따라 CLAUDE.md의 “명확화 규칙” 섹션은 이전만큼 필요하지 않습니다. CLAUDE.md가 “사용자가 Y를 요청하면 X도 고려하세요” 같은 보호 지침 200줄로 구성되어 있다면, 이제 모델 자체에서 처리하는 항목은 정리하세요.

Worktree 기준, Sandbox 경로 및 관리자 설정 (2026년 5월 7일)

Claude Code v2.1.133에는 프로덕션 harness에서 알아 두어야 할 관리자 수준 설정 4개가 추가되었습니다.³⁹

사용자에게 특히 알려야 할 변경 사항은 worktree.baseRef의 원복입니다. v2.1.128부터 v2.1.132까지의 동작, 즉 로컬 HEAD에서 worktree를 분기하는 방식에 의존했던 에이전트는 이를 다시 명시적으로 설정하지 않으면 새 worktree에서 푸시하지 않은 작업에 접근할 수 없습니다.

엔터프라이즈 관측성을 위한 OTel 피드백 설문 (2026년 5월 8일)

Claude Code v2.1.136에는 OpenTelemetry를 통해 응답을 수집하는 엔터프라이즈가 세션 내 품질 설문을 다시 활성화할 수 있도록 CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL이 추가되었습니다.⁴⁰ 조직에서 OTel 이벤트를 중앙 관측성 스택으로 전송한다면 이 환경 변수를 통해 설문을 데이터 경로에 다시 포함할 수 있으며, 품질 신호도 지연 시간 및 오류 지표와 동일한 파이프라인으로 전달됩니다. 이 설정은 명시적으로 활성화하는 방식으로 취급하세요. 기본적으로 설문은 비활성화되며, OTel을 사용하지 않는 배포에서는 이 설정이 적절합니다.

기업용 런처와 MCP 규모의 성능 (2026년 7월)

v2.1.207의 변경 사항 2개는 프로덕션 배포에서 중요합니다.⁶⁸ CLAUDE_CODE_PROCESS_WRAPPER를 사용하면 관리형 환경에서 기업용 래퍼 바이너리를 통해 Claude Code 프로세스를 실행할 수 있습니다. 이는 엔드포인트 에이전트, 실행 시점의 정책 검사, 모든 프로세스를 지정된 감독 프로세스 아래에서 실행해야 하는 환경을 위한 통합 지점입니다. 이전에 셸 별칭이나 자체 런처 스크립트로 이를 우회 구현했다면 이제 이 공식 지원 지점을 사용하세요.

같은 릴리스에서는 harness에 가장 큰 영향을 주던 런타임 오버헤드도 줄였습니다. MCP 도구 수가 많은 세션에서 도구 사용 라운드가 최대 7배 빨라졌으며, 세션 기록 크기는 79분의 1로 줄었습니다.⁶⁸ 이 개선은 비용을 아키텍처로 다루기 지침의 의미를 완화하지만 뒤집지는 않습니다. 상태를 유지하지 않는 일회성 작업에는 여전히 CLI 우선 방식이 유리합니다. 다만 수십 개의 MCP 도구를 탑재한 harness는 더 이상 봄에 발생했던 라운드별 비용을 부담하지 않으며, 세션 기록 저장소도 장시간 자율 실행의 숨겨진 비용으로 남지 않습니다.

quality loop

간단하지 않은 모든 변경 사항에 적용하는 필수 검토 절차입니다.

1. 구현 - 코드를 작성합니다
2. 검토 - 모든 줄을 다시 읽습니다. 오타, 논리 오류, 불명확한 부분을 찾아냅니다
3. 평가 - evidence gate를 실행합니다. 패턴, 예외 상황, 테스트 범위를 확인합니다
4. 개선 - 모든 문제를 수정합니다. 절대로 “나중”으로 미루지 않습니다
5. 전체 조망 - 통합 지점, 가져오기, 인접 코드에 회귀가 없는지 확인합니다
6. 반복 - evidence gate 기준을 하나라도 충족하지 못하면 4단계로 돌아갑니다
7. 보고 - 변경 사항과 검증 방법을 나열하고 구체적인 근거를 인용합니다

evidence gate

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

어느 행에서든 근거를 제시할 수 없다면 개선 단계로 돌아가세요.²²

사람의 병합 권한

2026년 5월에 발표된 29,585개의 AI 에이전트 풀 리퀘스트 생명 주기를 다룬 arXiv 연구는 운영 권한과 병합 거버넌스를 구분합니다.⁴⁷ 여기서 얻을 수 있는 유용한 아키텍처 교훈은 간단합니다. 에이전트가 작업을 시작하고, 브랜치를 이어서 관리하고, 풀 리퀘스트를 열고, 작업을 검토하고, 위험을 요약할 수는 있지만 병합 권한은 별도의 거버넌스 경계로 유지할 수 있습니다.

harness에서 이 경계를 명확히 하세요. 에이전트가 풀 리퀘스트를 준비하고 근거를 수집하도록 허용하되, 조직에 별도로 감사를 마친 자동화 정책이 없다면 병합, 릴리스, 저장소를 파괴적으로 변경하는 작업에는 사람의 승인을 요구하세요. 자동화가 병합을 실행하는 경우에는 실행 주체와 이를 승인한 사람 또는 정책을 구분할 수 있는 로그를 보존하세요.

오류 처리 패턴

원자적 파일 쓰기. 여러 에이전트가 같은 상태 파일에 동시에 쓰면 JSON이 손상됩니다. .tmp 파일에 쓴 다음 mv로 원자적으로 이동하세요. 같은 파일 시스템에서 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이 0일 때 0++는 0으로 평가되고 bash는 이를 거짓으로 처리하므로 ((VAR++))가 종료 코드 1을 반환합니다. set -e가 활성화되어 있으면 이 동작으로 스크립트가 종료됩니다. 대신 VAR=$((VAR + 1))을 사용하세요.¹⁶

영향 범위 분류

모든 에이전트 작업을 영향 범위에 따라 분류하고 그에 맞는 gate를 적용하세요.²

Remote Control은 브라우저나 모바일 앱에서 로컬 Claude Code에 연결하는 기능으로, “외부” gate의 승인 대기를 비동기 알림으로 바꿉니다. 사용자가 휴대전화에서 이전 작업을 검토하는 동안 에이전트는 다음 작업을 계속 진행합니다.²

자율 실행을 위한 작업 명세

효과적인 자율 작업에는 목표, 완료 기준, 컨텍스트 위치라는 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

기준은 테스트 통과 여부, 린터 출력, HTTP 상태 코드, 파일 존재 확인처럼 기계로 검증할 수 있어야 합니다. 초기 작업에서 에이전트에게 “통과하는 테스트를 작성하라”고 요청했더니 assert True와 assert 1 == 1이 생성되었습니다. 기술적으로는 맞지만 실질적으로는 아무 가치가 없습니다.¹⁶

주의해야 할 실패 유형

구체적인 세션 실행 기록

5개 스토리가 포함된 PRD을 처리한 자율 실행의 세션 기록입니다.²

1. SessionStart가 실행됩니다. dispatcher가 현재 날짜, 프로젝트 감지 결과, 철학적 제약 조건, 비용 추적 초기화를 주입합니다. hook 5개가 실행되며 총 180ms가 걸립니다.

2. 에이전트가 PRD을 읽고 첫 번째 스토리를 계획합니다. UserPromptSubmit이 실행됩니다. dispatcher가 활성 프로젝트 컨텍스트와 세션 이탈 기준선을 주입합니다.

3. 에이전트가 테스트를 실행하기 위해 Bash를 호출합니다. PreToolUse:Bash가 실행됩니다. 자격 증명 검사, sandbox 검증, 프로젝트 감지를 수행하며 90ms가 걸립니다. 테스트가 실행됩니다. PostToolUse:Bash가 실행되어 활동 heartbeat를 기록하고 이탈 여부를 확인합니다.

4. 에이전트가 파일을 생성하기 위해 Write를 호출합니다. PreToolUse:Write가 실행되어 파일 범위를 확인합니다. PostToolUse:Write가 실행되어 린트 검사와 커밋 추적을 수행합니다.

5. 에이전트가 스토리를 완료합니다. Stop이 실행됩니다. quality gate가 에이전트가 근거를 인용했는지, 얼버무리는 표현을 사용했는지, diff에 TODO 주석이 있는지 확인합니다. 하나라도 검사에 실패하면 종료 코드 2를 반환하고 에이전트는 작업을 계속합니다.

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

7. 코드 검토 에이전트 3개가 병렬로 생성됩니다. 각 에이전트는 diff를 독립적으로 검토합니다. 한 검토자라도 심각한 문제를 표시하면 스토리가 대기열로 돌아갑니다.

8. 스토리가 검사를 통과하면 다음 스토리를 불러옵니다. 5개 스토리 모두에서 이 주기가 반복됩니다.

5개 스토리에서 실행된 hook은 총 약 340개입니다. hook에 걸린 총시간은 약 12초입니다. 이 오버헤드를 통해 하룻밤의 실행에서 자격 증명 유출 3건, 파괴적 명령 1건, 불완전한 구현 2건을 방지했습니다.

사례 연구: 밤새 진행된 PRD 처리

프로덕션 harness가 8회의 야간 세션에 걸쳐 12개의 PRD과 47개의 스토리를 처리했습니다. 지표는 처음 4개의 PRD, 즉 CLAUDE.md만 사용한 최소 harness와 마지막 8개의 PRD, 즉 hooks, skills, quality gates, 다중 에이전트 검토를 사용하는 전체 harness를 비교합니다.

자격 증명 유출 2건으로 인해 API 키를 교체하고 하위 서비스를 감사해야 했으며, 사고 대응에 약 4시간이 걸렸습니다. 이에 상응하는 사고를 방지한 harness 오버헤드는 스토리당 2.4초의 bash 실행이 전부였습니다. Stop hook이 에이전트의 완료 보고를 허용하기 전에 독립적으로 테스트를 실행했기 때문에 잘못된 완료율은 35%에서 4%로 감소했습니다.

보안 고려 사항

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

Anthropic는 2026년 4월 9일에 에이전트 신뢰성에 관한 공식 프레임워크를 발표했어요.²⁷ 5가지 원칙은 이 가이드의 evidence gate 사고방식과 맥을 같이하면서도 그 범위를 확장해요.

Anthropic는 MCP도 Linux Foundation의 Agentic AI Foundation에 기부했어요. 이로써 AGENTS.md와 함께 관리되며, AGENTS.md는 현재 OpenAI, Google, Cursor, Factory, Sourcegraph가 공동으로 관리해요. 이제 에이전트 상호 운용성 표준은 특정 공급업체에 종속되지 않아요.²⁷

MCP의 상태 비저장 턴과 자체 보고 신원 정보(2026년 7월). MCP 사양은 상태 비저장 코어로 전환하는 과정에 있어요(SEP-2575). 이 변경으로 이전에 서버 신원 정보를 전달하던 상태 저장형 초기화 핸드셰이크가 사라져요. 7월 16일에 병합된 사양 초안 변경 사항(PR #3002)은 신원 정보를 선택 사항으로 복원했어요. 서버는 응답 _meta에 io.modelcontextprotocol/serverInfo 객체를 포함할 수 있으며, 요청의 clientInfo도 선택 사항이 돼요.⁷¹ 보안 측면에서 중요한 부분은 사양이 신뢰에 관해 명시한 내용이에요. 이 신원 정보는 자체 보고된 검증되지 않은 정보이므로 표시와 로깅에만 사용해야 하며, 보안 결정을 내리는 데 사용해서는 안 돼요. harness의 허용 목록, 권한 규칙 또는 로그 기반 감사가 MCP 서버가 선언한 이름을 기준으로 작동한다면, 그 이름은 자격 증명이 아니라 주장일 뿐이에요. 서버가 스스로 밝힌 신원이 아니라 전송 방식과 설정, 즉 사용자가 어떤 엔드포인트에 어떤 서버를 설정했는지를 기준으로 신뢰를 고정하세요. 최종 상태 비저장 사양 개정판은 2026년 7월 28일에 공개될 예정이므로, 다음 업데이트에서는 이 섹션의 프로토콜 수준 세부 사항이 확정될 것으로 예상해요.

Skill 샌드박스 도구: skills를 공격 표면으로 간주하는 팀을 위해 Permiso의 SandyClaw는 skills를 전용 샌드박스에서 실행하고 Sigma/YARA/Nova/Snort 탐지 결과를 근거로 판정을 제공해요. 2026년 4월 2일에 출시된 skill 샌드박스 범주의 첫 번째 제품이에요.²⁸

샌드박스

Claude Code는 OS 수준의 격리 기능을 사용해 네트워크 접근과 파일 시스템 작업을 제한하는 선택적 샌드박스 모드를 지원해요. macOS에서는 seatbelt, Linux에서는 bubblewrap을 사용하며 settings.json이나 /sandbox 명령으로 활성화할 수 있어요. 샌드박스를 활성화하면 모델이 임의의 네트워크 요청을 보내거나 프로젝트 디렉터리 외부의 파일에 접근하지 못해요. 샌드박스를 사용하지 않으면 Claude Code는 개별 도구 호출을 사용자가 승인하거나 거부하는 권한 기반 모델을 사용해요.¹³

2026년 5월의 보안 최저선. Claude Code v2.1.149에서는 PowerShell 작업 디렉터리 권한 우회, 여러 PowerShell 허용 규칙 및 오래된 변수와 관련된 권한 분석 누락, 공유 git 내부 요소만이 아니라 기본 저장소 루트 전체를 허용하던 git-worktree 샌드박스 쓰기 허용 목록 문제가 수정됐어요.⁵³ harness가 PowerShell이나 worktree로 격리된 에이전트를 허용한다면 v2.1.149 이상을 최저선으로 삼고 셸 규칙의 범위를 좁게 유지하세요. 광범위한 PowerShell(*) 규칙과 저장소 전체에 대한 쓰기 예외는 오케스트레이션을 위한 지름길일 뿐, 안전 경계가 아니에요.

OpenAI Agents SDK 샌드박스 제한 강화(v0.17.0, 2026년 5월 8일). OpenAI 측에서는 openai-agents-python v0.17.0을 통해 이와 유사한 경계를 강화했어요. 이제 LocalFile.src와 LocalDir.src는 구체화 과정의 base_dir, 즉 매니페스트가 적용될 때 SDK 프로세스가 사용하는 현재 작업 디렉터리 내부로 제한돼요. 단, 소스가 SandboxPathGrant와 함께 Manifest.extra_path_grants를 통해 명시적으로 허용된 경우는 예외예요.⁴¹ 상대 경로인 로컬 소스는 base_dir을 기준으로 해석돼요. 절대 경로는 이미 해당 디렉터리 안에 있거나 별도의 허용 항목이 있어야 해요. 이 변경은 로컬 아티팩트 경계 문제를 해결해요. 이전 버전에서는 매니페스트가 호스트의 임의 경로를 샌드박스 작업 공간으로 가져올 수 있었어요. 마이그레이션할 때는 읽기 전용 마운트에 SandboxPathGrant(path=..., read_only=True)를 사용해 신뢰하는 호스트 루트를 매니페스트 수준에서 선언하세요. extra_path_grants는 신뢰할 수 있는 애플리케이션 설정으로 취급해야 해요. 모델 출력이나 신뢰할 수 없는 매니페스트 입력으로 허용 항목을 채우지 마세요.

OpenAI Agents SDK의 후속 최저선(v0.17.3). 0.17.1부터 0.17.3까지의 버전에는 샌드박스와 세션을 더욱 강화하는 변경 사항이 추가됐어요. 여기에는 압축 파일 추출 제한, GitRepo 하위 경로 검증, 더 명확한 샌드박스 공급자 오류, 샌드박스 명령에서 마운트 지점 자격 증명 제외, 상대 경로인 샌드박스 작업 공간 루트 거부, Vercel 샌드박스의 종료 상태 처리가 포함돼요.⁵⁴ Claude Code hooks만 사용하는 대신 OpenAI가 호스팅하거나 공급자가 지원하는 샌드박스를 사용한다면, 이 섹션의 패턴을 적용할 때 0.17.3을 현재 최저선으로 삼으세요.

제품별 3가지 격리 패턴 (Anthropic, 2026년 5월)

Anthropic가 2026년 5월 25일에 게시한 엔지니어링 글 “제품 전반에서 Claude을 격리하는 방법”은 이 섹션에서 나누어 설명한 원칙을 공급업체가 직접 정리한 글이에요. 위에서 다룬 설정 수준의 샌드박스, worktree 격리의 최저선, 모든 대상을 신뢰하지 않는다는 관점이 포함돼요.⁸¹ 핵심은 제품 표면에 맞춰 격리 강도를 정하는 것이며, 그 대응 관계 자체가 중요한 교훈이에요. 하나의 올바른 격리 설계가 있는 것이 아니라 누가 지켜보고 있으며 어떤 문제가 발생할 수 있는지에 맞는 격리가 필요해요.

• 일회성 gVisor 컨테이너(claude.ai). 서버 측 실행은 격리된 인프라의 gVisor 컨테이너에서 이루어지며, 세션별 일회성 파일 시스템을 사용해요. 위협 모델은 인프라와 테넌트 격리에 초점을 맞춰요. 사용자의 컴퓨터에는 접근할 수 없으므로 로컬에서 방어해야 할 대상도 없어요.
• 사람이 개입하는 OS 샌드박스(Claude Code). 위 샌드박스 단락에서 설명한 패턴을 정책으로 표현한 방식이에요. macOS에서는 Seatbelt, Linux에서는 bubblewrap을 사용하고 읽기는 허용하되 쓰기는 작업 공간으로 제한하며 네트워크는 기본적으로 거부해요. 경계가 다루지 못하는 작업은 사람이 승인해요. Anthropic는 경계를 감사할 수 있도록 런타임을 오픈 소스로 공개했어요(sandbox-runtime). 이 글은 취약 지점도 솔직하게 밝혀요. 권한 요청의 약 93%가 승인되며, 실행 전에 지나치게 적극적인 행동의 약 83%를 포착하면서 승인 요청을 84% 줄이는 자동 모드 분류기가 존재하는 이유도 바로 여기에 있어요. 승인 피로는 사용자 경험상의 불만이 아니라 보안 특성이기 때문이에요. 이는 이 가이드가 v2.1.193부터 다뤄 온 확인 계층 관점이에요.
• 밀폐형 VM(Claude Cowork). 플랫폼 하이퍼바이저에서 완전한 가상 머신을 실행하는 방식이에요. macOS에서는 Apple Virtualization 프레임워크, Windows에서는 HCS를 사용하며 선택한 작업 공간과 .claude 폴더만 마운트해요. 호스트의 다른 요소는 전혀 보이지 않아요. 자격 증명은 VM 안으로 들어가지 않아요. 호스트의 키체인에 남아 있고 각 세션에는 범위가 제한되어 있으며 독립적으로 폐기할 수 있는 토큰이 제공돼요. VM 내부의 방어용 MITM 프록시가 이를 강제하며, VM에 발급된 자체 세션 토큰이 포함된 요청만 통과시켜요. 공격자가 삽입한 키는 경계에서 거부돼요. 출처를 아는 것은 VM뿐이기 때문이에요.

이 분류 체계의 기반이 되는 설계 원칙은 다른 환경에도 적용할 수 있어요. 먼저 환경 계층에서 격리하고, 그다음 모델 계층에서 행동을 유도하세요. 확률적 방어에는 항상 0이 아닌 누락률이 있으므로 프롬프트 수준의 유도가 놓친 대상을 결정적 경계가 잡아야 해요. 이는 이 가이드에서 설명한 hooks의 실행 보장 논리를 공급업체가 다시 표현한 것이에요. 사용자가 감독할 수 있는 역량에 맞춰 격리 강도를 조정하세요. 개발자는 bash 명령을 승인하기 전에 평가할 수 있지만 지식 근로자는 그러기 어려워요. 그래서 Code에는 권한 대화 상자가 제공되고 Cowork에는 밀폐형 VM이 제공돼요. 직접 만든 격리 코드보다 충분히 검증된 기본 요소를 사용하세요. 하이퍼바이저, seccomp, 컨테이너 런타임은 Anthropic가 직접 만든 허용 목록 프록시나 설정 파서보다 적대적 검증을 더 잘 견뎌 왔어요. 프로젝트 로컬 설정과 도구 출력을 신뢰하지 마세요. 이 글은 프로젝트를 열고 설정을 불러오는 작업을 인터넷에서 들어오는 다른 요청과 똑같이 취급하고, 도구를 신뢰하더라도 도구 출력은 공격 표면으로 간주하라고 지시해요. 이는 이 가이드가 에이전트 간 메시지, subagent가 읽은 콘텐츠, 자체 보고된 MCP 신원 정보에 적용하는 것과 같은 관점이에요. 자격 증명은 샌드박스 외부에 보관하세요. 에이전트가 유출할 수 있는 상시 키 대신 범위가 제한되고 폐기할 수 있는 세션별 토큰을 사용하세요.

설정 표면도 첫 번째 원칙을 따라잡고 있어요(v2.1.219). “먼저 환경 계층에서 격리한다”는 원칙에는 쉽게 동의할 수 있지만 실제 설정은 불편했어요. Claude Code의 샌드박스는 규칙이 다루지 않는 작업을 질문으로 해결했기 때문이에요. 위의 93% 승인 수치에서 드러나듯 권한 요청은 결정적 방어처럼 보이는 확률적 방어예요. sandbox.network.strictAllowlist를 설정하면 송신 요청에 관한 질문이 사라져요. 샌드박스 명령이 허용 목록에 없는 호스트로 요청을 보내면 질문하는 대신 즉시 거부해요.⁸⁴ 이를 v2.1.216의 sandbox.filesystem.disabled와 함께 사용하면 두 설정이 단순한 토글 모음이 아니라 하나의 보안 태세를 구성해요. 파일 시스템과 네트워크 격리를 독립적으로 선택할 수 있고, 이제 네트워크 격리를 결정적으로 적용할 수 있어요. 무인 harness에서는 네트워크 격리가 둘 중 더 중요해요. 송신 경로는 삽입된 지시가 정보 유출로 이어지는 곳이며, 승인 피로가 극단에 이르면 피로를 느낄 사람조차 키보드 앞에 없기 때문이에요. 결정적 경계에는 일반적인 비용이 따라요. 허용 목록이 정확해야 하며, 누락한 호스트는 질문을 표시하는 대신 이유가 불분명한 거부로 실패해요. 에이전트에 실제로 필요한 호스트를 열거한 다음 질문을 없애세요.

이러한 격리도 hook 계층을 대체하지는 않으며 그 아래에 자리 잡아요. 격리 패턴은 결정적 최저선이고, 이 가이드에서 다룬 worktree 강제 적용의 역사는 같은 교훈을 축소해서 보여 줘요. 의도적인 경로 변경에도 유지되어야 경계라고 할 수 있으며, 특별히 이 목적을 위해 만들어진 것이 아닌 검증된 기본 요소가 가장 잘 유지될 가능성이 높아요.

권한 경계

권한 시스템은 여러 수준에서 작업을 통제해요.

매개변수 수준의 권한 규칙(2026년 6월)

Claude Code v2.1.178에서는 권한 규칙이 도구 수준에서 매개변수 수준까지 확장됐어요. Tool(param:value)은 도구 입력 매개변수와 일치하며 *는 와일드카드로 사용해요. 대표적인 예시는 Agent(model:opus)예요. 특정 모델 등급으로 subagents가 생성되지 못하도록 차단하는 규칙이에요.⁶³ 아키텍처 측면에서는 위의 4단계 표로 표현할 수 없었던 공백을 메워요. 이전에는 도구 전체를 허용하거나 거부할 수만 있었고, 도구가 어떻게 호출되는지는 제한할 수 없었어요. 이제 거버넌스 정책은 “subagents를 생성할 수 있지만 Fable 5 등급에서는 생성할 수 없다” 또는 “Bash는 허용하지만 이 플래그는 사용할 수 없다”와 같은 조건을 프롬프트 수준의 요청이 아닌 결정적 규칙으로 지정할 수 있어요.

함께 제공되는 관리형 설정인 enforceAvailableModels(v2.1.175)는 위에서부터 모델 선택을 제한해요. Default 모델을 고정하고 사용자 또는 프로젝트 범위의 설정이 관리형 availableModels 허용 목록을 확장하지 못하게 해요.⁶³ 두 기능은 함께 작동해요. 허용 목록은 세션에 존재할 수 있는 모델 등급을 정의하고, 매개변수 수준 규칙은 subagents가 그중에서 모델을 선택하는 방식을 제한해요. v2.1.196부터 관리자는 조직 콘솔에서 조직 전체의 기본 모델도 설정할 수 있어요. /model에는 “Org default”로 표시되며, 각 운영자가 모델을 고정하지 않아도 전체 환경에서 관리되는 기본값을 상속해요. 이는 허용 목록의 상한선을 보완하는 최저선이에요.

작업 디렉터리를 기준으로 하는 경로 범위의 허용 규칙(2026년 7월)

Claude Code v2.1.214에서는 경로 범위 권한 규칙이 의도보다 넓게 일치하던 조용한 문제를 해결했어요. Edit(src/**)처럼 단일 세그먼트 dir/** 패턴을 사용한 허용 규칙은 이전에 모든 깊이에서 이름이 src인 모든 디렉터리의 편집을 자동 승인했어요. 규칙 작성자가 허용할 의도가 없었던 vendor/some-package/src/와 그 밖의 모든 중첩된 src/도 포함됐어요. 이제 이러한 규칙은 <cwd>/dir에만 고정돼요. 실제로 모든 깊이에서 일치시키려면 **/dir/**로 선언하세요.⁷⁴ 거부 및 질문 규칙은 의도적으로 기존의 모든 깊이 일치 방식을 유지해요. 이러한 비대칭은 올바른 안전 실패 설계예요. 허용 규칙이 너무 좁게 일치하면 안전하게 실패해서 질문이 표시되지만, 거부 규칙이 너무 좁게 일치하면 열린 상태로 실패해서 차단해야 할 경로가 빠져나가요. 그래서 허용 규칙은 더 엄격해졌고 거부 규칙은 넓게 유지됐어요. 설정에서 단일 세그먼트 허용 패턴으로 중첩 경로까지 다루고 있었다면 v2.1.214부터는 더 이상 그렇게 작동하지 않아요. 이는 수정 사항이 의도대로 작동하는 것이지만, 허용 목록을 검토해 실제로 원하는 범위를 다시 선언할 필요가 있어요.

Auto Mode의 파괴적 명령 보호 장치(2026년 6월)

Claude Code v2.1.183에서는 작업을 조용히 잃게 하거나 환경을 제거하는 작업에 대해 자동 모드의 피해 범위를 줄였어요. 이제 세션에서 사용자가 명시적으로 요청하지 않는 한 자동 모드는 파괴적인 git 작업(git reset --hard, git checkout -- ., git clean -fd, git stash drop), 이번 세션에서 에이전트가 만들지 않은 커밋에 대한 git commit --amend, 특정 스택을 지정하지 않은 인프라 제거 작업(terraform destroy, pulumi destroy, cdk destroy)을 강제로 차단해요.⁶⁵ 아키텍처 측면에서 이는 위에서 다룬 생성 검증과 매개변수 수준 규칙을 보완해요. 어떤 도구인지 또는 어떻게 생성됐는지를 통제하는 대신, 의도를 기준으로 소수의 구체적인 되돌릴 수 없는 명령을 통제해요. 에이전트는 여전히 명령을 실행할 수 있지만 자체 판단이 아닌 명시적 지시가 있어야 해요. 자율형 harness에서도 같은 원칙을 자체 PreToolUse hooks에 적용하세요. 상태를 파괴하는 명령에는 명시적인 운영자 신호가 있을 때만 해제되는 기본 거부 규칙이 필요해요.

2026년 7월: 자동 모드가 기업 환경에 도입되고, 하나의 확인 요청은 건너뛸 수 없게 됐어요. 자동 모드는 v2.1.207에서 Amazon Bedrock, Google Vertex AI, Microsoft Foundry에 정식 출시됐으며 기업용 비활성화 설정으로 disableAutoMode가 제공돼요. 이제 분류기를 확인 계층으로 사용하는 보안 태세를 모든 공식 기업 플랫폼에서 사용할 수 있으며, 자동 모드를 끄는 것은 플랫폼의 한계가 아니라 명시적인 거버넌스 결정이에요.⁶⁸ 이어서 v2.1.208에서는 치명적 제거에 대한 보호를 절대적인 규칙으로 만들었어요. 이제 치명적 제거에 대한 확인 요청은 --dangerously-skip-permissions와 자동 모드를 모두 무시하고 표시돼요.⁶⁸ 이는 주목할 만한 선례예요. 명시적인 우회 플래그를 포함해 어떠한 권한 태세로도 건너뛸 수 없는 Claude Code 최초의 확인 절차예요. --dangerously-skip-permissions가 말 그대로 확인 요청을 전혀 표시하지 않는다고 가정한 자율형 harness 설계에서는 이 한 가지 예외를 고려해야 해요. 무인 반복 작업이 가장 복구하기 어려운 피해를 일으킬 수 있는 바로 그 지점에서 작동해요.

조작 방지 보호 장치(2026년 7월)

v2.1.203부터 v2.1.206까지의 릴리스에서는 에이전트가 자체 감사 기록을 조작할 수 있었던 2가지 경로를 차단했어요.⁶⁸ 첫째, 이제 자동 모드 규칙이 세션 기록 파일 변조를 차단해요. 더 이상 세션 자체의 도구 호출로 세션 기록을 다시 작성할 수 없어요. 둘째, 백그라운드 작업 알림에는 작업이 실행되는 동안 사람의 입력이 없었다는 사실이 명시돼요. 두 번째 변경은 미묘한 실패를 겨냥해요. 이전에는 백그라운드 작업을 요약하는 모델이 실제로는 없었던 세션 기록상의 “승인”을 제시하거나 꾸며낼 수 있었으며, 알림에도 이를 반박하는 내용이 없었어요. 이제 알림 자체가 반대 증거가 돼요.

이 아키텍처의 교훈은 Evidence Gate에도 적용할 수 있어요. 세션 기록, 알림, 로그는 감사 표면이며 감사 대상이 이를 수정할 수 없어야 해요. 이제 플랫폼은 자체 세션 기록에 이 원칙을 강제해요. harness에도 같은 규칙을 적용하세요. 증거 보고서, 테스트 출력, deliberation 기록은 모델이 쓸 수 없는 경로에 보관해야 해요.

프롬프트 인젝션 방어

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는 프롬프트가 침해되어도 변경할 수 없어요.

플랫폼의 최저선은 2026년 7월에 높아졌어요. Claude Code v2.1.210에서는 subagent가 읽은 콘텐츠를 통해 전달되는 간접 프롬프트 인젝션에 대응하도록 Agent tool을 강화했어요. 오염된 파일, 웹 페이지 또는 subagent가 가져온 도구 결과가 위임 표면 자체를 조종하기 더 어려워졌어요.⁶⁹ v2.1.211에서는 사람과 연결되는 고리도 강화했어요. 이제 권한 미리 보기에서 양방향 재정의, 폭이 0인 문자, 모양이 비슷한 유니코드 문자를 무력화하므로 승인 대화 상자에는 무해한 것처럼 보이지만 실제로는 다른 작업을 실행하는 명령을 만들 수 없어요.⁶⁹ 두 번째 수정은 특히 사람이 시간 압박 속에서 렌더링된 미리 보기를 승인하는 harness에서 중요해요. 표시 화면도 인젝션 공격 표면이었기 때문이에요. 어느 변경도 위의 hook 수준 방어를 대체하지 않으며 그 아래의 최저선을 높여 줘요.

에이전트 로그와 보호 장치도 보안 표면이에요

2026년 5월의 보안 권고 2건은 하나의 패턴을 다시 보여 줘요. 에이전트 인프라는 민감한 콘텐츠와 실행 가능한 정책이 유출되거나 경계를 벗어날 수 있는 새로운 지점을 만들어요. GitHub 보안 권고 GHSA-f3jg-756w-gm35는 기본 로깅 동작에서 민감한 도구 페이로드 콘텐츠가 로컬 SQLite 로그에 남을 수 있었던 Gryph Agents 페이로드 필터 문제를 다뤄요.⁴⁵ OSV GHSA-wxxx-gvqv-xp7p는 관리자가 보호하는 프록시 엔드포인트에서 발생한 LiteLLM 사용자 지정 코드 보호 장치의 샌드박스 탈출 문제를 다뤄요.⁴⁶

프로덕션 환경에서는 에이전트 세션 기록, 도구 페이로드, SQLite 로그, 보호 장치 실행을 민감한 인프라로 취급하세요. 저장하기 전에 민감한 정보를 가리고 보존 기간을 제한하며, 사용자 지정 보호 장치 코드는 샌드박스에서 실행하고 검토할 수 있게 유지하세요. 프롬프트 수준의 “비밀 정보를 기록하지 말라”는 규칙만으로는 부족해요. 로깅과 보호 장치 경로에는 결정적 테스트가 필요해요.

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 tool을 통해 subagent를 생성하면 subagent가 사용하는 모든 도구에서 PreToolUse와 PostToolUse hooks가 실행돼요. 재귀적 hook 강제 적용이 없다면 subagent가 안전 게이트를 우회할 수 있어요. SubagentStop 이벤트를 사용하면 subagent가 작업을 완료할 때 정리나 검증을 실행할 수 있어요.

이는 선택 사항이 아니에요. 보안 hooks 없이 subagent를 생성할 수 있는 에이전트는 기본 대화를 감시하는 게이트가 아무것도 하지 않는 동안 main 브랜치에 강제 푸시하거나, 자격 증명 파일을 읽거나, 파괴적 명령을 실행할 수 있어요.

아키텍처로서의 비용

비용은 운영 단계에서 나중에 고려할 문제가 아니라 아키텍처 결정이에요.² 다음과 같은 3가지 수준이 있어요.

토큰 수준. 시스템 프롬프트를 압축하세요. 튜토리얼 코드 예시는 제거하세요. 모델은 APIs를 알고 있어요. 여러 파일에 중복된 규칙은 합치고 설명은 제약 조건으로 바꾸세요. “민감한 경로와 일치하는 도구 호출을 거부한다”는 제약 조건은 자격 증명을 읽으면 안 되는 이유를 15줄로 설명하는 것과 같은 역할을 해요.

에이전트 수준. 긴 대화를 이어가는 대신 새 에이전트를 생성하세요. 자율 실행의 각 스토리는 깨끗한 컨텍스트를 가진 새 에이전트에 할당해요. 각 에이전트가 새로 시작하므로 컨텍스트가 계속 부풀지 않아요. 메모리 대신 브리핑을 사용하세요. 모델은 누적된 30단계의 컨텍스트를 탐색하는 것보다 명확한 브리핑을 더 잘 실행해요.

아키텍처 수준. 작업이 상태 비저장이라면 MCP보다 CLI를 먼저 고려하세요. 일회성 평가를 위한 claude --print 호출은 비용이 적게 들고 연결 오버헤드도 없어요. 도구에 지속적인 상태나 스트리밍이 필요할 때는 MCP가 적합해요.

의사결정 프레임워크

각 메커니즘을 언제 사용해야 하는지:

Skills vs Hooks vs Subagents

FAQ

hooks는 몇 개부터 너무 많은가요?

제약은 개수가 아니라 성능입니다. 각 hook은 동기적으로 실행되므로, 전체 hook 실행 시간이 매칭된 모든 tool call에 더해집니다. 각 hook이 200ms 안에 완료된다면 user-level과 project-level 설정을 합쳐 95개의 hook도 눈에 띄는 지연 없이 실행됩니다. 주의해야 할 기준은 PostToolUse hook이 모든 파일 편집에 500ms 이상을 추가해 세션이 둔하게 느껴지는 경우입니다. 배포하기 전에 time으로 hooks를 프로파일링하세요.¹⁴

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

예. PreToolUse hooks는 code 2로 종료해 어떤 tool action이든 차단할 수 있습니다. Claude Code은 대기 중인 action을 취소하고 hook의 stderr 출력을 model에 보여줍니다. Claude은 거부 사유를 확인하고 더 안전한 대안을 제안합니다. Exit 1은 차단하지 않는 경고이며, action은 계속 진행됩니다.³

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

Hook 설정은 project-level hooks의 경우 .claude/settings.json에 둡니다. 이 파일은 repository에 commit되어 팀과 공유됩니다. user-level hooks의 경우 ~/.claude/settings.json에 둡니다. 이 설정은 개인용이며 모든 프로젝트에 적용됩니다. 둘 다 존재하면 project-level hooks가 우선합니다. 작업 디렉터리 문제를 피하려면 script 파일에는 절대 경로를 사용하세요.¹⁴

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

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

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

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

deliberation의 latency 영향은 어느 정도인가요?

3-agent deliberation은 wall-clock time으로 30-60초를 추가합니다(agents는 Agent tool을 통해 순차 실행됩니다). 10-agent deliberation은 2-4분을 추가합니다. consensus와 pride check hooks는 각각 200ms 안에 실행됩니다. 주요 bottleneck은 orchestration overhead가 아니라 agent마다 발생하는 LLM inference time입니다.⁷

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

각 섹션은 50줄 미만, 전체 파일은 150줄 미만으로 유지하세요. 긴 파일은 컨텍스트 창에서 잘릴 수 있으므로 가장 중요한 지침을 앞에 두세요. style preferences보다 commands와 closure definitions를 먼저 배치하세요.²¹

이 방식은 Claude Code이 아닌 다른 tools에서도 작동하나요?

아키텍처 원칙(hooks는 deterministic gates, skills는 domain expertise, subagents는 isolated contexts, filesystem은 memory)은 어떤 agentic system에도 개념적으로 적용됩니다. 구체적인 구현은 Claude Code의 lifecycle events, matcher patterns, Agent tool을 사용합니다. AGENTS.md는 같은 패턴을 Codex, Cursor, Copilot, Amp, Windsurf로 가져갑니다.²¹ 구현 세부 사항이 tool별로 다르더라도 harness pattern 자체는 tool-agnostic입니다.

빠른 참조 카드

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

주요 명령

파일 위치

변경 이력

참고 문헌