고급 기능

공식 문서: https://code.claude.com/docs/ko/overview

Claude Code의 고급 기능인 헤드리스 모드, 에이전트 팀, MCP 서버, 후크, IDE 통합 등을 알아봅니다.

---

고급 기능 아키텍처

🤖

Headless Mode

claude -p "..."

비대화형 단일 실행
스크립트·자동화

🧩

Agent SDK

--agents '[...]'

멀티 에이전트 팀
병렬 복합 작업

⚙️

GitHub Actions

on: pull_request

PR 자동 리뷰
CI/CD 통합

↓

공통 기반 (Claude Code Core)

권한 모드 (acceptEdits / dontAsk)

후크 (28가지 이벤트 / 5가지 타입)

구조화 출력 (JSON Schema)

MCP 서버 연동

---

헤드리스 모드 (비대화형 실행)

Claude Code를 스크립트나 CI/CD 파이프라인에서 비대화형으로 실행할 수 있습니다.

기본 사용법

# -p 플래그로 비대화형(headless) 모드 실행
claude -p "src/utils.ts에서 사용되지 않는 import를 찾아줘"

# 결과를 파일로 저장
claude -p "프로젝트 구조를 분석해줘" > analysis.txt

--bare 모드

CLAUDE.md, .claude/ 규칙, Auto Memory 등 모든 자동 디스커버리를 건너뛰어 CI 환경에서 빠르게 시작할 수 있습니다:

claude -p "이 코드를 분석해줘" --bare

구조화된 출력 (Structured Output)

JSON 형식으로 결과를 받을 수 있습니다:

# JSON 출력
claude -p "이 프로젝트의 의존성을 분석해줘" --output-format json

# JSON Schema로 출력 형식 지정
claude -p "src/ 디렉토리의 파일 목록과 줄 수를 알려줘" \
  --output-format json \
  --json-schema '{
    "type": "object",
    "properties": {
      "files": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "path": {"type": "string"},
            "lines": {"type": "number"}
          }
        }
      }
    }
  }'

스트리밍 출력

실시간으로 진행 상황을 모니터링:

# 스트리밍 JSON 출력 (상세 모드)
claude -p "전체 테스트를 실행하고 결과를 알려줘" \
  --output-format stream-json \
  --verbose

도구 자동 승인

비대화형 환경에서 도구 사용 권한을 미리 지정:

# 특정 도구만 허용
claude -p "코드를 수정해줘" \
  --allowedTools "Bash,Read,Edit"

# 모든 편집 자동 승인
claude -p "린트 에러를 수정해줘" \
  --permission-mode acceptEdits

# 권한 프롬프트 자동 거부 (pre-allowed 도구만 동작, CI 전용)
claude -p "테스트를 실행하고 실패를 수정해줘" \
  --permission-mode dontAsk

보안 주의

--permission-mode dontAsk는 권한 프롬프트를 자동으로 거부합니다. pre-allowed 도구는 계속 동작하며, 신뢰할 수 있는 CI 환경에서만 사용하세요.

권한 모드 비교

모드	설명	사용 환경
default	매번 사용자에게 승인 요청	대화형 사용
acceptEdits	파일 편집만 자동 승인	반자동화
dontAsk	권한 프롬프트를 자동으로 거부 (pre-allowed 도구는 계속 동작)	CI/CD

권한 규칙 상세 동작

인식되는 쉘 연산자

Bash 도구 사용 시 권한 규칙은 다음 쉘 연산자를 기준으로 명령어를 분리하여 각각 평가합니다:

&&, ||, ;, |, |&, &, 개행

프로세스 래퍼 자동 제거

Bash 매칭 전 다음 프로세스 래퍼들은 자동으로 제거됩니다:

timeout, time, nice, nohup, stdbuf

예시: timeout 30 git push는 git push로 평가됩니다.

심링크 권한 동작

• Allow 규칙: 링크 경로와 대상 경로 모두 패턴에 일치해야 허용됩니다.
• Deny 규칙: 링크 경로 또는 대상 경로 중 하나라도 패턴에 일치하면 거부됩니다.

additionalDirectories 플러그인 설정 로드 범위

--add-dir(additionalDirectories)로 추가된 디렉토리에서는 플러그인 설정 중 enabledPlugins와 extraKnownMarketplaces 만 로드됩니다.

--add-dir 디렉토리의 CLAUDE.md 로드 조건

--add-dir 로 추가된 디렉토리의 CLAUDE.md 파일은 CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 환경변수를 설정한 경우에만 로드됩니다:

export CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1
claude --add-dir /shared/team-context "작업 시작"

커스텀 시스템 프롬프트

# 시스템 프롬프트 교체
claude -p "코드 리뷰해줘" \
  --system-prompt "당신은 시니어 보안 엔지니어입니다. 보안 취약점만 집중적으로 분석하세요."

# 기존 시스템 프롬프트에 추가
claude -p "코드 리뷰해줘" \
  --append-system-prompt "응답은 반드시 한국어로 하세요."

세션 이어가기

# 마지막 세션 이어서 작업
claude -p "아까 수정한 부분에 테스트도 추가해줘" --continue

# 특정 세션 ID로 복원
claude -p "추가 수정 요청" --resume "$SESSION_ID"

--resume과 훅 동작

--resume으로 세션을 재개할 때는 SessionStart 훅의 matcher가 resume인 훅만 실행됩니다 (startup matcher 훅은 실행되지 않음).

에이전트 팀 (Agent Teams)

여러 Claude 에이전트를 팀으로 구성하여 복잡한 작업을 병렬로 처리할 수 있습니다.

팀원 모드

# 팀원 모드로 실행 (다른 에이전트의 하위 에이전트로 동작)
claude --teammate-mode

에이전트 정의 (--agents)

JSON 형식으로 에이전트 팀을 정의합니다:

