Claude SDK는 세 개야, 한 개가 아니라

표면이 세 개라는 사실

입문자가 가장 비싸게 치르는 착각은 Claude 생태계를 한 통에 넣어버리는 거야. 실제로는 세 개야. Anthropic Client SDK(파이썬 anthropic, 타입스크립트 @anthropic-ai/sdk)는 Messages API를 직접 부르는 운반층. Claude Agent SDK(2025년 후반에 Claude Code SDK에서 이름 바뀐 그거)는 파일시스템·셸·MCP·세션·훅·퍼미션을 끼고 도는 자율 Claude 하니스. Claude Code CLI는 사람이 터미널에서 직접 운전하는 도구. 같은 모델 가족, 다른 추상층, 다른 위협 모델, 다른 과금 형태야.

각 표면은 자기만의 계약을 가져

Client SDK는 Messages API 한 턴짜리 운반층. Agent SDK는 Claude를 오래 사는 서브프로세스로 띄우고 도구 붙이고 위험한 액션마다 퍼미션 게이트를 거는 하니스. CLI는 사람이 제안 보고 편집 승인하고 다음 질문 던지는 인터랙티브 도구. cwkPippa는 ChatGPT랑 Gemini 베리언트는 Client SDK 류로(피파는 persistent subprocess + MCP + JSONL 스트림이 필요해서 Claude만 Agent SDK로), 그리고 cwkPippa 코드 자체는 매일 CLI로 아빠가 짜고 있어.

한 통 트랩

가장 비싼 실수는 일에 안 맞는 층을 고르는 거야. 분류 한 번 받으려고 Agent SDK 끌어다 쓰면 시작 비용·파일시스템 표면·인증 복잡도까지 다 짊어지고도 정작 쓰는 건 한 줄. 반대로 코드 편집 루프를 Client SDK로 손코딩하면 이미 Agent SDK가 검증해놓은 도구 디스패치, 작업 디렉토리 관리, 퍼미션 프롬프트를 처음부터 다시 만드는 짓이야. 층 헷갈리는 게 곧 brittleness야.

원칙: 코드 한 줄 쓰기 전에 SDK 층부터 명명해. 아키텍처는 층 선택을 따라가, 그 반대 아니야.

Code

층 선택 치트시트·yaml

# 어느 SDK가 더 모던하냐가 아니라, 런타임이 뭘 해야 하느냐로 골라.
use_anthropic_client_sdk_when:
  - you_need: one_shot_response_from_messages_api
  - you_need: streaming_chat_with_your_own_history
  - you_need: structured_output_against_a_schema
  - you_need: comparison_against_other_provider_sdks
  - example: cwkpippa_chatgpt_or_gemini_variants_calling_their_apis

use_claude_agent_sdk_when:
  - you_need: a_long_lived_subprocess_with_tools_and_sessions
  - you_need: filesystem_or_command_execution_with_permission_prompts
  - you_need: mcp_servers_attached_dynamically
  - you_need: hooks_for_pre_or_post_tool_events
  - example: cwkpippa_claude_brain_holding_persistent_session_per_conversation

use_claude_code_cli_when:
  - you_need: human_in_the_loop_software_engineering
  - you_need: interactive_diff_review_and_approval
  - example: dad_writing_cwkpippa_in_terminal_right_now

빠른 설치 레퍼런스·bash

# Anthropic Client SDK — Python
pip install -U anthropic

# Anthropic Client SDK — TypeScript / Node
npm install @anthropic-ai/sdk

# Claude Agent SDK — Python (이름 바뀐 패키지)
pip install -U claude-agent-sdk

# Claude Agent SDK — TypeScript / Node
npm install @anthropic-ai/claude-agent-sdk

# Claude Code CLI (사람이 운전하는 도구)
npm install -g @anthropic-ai/claude-code
claude --help

Exercise

이미 출시했거나 출시하고 싶은 기능 세 가지를 골라. 각각에 대해 한 문장으로 답해 — 어느 표면이고(Client SDK / Agent SDK / CLI), 그 선택을 강제하는 능력 한 가지가 뭔지.

Hint

퍼미션 프롬프트 끼고 파일 편집해야 하면 Agent SDK. 구조화된 응답 한 번 받으면 Client SDK. 사람이 운전하면 CLI.

Claude SDK는 세 개야, 한 개가 아니라

표면이 세 개라는 사실

각 표면은 자기만의 계약을 가져

한 통 트랩

Code

External links

Exercise

Progress

댓글 0