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

TL;DR: Claude Code은 파일에 접근할 수 있는 채팅 상자가 아닙니다. 모델이 건너뛸 수 없는 셸 스크립트를 연결할 수 있는, 문서화된 31개의 라이프사이클 이벤트를 갖춘 프로그래밍 가능한 런타임입니다. hooks를 dispatcher로 쌓고, dispatcher를 skills로, skills를 agents로, agents를 workflows로 쌓으면 제약을 강제하고, 작업을 위임하며, 세션 간에 memory를 유지하고, 멀티 에이전트 숙고를 조율하는 자율 개발 harness가 만들어집니다. Claude Code의 동적 workflows(v2.1.154+)는 결정론적인 멀티 에이전트 조율을 퍼스트파티 기본 기능으로 만들었습니다. /workflows를 통해 수십에서 수백 개의 백그라운드 agents를 운용할 수 있습니다. 또한 플랫폼은 이제 기본적으로 subagents를 백그라운드에서 실행하고(동시 20개, 깊이 3 중첩), 세션들이 동료처럼 서로 메시지를 주고받게 하며(v2.1.224), 자체 호스팅 runner에서 클라우드 세션을 실행합니다. 정확성은 여전히 Hooks와 evidence gates가 책임집니다.⁵²⁵³⁸⁷ 이 가이드는 단일 hook부터 10-agent 합의 시스템까지 이 스택의 모든 계층을 다룹니다. 프레임워크는 전혀 필요하지 않습니다. 모두 bash와 JSON로 구성됩니다.

Andrej Karpathy는 LLM agent 주변에서 자라나는 것을 가리키는 용어를 만들었습니다. 바로 claws입니다. agent가 컨텍스트 윈도우 밖의 세계를 붙잡을 수 있게 하는 hooks, scripts, orchestration을 뜻합니다.¹ 대부분의 개발자는 AI 코딩 agents를 대화형 보조 도구로 여깁니다. 프롬프트를 입력하고, 파일을 수정하는 모습을 지켜본 뒤 다음 작업으로 넘어갑니다. 이런 관점에서는 생산성이 개인적으로 감독할 수 있는 범위를 넘지 못합니다.

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

이 차이는 중요합니다. 인프라는 복리처럼 누적되기 때문입니다. bash commands에서 credentials를 차단하는 hook 하나는 모든 세션, 모든 agent, 모든 자율 실행을 보호합니다. 평가 기준을 인코딩한 skill은 여러분이 호출하든 agent가 호출하든 일관되게 적용됩니다. 보안을 위해 코드를 검토하는 agent는 여러분이 지켜보고 있든 아니든 동일한 검사를 수행합니다.²

핵심 요점

• Hooks는 실행을 보장하지만, prompts는 그렇지 않습니다. 모델의 동작과 관계없이 매번 반드시 실행되어야 하는 linting, formatting, security checks에는 hooks를 사용하세요. 종료 코드 2는 작업을 차단합니다. 종료 코드 1은 경고만 표시합니다.³
• Skills는 자동으로 활성화되는 도메인 전문성을 인코딩합니다. description 필드가 모든 것을 결정합니다. Claude은 keyword matching이 아니라 LLM reasoning을 사용해 skill 적용 여부를 판단합니다.⁴
• Subagents는 컨텍스트 비대화를 막습니다. 탐색과 분석을 위한 격리된 컨텍스트 윈도우가 메인 세션을 가볍게 유지합니다. 독립적인 subagents는 병렬로 실행하고, workers 간에 지속적인 조율이 필요할 때는 agent teams를 사용하세요.⁵
• Memory는 파일 시스템에 있습니다. 파일은 컨텍스트 윈도우를 넘어 유지됩니다. CLAUDE.md, MEMORY.md, rules directories, handoff documents가 구조화된 외부 memory 시스템을 구성합니다.⁶
• 멀티 에이전트 숙고는 사각지대를 포착합니다. 단일 agents는 자기 가정에 이의를 제기할 수 없습니다. 평가 우선순위가 서로 다른 두 독립 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        │
└──────────────────────────────────────────────────────────────┘

Instruction Layer: CLAUDE.md 파일과 rules 디렉터리는 에이전트가 프로젝트에 관해 알아야 할 내용을 정의합니다. 세션 시작 시와 모든 compaction 이후에 자동으로 로드됩니다. 이는 에이전트의 장기 아키텍처 메모리입니다.

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

Orchestration Layer: multi-agent 패턴은 리서치, 검토, 숙의를 위해 독립적인 에이전트를 조율합니다. spawn 예산은 제어되지 않는 재귀를 방지합니다. 합의 검증은 품질을 보장합니다.

핵심은 대부분의 사용자가 Core Layer에서만 작업하며 컨텍스트가 비대해지고 비용이 증가하는 모습을 지켜본다는 점입니다. 고급 사용자는 Instruction 및 Extension Layer를 구성한 다음, Core Layer는 오케스트레이션과 최종 결정에만 사용합니다.²

Managed harness와 self-hosted harness 비교 (2026년 4월)

2026년 초까지는 “직접 harness를 구축하는” 방식이 유일한 현실적 선택지였습니다. 2026년 4월에 상황이 바뀌었습니다. Anthropic는 4월 8일 공개 베타로 Claude Managed Agents를 출시했습니다. harness loop + tool execution + sandbox container + state persistence를 REST API로 제공하며, 표준 토큰 비용에 세션 시간당 $0.08이 추가로 청구됩니다. OpenAI의 Agents SDK 업데이트(4월 16일)는 동일한 구분을 공식화했습니다. harness와 compute를 별도 계층으로 분리하고, 네이티브 sandbox provider(Blaxel, Cloudflare, Daytona, E2B, Modal, Runloop, Vercel) 및 컨테이너 손실 이후에도 유지되는 snapshot/rehydrate를 제공합니다.²³²⁴

OpenAI 측의 더 심화된 SDK 표면은 openai-agents Python v0.14.0에서 제공되었습니다(2026년 4월 15일 출시, 4월 16일 발표). 여기에는 default_manifest, sandbox instructions, capabilities를 갖춘 Agent의 SandboxAgent subclass, 새 workspace 계약(files, dirs, local files, Git repos, env, users, mounts)을 설명하는 Manifest, 그리고 sandbox client, live session injection, manifest overrides, snapshots, materialization concurrency limits를 실행별로 연결하는 SandboxRunConfig가 포함됩니다. 내장 capabilities는 shell access, filesystem editing, image inspection, skills, sandbox memory, compaction을 지원합니다. Sandbox memory는 실행 간 추출된 교훈을 유지하고 점진적으로 공개합니다. workspaces는 local files, Git repo entries, remote mounts(S3, R2, GCS, Azure Blob, S3 Files)를 지원하며 snapshots는 provider 간 이식 가능합니다. 백엔드는 UnixLocalSandboxClient, DockerSandboxClient, 그리고 optional extras를 통한 Blaxel, Cloudflare, Daytona, E2B, Modal, Runloop, Vercel용 hosted clients입니다.²⁴

Python 프로젝트에서 Claude Code runtime을 라이브러리로 임베드하려는 경우, 즉 “claude를 shell out”하는 방식과 Managed Agents에 REST API를 사용하는 방식 사이에는 claude-agent-sdk-python이라는 세 번째 선택지가 있습니다. 4월 28~29일 릴리스 시리즈(v0.1.69 → v0.1.71)는 번들된 CLI를 v2.1.123으로 올리고, mcp dependency의 최소 버전을 >=1.19.0으로 높였으며, SandboxNetworkConfig를 TypeScript SDK의 schema와 동일하게 맞췄습니다(allowedDomains, deniedDomains, allowManagedDomainsOnly, allowMachLookup). 이전 버전은 in-process MCP tools의 CallToolResult 반환을 조용히 누락해 모델에 validation-error blob만 남겼습니다.³⁰ 2026-08-12 기준으로 이 패키지는 PyPI에서 v0.2.137, TypeScript SDK는 v0.3.229입니다(둘 다 live registries에서 검증됨). 0.2.x 라인은 여기에서 설명한 0.1.x 표면을 점진적으로 확장한 버전입니다. 아래의 include_hook_events, skills, sandbox-config 옵션은 여전히 유효하며, 최근 릴리스는 subprocess-cleanup 및 NDJSON-stream 안정성에 집중했습니다.⁹⁰⁸⁶

harness에 voice 또는 realtime layer가 포함된다면, openai-agents-python v0.17.0(2026년 5월 8일)은 RealtimeAgent의 기본 모델을 gpt-realtime-2로 변경했습니다.⁴¹ 기존 realtime sessions도 자동으로 새 기본값을 적용합니다. 평가를 위해 이전 동작을 유지해야 한다면 이전 모델을 명시적으로 고정하세요.

2026년 7월에는 managed 진영에 OpenAI 측 multi-agent 기능도 추가되었습니다. openai-agents-python v0.18.2(7월 11일)와 openai-agents-js v0.13.2(7월 10일)는 베타로 hosted multi-agent support를 추가했습니다. 이는 여러 에이전트의 오케스트레이션을 OpenAI가 hosted service로 관리하는 기능이며, Multi-Agent Orchestration 섹션에서 다룬 Anthropic의 Managed Multiagent Orchestration 공개 베타에 직접 대응합니다.⁷³ 이제 두 vendor 모두 단일 에이전트에 대해 아래 표가 설명하는 것과 동일한 선택지를 multi-agent 계층에서도 제공합니다. vendor가 delegation loop를 실행하는 대신 hook surface는 포기해야 합니다.

이제 아키텍처 선택지는 분명합니다.

선택 기준: self-hosted는 이미 인프라 역량을 갖췄거나, 직접 제어하는 skills/hooks가 필요하거나, 특정 workflow를 깊이 최적화하려는 팀에 여전히 적합합니다. Managed는 전담 platform engineer가 없는 팀, customization보다 time-to-value가 더 중요한 경우, 또는 persistence layer를 직접 구축하지 않고 laptop을 닫아도 agent runs가 안정적으로 유지되어야 하는 경우에 적합합니다. 두 방식은 함께 사용할 수 있습니다. self-hosted harness에서 REST API를 통해 특정 장기 작업을 Managed Agents에 delegates할 수 있습니다.

디스크에 저장된 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/ 트리는 모든 프로젝트에 적용되는 개인 인프라입니다. 각 repository의 .claude/ 트리는 프로젝트별로 적용되며 git을 통해 공유됩니다. 두 트리를 합치면 완전한 harness가 됩니다.

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는 언어 모델 추론을 사용해 관련된 skill이 있는지 판단합니다. Claude Code 소스를 독립적으로 분석한 결과도 이 메커니즘을 확인합니다. skill descriptions는 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)입니다.

자동 활성화는 법칙이 아니라 조절 장치라는 점에 유의하세요. v2.1.215부터 Claude는 번들된 /verify 및 /code-review skills를 더 이상 자체 호출하지 않습니다. 이들은 명시적으로 호출할 때만 실행되며, 요청 없이 실행할 때 얻는 것보다 비용이 더 컸던 무거운 검토 skills의 description 기반 활성화를 의도적으로 되돌린 것입니다.⁷⁴

Context 예산

모든 skill descriptions는 컨텍스트 창의 1%에 맞춰 동적으로 조정되는 context 예산을 공유하며, 대체 값은 8,000자입니다.⁴ skills가 많다면 각 description을 간결하게 유지하고 핵심 사용 사례를 앞에 두세요. SLASH_COMMAND_TOOL_CHAR_BUDGET 환경 변수를 통해 예산을 재정의할 수 있지만,¹¹ 더 나은 해결책은 더 짧고 정확한 descriptions입니다. 세션 중 /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 공유

Project skills(저장소 루트의 .claude/skills/)는 version control을 통해 공유됩니다.⁴

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

단일 목적 skills를 넘어, 디렉터리 구조는 정리된 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가 자동으로 활용하는 knowledge base를 구성합니다. 주니어 개발자는 요청하지 않아도 시니어 수준의 가이드를 받습니다.

Hooks와 결합되는 Skills

Skills는 skill이 실행되는 동안에만 활성화되는 자체 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'"
---

Philosophy skills는 SessionStart hooks를 통해 자동 활성화되어, 명시적 호출 없이 모든 세션에 품질 제약을 주입합니다. skill 자체는 지식입니다. hook은 강제입니다. 둘이 함께 policy layer를 형성합니다.