claude --agents '{
  "reviewer": {
    "description": "코드 리뷰어",
    "prompt": "PR의 코드 품질을 리뷰하세요",
    "tools": ["Read", "Bash"]
  },
  "tester": {
    "description": "테스트 작성자",
    "prompt": "테스트 커버리지를 분석하고 누락된 테스트를 작성하세요",
    "tools": ["Read", "Edit", "Bash"]
  }
}'

tmux 통합

tmux를 사용하면 여러 에이전트를 시각적으로 모니터링할 수 있습니다. --tmux는 반드시 --worktree와 함께 사용해야 합니다:

# tmux 통합 모드 (--worktree 필요)
claude -w feature-auth --tmux

tmux 필요

--tmux 옵션을 사용하려면 시스템에 tmux가 설치되어 있어야 하며, --worktree 플래그와 함께 사용해야 합니다.

MCP 서버

MCP(Model Context Protocol)는 Claude가 외부 도구와 데이터 소스에 접근할 수 있게 하는 프로토콜입니다.

MCP란?

MCP 서버를 연결하면 Claude Code가 다음과 같은 외부 리소스에 접근할 수 있습니다:

• 데이터베이스: PostgreSQL, MongoDB 등에 직접 쿼리
• API: GitHub, Jira, Slack 등과 연동
• 파일 시스템: 원격 파일 접근
• 브라우저: 웹 페이지 읽기

MCP 서버 설정

프로젝트 루트의 .mcp.json 파일에 MCP 서버를 설정합니다:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "DATABASE_URL": "${DATABASE_URL}"
      }
    }
  }
}

자세한 설정 방법은 MCP 서버 가이드를 참고하세요.

자주 사용되는 MCP 서버

서버	용도
server-github	GitHub 이슈, PR 관리
server-postgres	PostgreSQL 쿼리 실행
server-filesystem	추가 파일시스템 접근
server-brave-search	웹 검색

Claude Code SDK

Claude Code SDK를 사용하면 Python이나 TypeScript 코드에서 Claude Code를 프로그래밍 방식으로 제어할 수 있습니다.

설치

# Python
pip install anthropic

# TypeScript/Node.js
npm install @anthropic-ai/sdk

Python 사용 예시

import anthropic

client = anthropic.Anthropic()

# Claude Code 프로세스 시작
with client.beta.claude_code.process(
    cwd="/my/project",
    allowed_tools=["Read", "Write", "Bash"]
) as proc:
    result = proc.run("테스트 파일에서 실패하는 테스트를 찾아서 수정해줘")
    print(result.output)

TypeScript 사용 예시

import Anthropic from '@anthropic-ai/sdk';

const client = new Anthropic();

const result = await client.beta.claudeCode.process({
  cwd: '/my/project',
  allowedTools: ['Read', 'Write', 'Bash'],
}).run('테스트 파일에서 실패하는 테스트를 찾아서 수정해줘');

console.log(result.output);

주요 옵션

옵션	설명
cwd	작업 디렉토리
allowedTools	허용할 도구 목록
maxTurns	최대 대화 턴 수
systemPrompt	시스템 프롬프트
model	사용할 모델

SDK 공식 문서

더 자세한 SDK 사용법은 Anthropic Python SDK 및 TypeScript SDK를 참고하세요.

후크 (Hooks)

후크는 Claude Code의 특정 이벤트에 반응하여 자동으로 실행되는 명령어 또는 로직입니다.

공식 문서: https://code.claude.com/docs/ko/hooks

아래 다이어그램은 세션 시작부터 종료까지 후크 이벤트가 언제 실행되는지 전체 흐름을 보여줍니다.

후크 타입

후크는 5가지 타입을 지원합니다:

타입	설명	예시
command	로컬 셸 명령어 실행	"npx prettier --write ${file}"
http	HTTP 엔드포인트에 요청 전송	"url": "https://api.example.com/hook"
prompt	LLM 프롬프트로 동적 결정	코드 품질 판단, 조건부 차단
agent	복잡한 멀티스텝 작업을 위한 에이전트 실행	자동화된 리뷰, 분석
mcp_tool	MCP 도구 서버를 훅 핸들러로 사용	외부 서비스 연동 훅

후크 이벤트 (28가지)

세션 및 생명주기 이벤트

이벤트	설명
SessionStart	세션 시작 시 (matcher: startup/resume/clear/compact)
SessionEnd	세션 종료 시 (matcher: clear/resume/logout/prompt_input_exit/bypass_permissions_disabled/other)
Stop	Claude Code 중단 시
StopFailure	Claude Code 중단 실패 시 (matcher로 오류 유형 지정 가능)
InstructionsLoaded	CLAUDE.md 등 지시사항 로드 시 (matcher: user/project/local/plugin/managed)
ConfigChange	설정 파일 변경 시 (matcher: user_settings/project_settings/local_settings/mcp/permissions/policy_settings/skills)

StopFailure 매처 값

StopFailure 훅에서 matcher 필드로 특정 오류 유형에만 반응하도록 지정할 수 있습니다:

matcher 값	설명
rate_limit	API 요청 속도 제한 초과
authentication_failed	인증 실패
billing_error	청구/결제 오류
invalid_request	잘못된 API 요청
server_error	서버 내부 오류
max_output_tokens	최대 출력 토큰 초과
unknown	알 수 없는 오류

도구 실행 이벤트

이벤트	설명
PreToolUse	도구 실행 전
PostToolUse	도구 실행 후
PostToolUseFailure	도구 실행 후 실패 시

권한 이벤트

이벤트	설명
PermissionRequest	권한 요청 발생 시
PermissionDenied	권한 거부 시

파일 및 환경 이벤트

이벤트	설명
FileChanged	파일 변경 감지 시
CwdChanged	작업 디렉토리 변경 시
WorktreeCreate	워크트리 생성 시 (출력: worktreePath — 생성된 worktree 경로)
WorktreeRemove	워크트리 제거 시

