[Claude Code 번역] Claude Code SDK (Claude Code SDK)

출처: https://docs.anthropic.com/en/docs/claude-code/sdk

---

개요

Claude Code SDK를 사용하면 Claude Code를 프로그래밍적으로 애플리케이션에 통합할 수 있습니다. SDK는 Claude Code를 서브프로세스로 실행할 수 있게 하여, Claude의 기능을 활용하는 AI 기반 코딩 어시스턴트 및 도구를 구축할 수 있습니다.

현재 SDK는 커맨드라인 사용을 지원합니다. TypeScript 및 Python SDK는 곧 제공될 예정입니다.

---

기본 SDK 사용법

Claude Code SDK를 사용하면 애플리케이션에서 비대화(non-interactive) 모드로 Claude Code를 사용할 수 있습니다. 기본 예시는 다음과 같습니다:

# 단일 프롬프트 실행 후 종료 (print 모드)
$ claude -p "피보나치 수를 계산하는 함수를 작성해줘"

# 파이프로 stdin 제공
$ echo "이 코드를 설명해줘" | claude -p

# 메타데이터와 함께 JSON 형식으로 출력
$ claude -p "hello world 함수를 생성해줘" --output-format json

# JSON 출력 스트림으로 실시간 결과 받기
$ claude -p "React 컴포넌트를 만들어줘" --output-format stream-json

---

고급 사용법

다중 턴 대화

여러 턴의 대화가 필요한 경우, 최근 세션을 이어가거나 특정 세션 ID로 재개할 수 있습니다:

# 가장 최근 대화 이어가기
$ claude --continue

# 이어가면서 새 프롬프트 제공
$ claude --continue "이제 성능을 개선해줘"

# 세션 ID로 특정 대화 재개
$ claude --resume 550e8400-e29b-41d4-a716-446655440000

# print 모드로 세션 재개 (비대화)
$ claude -p --resume 550e8400-e29b-41d4-a716-446655440000 "테스트를 업데이트해줘"

# print 모드로 최근 대화 이어가기
$ claude -p --continue "에러 핸들링을 추가해줘"

커스텀 시스템 프롬프트

Claude의 행동을 안내하는 커스텀 시스템 프롬프트를 제공할 수 있습니다:

# 시스템 프롬프트 오버라이드 (print 모드에서만 동작)
$ claude -p "REST API를 만들어줘" --system-prompt "당신은 시니어 백엔드 엔지니어입니다. 보안, 성능, 유지보수성을 중시하세요."

# 특정 요구사항이 있는 시스템 프롬프트
$ claude -p "데이터베이스 스키마를 생성해줘" --system-prompt "당신은 데이터베이스 아키텍트입니다. PostgreSQL 베스트 프랙티스를 따르고 적절한 인덱싱을 포함하세요."

기본 시스템 프롬프트에 추가 지침을 덧붙일 수도 있습니다:

# 시스템 프롬프트에 추가 지침 (print 모드에서만 동작)
$ claude -p "REST API를 만들어줘" --append-system-prompt "코드 작성 후 반드시 셀프 코드 리뷰를 하세요."

MCP 구성

Model Context Protocol(MCP)을 사용하면 외부 서버의 추가 도구 및 리소스를 Claude Code에 확장할 수 있습니다. --mcp-config 플래그로 MCP 서버를 로드하면 데이터베이스 접근, API 연동, 커스텀 툴링 등 특화된 기능을 사용할 수 있습니다.

MCP 서버가 정의된 JSON 구성 파일 예시:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/path/to/allowed/files"
      ]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "your-github-token"
      }
    }
  }
}

Claude Code에서 MCP 서버 사용 예시:

# MCP 서버 구성 파일 로드
$ claude -p "프로젝트의 모든 파일을 나열해줘" --mcp-config mcp-servers.json