흔한 Skill 실수

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

예산을 두고 경쟁하는 skills가 너무 많음. skills가 많을수록 1% context 예산을 두고 경쟁하는 descriptions도 많아집니다. skills가 활성화되지 않는다면 /context에서 제외된 항목을 확인하세요. 모호한 skills를 많이 두기보다 잘 설명된 skills를 적게 두는 편이 낫습니다.

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

SDK Skill Surface (2026년 5월 8일)

claude-agent-sdk-python v0.1.77+를 사용하는 self-hosted harnesses는 legacy "Skill" 값을 allowed_tools에 넣는 대신 ClaudeAgentOptions의 skills 옵션으로 사용 가능한 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합니다.⁵⁸ 이로써 이전에는 서로 다른 위치에 있던 두 프로젝트 tooling 형태, 즉 저장소에 바로 커밋하는 bare skill과 skill, hooks, MCP server를 묶지만 설치하려면 marketplace가 필요했던 plugin 사이의 간극이 사라졌습니다. harness 설계에 미치는 실질적 효과는 다음과 같습니다. 프로젝트 범위 tooling을 배포하기 위해 더 이상 registry를 거칠 필요가 없습니다. 작성하고 커밋하면 팀원은 git pull로 동일한 surface를 받습니다. Plugins는 여전히 bundled-installable 사용 사례(hooks + skills + MCP servers + agents를 하나의 ZIP으로 묶는 경우)를 담당합니다. 달라진 점은 프로젝트가 자체 트리에서 하나를 로드하기 위해 marketplace를 구축할 필요가 없어졌다는 것입니다. 이러한 통합은 이제 cross-vendor 기반도 갖추고 있습니다. Agent Plugins 1.0.0(2026년 8월 6일 공개)은 plugin.json manifest, SKILL.md 폴더로 이루어진 skills/ 디렉터리, 선택적 mcp.json이라는 동일한 package shape를 “AI agents를 위한 portable package format”으로 표준화했으며, 출시 시점에 VS Code, Cursor, GitHub Copilot, ChatGPT & Codex, Kiro가 채택했습니다. 이는 Agent Skills와 MCP를 대체하는 것이 아니라 그 위에 놓이는 packaging layer입니다. Agent Skills spec의 작성자인 Anthropic는 아직 coalition에 포함되지 않았다는 점에 유의하세요. 따라서 Claude-Code 외부로의 portability는 공식적인 양방향 계약이 아니라 format-level compatibility로 다뤄야 합니다.⁸⁹

거버넌스로서 번들된 Surface 숨기기 (2026년 6월 8일)

Skills는 capability이고, capability는 attack surface입니다. Claude Code v2.1.169는 disableBundledSkills 설정과 이에 대응하는 CLAUDE_CODE_DISABLE_BUNDLED_SKILLS 환경 변수를 추가해, bundled skills, workflows, built-in slash commands를 모델에서 완전히 숨깁니다.⁶⁰ hardened 또는 regulated harness에서는 의도적인 attack-surface 축소입니다. 특정 project 및 personal skills 집합을 감사하고 승인한 운영자는 Anthropic가 기본 제공하는 모든 것을 억제할 수 있으므로, 모델은 운영자가 검증한 surface만을 대상으로 추론하게 됩니다. 이를 tool allowlist와 같은 방식으로 다루세요. 기본값은 폭넓은 capability이며, 기본값을 끄는 일은 편의 토글이 아니라 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도 working directory와 가장 가까운 위치를 기준으로 resolve하도록 변경되었습니다. agent, workflow 또는 output-style 이름이 중첩된 .claude/ 디렉터리 간에 충돌하면 working directory에 가장 가까운 항목이 우선하며, project-scope workflow 저장은 항상 루트가 아니라 가장 가까운 기존 .claude/workflows/를 대상으로 합니다.⁶³ monorepo 또는 repo-of-repos에서는 하나의 평평한 global surface와 컨텍스트에 맞춰 활성화되는 package별 tooling의 차이를 만듭니다. services/api/.claude/skills/에는 해당 트리에서 작업할 때만 표시되는 API-specific skills를 둘 수 있고, 이름이 같은 services/web/ skill과 충돌하지 않습니다.

Hook 아키텍처

Hooks는 Claude Code lifecycle events에 의해 트리거되는 shell 명령어입니다.³ 이들은 모델이 해석하는 프롬프트가 아니라 일반 스크립트로서 LLM 외부에서 실행됩니다. 모델이 rm -rf /를 실행하려 한다고요? 10줄짜리 bash 스크립트가 명령어를 blocklist와 대조해 shell이 이를 처리하기도 전에 거부합니다. 모델의 의사와 관계없이 hook은 실행됩니다.

사용 가능한 이벤트

이 가이드 업데이트 기준으로 Claude Code는 8개 범주에 걸쳐 문서화된 lifecycle events 31개를 제공합니다. 릴리스에 따라 이벤트 목록이 늘어나므로 reference docs를 기준으로 삼고, production hooks를 연결하기 전에 최신 전체 표는 cheat sheet에서 확인하세요.¹³

DirectoryAdded (v2.1.219)는 세션 중간 workspace 공백을 메웁니다. 이벤트 목록은 MessageDisplay가 v2.1.152에 추가된 이후 안정적으로 유지됐으며, DirectoryAdded는 그 이후 처음 추가된 lifecycle event입니다. 이는 /add-dir 또는 SDK의 register_repo_root control request가 세션 도중 새 working directory를 등록한 뒤 실행됩니다.⁸⁴ 이 이벤트가 메우는 공백은 실제로 존재합니다. 지금까지 harness는 SessionStart에서 workspace를 철저히 검증한 뒤에도, 두 번째 repository가 어떤 hook도 실행하지 않은 채 추가되는 상황을 지켜봐야 했습니다. startup 시 workspace에 대해 적용하는 모든 검증, 즉 trust checks, secret scans, tree에서 파생한 path-scoping rules, per-repo policy loading은 여기서 다시 실행해야 합니다. 세션의 directory set은 더 이상 시작 시점에 고정되지 않기 때문입니다. 이 이벤트는 차단이 아닌 정보 제공용이므로 gate가 아니라 state를 다시 도출하고 provenance를 기록하는 trigger로 다루세요. 절대로 추가되면 안 되는 directory가 있다면 hook에서 거부하려 하지 말고 settings에서 이를 금지하세요. SDK 측도 같은 릴리스에 반영됐습니다. TypeScript v0.3.219는 control-protocol lifecycle events에 DirectoryAdded를 추가하므로, SDK-hosted harnesses도 CLI 기반 harnesses와 동일하게 이를 처리합니다.⁸⁵

Exit Code 의미

Exit codes는 hooks가 작업을 차단하는지 결정합니다.³

Hook 구성