태스크 및 에이전트 이벤트

이벤트	설명
TaskCreated	새 태스크 생성 시
TaskCompleted	태스크 완료 시
SubagentStart	서브에이전트 시작 시 (matcher: background/foreground)
SubagentStop	서브에이전트 종료 시
TeammateIdle	팀메이트 에이전트 대기 상태 시
UserPromptSubmit	사용자 프롬프트 제출 시
UserPromptExpansion	사용자 프롬프트 전송 직전에 내용 수정/확장 가능한 이벤트

배치 및 기타 이벤트

이벤트	설명
PostToolBatch	하나의 턴에서 여러 도구 실행이 완료된 후 (배치 완료)
PreCompact	컨텍스트 압축 전 (matcher: auto/user_initiated)
PostCompact	컨텍스트 압축 후

자동 컴팩트 비율 조절

CLAUDE_AUTOCOMPACT_PCT_OVERRIDE 환경변수로 자동 컴팩트가 실행되는 컨텍스트 사용률 임계값을 재정의할 수 있습니다. 0–100 사이의 값을 지정하세요.

# 컨텍스트 80% 사용 시 자동 컴팩트 실행
export CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=80

| Notification | 알림 발생 시 (작업 완료 등, matcher: permission_prompt/idle_prompt/auth_success/elicitation_dialog) | | Elicitation | MCP 서버가 사용자 입력을 요청할 때 (출력: action — allow/reject/modify, content — 수정된 요청 내용) | | ElicitationResult | MCP 서버에 응답 전송 전 (출력: content 재정의 가능 — 서버 전송 전 응답 수정) | | preToolCall | 도구 실행 전 (레거시) | | postToolCall | 도구 실행 후 (레거시) |

후크 설정

.claude/settings.json에서 설정합니다:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit",
        "hooks": [
          {
            "type": "command",
            "command": "echo '파일 수정 시작: ${toolInput.file_path}'"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write ${toolInput.file_path}"
          }
        ]
      }
    ],
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "node -v && npm -v && echo '환경 준비 완료'"
          }
        ]
      }
    ]
  }
}

후크 핸들러 필드

아래 다이어그램은 이벤트 발생 시 matcher와 if 조건이 어떻게 평가되어 훅 핸들러가 실행되는지 흐름을 보여줍니다.

각 훅 핸들러에서 사용할 수 있는 설정 필드입니다:

필드	타입	설명
type	string	훅 타입: command, http, prompt, agent, mcp_tool
command	string	실행할 셸 명령어 (command 타입)
matcher	string	특정 도구명 매칭 패턴 (선택사항)
if	string	훅 실행 조건식 (조건 불충족 시 건너뜀)
once	boolean	true이면 세션당 한 번만 실행
async	boolean	true이면 비동기로 실행 (결과 기다리지 않음)
asyncRewake	boolean	async: true일 때 훅 완료 후 Claude를 다시 깨울지 여부. true이면 훅 완료 시 stop_reason: "async_hook_wakeup"으로 Claude 재개
timeout	number	훅 실행 최대 대기 시간 (초 단위, 기본값: command=600초, prompt=30초)
statusMessage	string	훅 실행 중 Claude가 표시할 상태 메시지
shell	string	사용할 쉘 경로 (기본값: /bin/sh)
allowedEnvVars	array	훅에 전달할 환경변수 이름 목록

훅 기본 타임아웃

timeout 필드를 지정하지 않으면 이벤트 유형별 기본 타임아웃이 적용됩니다:

이벤트 유형	기본 타임아웃
command (동기)	600초 (10분)
command (비동기, async: true)	300초 (5분)
http	30초
prompt	30초
agent	600초 (10분)

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write ${toolInput.file_path}",
            "if": "${toolInput.file_path.endsWith('.ts')}",
            "once": false,
            "async": true,
            "statusMessage": "코드 포매팅 중...",
            "allowedEnvVars": ["NODE_ENV", "PATH"]
          }
        ]
      }
    ]
  }
}

후크 응답 형식

훅에서 Claude Code로 JSON 응답을 반환할 수 있습니다:

{
  "continue": true,
  "suppressOutput": false,
  "systemMessage": "파일 포매팅이 완료되었습니다.",
  "hookSpecificOutput": {
    "permissionDecision": "allow"
  }
}

필드	타입/값	설명
continue	boolean	워크플로우 계속 여부 (false이면 중단)
suppressOutput	boolean	훅 출력 억제 여부
systemMessage	string	Claude에게 전달할 시스템 메시지
updatedInput	object	도구 입력값 수정 (PreToolUse 전용)
retry	boolean	현재 턴을 재시도할지 여부 (PermissionDenied 훅에서 retry: true를 반환하면 다른 권한 결정으로 재시도)
sessionTitle	string	세션 제목 지정 (SessionStart 등)
watchPaths	array	변경 감지할 경로 목록 추가 (SessionStart 전용)
hookSpecificOutput.permissionDecision	string	권한 결정: allow, deny, ask, defer (PreToolUse 전용)
hookSpecificOutput.permissionDecisionReason	string	권한 결정 이유 (사용자에게 표시)
hookSpecificOutput.additionalContext	string	Claude에게 추가 컨텍스트 전달 (SessionStart, UserPromptSubmit, PostToolUse 등 지원)
stopReason	string	워크플로우 중단 이유 (선택사항)

PermissionRequest hookSpecificOutput 상세 응답 형식:

{
  "hookSpecificOutput": {
    "hookEventName": "PermissionRequest",
    "decision": {
      "behavior": "allow",
      "updatedInput": { "command": "수정된 명령어" },
      "updatedPermissions": [
        {
          "type": "addRules",
          "rules": [{ "toolName": "Bash", "ruleContent": "npm *" }],
          "behavior": "allow",
          "destination": "localSettings"
        }
      ]
    },
    "message": "거부 이유 (deny 시 사용자에게 표시)"
  }
}

