Claude Code SDK

# 단일 프롬프트를 실행하고 종료 (인쇄 모드)
$ claude -p "피보나치 수를 계산하는 함수를 작성하세요"

# 파이프를 사용하여 stdin 제공
$ echo "이 코드를 설명하세요" | claude -p

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

# 도착하는 대로 JSON 출력을 스트리밍
$ claude -p "React 컴포넌트를 구축하세요" --output-format stream-json

import { query, type SDKMessage } from "@anthropic-ai/claude-code";

const messages: SDKMessage[] = [];

for await (const message of query({
  prompt: "foo.py에 대한 하이쿠를 작성하세요",
  abortController: new AbortController(),
  options: {
    maxTurns: 3,
  },
})) {
  messages.push(message);
}

console.log(messages);

pip install claude-code-sdk

import anyio
from claude_code_sdk import query, ClaudeCodeOptions, Message

async def main():
    messages: list[Message] = []
    
    async for message in query(
        prompt="foo.py에 대한 하이쿠를 작성하세요",
        options=ClaudeCodeOptions(max_turns=3)
    ):
        messages.append(message)
    
    print(messages)

anyio.run(main)

from claude_code_sdk import query, ClaudeCodeOptions
from pathlib import Path

options = ClaudeCodeOptions(
    max_turns=3,
    system_prompt="당신은 도움이 되는 어시스턴트입니다",
    cwd=Path("/path/to/project"),  # 문자열 또는 Path 가능
    allowed_tools=["Read", "Write", "Bash"],
    permission_mode="acceptEdits"
)

async for message in query(prompt="안녕하세요", options=options):
    print(message)

# 가장 최근 대화를 계속
$ claude --continue

# 계속하면서 새 프롬프트 제공
$ claude --continue "이제 더 나은 성능을 위해 리팩터링하세요"

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

# 인쇄 모드에서 재개 (비대화형)
$ claude -p --resume 550e8400-e29b-41d4-a716-446655440000 "테스트를 업데이트하세요"

# 인쇄 모드에서 계속 (비대화형)
$ claude -p --continue "오류 처리를 추가하세요"

# 시스템 프롬프트 재정의 (--print와만 작동)
$ claude -p "REST API를 구축하세요" --system-prompt "당신은 시니어 백엔드 엔지니어입니다. 보안, 성능, 유지보수성에 집중하세요."

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

# 시스템 프롬프트 추가 (--print와만 작동)
$ claude -p "REST API를 구축하세요" --append-system-prompt "코드를 작성한 후 스스로 코드 리뷰를 하세요."

{
  "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"
      }
    }
  }
}

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

# 중요: MCP 도구는 --allowedTools를 사용하여 명시적으로 허용되어야 합니다
# MCP 도구는 다음 형식을 따릅니다: mcp__$serverName__$toolName
$ 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

// 도구 호출이 허용됨
{
  "behavior": "allow",
  "updatedInput": {...}, // 업데이트된 입력, 또는 원래 입력을 그대로 반환
}

// 도구 호출이 거부됨
{
  "behavior": "deny",
  "message": "..." // 권한이 거부된 이유를 설명하는 사람이 읽을 수 있는 문자열
}

const server = new McpServer({
  name: "Test permission prompt MCP Server",
  version: "0.0.1",
});

server.tool(
  "approval_prompt",
  '권한 확인 시뮬레이션 - 입력에 "allow"가 포함되면 승인, 그렇지 않으면 거부',
  {
    tool_name: z.string().describe("권한을 요청하는 도구"),
    input: z.object({}).passthrough().describe("도구의 입력"),
  },
  async ({ tool_name, input }) => {
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(
            JSON.stringify(input).includes("allow")
              ? {
                  behavior: "allow",
                  updatedInput: input,
                }
              : {
                  behavior: "deny",
                  message: "테스트 approval_prompt 도구에 의해 권한이 거부됨",
                }
          ),
        },
      ],
    };
  }
);

claude -p "..." \
  --permission-prompt-tool mcp__test-server__approval_prompt \
  --mcp-config my-config.json

$ claude -p "src/components/Header.tsx 파일을 설명하세요"
# 출력: 이것은 다음을 보여주는 React 컴포넌트입니다...

$ claude -p "데이터 레이어는 어떻게 작동하나요?" --output-format json

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

$ claude -p "애플리케이션을 구축하세요" --output-format stream-json

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

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

  // 마지막 메시지로 방출됨
  | {
      type: "result";
      subtype: "success";
      duration_ms: float;
      duration_api_ms: float;
      is_error: boolean;
      num_turns: int;
      result: string;
      session_id: string;
      total_cost_usd: float;
    }

  // 최대 턴 수에 도달했을 때 마지막 메시지로 방출됨
  | {
      type: "result";
      subtype: "error_max_turns" | "error_during_execution";
      duration_ms: float;
      duration_api_ms: float;
      is_error: boolean;
      num_turns: int;
      session_id: string;
      total_cost_usd: float;
    }

  // 대화 시작 시 첫 번째 메시지로 방출됨
  | {
      type: "system";
      subtype: "init";
      apiKeySource: string;
      cwd: string;
      session_id: string;
      tools: string[];
      mcp_servers: {
        name: string;
        status: string;
      }[];
      model: string;
      permissionMode: "default" | "acceptEdits" | "bypassPermissions" | "plan";
    };

$ claude -p "이 코드를 설명하세요"

$ echo "이 코드를 설명하세요" | claude -p

$ echo '{"type":"user","message":{"role":"user","content":[{"type":"text","text":"이 코드를 설명하세요"}]}}' | claude -p --output-format=stream-json --input-format=stream-json --verbose

#!/bin/bash

# Claude를 실행하고 종료 코드를 확인하는 간단한 함수
run_claude() {
    local prompt="$1"
    local output_format="${2:-text}"

    if claude -p "$prompt" --output-format "$output_format"; then
        echo "성공!"
    else
        echo "오류: Claude가 종료 코드 $?로 실패했습니다" >&2
        return 1
    fi
}

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

# Claude를 통해 파일 처리
$ cat mycode.py | claude -p "이 코드에서 버그를 검토하세요"

# 여러 파일 처리
$ for file in *.js; do
    echo "$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)" "단위 테스트를 추가하세요"