Hooks는 settings 파일에 위치합니다. 공유 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 필드는 이벤트별 값을 필터링합니다. tool events의 경우 Bash, Edit, Write, Read, Glob, Grep, MCP tool names인 mcp__server__tool, 또는 모든 tools를 의미하는 * 같은 tool_name 값을 매칭합니다. 단순한 이름과 |로 구분한 목록은 정확히 일치하며, 그 외 문자를 포함한 값은 JavaScript regular expressions입니다. 일부 이벤트는 matchers를 지원하지 않으며 구성되면 항상 실행됩니다.¹³ Claude Code v2.1.195부터 hyphenated identifiers (code-reviewer, mcp__brave-search)를 포함한 matchers는 실수로 substring-matching하지 않고 정확히 일치합니다. 이제 특정 agent 또는 server를 대상으로 한 hook이 문자열을 단순히 포함하는 모든 이름에서 실행되지 않습니다. hyphenated MCP server의 모든 tools를 대상으로 하려면 명시적 패턴 mcp__brave-search__.*를 작성하세요.⁶⁶ v2.1.214는 path patterns에도 같은 원칙을 적용했습니다. 단일 세그먼트 dir/** pattern을 사용하는 hook if: condition은 이제 tree 안의 모든 dir이 아니라 <cwd>/dir만 매칭합니다. 실제로 모든 깊이를 의미한다면 **/dir/**를 작성하세요.⁷⁴ v2.1.195 변경과 마찬가지로 이 수정은 의도치 않은 광범위한 매칭 대신 명시된 의도를 택합니다. 이전의 모든 깊이 동작에 조용히 의존하던 hook conditions를 점검하세요.

Hook Input/Output Protocol

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는 tool input을 수정하거나, context를 주입하거나, permission decisions를 내리도록 JSON을 출력할 수 있습니다. hookSpecificOutput wrapper를 사용하세요. 이전의 최상위 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는 위험한 작업이 실행되기 전에 막습니다. Bash의 PreToolUse hooks는 명령어를 검사하고 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는 의사결정 지점에서 state를 검증합니다. git commit 명령어의 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 명령어 외 Hook 유형

Claude Code는 5가지 hook types를 지원합니다.¹³ Command hooks (type: "command")는 셸 스크립트를 실행해요. 빠르고 결정적이며 토큰 비용이 들지 않아요.

MCP tool hooks (type: "mcp_tool")는 이미 연결된 MCP 서버에서 도구를 호출해요. 검증 로직이 이미 MCP 경계 뒤에 있고 별도의 셸 스크립트가 필요하지 않을 때 사용하세요.

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

Agent hooks (type: "agent")는 다중 턴 검증을 위해 도구 액세스(Read, Grep, Glob)가 있는 subagent를 생성해요. 실험적 기능이므로 프로덕션 gate에는 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을 다시 받아요. webhook, 외부 알림 서비스 또는 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
}

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

독립 Hook 대신 Dispatcher 사용하기

동일한 이벤트에서 7개의 hook이 모두 실행되고 각각 stdin을 독립적으로 읽으면 race condition이 생겨요. 2개의 hook이 동일한 JSON state 파일에 동시에 쓰면 JSON이 잘려요. 해당 파일을 파싱하는 모든 downstream hook이 실패해요.²

해결책은 캐시된 stdin에서 hook을 순차적으로 실행하는 이벤트별 dispatcher 하나예요.

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

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

Hook 디버깅

조용히 실패하는 hook을 디버깅하는 5가지 방법이에요.¹⁴

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

SDK 측 Hook 이벤트 스트리밍

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

이벤트 스트림 패턴은 harness가 이미 Python에 있고 model output과 동일한 제어 흐름에서 hook 신호를 사용하려는 경우에 적합해요. 여러 tool을 조합하거나, Claude Code와 Codex 전반에서 hooks를 공유하거나, 차단을 위한 exit-code semantics가 필요한 harness에는 셸 스크립트 hook 계약(exit codes, stdin JSON, dispatchers)이 여전히 적합해요.

TypeScript SDK의 2026년 7월 시리즈(v0.3.205–v0.3.208)는 스트리밍 프로토콜 자체를 더욱 계약적으로 만들었어요.⁷⁰ 이제 interrupt는 typed receipts를 반환해요. interrupt는 still_queued UUID를 통해 어떤 큐 메시지가 아직 대기 중인지 확인하고, 세션은 system/init에서 interrupt_receipt_v1 capability를 알리므로 coordinator는 “interrupt가 도착함”과 “이미 전송 중인 메시지를 지나쳐 interrupt가 경쟁함”을 구분할 수 있어요. command_lifecycle frames는 메시지별로 queued/started/completed/cancelled/discarded를 보고해요. transcript 추론 없이 “내가 보낸 메시지에 무슨 일이 일어났나”에 답하는 최초의 first-party 방법이에요. 더 작은 표면도 추가됐어요. subagent 완료 payload를 위한 AgentToolCompletedOutput type, 그리고 이제 canUseTool callbacks는 updatedInput field 없이도 {behavior: 'allow'}를 반환할 수 있어요.

이 시리즈의 한 줄은 기능이 아니라 보안 하한선이에요. v0.3.208은 pending hook 중에 caller abort가 도착했을 때 hook success로 변환되는 문제를 수정했어요. 이 문제로 인해 PreToolUse hook이 gate로 설정된 tool이 caller가 abort한 후에도 실행될 수 있었어요.⁷⁰ harness가 SDK 측 hooks를 permission gate로 사용하고 abort에 의존해 in-flight 작업을 취소한다면 v0.3.208을 최소 버전으로 취급하세요. 그보다 낮은 버전에서는 “aborted”가 안정적으로 “blocked”를 의미하지 않았어요. Python v0.2.127(2026년 7월 24일)은 한 달 안에 발생한 같은 형태의 두 번째 bypass예요. query()가 background subagents가 아직 실행 중인 상태에서 첫 번째 result frame에 stdin을 닫았고, 그 결과 subagent의 SDK-MCP tool calls는 "Stream closed"로 실패하면서 동시에 PreToolUse hooks를 완전히 우회했어요.⁸⁵ 이 패턴을 명명하고 주시하세요. SDK 측 hook enforcement는 lifecycle edge, 즉 abort, teardown, stream close에서 fail open돼요. hook verdict가 수집되기 전에 transport가 종료되기 때문이에요. 그리고 우회된 hook은 승인한 hook과 완전히 똑같이 보이므로 조용히 실패해요. 두 SDK 하한선을 모두 고정하고, 증명할 수 있는 enforcement로 셸-hook layer를 유지하세요.

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

Claude Code v2.1.132와 v2.1.133의 두 추가 사항은 hooks와 subprocesses가 실행 컨텍스트를 더 잘 파악할 수 있게 해줘요.³⁸³⁹

• Hook 입력의 effort.level. Hooks는 이제 tool_input, session_id와 같은 입력에 포함된 effort.level JSON field를 받아요. 동일한 값이 $CLAUDE_EFFORT env var로도 내보내지므로 Bash commands는 JSON을 파싱하지 않고 읽을 수 있어요. 이를 사용해 effort tier에 따라 hook 비용을 조절하세요. low에서는 비용이 큰 검증을 건너뛰고, xhigh 또는 max에서는 전체 security gate를 실행하세요.
• Bash subprocesses의 CLAUDE_CODE_SESSION_ID env var. Bash tool subprocesses는 이제 hooks가 보는 것과 동일한 session_id 값을 CLAUDE_CODE_SESSION_ID로 노출해요. 이로써 세션별 state를 기록하지만 이전에는 subprocess 이벤트와 hook 이벤트를 연관 지을 수 없었던 tool의 provenance gap이 해소돼요.

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

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

Claude Code v2.1.136은 auto mode에 새로운 hard-deny tier를 추가하고, 장기 실행 harness에 영향을 주던 plugin 및 MCP 문제 묶음을 수정했어요.⁴⁰ - settings.autoMode.hard_deny. 사용자 의도나 allow 예외와 관계없이 무조건 차단하는 auto mode 분류기 규칙입니다. 이는 기존 allow/deny matcher보다 상위에 위치하는, 협상 불가한 거버넌스 제어 수단입니다. 운영자가 개인 설정에서 더 넓은 범주를 승인했더라도 절대 재정의되어서는 안 되는 규칙(예: main 브랜치로의 force-push, 비밀 정보가 포함된 파일, 프로덕션 데이터베이스 접근)에 사용하세요. - autoMode.classifyAllShell (v2.1.193). 기본적으로 auto-mode 분류기는 임의 코드 실행 패턴과 일치하는 shell 명령만 검토합니다. 이 설정은 모든 Bash/PowerShell 명령을 분류기로 전달합니다. 즉, 통제된 harness를 위한 최대 범위 접근 방식입니다. 같은 릴리스에서는 transcript, toast, /permissions에 거부 사유도 표시하므로, 조용히 차단되던 동작이 감사 가능한 결정으로 바뀝니다. Codex는 v0.142.2에서 동등한 표면을 강화했습니다. 안전 분류기가 검사할 수 없는 실행 가능한 AST 영역을 포함한 PowerShell 명령은 이제 조용히 통과하는 대신 승인이 필요합니다.⁶⁶ - Hook ask가 분류기의 하한을 정합니다 (v2.1.211). hook과 auto mode 간 우선순위 문제는 이제 정리되었습니다. ask 권한 결정을 반환하는 PreToolUse hook은 최종 결과의 하한을 프롬프트로 설정하며, auto mode는 sandbox 없이 실행되는 Bash 명령에 대해 이를 다시 allow로 승격할 수 없습니다.⁶⁹ 통제된 harness에서 이는 빠져 있던 보장 계층입니다. hook의 ask는 완전 자동 권한 정책에서도 유지되는 결정론적 human-in-the-loop 중단 지점입니다. 거부가 아니라 사람이 결정해야 하는 작업에는 단순한 exit-2 차단이 아닌 ask를 사용하세요. - 분류기 모델은 세션별로 고정됩니다 (v2.1.210). auto-mode 분류기는 기본적으로 Sonnet 5를 사용하며 세션 동안 고정되므로, 세션 중간에 모델을 변경해도 권한 분류를 수행하는 모델이 더 이상 바뀌지 않습니다.⁶⁹ 분류 일관성은 거버넌스 속성입니다. 이 변경으로 조용한 드리프트 원인이 제거됩니다. - MCP 서버가 /clear 후 더 이상 사라지지 않습니다. .mcp.json, plugins, claude.ai connectors에 설정된 서버는 VS Code extension, JetBrains plugin, Agent SDK에서 /clear 후 활성 집합에서 조용히 빠지고 있었습니다. 수정은 v2.1.136에 적용되었습니다. “MCP server X went missing mid-session” 문제가 있었다면 이것이 원인이었습니다. - 동시 갱신 시 MCP OAuth refresh-token 손실. 여러 원격 MCP 서버를 사용하는 사용자는 더 이상 매일 재인증할 필요가 없습니다. 동시 갱신 쓰기가 서로를 덮어쓰고 있었습니다. - Plan mode가 이제 파일 쓰기를 올바르게 차단합니다. 일치하는 Edit(...) allow 규칙이 plan-mode 쓰기 보호를 우회하고 있었습니다. 이제 allow 규칙과 관계없이 Plan mode가 적용됩니다. - Plugin Stop 및 UserPromptSubmit hooks가 더 이상 세션 중간에 실패하지 않습니다. 캐시 정리가 실행 중인 세션에서 아직 사용 중인 plugin-version 파일을 삭제해 이 두 hook event가 특히 중단되고 있었습니다. 수정 후에는 사용 중인 버전이 고정됩니다. - plugin.json의 skills 항목. skills를 설정하면 plugin의 기본 skills/ 디렉터리가 숨겨지고 있었습니다. 이제 이 항목은 올바르게 조합되며, 파일 경로를 가리키면 조용히 실패하는 대신 명시적인 오류가 발생합니다. - CLAUDE_ENV_FILE SessionStart hook 환경 변수의 오래된 값 문제. CLAUDE_ENV_FILE을 통해 SessionStart hooks가 내보낸 변수는 /resume 또는 /clear 후 오래된 값으로 남아 있었습니다. v2.1.136에서 수정되었습니다. 이제 세션은 이 이벤트에서 env file을 다시 source합니다.

거버넌스 harness에서 운영상 흥미로운 항목은 autoMode.hard_deny(새 제어 수단)와 MCP-사라짐 수정(긴 세션을 망가뜨리던 조용한 실패)입니다. 나머지는 모두 사용 편의성 정리입니다.

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

Claude Code v2.1.139에는 프로덕션 harness에 중요한 두 가지 hook 세부 사항이 추가되었습니다. 명령 hook을 위한 args: string[] exec 형식과 PostToolUse hooks를 위한 continueOnBlock입니다.⁴²⁴⁴ hook에 동적 값이나 경로 placeholder가 필요하면 args를 우선 사용하세요. shell 없이 명령을 직접 실행하므로 quoting 및 injection 실수의 한 범주를 제거합니다.

PostToolUse hook이 거부 사유를 Claude에 다시 전달하고 흐름을 끝내는 대신 turn을 계속 진행해야 할 때는 continueOnBlock을 사용하세요. 이는 보안 우회가 아니라 운영자 경험 기능으로 다루세요. 차단 게이트는 여전히 안전하지 않은 결과를 차단해야 합니다.

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

Claude Code v2.1.140은 주로 harness 운영자를 위한 안정성 릴리스입니다. 설정 변경 시 ConfigChange hooks가 실행되지 않던 문제를 수정하고, disableAllHooks와 allowManagedHooksOnly가 설정 계층 전반에서 올바르게 조합되지 않던 예외 상황을 해결하며, hook 결과가 반환한 의도하지 않은 환경 변수가 권한 dialog에 노출되지 않도록 막습니다.⁴⁹ 이 변경은 이 섹션의 기존 거버넌스 패턴을 더 신뢰할 수 있게 만듭니다. 새로운 hook architecture가 필요한 것은 아닙니다.

Claude Code v2.1.141에는 controlling terminal 없이 desktop notification, window title, bell을 위한 hook-output terminalSequence 필드가 추가되었습니다.⁵⁰ 이를 강제가 아닌 운영자 신호로 다루세요. 보안 및 품질 게이트는 여전히 일반 차단 계약, 즉 구조화된 hook output과 안전하지 않은 작업을 방지하는 exit 동작을 통해 실패를 전달해야 합니다. 같은 릴리스에는 Agent View를 한 디렉터리로 범위 지정하는 claude agents --cwd <path>, GitHub SSH 키가 없는 환경에서 plugin 설치를 위한 CLAUDE_CODE_PLUGIN_PREFER_HTTPS, 그리고 둘 이상의 workspace를 포괄하는 workload-identity federation 규칙을 위한 ANTHROPIC_WORKSPACE_ID도 추가되었습니다.⁵⁰ 이는 team harness의 architecture 세부 사항입니다. 더 좁은 운영 뷰, 더 적은 plugin-install 가정, 명시적인 enterprise token 범위 지정입니다.

Claude Code v2.1.142는 hook semantics보다 background-session orchestration에 더 중요합니다.⁵¹ 이제 claude agents는 wrapper state에 의존하지 않고 명시적인 directory, settings, MCP, plugin, permission, model, effort flags로 background session을 dispatch할 수 있습니다. 해당 릴리스에서 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 discovery 및 plugin 제공 LSP 가시성은 패키징 모호성을 줄입니다. MCP_TOOL_TIMEOUT, 기존 background-session worktree, daemon sleep/wake 및 업그레이드 후 정리, plugin cache cleanup 관련 수정은 그렇지 않으면 orchestration bug처럼 보이는 신뢰성 공백을 해소합니다.

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

6월 초 변경 사항 4개가 harness 및 multi-agent 설계에 중요합니다.⁵⁹

Stop/SubagentStop hooks에 steering channel이 추가되었습니다. Claude Code v2.1.163부터 Stop 또는 SubagentStop hook은 hookSpecificOutput.additionalContext를 반환하여 Claude에 피드백을 전달하고 turn을 계속 진행할 수 있으며, 응답이 hook error로 표시되지 않습니다. 이전에는 Stop hook의 유일한 실질적 제어 수단이 exit-2 차단이었고, 이는 error처럼 보이며 연속 차단 상한에 포함되었습니다. 품질 게이트 harness에서는 이것이 더 깔끔한 기본 수단입니다. “완료했다고 했지만 테스트가 실패했습니다”를 감지하는 Stop hook은 이제 hard-block하는 대신 “아직 실패 중인 항목은 다음과 같으니 계속 진행하세요”를 주입할 수 있습니다. 진정한 중단 조건에는 block을 사용하고, “아직 완료되지 않았으며 이유는 다음과 같습니다”에는 additionalContext를 사용하세요.

세션 간 메시지가 더 이상 빌린 권한을 전달하지 않습니다. v2.1.166은 multi-session 사례를 강화했습니다. 다른 Claude 세션에서 SendMessage를 통해 전달된 메시지는 더 이상 원래 사용자의 권한을 함께 전달하지 않으므로, 수신 세션은 전달된 권한 요청을 거부하고 auto mode가 이를 차단합니다. orchestration에서 agents가 서로 메시지를 보낸다면, 수신 메시지를 인증된 지시가 아닌 신뢰할 수 없는 데이터로 취급하세요. 이는 security section이 tool output에 적용하는 것과 같은 원칙을 inter-agent messaging으로 확장한 것입니다. v2.1.199부터 Claude Code은 두 agent가 같은 이름을 공유해 SendMessage가 잘못 라우팅될 때도 감지하고 경고합니다. 같은 이름의 잘못된 agent에 메시지가 도달하는 것 역시 orchestration bug의 한 유형이므로, 이는 이 권한 경계의 신뢰성 측면을 보완합니다. 세션은 이제 동등한 핵심 구성 요소입니다(v2.1.224+). 세션 간 메시징은 relay 강화 단계를 넘어 완전한 기능으로 발전했습니다. SendMessage/ListAgents를 사용하면 macOS/Linux 환경의 여러 머신에서 세션을 검색하고 서로 메시지를 보낼 수 있으며, 수신 측에서는 crossSessionInbound로 수락, 보류, 거부를 제어할 수 있습니다. 또한 self-hosted runners를 사용하면 Claude Code 웹 및 모바일 세션을 사용자가 제어하는 하드웨어에서 실행할 수 있습니다. harness 아키텍처 관점에서 이는 “세션”을 주소 지정 가능한 노드로 바꿉니다. 이제 검색, 인바운드 정책, 그리고 앞서 설명한 권한 경계는 mailbox 스크립트가 아니라 플랫폼 기본 기능입니다(Claude Code 가이드에서 전체 계약을 설명합니다).⁸⁷ 이와 함께 한 가지 운영 방식도 바뀝니다. 2026년 8월 14일부터 Pro, Max, Team 요금제에서는 auto mode가 기본 권한 모드가 됩니다. Manual mode의 프롬프트를 human-in-the-loop 안전장치로 여기는 harness라면 이를 당연하게 가정하지 말고 defaultMode를 명시적으로 고정해야 합니다.⁸⁷

모델 복원력이 핵심 설정으로 자리 잡았습니다. 이제 fallbackModel 설정으로 최대 3개의 백업 모델을 연결할 수 있으며, 기본 모델이 과부하 상태이거나 사용할 수 없을 때 순서대로 시도합니다. 예기치 않은 재시도 불가능한 API 오류가 발생하면 해당 턴은 fallback에서 자동으로 한 번 재시도됩니다. 장시간 실행되는 자율 harness에서는 일시적인 기본 모델 장애가 실행 중단이 아니라 점진적인 성능 저하로 처리됩니다. 또한 claude agents --json에는 차단된 백그라운드 세션이 권한 프롬프트처럼 무엇을 기다리는지 보여 주는 waitingFor 필드가 추가되었습니다(v2.1.162). 이는 agent fleet를 폴링하는 모든 coordinator에게 유용한 관측성 개선입니다.

clean-room 거버넌스 및 문제 해결을 위한 safe mode. Claude Code v2.1.169에서는 --safe-mode 플래그와 이에 대응하는 CLAUDE_CODE_SAFE_MODE 환경 변수를 추가했습니다. 이 모드로 세션을 시작하면 CLAUDE.md, plugins, skills, hooks, MCP servers 등 모든 사용자 지정이 한꺼번에 비활성화됩니다.⁶⁰ 이는 harness의 반대편에 있는 의도적인 clean-room입니다. 모든 운영자가 결국 묻게 되는 질문, 즉 “이 동작은 모델에서 비롯된 것인가, 아니면 내가 설정한 무언가에서 비롯된 것인가?”에 답할 때 사용하세요. hook이 잘못 실행되거나, skill이 실행되지 말아야 할 때 활성화되거나, MCP server가 컨텍스트를 오염시킬 때 --safe-mode는 비교할 수 있는 알려진 빈 기준선을 제공합니다. 이는 거버넌스 기본 요소이기도 합니다. harness가 일반적으로 부여하는 지속적 권한 없이 bare model을 실행하는 방법이며, 운영자가 정의한 scaffolding의 영향을 전혀 받지 않고 결과를 재현해야 할 때 중요합니다.

모델 tier에 대한 참고 사항. Claude Code v2.1.197(2026년 6월 30일) 기준으로 Claude Sonnet 5는 새 세션의 기본 제공 모델입니다. 기본 선택지였던 Opus 4.8을 대체하며, native 1M context와 8월 31일까지 적용되는 MTok당 $2/$10 프로모션 가격을 제공합니다. 이 가이드에서는 Opus 5(claude-opus-5)를 권장 agentic 기본값으로 봅니다. 장기적이고 높은 위험도의 agent loop에서는 Opus의 추론 깊이가 비용을 정당화하므로, 특별히 다른 선택을 하지 않는 한 자율 harness를 실행할 모델입니다. Opus 5는 2026년 7월 24일 Claude Code v2.1.219에서 새로운 기본 Opus로 출시되었습니다. 1M context, 대체하는 Opus 4.8과 같은 MTok당 $5/$25 가격, 기본 속도의 약 2.5배를 제공하는 $10/$50 fast mode를 갖추고 있으며, Anthropic는 Frontier-Bench v0.1에서 Opus 4.8의 성능을 두 배 이상 앞섰고 Fable 5의 CursorBench 3.2 점수와는 절반 비용으로 0.5% 이내 차이를 기록했다고 보고합니다.⁸⁴⁹¹ 같은 가격에 더 높은 성능, 그리고 Anthropic가 “작업을 검증하고 신중하게 반복하는 능력이 훨씬 강하다”고 평가한 모델은 harness 작업에서 비용 논의가 필요 없는 드문 업그레이드입니다. 4.8에서의 마이그레이션은 ID 변경만으로 끝납니다. 비용에 민감하거나 처리량이 높은 작업에서는 속도 대비 지능 비율이 더 유리한 Sonnet 5로 낮추세요. Opus 위에는 2026년 6월 9일 출시된 Claude Fable 5(claude-fable-5)가 있습니다. Anthropic가 가장 강력한 모델로 설명하는 이 모델은 일반 사용에 안전하도록 만든 “Mythos-class” 시스템이며, Claude Code v2.1.170에서 /model claude-fable-5로 선택할 수 있습니다.⁶⁰ 더 높은 tier는 fleet 전체의 일괄 설정이 아니라, 순수한 추론 깊이가 비용을 정당화하는 의사결정에만 의도적으로 사용하세요. Opus 5 전환에는 두 가지 정리 사항도 있습니다. Opus 4.7은 fast mode 대상에서 제외되었으며(/fast는 이제 Opus 5와 Opus 4.8에 적용됨), v2.1.176부터 “사용 가능한 최선의 Opus 모델”이었던 auto-mode classifier의 Fable-5 fallback은 이제 Opus 5로 해석됩니다.⁸⁴

Codex는 multi-agent v2를 출시했습니다. Codex CLI v0.137.0은 각 thread에 runtime 선택을 유지하고, spawned agent를 위한 더 깔끔한 후속 처리 및 metadata 기본값을 제공하며(hide_spawn_agent_metadata는 이제 기본적으로 true), 원시 parent event를 child listener에 전파합니다. subagent 모델은 여전히 명시적입니다. 기본 제공 default/worker/explorer agent type, TOML로 정의하는 custom agent, 그리고 concurrency 제어(agents.max_threads 기본값 6, agents.max_depth 기본값 1)를 사용합니다. 같은 릴리스에서는 턴별 skill catalog 해석을 지원하는 v1 skills extension과 새로운 thread-start/turn-error lifecycle contributor event도 추가했습니다. 이를 통해 kernel-sandbox 운영 방식을 기본 경계로 유지하면서 Claude Code의 hook/skill 기능 범위와의 격차를 줄였습니다. 이후 Codex v0.138.0–v0.139.0은 production 환경을 위해 multi-agent v2를 강화했습니다. 이제 inter-agent message payload는 암호화되고, v2 agent config catalog 및 agent-residency LRU가 상주 상태를 유지할 agent를 관리하며, concurrency는 spawned thread가 아닌 활성 실행 기준으로 계산됩니다. 따라서 idle agent는 더 이상 slot을 차지하지 않습니다.⁶¹ lifecycle API도 성숙했습니다. close_agent는 단순히 handle을 닫는 것이 아니라 실행 중인 agent를 중단한다는 의미를 반영해 interrupt_agent로 이름이 바뀌었으며(v0.139.0), subagent가 발생시킨 MCP startup warning은 이제 parent transcript에 중복되어 올라가지 않고 소유 thread 범위에 머뭅니다.⁶¹ Codex 측 orchestration을 구축하는 사람에게 이것들은 데모와 fleet의 차이를 만듭니다. 암호화된 메시지 전송, 제한된 상주 상태, 실행 기준 concurrency, 그리고 thread 경계를 넘어 누출되지 않는 warning이 그것입니다. 이후 Codex v0.140.0은 cross-tool 연결 지점을 열었습니다. /import는 Claude Code의 setup, project config, 최근 chat을 선택적으로 Codex로 가져오며, 세션은 영구 삭제할 수 있게 되었습니다(codex delete / /delete, 확인 안전장치 포함).⁶⁴ /import는 운영자가 harness 사이를 이동한다는 사실을 처음으로 공식 인정한 기능입니다. 이제 한쪽에서 구축한 configuration이 그곳에만 갇히지 않습니다.

메모리와 컨텍스트

모든 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 파일은 세션 전반의 오류, 결정, 패턴을 기록합니다. 예를 들어 VAR이 0일 때 bash에서 set -e와 함께 ((VAR++))를 사용하면 실패한다는 사실을 발견했다면 이를 기록합니다. 3개 세션 뒤 Python에서 유사한 정수 경계 사례를 마주하면 MEMORY.md 항목이 그 패턴을 알려줍니다.¹⁵

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

메모리 양보다 메모리 큐레이션 (2026년 5월): 최근 LLM-agent 협력에 관한 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 (continue)로 새 세션을 시작하거나 인계 문서를 읽으면 바로 구현으로 들어갈 수 있습니다.¹⁵

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

60-90분을 넘는 세션에서는 반복마다 새 Claude 인스턴스를 생성하세요. 상태는 대화 메모리가 아니라 파일 시스템을 통해 유지됩니다. 각 반복은 전체 컨텍스트 예산을 받습니다.¹⁶

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

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

Minute 0:   [fresh context]        -> productive
Minute 30:  [context filling]      -> somewhat productive
Minute 60:  [mostly consumed]      -> degraded
Minute 90:  [compaction pending]   -> significantly degraded
Minute 120: [compressed, lossy]    -> errors accumulate

반복마다 새 컨텍스트를 사용하는 접근 방식은 전체 인지 자원을 반복마다 확보하는 대신, 상태 파일 읽기와 git 기록 스캔 같은 orient 단계에 15-20%의 오버헤드가 듭니다.¹⁶ 비용 대비 효과는 다음과 같습니다. 60분 미만의 세션에서는 단일 대화가 더 효율적입니다. 90분을 넘으면 오버헤드가 있더라도 새 컨텍스트가 더 높은 품질의 결과를 만듭니다.

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

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

Dreaming은 중요 경로가 아니라 세션 사이에 백그라운드에서 실행됩니다. 이는 메모리로서의 파일 시스템 패턴을 대체하는 것이 아니라 보완합니다. MEMORY.md 파일은 계속해서 핵심 기반 역할을 하고, Dreaming은 에이전트가 세션 시작 시 읽는 Managed Agents 메모리 저장소에 큐레이션된 메모리 항목을 작성합니다. 자체 호스팅 파일 시스템 상태와 관리형 측 큐레이션을 함께 사용하는 harness에서는 두 패턴이 공존합니다.

Dreaming은 Research Preview이므로 동작이 변경될 수 있습니다. 위에서 설명한 세션 인계 및 CLAUDE.md 패턴은 자체 호스팅 harness를 위한 권위 있는 메모리 메커니즘으로 계속 유지됩니다.

안티패턴

10줄만 필요할 때 파일 전체를 읽는 것. 2,000줄 파일을 한 번 읽으면 15,000-20,000토큰을 소비합니다. 줄 오프셋을 사용하세요. Read file.py offset=100 limit=20를 사용하면 그 비용 대부분을 절약할 수 있습니다.¹⁵

자세한 오류 출력을 컨텍스트에 유지하는 것. 버그를 디버깅한 후에는 컨텍스트에 실패한 반복에서 나온 40개 이상의 스택 트레이스가 남아 있습니다. 버그를 수정한 뒤 /compact를 한 번 실행하면 그런 불필요한 부담을 제거할 수 있습니다.

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

subagents 패턴

subagents는 복잡한 작업을 독립적으로 처리하는 특화된 Claude 인스턴스입니다. 대부분은 깨끗한 컨텍스트에서 시작해 기본 대화의 내용에 영향을 받지 않습니다. 단, 아래의 fork 유형은 의도적으로 모든 내용을 상속합니다. subagents는 지정된 도구로 작업하고 결과를 요약해 반환합니다. 탐색 결과는 기본 대화를 불필요하게 늘리지 않으며, 결론만 반환됩니다.⁵

기본 제공 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 worktree에서 작업해 저장소의 완전히 격리된 사본을 사용할 수 있습니다.⁵

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

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

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

격리가 유지되어야 진정한 격리입니다. Claude Code v2.1.210에서는 worktree로 격리된 subagents가 기본 체크아웃을 변경할 수 있던 버그를 수정했습니다. 이는 이 메커니즘이 방지하려던 바로 그 문제였습니다.⁶⁹ isolation: worktree를 편의 기능이 아닌 안전 경계로 사용한다면 v2.1.210을 최소 버전으로 삼으세요. 함께 적용된 권한 변경은 반대 방향으로 작용합니다. v2.1.211부터 “always allow” 규칙은 여러 worktree에 걸쳐 저장소 루트에 유지되므로, 한 worktree에서 허용한 규칙이 같은 저장소의 다른 worktree에도 적용됩니다.⁶⁹ 병렬 worktree agents에는 적절한 사용성이지만, 일회성 실험 중에 부여한 허용 권한이 실험 후에도 유지된다는 뜻입니다. 현재 보고 있는 worktree만이 아니라 저장소 전체를 고려해 권한을 부여하세요.

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

병렬 subagents

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

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

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

재귀 방지 장치

생성 한도가 없으면 agents가 다른 agents에 작업을 위임하고, 그 agents가 다시 agents에 위임합니다. 단계가 거듭될 때마다 컨텍스트가 손실되고 토큰이 소모됩니다. 재귀 방지 패턴은 예산을 강제합니다.¹⁶

#!/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별 활성 하위 agent의 총수를 추적하고 설정 가능한 최댓값으로 제한합니다. 예산 모델은 대리 지표인 과도한 중첩 단계가 아니라 실제 실패 원인인 과도한 전체 agent 수에 대응합니다.⁷

기본 중첩 깊이는 세 번 바뀌었으므로 이에 의존하지 마세요. 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으로 바뀌었으며 마지막 두 변경은 3일 안에 이루어졌습니다.

여기서 얻어야 할 교훈은 이 숫자 중 하나가 정답이라는 뜻이 아닙니다. 플랫폼이 여전히 적절한 기본값을 찾고 있으므로 harness가 “현재 제공되는 값”을 그대로 상속해서는 안 된다는 뜻입니다. 중첩 깊이는 명시적인 예산 항목으로 다루세요. CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH를 아키텍처에 실제로 필요한 깊이로 설정하세요. 대부분의 오케스트레이션에서는 1이나 2가 적절합니다. 이렇게 하면 업그레이드로 인해 agent 집단의 위임 깊이가 조용히 바뀌는 일을 막을 수 있습니다. 이러한 변경과 관계없이 기존 주장은 여전히 유효합니다. agents가 agents에게 위임하는 체인은 결과를 만들어 내는 속도보다 더 빠르게 컨텍스트와 토큰을 소모하며, 깊이는 활용해야 할 기능이 아니라 예산을 정해 관리해야 할 위험 요소입니다. 위의 재귀 방지 장치는 다음 기본값이 어느 방향으로 바뀌더라도 깊은 트리가 수백 개의 활성 agents로 확장되지 않도록 막아 줍니다. 직접 설정한 제한만이 다음 릴리스 후에도 예상한 의미를 그대로 유지하는 유일한 깊이 값입니다.

이제 자동 모드는 생성 전에 적합성을 검사합니다. Claude Code v2.1.178은 관련된 거버넌스 공백도 해소했습니다. 자동 모드에서는 subagent가 동작을 시작한 뒤가 아니라 실행되기 전에 권한 분류기가 subagent 생성을 평가합니다.⁶³ 이전에는 상위 세션에 금지된 동작을 요청하도록 subagent를 생성할 수 있었으므로, 생성 자체가 우회 경로였습니다. 생성 시점에 적합성을 검사하면서 재귀 방지 장치와 권한 모델이 마침내 맞물리게 되었습니다. 이제 정책이 금지한 동작을 세탁하는 단계로 하위 agent를 사용할 수 없습니다.

이제 플랫폼에 기본 생성 예산이 제공됩니다. Claude Code v2.1.212(2026년 7월)는 폭주 루프를 막는 자체 보호 장치를 추가했습니다. 세션당 subagent 생성은 기본 200회로 제한되며(CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION으로 조정하고 /clear로 카운터 재설정), WebSearch도 세션당 200회로 제한됩니다(CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSION).⁶⁹ 이 섹션에서 v1.0부터 사용자 영역 스크립트로 설명해 온 생성 예산 패턴을 이제 플랫폼에서 직접 제공합니다. 이는 깊이 모델보다 예산 모델이 더 적절하다는 점을 입증합니다. 하지만 설정값의 규모에 유의하세요. 생성 200회는 위 설정의 agent 12개 예산보다 10배 이상 큽니다. 기본 제한은 아키텍처에 맞춘 예산이 아니라 완전히 폭주한 루프를 차단하는 퓨즈입니다. 상위 agent별 예산, 깊이 추적, 오케스트레이션에서 실제로 필요한 수준에 맞는 제한에는 사용자 영역의 방지 장치를 계속 사용하고, 이를 빠져나간 상황은 플랫폼 제한으로 차단하세요.

이제 자체 보호 장치는 네 가지 축을 다룹니다. 그중 세 가지는 이 섹션의 사용자 영역 방지 장치가 추적하는 항목을 그대로 보완합니다. 세션당 총 생성 횟수(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는 사용자 영역 방지 장치에는 일반적으로 없던 네 번째 축인 오케스트레이션 너비를 추가합니다. 이는 계획된 workflow 하나에 포함할 수 있는 agent 수이며, “agent 15개 미만을 목표로 삼으세요”라는 기본 지침으로 제공됩니다. 아래 Workflow Tool 섹션에서 다루는 workflowSizeGuideline을 통해 모든 설정 파일에서 지정할 수 있습니다. 이제 생성 예산 패턴은 설계 당시 고려했던 모든 축과 고려하지 않았던 축 하나까지 플랫폼에서 보완합니다.

설정값에 관한 주의 사항은 여전히 유효하지만 모든 값에 똑같이 적용되지는 않습니다. 생성 200회와 동시 agent 20개는 퓨즈입니다. 위 설정의 agent 12개 deliberation 예산보다 10배가량 크며, 아키텍처를 형성하기보다 폭주 루프를 잡도록 설계되었습니다. 너비 지침은 실제 예산과 비슷한 범위에 들어온 최초의 기본 제공 수치입니다. workflow당 agent 15개는 이 가이드의 12개와 매우 가깝기 때문에 플랫폼 기본값을 채택해도 손해가 없으며, 다른 값을 사용하려면 그에 합당한 이유가 있어야 합니다. 세 가지 퓨즈는 근거를 제시할 수 있는 값으로 설정하고, 너비 지침은 구축하려는 오케스트레이션의 형태에 맞게 설정하세요.

Agent Teams(연구 프리뷰)

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

다음과 같이 활성화하세요. export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

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

Agent View와 목표 루프(2026년 5월)

Claude Code v2.1.139는 claude agents로 시작하며 실행 중이거나 차단되었거나 완료된 Claude Code 세션을 한 화면에 표시하는 연구 프리뷰 인터페이스인 Agent View를 추가했습니다.⁴²⁴³ 공식 문서에서는 여러 세션을 배포하고 관리하며, 각 세션의 작업을 확인하고, 운영자의 입력이 필요한 세션을 식별하는 수단으로 설명합니다.⁴³ 이를 통해 다중 agent 작업은 최종 요약만으로는 제공할 수 없는 운영 현황을 확인할 수 있습니다.

subagent 또는 팀 패턴을 확대 적용할 때 Agent View를 사용하세요. 차단된 세션과 아직 실행 중인 세션을 살펴보고, 작업 분배가 의도한 아키텍처와 일치하는지 확인하세요. 하지만 이를 품질의 증거로 간주해서는 안 됩니다. Agent View는 관찰 가능성을 제공할 뿐이며, 작업의 건전성은 여전히 테스트, 검토 게이트, evidence 보고서로 판단해야 합니다.

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

Workflow Tool(v2.1.147 이상)

Claude Code의 동적 workflows는 정식 출시되어 기본으로 사용할 수 있는 기능입니다. v2.1.154부터 수십에서 수백 개의 agents를 백그라운드에서 오케스트레이션하고 /workflows로 모니터링할 수 있으며, “Dynamic workflow size” /config 제어 기능(v2.1.202)과 기본 지침이 medium인 workflowSizeGuideline 설정 키가 제공됩니다. 별도 지시가 없다면 agent 15개 미만을 목표로 합니다(v2.1.219). 이 기능은 한 릴리스 전인 v2.1.147에서 CLAUDE_CODE_WORKFLOWS=1 뒤에 숨겨진 기본 비활성화 Workflow 도구로 처음 등장했습니다. 플래그를 사용하던 시기는 이제 지나갔지만 당시 제시한 아키텍처상의 의미는 여전히 유효합니다.⁵² 이전에는 사용자 지정 dispatcher 스크립트, mailbox 상태, subagent 조율 규칙이 필요했던 흐름에 Claude Code의 자체 오케스트레이션 기본 요소를 제공합니다.

이를 둘러싼 harness를 삭제해서는 안 됩니다. Workflow는 실행 구조를 정리할 수 있지만 안전 모델을 대체하지는 않습니다. PreToolUse와 PostToolUse hooks를 차단 계층으로 유지하고, 생성 예산이나 workflow 단계 예산으로 너비 폭주를 방지하며, 파일 시스템 상태를 감사 가능한 형태로 유지하고, 최종 evidence 보고서는 모델의 자체 평가와 분리하세요. 실무에서는 Workflow로 오케스트레이션 형태를 구성하고 hooks, 테스트, 검토 게이트로 사실을 검증하세요.

이제 동적 workflows에는 너비에 관한 기본 방침이 포함됩니다(v2.1.219). 동적 workflows의 기본 크기 지침은 medium으로, “agent 15개 미만을 목표로 삼으세요”라는 의미입니다. 다른 크기와 무제한 옵션은 /config의 Dynamic workflow size에서 선택할 수 있으며, 현재 지침은 실행 중인 workflow 상태 줄에 표시됩니다.⁸⁴ 이 수치는 강제되는 제한이 아니라 권고 사항이며, 너비가 큰 계획을 차단하지 않고 planner의 방향을 유도합니다. 이를 설정할 가치가 있는 이유는 제공 방식에 있습니다. 새로운 workflowSizeGuideline 설정 키는 관리형 설정과 프로젝트 설정을 포함한 모든 설정 파일에서 지정할 수 있으며, v0.3.219부터 TypeScript SDK 설정 유형에도 포함됩니다. 따라서 오케스트레이션 너비는 운영자마다 새로 찾는 값이 아니라 팀이나 조직이 표준화할 수 있는 값이 됩니다.⁸⁵ 코드베이스의 작업이 실제로 분해되는 방식에 맞게 프로젝트 수준에서 설정하세요. 운영자가 알아야 할 사항이 두 가지 있습니다. 첫째, 설정 파일로 값을 지정하면 /config 행이 숨겨집니다. 이는 올바른 동작이지만 이유를 모르면 설정이 사라진 것처럼 보일 수 있습니다. 둘째, 이 지침은 실행을 제한하지 않고 planner를 유도하므로 안전 항목이 아니라 형태 항목에 속합니다. 너비 폭주는 여전히 생성 한도로 막아야 합니다.

이 기능은 생성 횟수, 중첩 깊이, 동시 실행에 이은 네 번째 자체 보호 축인 오케스트레이션 너비이며, Anthropic가 폭주 방지용 퓨즈가 아닌 현실적인 작업 규모로 설정한 최초의 축이라는 관점이 중요합니다. workflow당 agent 15개는 이 가이드가 v1.0부터 사용해 온 agent 12개 deliberation 예산과 같은 규모입니다. 플랫폼 기본값과 자체 예산이 서로 다른 방향에서 비슷한 값에 도달했다면, 이러한 수치에 관해 얻을 수 있는 가장 확실한 독립적 근거에 가깝습니다.

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

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

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

헤드리스 오케스트레이션을 위해 v2.1.211은 subagent의 assistant 텍스트를 stream-json 출력으로 전달하는 --forward-subagent-text(환경 변수: CLAUDE_CODE_FORWARD_SUBAGENT_TEXT)를 추가했습니다.⁶⁹ 이제 상위 agent의 스트림을 소비하는 코디네이터 프로세스는 트랜스크립트를 폴링하거나 최종 요약을 기다리지 않고 subagent의 진행 상황을 직접 확인할 수 있습니다. 이는 기본적으로 백그라운드에서 실행되는 subagents를 위한 관찰 가능성 기능입니다. v2.1.219에서는 첫 단계를 넘어 확장되어 깊이 2 이상에서 생성된 subagents도 해당 agent를 생성한 Agent tool_use id를 키로 사용해 전달된 스트림에 표시됩니다.⁸⁴ 이 키를 중심으로 구현해야 합니다. 중첩이 다시 기본적으로 활성화되면서 subagent 텍스트를 평면적인 스트림으로만 보면 구분하기 어렵습니다. 이 id를 사용하면 어떤 상위 agent가 어떤 하위 agent를 만들었는지 코디네이터가 알 수 있으므로, 위임 트리를 추론하지 않고 스트림에서 재구성할 수 있습니다. 스트림 소비자가 subagents 한 단계만 고려해 작성되었다면 이제 존재조차 알지 못했던 agents의 텍스트도 보게 됩니다. 전달된 모든 줄이 직접적인 하위 agent의 것이라고 가정하지 말고, 생성에 사용된 tool_use id를 기준으로 그룹화하세요.

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

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

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

토론이 만능 해결책은 아닙니다: M3MAD-Bench 연구 클러스터(2026년 초)는 멀티 에이전트 토론이 정체될 수 있으며 오도하는 합의로 인해 왜곡될 수 있음을 확인했습니다. 다른 에이전트가 자신 있게 틀린 답을 주장하면 타당한 주장이 밀려납니다.²⁶ Tool-MAD는 각 에이전트에 이질적인 도구 접근 권한을 부여하고 심사 단계에서 Faithfulness/Relevance 점수를 사용해 이를 개선합니다. 토론형 오케스트레이션을 구축한다면, 에이전트별 (a) 도구 이질성과 (b) 더 많은 에이전트 = 더 나은 답변이라고 가정하지 않는 정량적 심사 점수에 투자하세요.

관리형 Multiagent Orchestration 및 Outcomes(Public Beta)

아래에서 설명하는 숙의 인프라를 직접 구축하고 싶지 않다면, Multiagent Orchestration은 2026년 5월 6일 Claude Managed Agents에서 Public Beta로 도입되었습니다.³⁵ Anthropic에 따르면, “한 에이전트가 잘 수행하기에 작업량이 너무 많을 때 multiagent orchestration을 사용하면 리드 에이전트가 작업을 여러 부분으로 나누고 각각을 자체 모델, 프롬프트, 도구를 갖춘 전문가에게 위임할 수 있습니다.”³⁵ 전문가들은 “공유 파일 시스템에서 병렬로 작업하며 리드 에이전트의 전체 컨텍스트에 기여합니다.”³⁵

추적 기능도 기본으로 제공됩니다. Anthropic에 따르면, “Claude Console에서 모든 단계를 추적할 수도 있습니다. 어떤 에이전트가 무엇을, 어떤 순서로, 왜 수행했는지 확인할 수 있으므로 작업이 어떻게 위임되고 실행되었는지 완전히 파악할 수 있습니다.”³⁵

함께 제공되는 Public Beta 기능은 Outcomes입니다. Anthropic에 따르면, “성공의 기준을 설명하는 루브릭을 작성하면 에이전트가 이를 향해 작업합니다. 별도의 grader가 자체 컨텍스트 윈도우에서 기준에 따라 출력을 평가하므로 에이전트의 추론에 영향을 받지 않습니다.”³⁵ 이는 이 섹션 뒤에서 문서화하는 2단계 검증 패턴의 관리형 서비스 버전입니다. 루브릭은 수동으로 작성한 gate를 대체하고, 별도의 grader는 합의 validator를 대체합니다.

검증이 자체 hook 표면(PreToolUse 차단, exit-code 의미 체계, 커스텀 dispatcher)과 통합되어야 하거나 harness가 외부 종속성 없이 실행되어야 한다면 자체 호스팅 숙의가 여전히 적합합니다. 표준 위임과 루브릭 채점이 실제로 필요한 계약이라면 Managed Multiagent가 적합합니다.

최소 실행 가능 숙의

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%를 얻을 수 있습니다. 그 외의 요소는 모두 점진적인 개선을 더합니다.

신뢰도 트리거

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

1. 모호성 - 쿼리에 여러 타당한 해석이 있나요?
2. 도메인 복잡성 - 전문 지식이 필요한가요?
3. 위험도 - 결정을 되돌릴 수 있나요?
4. 컨텍스트 의존성 - 더 넓은 시스템을 이해해야 하나요?

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

임곗값은 작업 유형에 따라 달라집니다. 보안 결정에는 0.85의 합의가 필요합니다. 문서 변경에는 0.50이면 충분합니다. 이렇게 하면 단순한 작업을 과도하게 설계하지 않으면서 위험한 결정은 충분히 검토할 수 있습니다.⁷

상태 머신

각 단계는 이전 단계의 gate를 통과해야 하는 7단계로 구성됩니다.⁷

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

RESEARCH: 독립적인 에이전트가 주제를 조사합니다. 각 에이전트에는 서로 다른 페르소나(Technical Architect, Security Analyst, Performance Engineer 등)가 할당됩니다. 컨텍스트 격리를 통해 조사 중에는 에이전트가 서로의 조사 결과를 볼 수 없도록 합니다.

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

RANKING: 각 에이전트는 제안된 모든 접근 방식을 가중치가 적용된 5개 차원으로 점수화합니다.

2단계 검증 아키텍처

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

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

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

서로 다른 라이프사이클 지점의 두 hooks는 실패가 실제로 발생하는 방식과 맞닿아 있습니다. 일부는 즉시 발생하고(낮은 점수), 일부는 점진적으로 발생합니다(낮은 다양성, 반대 의견 문서화 누락).⁷

합의가 위험한 이유

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

Wu 등은 LLM 에이전트가 진정으로 토론할 수 있는지 검증했습니다. 그 결과, 반대를 위한 구조적 유인이 없으면 에이전트는 정확성과 무관하게 가장 자신감 있어 보이는 초기 응답으로 수렴했습니다.¹⁹ Liang 등은 이를 “Degeneration-of-Thought”라는 근본 원인으로 규명했습니다. LLM가 특정 입장에 대한 확신을 형성하면 자기 성찰만으로는 새로운 반론을 만들어 낼 수 없으므로, 멀티 에이전트 평가는 구조적으로 필요해집니다.²⁰

독립성은 핵심 설계 제약입니다. 서로의 조사 결과를 볼 수 있는 상태에서 같은 배포 전략을 평가한 두 에이전트는 0.45와 0.48을 기록했습니다. 같은 에이전트를 서로 보이지 않게 한 경우에는 0.45와 0.72를 기록했습니다. 0.48과 0.72 사이의 차이가 군집 추종의 비용입니다.⁷

가짜 합의 탐지

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

점수 군집화: 10점 척도에서 모든 에이전트의 점수가 0.3점 이내에 모이면 독립적 평가가 아니라 공유 컨텍스트 오염 신호입니다. 인증 리팩터링을 평가한 5개 에이전트가 모두 보안 위험을 7.1~7.4점으로 매겼을 때, 새로운 컨텍스트 격리로 다시 실행하자 점수가 5.8~8.9로 분산되었습니다.

상투적인 반대: 에이전트가 독립적인 이의를 생성하는 대신 서로의 우려 표현을 복사하는 경우입니다.

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

동조 탐지기는 명백한 사례, 즉 에이전트가 지나치게 빠르게 수렴하는 숙의의 약 10-15%를 포착합니다. 나머지 85-90%에서는 합의 및 pride check gates가 충분한 검증을 제공합니다.

숙의에서 작동하지 않았던 방식

자유 형식 토론 라운드. 데이터베이스 인덱싱 논의를 위해 3번의 텍스트 왕복 라운드를 진행했더니 7,500토큰의 토론이 생성되었습니다. 1라운드에서는 진정한 이견이 있었습니다. 2라운드에서는 입장을 반복했습니다. 3라운드에서는 같은 주장을 다른 말로 반복했습니다. 자유 형식 토론을 구조화된 차원 점수화로 대체하자 순위 품질은 개선되면서 비용은 60% 감소했습니다.⁷

단일 검증 gate. 첫 구현에서는 세션 종료 시 하나의 검증 hook을 실행했습니다. 에이전트는 0.52의 합의 점수(임곗값 미만)로 숙의를 완료한 뒤, 세션 종료 hook이 실패를 표시하기 전까지 20분간 관련 없는 작업을 계속했습니다. 두 개의 gates(작업 완료 시 하나, 세션 종료 시 하나)로 나누자 동일한 문제를 서로 다른 라이프사이클 지점에서 포착할 수 있었습니다.⁷

숙의 비용

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

현재 Opus 5 가격(MTok당 $5/$25) 기준으로 3개 에이전트 숙의 비용은 약 $0.23-0.30입니다. 10개 에이전트 숙의 비용은 $0.75-1.00입니다. 시스템은 약 10%의 결정에서 숙의를 트리거하므로, 모든 결정에 대한 상각 비용은 세션당 $0.08-0.10입니다. (이전 버전에서는 기존 $15/$75 Opus 4.x 가격으로 계산한 이 수치의 3배를 인용했습니다.) 이것이 가치 있는지는 잘못된 결정의 비용에 달려 있습니다.

숙의가 필요한 경우

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과 함께 도입되었으며 현재 Opus 모델에서 지원됩니다(Opus 4.8은 v2.1.154에서 /effort xhigh로 출시되었고, Opus 5도 이를 계승합니다). high와 max 사이에 위치합니다. 코딩 및 agentic 워크로드의 권장 기본값입니다. 장시간 실행되는 subagents에서는 xhigh가 토큰 비용의 비례 이하 증가로 high보다 의미 있게 뛰어난 성능을 냅니다. 단발성의 어려운 추론에는 여전히 max가 적합하지만, 지속 작업에는 xhigh가 더 낫습니다.
• 토큰 예산 상한: output_config.task_budget으로 에이전트 실행별로 구성할 수 있습니다(beta 헤더 task-budgets-2026-03-13). 모델은 남은 예산을 실시간으로 확인하며 예기치 않게 소진되는 대신 예산에 맞춰 작업 범위를 자연스럽게 조정합니다. 짧은 프롬프트의 품질을 희생하지 않으면서 예측 가능한 토큰 지출을 원하는 agentic 루프에 사용하세요.
• 암묵적 요구 인식: 사용자의 문자 그대로의 요청이 실제 필요한 내용을 충분히 명시하지 못한 경우를 알아채는 “implicit-need” 테스트를 통과한 최초의 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의 두 가지 변경 사항은 프로덕션 배포에 중요합니다.⁶⁸ CLAUDE_CODE_PROCESS_WRAPPER를 사용하면 관리형 환경에서 기업용 래퍼 바이너리를 통해 Claude Code 프로세스를 실행할 수 있습니다. 엔드포인트 에이전트, 실행 시점 정책 검사, 모든 프로세스가 지정된 감독자 아래에서 실행되어야 하는 환경을 위한 통합 지점입니다. 이전에 엔터프라이즈에서 셸 별칭이나 포크한 런처 스크립트로 이를 흉내 냈다면, 이제 지원되는 연결 지점이 있습니다.

같은 릴리스에서는 harness가 가장 민감하게 체감하는 런타임 오버헤드도 줄였습니다. MCP 도구 수가 많은 세션에서 도구 사용 라운드는 최대 7배 빨라졌고, 세션 트랜스크립트는 79배 작아졌습니다.⁶⁸ 이는 아키텍처로서의 비용 지침을 뒤집지는 않지만 완화합니다. 상태가 없는 단발성 작업에는 여전히 CLI 우선 방식이 유리하지만, 수십 개의 MCP 도구를 가진 harness는 더 이상 봄철과 같은 라운드당 비용을 치르지 않으며 트랜스크립트 저장소도 긴 자율 실행의 숨은 비용이 되지 않습니다.

Quality Loop

중요하지 않은 변경을 제외한 모든 변경에 적용하는 필수 검토 프로세스입니다.

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

Evidence Gate

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

어느 행이든 근거를 제시할 수 없다면 Refine으로 돌아가세요.²²

사람의 병합 권한

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

harness에서 이 경계를 명확히 하세요. 에이전트가 PR을 준비하고 근거를 수집하게 하되, 조직에 별도로 감사된 자동화 정책이 없다면 병합, 릴리스, 파괴적인 리포지토리 작업에는 사람의 승인을 요구하세요. 자동화가 병합을 실행하는 경우에는 실행자와 이를 승인한 사람 또는 정책을 구분하는 로그를 보존하세요.

오류 처리 패턴

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

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

상태 손상 복구. 상태가 손상되면 이 복구 패턴은 충돌하는 대신 안전한 기본값에서 다시 만듭니다.¹⁶

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

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

Blast Radius 분류

모든 에이전트 작업을 blast radius로 분류하고 그에 맞게 게이트를 적용하세요.²

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

자율 실행을 위한 작업 명세

효과적인 자율 작업에는 목표, 완료 기준, 컨텍스트 포인터라는 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 상태 코드, 파일 존재 여부 검사처럼 기계적으로 검증할 수 있어야 합니다. 초기 작업 중 하나는 에이전트에게 “통과하는 테스트를 작성하라”고 요청했고, 그 결과 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가 실행되어 lint 검사와 커밋 추적을 수행합니다.

5. 에이전트가 스토리를 완료합니다. Stop이 실행됩니다. quality gate가 다음을 검사합니다. 에이전트가 근거를 인용했는가? 완곡한 표현을 사용했는가? diff에 TODO 주석이 있는가? 검사 중 하나라도 실패하면 종료 코드 2를 반환하고 에이전트가 계속 진행합니다.

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

7. 코드 검토 에이전트 3개가 병렬로 생성됩니다. 각 에이전트가 diff를 독립적으로 검토합니다. 검토자 중 누구라도 CRITICAL을 표시하면 스토리는 큐로 돌아갑니다.

8. 스토리가 통과합니다. 다음 스토리를 불러옵니다. 5개 스토리 전체에 이 사이클을 반복합니다.

5개 스토리에서 실행된 총 hook 수는 약 340개입니다. hook에 사용한 총 시간은 약 12초입니다. 이 오버헤드는 단일 야간 실행에서 자격 증명 유출 3건, 파괴적 명령 1건, 불완전한 구현 2건을 막았습니다.

사례 연구: 야간 PRD 처리

프로덕션 harness는 8회의 야간 세션에서 PRD 12개(스토리 47개)를 처리했습니다. 지표는 처음 4개의 PRD(최소 harness: CLAUDE.md만 사용)와 이후 8개(전체 harness: hooks, skills, quality gates, multi-agent 검토)를 비교합니다.

자격 증명 유출 2건으로 API 키를 교체하고 다운스트림 서비스를 감사해야 했으며, 사고 대응에 약 4시간이 들었습니다. 동등한 사고를 막은 harness 오버헤드는 스토리당 bash 2.4초였습니다. 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의 상태 비저장 턴과 자체 보고 ID. MCP 사양은 현재 사양인 2026년 7월 28일 개정판에서 상태 비저장 코어(SEP-2575)로의 전환을 완료했습니다. 이 개정판은 이전에 서버 ID를 전달하던 상태 유지 initialize 핸드셰이크를 제거합니다. 7월 16일에 병합된 초안 사양 변경(PR #3002)은 ID를 선택적 표면으로 복원했습니다. 서버는 응답 _meta에 io.modelcontextprotocol/serverInfo 객체를 포함할 수 있으며, 요청의 clientInfo는 선택 사항이 됩니다.⁷¹ 보안과 관련해 중요한 부분은 신뢰에 관해 사양이 말하는 내용입니다. 이 ID는 자체 보고되며 검증되지 않으므로, 표시 및 로깅 용도로만 사용해야 하고 보안 의사결정을 이끌어서는 안 됩니다. harness가 MCP 서버가 선언한 이름을 기준으로 허용 목록, 권한 규칙 또는 로깅 기반 감사를 수행한다면, 그 이름은 자격 증명이 아니라 주장입니다. 신뢰는 서버가 자신을 무엇이라고 말하는지가 아니라 전송 수단과 구성, 즉 사용자가 어떤 엔드포인트에 어떤 서버를 구성했는지에 고정하세요. 상태 비저장 개정판은 예정대로 2026년 7월 28일에 출시되었습니다. 여기에는 필수 server/discover, _meta를 통한 프로토콜 버전 협상, Streamable HTTP 헤더가 포함됩니다. 위의 신뢰 지침은 출시된 동작을 설명합니다.

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

Sandbox

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

2026년 5월 보안 기준선. Claude Code v2.1.149는 PowerShell 작업 디렉터리 권한 우회, 여러 PowerShell 허용 규칙 및 오래된 변수의 권한 분석 공백, 공유 git 내부 영역만이 아니라 전체 메인 리포지터리 루트를 포함하던 git-worktree sandbox 쓰기 허용 목록 버그를 수정했습니다.⁵³ harness가 PowerShell 또는 worktree 격리 에이전트를 허용한다면 v2.1.149+를 최소 기준으로 삼고 shell 규칙을 좁게 유지하세요. 광범위한 PowerShell(*) 및 전체 리포지터리 쓰기 예외는 안전 경계가 아니라 오케스트레이션 편의책입니다.

OpenAI Agents SDK sandbox 잠금(v0.17.0, 2026년 5월 8일). OpenAI 측에서는 openai-agents-python v0.17.0이 병렬 경계를 강화했습니다. 이제 LocalFile.src 및 LocalDir.src는 manifest가 적용될 때의 materialization base_dir, 즉 SDK 프로세스의 현재 작업 디렉터리 안으로 제한됩니다. 단, SandboxPathGrant를 사용한 Manifest.extra_path_grants를 통해 소스를 명시적으로 부여한 경우는 예외입니다.⁴¹ 상대 로컬 소스는 base_dir에서 해석되며, 절대 경로는 이미 그 안에 있거나 grant를 포함해야 합니다. 이 변경은 로컬 아티팩트 경계 문제를 해결합니다. 이전 버전에서는 manifests가 임의의 호스트 경로를 sandbox workspace로 가져올 수 있었습니다. 마이그레이션 방법은 읽기 전용 마운트에 SandboxPathGrant(path=..., read_only=True)를 사용해 신뢰할 수 있는 호스트 루트를 manifest 수준에서 선언하는 것입니다. extra_path_grants는 신뢰할 수 있는 애플리케이션 구성으로 취급하세요. 모델 출력이나 신뢰할 수 없는 manifest 입력으로 grants를 채우면 안 됩니다.

OpenAI Agents SDK 후속 기준선(v0.17.3). 0.17.1-0.17.3 계열에는 추가 sandbox 및 세션 강화가 포함되었습니다. 아카이브 추출 제한, GitRepo 하위 경로 검증, 더 명확한 sandbox 제공자 오류, sandbox 명령에서 제외된 마운트포인트 자격 증명, 상대 sandbox workspace 루트 거부, Vercel-sandbox 종료 상태 처리가 이에 해당합니다.⁵⁴ Claude Code hooks만이 아니라 OpenAI 호스팅 또는 제공자 기반 sandboxes를 사용한다면, 이 섹션의 패턴에서는 0.17.3을 현재 최소 기준으로 취급하세요.

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

Anthropic의 엔지니어링 게시물 “How we contain Claude across products”(2026년 5월 25일)는 이 섹션이 부분적으로 가르치는 원칙, 즉 위의 설정 수준 sandbox, worktree 격리 기준선, 모든 것을 신뢰할 수 없는 것으로 취급하는 태도를 벤더 관점에서 직접 설명합니다.⁸¹ 핵심은 격리 강도를 제품 표면에 매핑하는 것이며, 이 매핑 자체가 교훈입니다. 하나의 올바른 격리 설계가 있는 것이 아니라, 누가 감독하고 무엇이 잘못될 수 있는지에 맞는 격리가 있을 뿐입니다.

• 일회성 gVisor 컨테이너(claude.ai). 서버 측 실행은 격리된 인프라의 gVisor 컨테이너에서 세션별 일회성 파일 시스템으로 실행됩니다. 위협 모델은 인프라와 테넌트 격리입니다. 사용자의 장비에는 절대 접근할 수 없으므로 로컬에서 방어할 대상이 없습니다.
• 인간 개입형 OS sandboxing (Claude Code). 위 sandbox 단락에서 설명한 패턴을 정책으로 표현하면 다음과 같습니다. macOS에서는 Seatbelt, Linux에서는 bubblewrap을 사용하며, 읽기는 허용하고 쓰기는 workspace로 제한하며 네트워크는 기본적으로 거부합니다. 경계가 다루지 못하는 부분은 인간이 승인합니다. Anthropic은 경계를 감사할 수 있도록 런타임(sandbox-runtime)을 오픈 소스로 공개했습니다. 이 게시물은 약한 고리에 대해서도 솔직합니다. 권한 프롬프트의 약 93%가 승인되며, 실행 전에 과도한 동작의 약 83%를 포착하면서 승인 프롬프트를 84% 줄이는 auto-mode 분류기는 승인 피로가 UX 불만이 아니라 보안 속성이기 때문에 존재합니다. 이것이 이 가이드가 v2.1.193부터 추적해 온 점검 계층의 자세입니다.
• 봉인된 VM(Claude Cowork). 플랫폼 하이퍼바이저 위의 전체 가상 머신으로, macOS에서는 Apple Virtualization framework, Windows에서는 HCS를 사용합니다. 선택한 workspace와 .claude 폴더만 마운트되며 호스트의 다른 항목은 보이지 않습니다. 자격 증명은 VM에 들어가지 않습니다. 호스트 keychain에 유지되며, 각 세션에는 범위가 지정되고 독립적으로 취소 가능한 토큰이 제공됩니다. VM 내부의 방어적 MITM 프록시가 이를 강제하며, VM 자체가 프로비저닝한 세션 토큰을 지닌 요청만 전달합니다. 공격자가 삽입한 키는 VM만 출처를 알기 때문에 경계에서 거부됩니다.

이 분류 체계 아래의 설계 원칙이 이식 가능한 부분입니다. 먼저 환경 계층에서 격리하고, 그다음 모델 계층에서 조정하세요. 확률적 방어에는 0이 아닌 실패율이 있으므로, 결정론적 경계는 프롬프트 수준 조정이 놓치는 것을 잡아야 합니다. 이는 이 가이드의 hooks-guarantee-execution 논지를 벤더가 다시 말한 것입니다. 격리 강도를 사용자의 감독 역량에 맞추세요. 개발자는 승인 전 bash 명령을 평가할 수 있지만 지식 근로자는 그렇지 못합니다. 그래서 Code에는 권한 대화 상자가, Cowork에는 봉인된 VM이 제공됩니다. 맞춤형 격리 코드보다 검증된 기본 요소를 선호하세요. 하이퍼바이저, seccomp, 컨테이너 런타임은 Anthropic 자체의 맞춤형 허용 목록 프록시 및 구성 파서보다 적대적 검토를 더 잘 견뎌냈습니다. 프로젝트 로컬 구성과 도구 출력을 신뢰할 수 없는 것으로 취급하세요. 이 게시물은 프로젝트 열기와 구성 로드를 인터넷에서 들어오는 다른 모든 요청처럼 취급하고, 도구가 신뢰할 수 있는 경우에도 도구 출력을 공격 표면으로 취급하라고 지시합니다. 이는 이 가이드가 에이전트 간 메시지, subagent가 읽은 콘텐츠, 자체 보고된 MCP ID에 적용하는 것과 같은 자세입니다. 자격 증명은 sandbox 밖에 두세요. 에이전트가 유출할 수 있는 상시 키 대신 범위가 지정되고 취소 가능하며 세션별인 토큰을 사용하세요.

설정 표면이 첫 번째 원칙을 따라잡고 있습니다(v2.1.219). “먼저 환경 계층에서 격리”에 동의하기는 쉽지만 실제로 구성하기는 불편했습니다. Claude Code의 sandbox는 규칙이 다루지 못하는 부분을 질문으로 해결했고, 위의 93% 승인 수치가 인정하듯 권한 프롬프트는 결정론적 복장을 한 확률적 방어이기 때문입니다. sandbox.network.strictAllowlist를 설정하면 egress에 대한 질문을 없앨 수 있습니다. 설정된 sandbox 명령이 허용 목록에 없는 호스트에 요청하면 프롬프트를 표시하는 대신 즉시 거부됩니다.⁸⁴ 이를 v2.1.216의 sandbox.filesystem.disabled와 함께 사용하면 두 설정이 토글의 모음이 아니라 하나의 자세가 됩니다. 파일 시스템과 네트워크 격리를 독립적으로 선택할 수 있고, 네트워크 격리는 이제 결정론적으로 만들 수 있습니다. 무인 harness에서는 이 둘 중 egress가 더 중요합니다. 인젝션된 지시가 유출로 바뀌는 곳이 egress이고, 승인 피로의 최종 상태는 키보드 앞에 피로할 사람이 아무도 없는 상태이기 때문입니다. 비용은 결정론적 경계의 일반적인 비용입니다. 허용 목록이 정확해야 하고, 빠뜨린 호스트는 질문이 아니라 불투명한 거부로 실패합니다. 에이전트가 정당하게 필요한 호스트를 열거한 뒤 프롬프트를 제거하세요.

이 중 어느 것도 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는 경로 범위 권한 규칙의 조용한 과잉 일치를 해결했습니다. 단일 세그먼트 dir/** 패턴이 있는 허용 규칙, 예를 들어 Edit(src/**)는 규칙 작성자가 허용할 의도가 없었던 vendor/some-package/src/ 및 다른 모든 중첩 src/를 포함해 모든 깊이에 있는 src라는 이름의 디렉터리 편집을 자동 승인했습니다. 이제 이런 규칙은 <cwd>/dir에만 고정됩니다. 어떤 깊이에서든 일치시키려면 **/dir/**로 명시하세요.⁷⁴ 거부 및 질문 규칙은 의도적으로 기존의 모든 깊이 일치를 유지합니다. 이 비대칭은 올바른 안전 실패 설계입니다. 너무 좁게 일치하는 허용 규칙은 안전하게 실패합니다. 프롬프트가 표시됩니다. 반면 너무 좁게 일치하는 거부 규칙은 개방적으로 실패합니다. 차단된 경로가 통과할 수 있습니다. 그래서 허용은 더 엄격해졌고 거부는 넓게 유지되었습니다. 설정이 중첩 경로를 포괄하기 위해 단일 세그먼트 허용 패턴에 의존했다면 v2.1.214에서 조용히 작동을 멈췄습니다. 이는 의도한 대로 작동하는 수정이지만, 실제로 원하는 범위를 다시 선언하도록 허용 목록을 검토할 가치가 있습니다.

Auto Mode 파괴적 명령 가드레일(2026년 6월)

Claude Code v2.1.183은 작업을 조용히 잃게 하거나 환경을 해체하는 작업에 대해 auto mode의 영향 범위를 좁혔습니다. 이제 auto mode는 세션에서 명시적으로 요청하지 않은 경우 파괴적인 git 작업(git reset --hard, git checkout -- ., git clean -fd, git stash drop), 이 세션에서 에이전트가 만든 커밋이 아닐 때의 git commit --amend, 특정 stack을 지정하지 않은 인프라 해체(terraform destroy, pulumi destroy, cdk destroy)를 강제로 차단합니다.⁶⁵ 아키텍처 측면에서 이는 위의 생성 검증 및 매개변수 수준 규칙을 보완합니다. 어떤 도구를 또는 어떻게 생성하는지 게이트 처리하는 대신, 소수의 특정 비가역 명령을 의도로 게이트 처리합니다. 에이전트는 여전히 실행할 수 있지만 자체 판단이 아니라 명시적 지시가 있을 때만 가능합니다. 자율 harness에서는 동일한 원칙을 자체 PreToolUse hooks에 적용하세요. 상태를 파괴하는 명령은 명시적 운영자 신호가 있어야만 해제되는 기본 거부 규칙이 필요합니다.

2026년 7월: auto mode가 엔터프라이즈에 도입되고, 하나의 프롬프트는 면제할 수 없게 됩니다. Auto mode는 v2.1.207에서 Amazon Bedrock, Google Vertex AI, Microsoft Foundry에 GA로 제공되었으며, disableAutoMode 관리형 설정으로 엔터프라이즈에서 선택 해제할 수 있습니다. 분류기를 점검 계층으로 사용하는 자세는 이제 모든 퍼스트파티 엔터프라이즈 플랫폼에서 사용할 수 있으며, 비활성화는 플랫폼 공백이 아니라 명시적인 거버넌스 결정입니다.⁶⁸ 이어서 v2.1.208은 재앙적 삭제에 대한 가드레일을 절대적으로 만들었습니다. 재앙적 삭제의 확인 프롬프트는 이제 --dangerously-skip-permissions와 auto mode 모두를 관통합니다.⁶⁸ 이는 주목할 만한 선례입니다. 명시적 우회 플래그를 포함한 어떤 권한 자세도 면제할 수 없는 Claude Code 최초의 확인 절차입니다. --dangerously-skip-permissions가 문자 그대로 프롬프트가 전혀 없다는 의미라고 가정한 자율 harness 설계는 이 한 가지 예외를 고려해야 합니다. 무인 루프가 가장 복구 불가능한 피해를 낼 수 있는 바로 그 지점에서 작동합니다.

조작 방지 가드레일(2026년 7월)

v2.1.203–v2.1.206 릴리스는 에이전트가 자체 감사 흔적을 조작할 수 있던 2가지 경로를 막았습니다.⁶⁸ 첫째, 이제 auto-mode 규칙은 기록 파일 조작을 차단합니다. 세션 기록은 더 이상 세션 자체의 도구 호출이 다시 쓸 수 있는 대상이 아닙니다. 둘째, 백그라운드 작업 알림은 작업이 실행되는 동안 인간 입력이 없었다고 명시합니다. 두 번째 변경은 미묘한 실패를 겨냥합니다. 모델이 백그라운드 작업을 요약하면서 이전에는 실제로 일어나지 않은 기록 내 “승인”을 제시하거나 만들어 낼 수 있었고, 알림에는 이를 반박하는 내용이 없었습니다. 이제 알림 자체가 반증이 됩니다.

아키텍처의 교훈은 Evidence Gate로 일반화됩니다. 기록, 알림, 로그는 감사 표면이며, 감사 표면은 자신이 감사하는 대상이 쓸 수 있어서는 안 됩니다. 플랫폼은 이제 자체 기록에 이를 강제합니다. harness에도 같은 규칙을 적용하세요. 증거 보고서, 테스트 출력, 심의 기록은 모델이 쓸 수 있는 경로 밖에 있어야 합니다.

프롬프트 인젝션 방어

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은 사슬의 인간 연결 고리도 강화했습니다. 이제 권한 미리보기는 양방향 재정의, 제로 폭, 유사한 Unicode 문자를 무력화합니다. 따라서 명령이 승인 대화 상자에서는 무해하게 표시되지만 실제로는 다른 작업을 실행하도록 작성될 수 없습니다.⁶⁹ 두 번째 수정은 사람이 시간 압박 속에서 렌더링된 미리보기를 승인하는 harness에서 특히 중요합니다. 표시 자체도 인젝션 표면이었기 때문입니다. 어느 변경도 위의 hook 수준 방어를 대체하지 않으며, 그 아래의 기준선을 높입니다.

Agent 로그와 가드레일은 보안 표면입니다

2026년 5월의 2가지 권고는 하나의 패턴을 강화합니다. 에이전트 인프라는 민감한 콘텐츠와 실행 가능한 정책이 유출되거나 탈출할 새로운 장소를 만듭니다. GitHub Advisory GHSA-f3jg-756w-gm35는 기본 로깅 동작에서 민감한 도구 페이로드 콘텐츠가 로컬 SQLite 로그에 남을 수 있는 Gryph Agents 페이로드 필터 문제를 다룹니다.⁴⁵ OSV GHSA-wxxx-gvqv-xp7p는 관리자 보호 프록시 엔드포인트의 LiteLLM 사용자 지정 코드 가드레일 sandbox 탈출을 다룹니다.⁴⁶

프로덕션 규칙은 다음과 같습니다. 에이전트 기록, 도구 페이로드, SQLite 로그, 가드레일 실행을 민감한 인프라로 취급하세요. 저장 전 데이터를 제거하고 보존 기간 제한을 적용하며, 사용자 지정 가드레일 코드는 sandbox에 두고 검토 가능하게 유지하세요. 프롬프트 수준의 “비밀 정보를 기록하지 마세요” 규칙만으로는 충분하지 않습니다. 로깅 및 가드레일 경로에는 결정론적 테스트가 필요합니다.

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를 생성하면 PreToolUse 및 PostToolUse hooks는 subagent가 사용하는 모든 도구에 대해 실행됩니다. 재귀적 hook 강제가 없으면 subagent가 안전 게이트를 우회할 수 있습니다. SubagentStop 이벤트를 사용하면 subagent가 완료될 때 정리 또는 검증을 실행할 수 있습니다.

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

아키텍처로서의 비용

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

토큰 수준. 시스템 프롬프트 압축입니다. 튜토리얼 코드 예제는 제거하세요. 모델은 APIs를 알고 있습니다. 파일 전반의 중복 규칙을 통합하고 설명을 제약으로 바꾸세요. “민감한 경로와 일치하는 도구 호출을 거부”는 자격 증명을 읽지 말아야 하는 이유를 15줄로 설명하는 것과 같은 작업을 합니다.

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

아키텍처 수준. 작업이 상태 비저장이라면 CLI-first를 MCP보다 우선하세요. 일회성 평가를 위한 claude --print 호출은 비용이 더 적고 연결 오버헤드도 추가하지 않습니다. MCP은 도구에 지속 상태 또는 스트리밍이 필요할 때 적합합니다.

의사결정 프레임워크

각 메커니즘을 사용해야 하는 경우:

Skills vs Hooks vs Subagents

자주 묻는 질문

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

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

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

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

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

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

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

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

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

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

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

3-agent deliberation은 실제 경과 시간으로 30~60초를 추가합니다(이 deliberation 설계는 Agent tool을 통해 에이전트를 순차적으로 실행합니다. 플랫폼 자체는 v2.1.198부터 백그라운드에서 subagents를 동시에 실행합니다). 10-agent deliberation은 2~4분을 추가합니다. consensus 및 pride check hooks는 각각 200ms 이내에 실행됩니다. 주요 병목은 오케스트레이션 오버헤드가 아니라 agent당 LLM 추론 시간입니다.⁷

CLAUDE.md 파일은 어느 정도 길이가 적절한가요?

각 섹션은 50줄 미만으로, 전체 파일은 150줄 미만으로 유지하세요. 긴 파일은 컨텍스트 창에서 잘리므로 가장 중요한 지침을 앞에 배치하세요. 스타일 선호도보다 명령과 완료 정의를 먼저 둡니다.²¹

이것은 Claude Code 이외의 도구에서도 작동하나요?

아키텍처 원칙(hooks는 결정적 게이트, skills는 도메인 전문성, subagents는 격리된 컨텍스트, 파일시스템은 메모리)은 어떤 agentic 시스템에도 개념적으로 적용됩니다. 구체적인 구현은 Claude Code의 라이프사이클 이벤트, matcher 패턴, Agent tool을 사용합니다. AGENTS.md는 같은 패턴을 Codex, Cursor, Copilot, Amp, Windsurf로 확장합니다.²¹ 구현 세부 사항은 도구별로 다르더라도 harness 패턴은 도구에 종속되지 않습니다.

빠른 참조 카드

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.

종료 코드

주요 명령

파일 위치

변경 내역

참고 자료