필드	타입/값	설명
decision.behavior	allow | deny	권한 허용 또는 거부
decision.updatedInput	object	도구 입력값 수정 (허용 시 실제 실행될 입력)
decision.updatedPermissions	array	영구 규칙 추가 — type: "addRules"로 설정
decision.updatedPermissions[].destination	localSettings	규칙 저장 위치 (.claude/settings.local.json)
message	string	거부 이유 (사용자에게 표시)

behavior 값	동작
allow	해당 작업 허용
deny	해당 작업 거부

PreToolUse permissionDecision과의 차이

PreToolUse 훅은 hookSpecificOutput.permissionDecision (allow/deny/ask/defer) 방식을 사용하지만, PermissionRequest 훅은 hookSpecificOutput.decision.behavior (allow/deny) 방식을 사용합니다. 두 이벤트의 응답 형식이 다름에 주의하세요.

지연된 도구 호출 (Deferred Tool Calls)

permissionDecision: "defer"를 사용하면 권한 결정을 다음 훅 핸들러에게 위임합니다. 여러 훅이 체인으로 연결된 경우, 먼저 일치하는 패턴을 가진 훅이 allow/deny/ask를 반환하면 그 결정이 최종이 됩니다. 모든 훅이 defer를 반환하면 Claude Code의 기본 권한 로직이 실행됩니다.

훅 출력 크기 제한

훅의 출력(stdout/stderr)은 10,000자로 제한됩니다. 초과된 내용은 잘립니다.

HTTP 훅 상태 코드별 동작:

HTTP 상태 코드	동작
200	성공 — 응답 본문을 훅 출력으로 처리
204	성공 — 출력 없음 (계속 진행)
4xx/5xx	오류 — 경고 표시 후 계속 진행
연결 실패	오류 — 경고 표시 후 계속 진행

레거시 응답 형식 (하위 호환):

{
  "decision": "block",
  "reason": "보안 취약점이 발견되어 파일 수정을 차단합니다",
  "output": "추가 출력 메시지"
}

필드	값	설명
decision	"block"	해당 작업 차단
decision	"approve"	해당 작업 승인
decision	"continue"	기본 동작 유지
reason	문자열	결정 이유 (사용자에게 표시)
output	문자열	추가 출력 메시지

훅 공통 입력 필드

모든 훅 이벤트는 공통으로 다음 JSON 필드를 입력으로 받습니다:

필드	타입	설명
session_id	string	현재 세션의 고유 ID
transcript_path	string	대화 트랜스크립트 파일 경로
cwd	string	현재 작업 디렉토리 경로
permission_mode	string	현재 권한 모드 (default/acceptEdits/plan/auto/dontAsk/bypassPermissions)
hook_event_name	string	발생한 훅 이벤트 이름 (예: PreToolUse)
agent_id	string	서브에이전트 컨텍스트에서 에이전트 ID
agent_type	string	서브에이전트 컨텍스트에서 에이전트 유형

후크 환경변수

훅 실행 시 다음 환경변수를 사용할 수 있습니다:

환경변수	설명
$CLAUDE_PROJECT_DIR	현재 프로젝트 디렉토리 경로
$CLAUDE_ENV_FILE	Claude Code 환경 파일 경로
$CLAUDE_PLUGIN_ROOT	플러그인 루트 경로
$CLAUDE_TASK_ID	현재 실행 중인 태스크 ID
$CLAUDE_PLUGIN_DATA	플러그인 간 데이터 공유를 위한 직렬화된 JSON 데이터

Exit Code 의미

Exit Code	의미
0	성공 (계속 진행)
2	차단 (블로킹 이벤트에서만 작동 — 해당 작업 중단)
기타	오류 (경고만 표시하고 계속 진행)

Exit Code 2 동작 범위

Exit Code 2의 차단 동작은 블로킹 이벤트에서만 작동합니다:

블로킹 이벤트	Exit Code 2 효과
PreToolUse	도구 실행 차단
PermissionRequest	권한 요청 거부
UserPromptSubmit	사용자 프롬프트 전송 차단
PreCompact	컨텍스트 압축 차단

PostToolUse, SessionStart 등 비블로킹 이벤트에서 Exit Code 2를 반환해도 워크플로우는 중단되지 않고 경고만 표시됩니다.

모든 후크 비활성화

설정에서 disableAllHooks로 모든 후크를 비활성화할 수 있습니다:

{
  "disableAllHooks": true
}

/hooks 슬래시 커맨드

현재 설정된 후크 목록을 확인하려면:

> /hooks

/hooks 출력에서 각 훅 항목의 소스 레이블을 확인할 수 있습니다:

레이블	설명
[User]	~/.claude/settings.json에서 로드된 사용자 전역 훅
[Project]	.claude/settings.json에서 로드된 프로젝트 훅
[Local]	.claude/settings.local.json에서 로드된 로컬 훅
[Session]	현재 세션에만 적용되는 훅 (임시)
[Built-in]	Claude Code 내장 훅

후크 실전 예제

파일 수정 후 자동 포매팅 + 린팅:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write ${toolInput.file_path} && npx eslint --fix ${toolInput.file_path}"
          }
        ]
      }
    ]
  }
}

커밋 전 테스트 자동 실행:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "if echo '${toolInput.command}' | grep -q 'git commit'; then npm test; fi"
          }
        ]
      }
    ]
  }
}

HTTP 후크로 알림 전송:

{
  "hooks": {
    "SessionEnd": [
      {
        "hooks": [
          {
            "type": "http",
            "url": "https://hooks.slack.com/services/YOUR/SLACK/WEBHOOK",
            "method": "POST",
            "body": "{\"text\": \"Claude Code 세션이 종료되었습니다.\"}"
          }
        ]
      }
    ]
  }
}