# 중요: MCP 도구는 --allowedTools로 명시적으로 허용해야 함
# MCP 도구 명명 규칙: mcp__서버이름__도구이름
$ claude -p "TODO 주석을 모두 찾아줘" \
  --mcp-config mcp-servers.json \
  --allowedTools "mcp__filesystem__read_file,mcp__filesystem__list_directory"

# 비대화 모드에서 권한 프롬프트를 MCP 도구로 처리
$ claude -p "애플리케이션을 배포해줘" \
  --mcp-config mcp-servers.json \
  --allowedTools "mcp__permissions__approve" \
  --permission-prompt-tool mcp__permissions__approve

참고: MCP 도구를 사용할 때는 반드시 --allowedTools 플래그로 명시적으로 허용해야 합니다. MCP 도구 이름은 mcp__<서버이름>__<도구이름> 패턴을 따릅니다.

---

사용 가능한 CLI 옵션

SDK는 Claude Code의 모든 CLI 옵션을 활용할 수 있습니다. 주요 옵션은 다음과 같습니다:

플래그	설명	예시
--print, -p	비대화(non-interactive) 모드로 실행	claude -p "질문"
--output-format	출력 형식 지정(text, json, stream-json)	claude -p --output-format json
--resume, -r	세션 ID로 대화 재개	claude --resume abc123
--continue, -c	가장 최근 대화 이어가기	claude --continue
--verbose	상세 로그 활성화	claude --verbose
--max-turns	비대화 모드에서 최대 에이전트 턴 제한	claude --max-turns 3
--system-prompt	시스템 프롬프트 오버라이드 (print 모드에서만 동작)	claude --system-prompt "커스텀 지침"
--append-system-prompt	시스템 프롬프트에 추가 지침 (print 모드에서만 동작)	claude --append-system-prompt "커스텀 지침"
--allowedTools	허용할 도구 목록(콤마/공백 구분, MCP 도구 포함)	claude --allowedTools "Bash(npm install),mcp__filesystem__*"
--disallowedTools	금지할 도구 목록(콤마/공백 구분)	claude --disallowedTools "Bash(git commit),mcp__github__*"
--mcp-config	MCP 서버를 JSON 파일로 로드	claude --mcp-config servers.json
--permission-prompt-tool	권한 프롬프트를 처리할 MCP 도구 (print 모드에서만 동작)	claude --permission-prompt-tool mcp__auth__prompt

전체 CLI 옵션 및 기능은 CLI 사용법 문서를 참고하세요.

---

출력 형식

SDK는 다양한 출력 형식을 지원합니다:

텍스트 출력(기본값)

응답 텍스트만 반환합니다:

$ claude -p "src/components/Header.tsx 파일을 설명해줘"
# 출력: 이 컴포넌트는 React로 작성된 헤더입니다...

JSON 출력

메타데이터가 포함된 구조화된 데이터를 반환합니다:

$ claude -p "데이터 레이어가 어떻게 동작하는지 설명해줘" --output-format json

응답 예시:

{
  "type": "result",
  "subtype": "success",
  "cost_usd": 0.003,
  "is_error": false,
  "duration_ms": 1234,
  "duration_api_ms": 800,
  "num_turns": 6,
  "result": "여기에 응답 텍스트...",
  "session_id": "abc123"
}

스트리밍 JSON 출력

각 메시지를 수신 즉시 스트림으로 반환합니다:

$ claude -p "애플리케이션을 만들어줘" --output-format stream-json

각 대화는 초기 init 시스템 메시지로 시작하며, 사용자/어시스턴트 메시지 목록, 마지막에 통계가 포함된 result 시스템 메시지로 구성됩니다. 각 메시지는 별도의 JSON 객체로 출력됩니다.

---

메시지 스키마

JSON API에서 반환되는 메시지는 아래 스키마를 따릅니다:

type Message =
  // 어시스턴트 메시지
  | {
      type: "assistant";
      message: APIAssistantMessage; // Anthropic SDK에서 제공
      session_id: string;
    }

  // 사용자 메시지
  | {
      type: "user";
      message: APIUserMessage; // Anthropic SDK에서 제공
      session_id: string;
    }

  // 마지막에 반환되는 메시지
  | {
      type: "result";
      subtype: "success";
      cost_usd: float;
      duration_ms: float;
      duration_api_ms: float;
      is_error: boolean;
      num_turns: int;
      result: string;
      session_id: string;
    }

  // 최대 턴 도달 시 반환
  | {
      type: "result";
      subtype: "error_max_turns";
      cost_usd: float;
      duration_ms: float;
      duration_api_ms: float;
      is_error: boolean;
      num_turns: int;
      session_id: string;
    }

  // 대화 시작 시 최초 메시지
  | {
      type: "system";
      subtype: "init";
      session_id: string;
      tools: string[];
      mcp_servers: {
        name: string;
        status: string;
      }[];
    };

이 타입들은 곧 JSONSchema 호환 형식으로도 제공될 예정입니다. 주요 Claude Code 패키지는 시맨틱 버전 관리를 통해 포맷 변경을 안내합니다.

---

예시

간단한 스크립트 통합

#!/bin/bash

# Claude 실행 및 종료 코드 확인 함수
run_claude() {
    local prompt="$1"
    local output_format="${2:-text}"

    if claude -p "$prompt" --output-format "$output_format"; then
        echo "Success!"
    else
        echo "Error: Claude failed with exit code $?" >&2
        return 1
    fi
}

# 사용 예시
run_claude "CSV 파일을 읽는 Python 함수를 작성해줘"
run_claude "이 데이터베이스 쿼리를 최적화해줘" "json"

파일 처리

# 파일을 Claude로 처리
$ cat mycode.py | claude -p "이 코드에 버그가 있는지 리뷰해줘"

# 여러 파일 처리
$ for file in *.js; do
    echo "Processing $file..."
    claude -p "이 파일에 JSDoc 주석을 추가해줘:" < "$file" > "${file}.documented"
done

# 파이프라인에서 Claude 사용
$ grep -l "TODO" *.py | while read file; do
    claude -p "이 파일의 모든 TODO 항목을 고쳐줘" < "$file"
done

세션 관리

# 세션 시작 및 세션 ID 저장
$ claude -p "새 프로젝트를 초기화해줘" --output-format json | jq -r '.session_id' > session.txt

# 동일 세션으로 이어서 작업
$ claude -p --resume "$(cat session.txt)" "단위 테스트를 추가해줘"

---

베스트 프랙티스

1. JSON 출력 형식 사용: 응답을 프로그램에서 파싱할 때 유용합니다.

   # jq로 JSON 응답 파싱
   result=$(claude -p "코드 생성해줘" --output-format json)
   code=$(echo "$result" | jq -r '.result')
   cost=$(echo "$result" | jq -r '.cost_usd')

2. 에러를 우아하게 처리: 종료 코드와 stderr를 확인하세요.

   if ! claude -p "$prompt" 2>error.log; then
    echo "Error occurred:" >&2
    cat error.log >&2
    exit 1
   fi

3. 세션 관리 활용: 다중 턴 대화에서 맥락을 유지할 수 있습니다.
4. 타임아웃 고려: 장시간 작업에는 타임아웃을 설정하세요.

   timeout 300 claude -p "$complex_prompt" || echo "Timed out after 5 minutes"

5. 요청 간 딜레이로 레이트 리밋 준수

---

실제 활용 사례

Claude Code SDK는 개발 워크플로우에 강력한 통합을 제공합니다. 대표적인 예로, Claude Code GitHub Actions는 SDK를 활용해 자동 코드 리뷰, PR 생성, 이슈 분류 기능을 GitHub 워크플로우에 직접 제공합니다.

---

관련 자료

• CLI 사용법 및 제어 - 전체 CLI 문서
• GitHub Actions 통합 - Claude로 GitHub 워크플로우 자동화
• 튜토리얼 - 주요 사용 사례별 단계별 가이드