Claude를 쓰는 길은 하나가 아니라 셋이야

이름부터 갈라 놓자

Claude 생태계를 한 덩어리로 보면 첫 설계부터 어긋나. Anthropic Client SDK(파이썬 anthropic, 타입스크립트 @anthropic-ai/sdk)는 Messages API를 직접 호출하는 통신층이야. Claude Agent SDK는 파일시스템·셸·MCP·세션·훅·권한을 묶어 자율 작업을 돌리는 실행 장치고, Claude Code CLI는 사람이 터미널에서 직접 지휘하는 개발 도구야. 같은 Claude 모델을 쓰더라도 책임과 위험, 비용의 모양은 전혀 달라.

일이 요구하는 능력으로 고르자

응답 한 번이나 자체 대화 이력을 가진 채팅이면 Client SDK가 맞아. 도구를 쓰며 오래 살아 있는 세션, 파일 편집, 명령 실행, 권한 확인이 필요하면 Agent SDK 차례야. 사람이 제안을 읽고 수정과 다음 질문을 결정하는 개발 작업은 CLI가 맡아. cwkPippa도 이 경계를 따른다. Claude 브레인은 지속 서브프로세스·MCP·JSONL 기록이 필요해 Agent SDK를 쓰고, ChatGPT와 Gemini 브레인은 각 API를 직접 호출하며, 코드베이스를 고치는 아빠의 손에는 CLI가 있어.

층을 잘못 고르면 무엇을 다시 만들게 되나

분류 한 번에 Agent SDK를 끌어오면 시작 비용과 넓은 파일 접근, 복잡한 인증까지 떠안아. 반대로 코드 편집 에이전트를 Client 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에 가까워.

이름부터 갈라 놓자

일이 요구하는 능력으로 고르자

층을 잘못 고르면 무엇을 다시 만들게 되나

Code

External links

Exercise

Progress

댓글 0