세션 시작 시 환경 확인:

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "node -v && npm -v && echo '환경 준비 완료'"
          }
        ]
      }
    ]
  }
}

Notification 훅으로 작업 완료 알림 보내기 (플랫폼별):

macOS:

{
  "hooks": {
    "Notification": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"${notification.message}\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}

Linux (libnotify):

{
  "hooks": {
    "Notification": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "notify-send 'Claude Code' '${notification.message}'"
          }
        ]
      }
    ]
  }
}

Windows (PowerShell Toast):

{
  "hooks": {
    "Notification": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "powershell -Command \"[Windows.UI.Notifications.ToastNotificationManager, Windows.UI.Notifications, ContentType=WindowsRuntime] | Out-Null; $template = [Windows.UI.Notifications.ToastNotificationManager]::GetTemplateContent([Windows.UI.Notifications.ToastTemplateType]::ToastText01); $template.SelectSingleNode('//text[@id=1]').InnerText = '${notification.message}'; [Windows.UI.Notifications.ToastNotificationManager]::CreateToastNotifier('Claude Code').Show([Windows.UI.Notifications.ToastNotification]::new($template))\""
          }
        ]
      }
    ]
  }
}

PermissionRequest 훅으로 권한 자동 결정:

{
  "hooks": {
    "PermissionRequest": [
      {
        "matcher": "Read",
        "hooks": [
          {
            "type": "command",
            "command": "echo '{\"continue\": true, \"hookSpecificOutput\": {\"decision\": {\"behavior\": \"allow\"}}}'"
          }
        ]
      }
    ]
  }
}

커스텀 워크플로우

프로젝트에 맞는 커스텀 워크플로우를 만들 수 있습니다. 현재 권장하는 방식은 **스킬(Skills)**입니다.

스킬로 만들기 (권장)

.claude/skills/ 디렉토리에 SKILL.md 파일을 생성합니다:

---
name: review
description: 현재 브랜치의 변경 사항을 리뷰합니다
---

현재 브랜치의 변경 사항을 리뷰해줘.
다음 항목을 확인해:
1. 보안 취약점
2. 성능 이슈
3. 코딩 컨벤션 위반
4. 테스트 누락

사용:

> /review

스킬에 대한 자세한 내용은 스킬 페이지를 참고하세요.

모델 선택 및 확장 사고

모델 선택

--model 플래그 또는 settings.json에서 사용할 Claude 모델을 지정할 수 있습니다:

# CLI에서 모델 지정
claude --model claude-opus-4-5 "복잡한 아키텍처 설계해줘"
claude --model claude-sonnet-4-5 "코드 리뷰해줘"
claude --model claude-haiku-4-5 "간단한 질문"

settings.json에서 기본 모델을 설정:

{
  "model": "claude-sonnet-4-5"
}

모델	플랜	특징
claude-opus-4-5	Max	최고 품질, 복잡한 추론
claude-sonnet-4-5	Pro/Max	균형 잡힌 성능 (기본값)
claude-haiku-4-5	모든 플랜	빠른 응답, 간단한 작업

확장 사고 (Extended Thinking)

프롬프트에 특수 키워드를 포함하거나 단축키로 깊은 추론 모드를 활성화합니다:

프롬프트 키워드:

키워드	노력 수준	설명
think	low	가볍게 생각
think hard	medium	보통 수준 사고
think harder	high	깊이 있는 사고
ultrathink	max	최대 사고 (가장 느리지만 정확)

# 프롬프트에 키워드 포함
> ultrathink - 이 알고리즘의 시간 복잡도를 분석하고 최적화해줘
> think hard - 이 아키텍처의 장단점을 분석해줘

단축키:

• Option+T / Alt+T - 확장 사고 토글
• Option+O / Alt+O - 빠른 모드(Haiku) 전환
• Ctrl+B - 백그라운드 태스크 패널 토글 (실행 중인 백그라운드 에이전트 확인)

CLI 플래그:

# 노력 수준 지정
claude --effort xhigh "복잡한 리팩토링 계획을 세워줘"
claude --effort high "이 버그의 근본 원인을 분석해줘"

설정 (항상 확장 사고 켜기):

{
  "alwaysThinkingEnabled": true,
  "showThinkingSummaries": true
}

환경변수로 제어:

# 최대 사고 토큰 수 지정
export MAX_THINKING_TOKENS=20000

# 기본 노력 수준
export CLAUDE_CODE_EFFORT_LEVEL=high

# 적응형 사고 비활성화 (항상 동일 수준 사용)
export CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1

확장 사고 활용 시점

• 복잡한 알고리즘 설계
• 아키텍처 의사결정
• 어려운 수학/논리 문제
• 미묘한 버그 근본 원인 분석

일반적인 코드 편집에는 표준 모드가 더 빠릅니다.

Plan Mode

Plan Mode는 Claude가 실제 작업 전에 계획을 세우고 사용자 승인을 받는 모드입니다. 위험한 변경을 방지하고 작업 범위를 미리 파악하는 데 유용합니다.

Plan Mode 활성화 방법

인터랙티브 모드에서 토글:

• Shift+Tab - Plan Mode 토글

CLI 플래그:

claude --permission-mode plan "모든 TypeScript 파일을 최신 ES2024 문법으로 업그레이드해줘"

항상 Plan Mode 사용 (설정):

{
  "permissions": {
    "defaultMode": "plan"
  }
}

Plan Mode 동작 방식

1. Claude가 작업 계획(목록)을 먼저 표시합니다
2. 사용자가 계획을 검토하고 승인하거나 수정합니다
3. 승인 후 실제 작업을 수행합니다

Plan Mode에서는 파일 읽기만 가능하고, 파일 수정이나 명령 실행은 승인 전까지 차단됩니다.

서브 에이전트 (Sub-agents)

서브 에이전트는 특정 역할과 도구를 부여받은 전문 에이전트입니다. .claude/agents/ 디렉토리에 정의하거나 /agents 슬래시 명령으로 관리합니다.

서브 에이전트 파일 구조

.claude/agents/ 디렉토리에 YAML 프론트매터를 가진 마크다운 파일로 정의합니다:

---
name: code-reviewer
description: 코드 품질과 보안을 리뷰하는 전문 에이전트
tools:
  - Read
  - Bash
model: claude-sonnet-4-6
permissionMode: ask
maxTurns: 20
---

당신은 경험 많은 시니어 엔지니어입니다.
코드 품질, 보안 취약점, 성능 문제를 중점적으로 리뷰하세요.
항상 구체적인 개선 방안을 제시하세요.

서브 에이전트 프론트매터 필드

필드	타입	설명
name	string	에이전트 이름 (필수)
description	string	에이전트 설명 (자동 발견 시 사용)
tools	array	사용 가능한 도구 목록
model	string	사용할 Claude 모델
permissionMode	string	권한 모드: default(기본값), acceptEdits(편집 자동 승인), plan(계획 모드), auto(자동 모드), dontAsk(권한 프롬프트를 자동으로 거부, pre-allowed 도구는 계속 동작), bypassPermissions(권한 검사 우회)
maxTurns	number	최대 대화 턴 수
memory	string	메모리 저장 범위: "user" → ~/.claude/agent-memory/<name>/, "project" → .claude/agent-memory/<name>/, "local" → .claude/agent-memory-local/<name>/
isolation	string	격리 수준 (none/worktree)
hooks	object	에이전트 전용 훅 설정
skills	array	사용할 스킬 목록
background	boolean	true이면 백그라운드에서 실행 (사용자 상호작용 없음)
color	string	에이전트 UI 색상 (HEX 또는 색상 이름)
initialPrompt	string	에이전트 시작 시 자동으로 실행할 초기 프롬프트
disallowedTools	array	사용 금지할 도구 목록
effort	string	기본 노력 수준 (low/medium/high/xhigh)
mcpServers	object	이 에이전트 전용 MCP 서버 설정

포어그라운드 vs 백그라운드 서브에이전트

구분	포어그라운드 (기본)	백그라운드 (background: true)
사용자 상호작용	가능 (확인 요청 등)	불가능 (자동 완료)
실행 방식	현재 세션 내 순차 실행	별도 세션에서 병렬 실행
결과 반환	즉시 반환	완료 후 알림
적합한 용도	대화형 리뷰, 확인이 필요한 작업	코드 분석, 테스트, 장시간 작업

서브에이전트 트랜스크립트

서브에이전트의 실행 기록은 다음 경로에 저장됩니다:

~/.claude/projects/{project}/{sessionId}/subagents/agent-{agentId}.jsonl

이 파일을 읽어 서브에이전트의 상세 실행 내역을 확인하거나 디버깅에 활용할 수 있습니다.

서브에이전트 모델 재정의

CLAUDE_CODE_SUBAGENT_MODEL 환경변수로 서브에이전트에서 사용할 모델을 지정합니다:

export CLAUDE_CODE_SUBAGENT_MODEL=claude-haiku-4-5

백그라운드 태스크 비활성화

CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1 환경변수를 설정하면 백그라운드 서브에이전트 실행이 비활성화됩니다:

export CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1

백그라운드 태스크를 비활성화하면 background: true로 설정된 서브에이전트도 포어그라운드에서 실행됩니다.

모델 결정 우선순위:

1. CLAUDE_CODE_SUBAGENT_MODEL 환경변수
2. 호출 시 전달하는 model 파라미터
3. 에이전트 frontmatter의 model 필드
4. 부모 대화 모델

에이전트 범위 우선순위

에이전트는 5단계 범위로 관리되며, 숫자가 낮을수록 높은 우선순위로 동작합니다:

우선순위	범위	설명
1	managed	조직 관리자가 배포하는 관리형(Managed) 에이전트
2	CLI 플래그	--agents CLI 플래그로 동적으로 정의한 인라인 에이전트
3	프로젝트	.claude/agents/ (프로젝트 전용 에이전트)
4	사용자	~/.claude/agents/ (개인 전역 에이전트)
5	플러그인	플러그인이 제공하는 에이전트

같은 이름의 에이전트가 여러 범위에 존재하면 우선순위가 높은 범위의 정의가 사용됩니다.

/agents 슬래시 명령

> /agents           # 등록된 에이전트 목록 표시
> /agents list      # 상세 목록
> /agents run code-reviewer   # 특정 에이전트 실행

에이전트 자동 발견

에이전트에 description을 설정하면 Claude가 작업 내용에 따라 자동으로 적합한 에이전트를 선택합니다.

@-멘션으로 특정 에이전트 지정

프롬프트에서 @agent-<이름> 형식으로 특정 에이전트를 직접 지정하여 호출할 수 있습니다:

> @agent-code-reviewer 이 파일의 보안 취약점을 확인해줘

CLI에서도 --agent 플래그 또는 설정의 agent 필드로 기본 에이전트를 지정할 수 있습니다:

claude --agent code-reviewer "PR을 리뷰해줘"

포크 서브에이전트

/fork 명령어나 CLAUDE_CODE_FORK_SUBAGENT=1 환경변수를 사용하면 현재 세션을 포크하여 독립적인 서브에이전트로 실행할 수 있습니다:

> /fork 이 기능을 실험적으로 구현해봐줘

포크된 에이전트는 원본 세션의 컨텍스트를 복사하지만 별도의 실행 환경에서 동작합니다.

포크 패널 키보드 단축키

포크 패널이 열려 있을 때 다음 단축키로 포크를 관리할 수 있습니다:

단축키	동작
↑ / ↓	포크 선택 이동
Enter	선택한 포크로 전환
x	선택한 포크 삭제
Esc	포크 패널 닫기

특정 에이전트 비활성화

permissions.deny에 Agent(에이전트-이름) 형식으로 추가하면 특정 서브에이전트의 사용을 막을 수 있습니다:

{
  "permissions": {
    "deny": [
      "Agent(code-reviewer)"
    ]
  }
}

내장 에이전트

Claude Code에는 기본 내장된 에이전트들이 있습니다:

에이전트	모델	특징
Explore	Haiku (빠름, 낮은 지연시간)	코드베이스 탐색 전용, 읽기 전용 도구만 사용
Plan	메인 모델 상속	계획 수립 전용, 읽기 전용 도구만 사용
General-purpose	메인 모델 상속	범용 에이전트, 모든 도구 사용 가능
statusline-setup	Sonnet	/statusline 실행 시 상태 표시줄 설정 전용
claude-code-guide	Haiku	Claude Code 기능·문서에 관한 질문 전용

IDE 통합

Claude Code는 VS Code와 JetBrains IDE에서 확장 프로그램으로도 사용할 수 있습니다.

VS Code 확장

1. VS Code 마켓플레이스에서 "Claude Code" 검색
2. 확장 프로그램 설치
3. 터미널 패널에서 Claude Code 사용

JetBrains 확장

1. JetBrains 플러그인 마켓플레이스에서 "Claude Code" 검색
2. 플러그인 설치
3. 도구 창에서 Claude Code 사용

실전 예제: GitHub Actions에서 자동 코드 리뷰

Anthropic은 GitHub Actions 통합을 위한 공식 Action **anthropics/claude-code-action@v1**을 제공합니다. PR/이슈에서 @claude 멘션으로 Claude를 트리거할 수 있습니다.

빠른 설정

터미널에서 아래 명령어를 실행하면 대화형으로 GitHub 앱을 설치합니다 (저장소 관리자 권한 필요):

/install-github-app

기본 워크플로우 (공식 Action 사용)

# .github/workflows/claude.yml
name: Claude Code
on:
  issue_comment:
    types: [created]
  pull_request_review_comment:
    types: [created]
  issues:
    types: [opened, assigned]

jobs:
  claude:
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
      issues: write
    steps:
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

설정 후 PR/이슈 댓글에서 @claude로 트리거합니다:

@claude 이 PR의 보안 취약점을 분석해줘
@claude 이 기능을 이슈 설명대로 구현해줘
@claude 이 버그 수정 후 테스트 코드도 작성해줘

자동 PR 리뷰 워크플로우

PR이 열릴 때마다 자동으로 코드 리뷰를 실행합니다:

name: Claude Code Review
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  review:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
    steps:
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: "이 PR을 리뷰해줘. 보안 취약점, 성능 이슈, 버그 가능성을 중점적으로 분석하고 개선 사항을 제안해줘."
          claude_args: "--max-turns 5 --model claude-sonnet-4-6"

주요 파라미터

파라미터	설명	필수
anthropic_api_key	Claude API 키 (직접 API 사용 시)	예
prompt	Claude에 전달할 지침 (생략 시 @claude 멘션에 자동 응답)	아니오
claude_args	Claude Code CLI 인수 (--max-turns, --model, --mcp-config 등)	아니오
trigger_phrase	트리거 구문 (기본값: @claude)	아니오
use_bedrock	Amazon Bedrock 사용 ("true")	아니오
use_vertex	Google Vertex AI 사용 ("true")	아니오
plugin_marketplaces	플러그인 마켓플레이스 Git URL	아니오
plugins	설치할 플러그인 목록	아니오

Amazon Bedrock / Google Vertex AI 사용

API 키 대신 클라우드 제공자를 사용할 수 있습니다:

# Amazon Bedrock 사용
- uses: anthropics/claude-code-action@v1
  with:
    use_bedrock: "true"
    claude_args: "--model us.anthropic.claude-sonnet-4-6 --max-turns 10"
  # AWS 자격증명은 별도 단계에서 구성 (configure-aws-credentials 등)

# Google Vertex AI 사용
- uses: anthropics/claude-code-action@v1
  with:
    use_vertex: "true"
    claude_args: "--model claude-sonnet-4-5@20250929 --max-turns 10"
  env:
    ANTHROPIC_VERTEX_PROJECT_ID: ${{ steps.auth.outputs.project_id }}
    CLOUD_ML_REGION: us-east5

CLAUDE.md로 동작 커스터마이징

저장소 루트에 CLAUDE.md를 생성하면 GitHub Actions에서도 Claude가 코딩 규칙, 리뷰 기준, 프로젝트 아키텍처를 반영합니다.

실전 예제: 구조화된 출력으로 코드 분석 자동화

코드 품질 메트릭을 JSON으로 추출:

claude -p "src/ 디렉토리의 코드 품질을 분석해줘" \
  --output-format json \
  --json-schema '{
    "type": "object",
    "properties": {
      "summary": {"type": "string"},
      "issues": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "file": {"type": "string"},
            "severity": {"type": "string", "enum": ["low", "medium", "high", "critical"]},
            "description": {"type": "string"},
            "suggestion": {"type": "string"}
          },
          "required": ["file", "severity", "description"]
        }
      },
      "score": {"type": "number", "minimum": 0, "maximum": 100}
    },
    "required": ["summary", "issues", "score"]
  }' \
  --permission-mode dontAsk \
  --bare

이 결과를 파이프라인에서 파싱하여 품질 게이트로 활용할 수 있습니다:

# 품질 점수가 70 미만이면 실패
SCORE=$(claude -p "..." --output-format json | jq '.score')
if [ "$SCORE" -lt 70 ]; then
  echo "코드 품질 점수가 기준 미달입니다: $SCORE/100"
  exit 1
fi

실전 예제: 멀티 에이전트 워크플로우

tmux와 에이전트 팀을 활용한 병렬 작업:

# 터미널 1: 프론트엔드 에이전트
claude -p "프론트엔드 컴포넌트의 접근성(a11y)을 점검하고 수정해줘" \
  --allowedTools "Read,Edit,Bash"

# 터미널 2: 백엔드 에이전트
claude -p "API 엔드포인트의 에러 핸들링을 점검하고 개선해줘" \
  --allowedTools "Read,Edit,Bash"

# 터미널 3: 테스트 에이전트
claude -p "테스트 커버리지를 분석하고 누락된 테스트를 작성해줘" \
  --allowedTools "Read,Edit,Bash"

tmux로 관리

claude --tmux를 사용하면 이러한 병렬 에이전트를 하나의 tmux 세션에서 관리할 수 있습니다. 각 에이전트의 진행 상황을 한눈에 모니터링할 수 있습니다.

문제 해결

헤드리스 모드에서 타임아웃

# 타임아웃 늘리기
claude -p "대규모 리팩토링" --timeout 600000

도구 권한 에러

# 필요한 도구를 명시적으로 허용
claude -p "작업 수행" --allowedTools "Bash,Read,Edit,Write"

후크가 실행되지 않는 경우

1. .claude/settings.json의 JSON 문법 확인
2. 이벤트 이름이 정확한지 확인 (PreToolUse, PostToolUse, SessionStart 등)
3. matcher 값이 정확한 도구 이름인지 확인 (Edit, Bash, Read 등)
4. command가 유효한 셸 명령어인지 확인
5. disableAllHooks: true로 설정되어 있지 않은지 확인
6. /hooks 커맨드로 현재 설정된 후크 목록 확인

연계 기능

고급 기능 확장을 위한 연계 가이드

💻 CLI 레퍼런스

-p, --output-format, --permission-mode 등 헤드리스 모드에서 사용하는 모든 플래그의 전체 목록을 확인하세요.

CLI 레퍼런스 →

☁️ 클라우드 세션

헤드리스 모드와 --remote 플래그를 결합하면 Anthropic 클라우드 VM에서 비대화형 작업을 실행할 수 있습니다.

클라우드 세션 →

📅 스케줄 (Schedule)

헤드리스 모드 명령어를 스케줄과 연결하면 매일 정해진 시간에 코드 분석, 테스트, 리포트 생성 등을 자동 실행할 수 있습니다.

스케줄 가이드 →

장점, 단점과 한계점

장점

• 헤드리스 모드로 완전 자동화: -p 플래그로 비대화형 실행이 가능하여 CI/CD 파이프라인, 스크립트, 크론잡 등에서 Claude Code를 완전 자동화할 수 있습니다.
• Agent SDK로 커스텀 도구 구축: 에이전트 팀을 JSON으로 정의하여 복잡한 멀티 에이전트 워크플로우를 구성할 수 있습니다.
• 구조화된 출력(JSON): --output-format json과 --json-schema로 프로그래밍적으로 파싱 가능한 정형 데이터를 받아 파이프라인에 통합할 수 있습니다.
• 후크로 워크플로우 확장: PreToolUse, PostToolUse, SessionStart 이벤트에 셸 명령어를 연결하여 자동 포매팅, 린팅, 테스트 실행 등을 자동화합니다.
• 에이전트 팀으로 병렬 처리: tmux 통합과 --agents 옵션으로 여러 에이전트를 동시에 실행하여 대규모 작업을 병렬로 처리할 수 있습니다.

단점과 한계점

• 러닝 커브가 높음: 헤드리스 모드, 후크, 에이전트 팀, 구조화 출력 등 다양한 옵션을 익히는 데 시간이 필요하며, 초보자에게는 진입 장벽이 됩니다.
• --permission-mode dontAsk 주의: 사전 승인되지 않은 도구를 자동으로 거부하므로, 반드시 permissions.allow 목록을 사전에 명시해야 합니다. 예상치 못한 도구가 차단될 수 있어 신중하게 설정해야 합니다.
• 후크 디버깅 어려움: 후크에서 오류가 발생해도 에러 메시지가 직관적이지 않으며, JSON 설정 파일의 작은 실수가 전체 후크 체인을 중단시킬 수 있습니다.
• 에이전트 팀 비용이 높음: 여러 에이전트를 병렬로 실행하면 API 사용량이 배로 증가하여, 대규모 팀 구성 시 비용 관리에 주의가 필요합니다.
• CI/CD 환경 설정 복잡: GitHub Actions 등에서 Claude Code를 실행하려면 API 키 관리, 권한 모드 설정, 출력 파싱 등 여러 단계의 구성이 필요합니다.

활용 팁

처음에는 --permission-mode acceptEdits로 시작하여 파일 편집만 자동 승인하고, 충분히 신뢰할 수 있는 환경에서만 dontAsk로 전환하세요. 후크 디버깅은 먼저 셸에서 command를 직접 실행하여 동작을 확인한 후 설정에 추가하는 것이 안전합니다.

다음 단계

• 규칙 - CLAUDE.md로 프로젝트 규칙 설정
• 스킬 - 재사용 가능한 워크플로우 만들기
• MCP 서버 - 외부 도구 연동 상세 가이드
• 스케줄 - 작업을 주기적으로 자동 실행
• 디스패치 - 모바일에서 작업 위임
• 원격 제어 - 어디서든 세션 이어가기
• 컴퓨터 사용 - GUI 앱 직접 조작
• 채널 - 텔레그램, 디스코드 등 연동
• 클라우드 세션 - 클라우드에서 실행
• 기능 비교 - 모든 원격/자동화 기능 한눈에 비교
• 문제 해결 - 자주 발생하는 문제와 해결법