▲

Claude Code SDK

 (docs.anthropic.com)
1P by GN⁺ 2일전 | ★ favorite | 댓글 1개
  • Claude Code SDK는 AI 기반 코딩 도구를 애플리케이션에 통합할 수 있는 기능 제공
  • 개발자는 서브프로세스 형태로 Claude Code 실행 가능, 커맨드라인 사용 우선 지원
  • 대화형 컨텍스트 관리, 커스텀 시스템 프롬프트 지정, 외부 도구 연동(MCP) 기능 포함
  • 출력 포맷 다양성(텍스트, JSON, 스트리밍 JSON) 및 상세한 CLI 옵션 활용 가능
  • 실제 사례로 GitHub Actions와 연계하여 자동화된 코드 리뷰, PR 생성 등 실제 개발 워크플로우 통합 가능성 제시

소개

Claude Code SDK는 Claude Code의 기능을 애플리케이션에 직접 프로그래밍적으로 통합할 수 있는 오픈소스 개발 도구임. SDK는 Claude Code를 별도 프로세스 형태로 실행하여, AI 기반 코드 어시스턴트, 자동화 도구, 코드 리뷰 시스템 등 다양한 개발 워크플로우에 접목할 수 있는 확장성을 제공함.

현재는 커맨드라인(CLI) 기반 인터페이스를 지원하며, TypeScript 및 Python용 SDK는 곧 출시될 예정임

기본 SDK 사용

Claude Code SDK는 비대화형(비인터랙티브) 실행을 지원함. 예를 들어, 프로그래밍 코드 내에서 Claude Code를 명령줄 인수와 함께 호출하여 원하는 출력을 자동으로 얻을 수 있음

고급 사용법

멀티턴 대화 세션 이어가기

  • 여러 차례의 대화를 주고받을 때, 이전의 세션이나 특정 세션 ID를 활용하여 대화 맥락을 유지하고 이어가는 기능 제공
  • 개발자는 최근 세션에서 대화를 계속 이어가거나, 특정 세션을 불러올 수 있음

커스텀 시스템 프롬프트

  • Claude의 기본 동작 방식을 개발자 맞춤형 시스템 프롬프트로 조정 가능
  • 기본 시스템 프롬프트에 추가 지침을 첨부하여 assistant의 업무 지향성과 행동 범위를 변경할 수 있음

MCP(Model Context Protocol) 설정

  • MCP는 Claude Code 기능 확장을 위한 외부 서버 연동 프로토콜임
  • --mcp-config 플래그와 JSON 설정 파일을 통해 외부 서버에서 제공하는 데이터베이스 접근, API 연동, 커스텀 툴 등을 추가할 수 있음
  • MCP 도구 사용 시, 명시적으로 허용한 도구만 사용 가능해야 하며(--allowedTools 플래그), 이름 패턴이 mcp__<serverName>__<toolName> 형식임

사용 가능한 CLI 옵션

Claude Code SDK에서는 다양한 커맨드라인 플래그를 사용하여 실행 환경을 설정할 수 있음

  • --print, -p : 비인터랙티브 모드 실행
  • --output-format : 출력 포맷 선택(텍스트, JSON, 스트림 JSON 등)
  • --resume, -r : 특정 세션 ID로 대화 이어가기
  • --continue, -c : 가장 최근 세션 이어가기
  • --verbose : 상세 로그 출력
  • --max-turns : 비인터랙티브 모드에서 최대 대화 라운드 제한
  • --system-prompt : 시스템 프롬프트 오버라이드
  • --append-system-prompt : 시스템 프롬프트에 추가 지침 첨부
  • --allowedTools : 허용 도구 리스트 지정(MCP 도구도 포함)
  • --disallowedTools : 금지 도구 리스트 지정
  • --mcp-config : MCP 서버 설정 파일 로드
  • --permission-prompt-tool : 권한 프롬프트 처리를 위한 MCP 도구 지정

전체 사용 가능한 옵션 및 사용 예시는 공식 CLI 문서 참고 필요

출력 포맷

SDK는 다양한 출력 포맷을 지원함

텍스트 출력(기본)

  • 응답 텍스트만 반환

JSON 출력

  • 메타데이터와 구조화된 데이터 반환으로 프로그래밍적 파싱에 유리
  • API 응답 메시지는 엄격한 타입 구조를 따르며, 앞으로 JSON Schema 포맷으로도 타입 정의 예정

스트리밍 JSON 출력

  • 각 메시지를 실시간으로 스트림 전송
  • 대화 세션 진행 시, 초기화 메시지(init), 사용자/assistant 메시지, 통계가 들어있는 최종 result 메시지 순으로 별도 JSON 객체로 전송

메시지 스키마

  • JSON API 응답 메시지는 정확한 스키마에 따라 구조화됨
  • 주기적으로 스키마 갱신 및 버전 관리 진행 예정

예시

  • 간단한 스크립트 통합
  • Claude를 활용한 파일 처리
  • 세션 관리로 복잡한 대화 플로우 지원

베스트 프랙티스

  1. JSON 출력 포맷을 활용한 응답 파싱 사용
  2. 오류 처리: 종료 코드 및 에러 스트림 확인
  3. 세션 관리: 다중 라운드 대화의 맥락 유지
  4. 타임아웃 고려: 장시간 작업의 안전성 확보
  5. 요청 간 간격 조정: 과다한 호출 방지 및 서비스 안정성 유지

실제 적용 사례

Claude Code SDK는 실무 개발 환경에서 강력한 자동화 및 통합 기능을 제공함

  • 대표적 사례로, GitHub Actions와 결합하여 자동 코드 리뷰, PR 생성, 이슈 분류 등의 개발 워크플로우를 완전 자동화할 수 있음
▲
GN⁺ 2일전  [-]
Hacker News 의견

  • Claude Code가 추구하는 방향이 바로 내가 원하던 agent 기반 코딩 도구의 "unix toolish" 철학 형태임을 강조하고 싶음. 초기 공개 프리뷰 때부터 Claude Code를 써왔고 발전 과정을 지켜봤다는 경험을 가지고 있음. 코딩 에이전트의 "황금 기준점"은 피처 요청(예: Jira 티켓)을 입력하면 PR을 받아서 내가 직접 리뷰하고 피드백할 수 있는 수준이라고 생각함. Cursor, windsurf 등은 로컬 에디터라서 CI 환경에 통합이 불가능해 한계가 있다고 봄. 코드베이스를 AI 최적화(MCP, 룰 등)하고 싶다면 헤드리스로도 쓸 수 있는 기술을 목표해야 함을 강조하고 싶음. Claude Code는 자동화 툴과 함께 간단하게 쓸 수 있어서 내가 코딩 에이전트를 생각할 때 이제는 기본이 됨. Codex npm 패키지도 비슷하게 생각함. 참고로, 나는 이런 최적 도구 설정을 돕는 역할을 하고 있어서 쉬운 설정이 가능한 툴에 자연스레 유리한 시각을 가질 수밖에 없음

    • 내가 바라는 "황금 엔드 스테이트"는 내가 AI 에이전트들, 예를 들면 코드 작성, 디자인, 테스트를 수행하는 AI 에이전트들로 둘러싸인 방 한가운데 있는 상황임. 나는 그 가운데에서 직접 키보드에 손을 거의 대지 않고 방향성과 미적 기준, 가이드만 대화로 제시하는 것임. 그런 미래를 기대함

    • Anthropic가 오늘 이와 비슷한 기능을 베타로 발표함을 언급하고 싶음. 관련 문서를 공유하고 싶음. https://docs.anthropic.com/en/docs/claude-code/github-actions

    • 내가 생각하는 코딩 에이전트의 "황금 엔드 스테이트"는 내 컴퓨터, 혹은 내가 원하는 어디든 자유롭게 실행할 수 있는 무료 오픈 소스 코딩 에이전트를 사용하는 상황임. 터미널에서 ls, ps, kill 같은 명령어를 실행할 때마다 비용 지불을 상상하는 게 말이 안 된다고 느끼는 것처럼, LLM도 마찬가지라고 생각함. 독점적 LLM을 "금지하자"는 건 아니지만, 이 분야에서 해커라 불리는 사람들은 오픈 소스 툴을 주요 도구로 삼았으면 하는 바람임

    • Cursor, windsurf 등은 로컬 에디터이기 때문에 CI에 쓰기 어렵다는 점을 지적하셨지만, 나는 Cursor와 MCP 조합으로 이걸 시도해 봤음. 하루 종일 성공적으로 써봤는데, 곧 rate limit에 걸려서 제일 느리고 멍청한 모델로 바뀌는 경험을 했음. Claude로도 시도해봤지만 얼마 안가 limit을 다 써버리게 됨. 게다가 PR은 25% 정도만 "즉시 사용 가능" 수준이고 AI가 어디서 실수했는지 파악하는 것보다 그냥 직접 하는 게 빠른 경우가 많음

    • 이미 그런 CI 기반 자동화를 할 수 있지 않냐는 생각임. Aider CLI를 GitHub Action으로 등록해서 issue가 생성되면 자동으로 실행되게 하면 이미 그런 구조가 구현 가능함

  • Claude Code는 내가 LLM을 코딩에 활용할 때 제일 좋아하는 방식임. 하지만 진짜 필요한 건 오픈 소스 버전의 Claude Code라고 생각함. 원하는 모델을 적용하고, 서로 다른 모델의 답변을 직접 비교할 수 있는 환경이 필요함. Aider 등 다른 대안은 Claude Code 수준의 경험을 주지 못한다고 느낌. 이런 방식을 Anthropic이 원하지 않는 건 예상할 수 있음(방어벽이 약해지니까). 하지만 소비자 입장의 나는 최고의 모델을 쓰고 싶고, 한 생태계에 묶이고 싶지 않음. LLM 프로바이더 입장에서 이게 가장 큰 두려움일 거라 예상함

    • OpenAI codex가 말씀하신 것과 가장 가까운 오픈 소스임. 원하는 프로바이더의 모델을 쓸 수 있음. 현재로선 Claude Code보다 못하지만 곧 따라잡을 거라고 봄. https://github.com/openai/codex/tree/main

    • Claude Code를 MCP 서버로 써서 어느 정도 원하는 환경을 구현할 수 있음

  • Aider는 Python과 shell 스크립팅 지원을 꽤 오래전부터 제공하고 있었음. 최근에 130개 새로운 프로그래밍 언어 지원을 추가하는 과정 일환으로 ad-hoc bash scripting aide를 포함시킨 스크린캐스트도 제작했음. 이 스크립팅 스타일 접근이 얼마나 강력한지 직접 느낄 수 있을 것임. https://aider.chat/docs/scripting.html, https://aider.chat/docs/recordings/tree-sitter-language-pack.html

    • Aider 정말 마음에 듦. MCPs도 곧 지원 예정이며, 개발 브랜치에서 테스트 중임. 이게 되면 신뢰하는 모델만으로 PR, 티켓 등 end-to-end 개발이 실제로 가능해짐

    • Aider를 Claude Code만큼 좋아할 수 있는 수준까지 가져갈 수 있을지 궁금함. Claude Code의 UX는 마음에 들지만, Gemini 2.5 Pro를 선호해서 Claude Code는 안 씀. 커밋 등 기능보다는 UX가 좋은 점이 매력임. 이에 대한 생각을 듣고 싶음

    • Aider가 GitHub Actions 연동 워크플로우를 더 polished하게 만든다면 진짜 크게 성장할 수 있다고 생각함. repo에 파일 하나만 추가하면 issue로 원하는 모델과 대화 가능함

  • Claude Code 팀이 직접 밝힌 추가 맥락을 공유하고 싶음. http://latent.space/p/claude-code 주요 내용 정리로는, Anthropic 직원들은 무제한 Claude로 평균 하루 6달러 정도를 사용하고 있음. CI를 위한 "linux" 유틸리티 같은 headless Claude Code가 매우 매력적임. 확장 가능한 사용자 플랫폼이라는 지향점도 있음. 앞으로의 로드맵은 샌드박싱, 브랜칭, 플래닝 기능임. sonnet 3.7이라는 지속적 agentic 모델도 예정임

    • "Anthropic 직원들, 무제한 Claude로 평균 $6/일 사용"이라고 하셨지만, 기사엔 어떤 엔지니어는 하루에 $1,000도 썼다는 이야기도 있음. 평균보다는 P50, P75, P95 같은 분포가 궁금함

    • 나는 Claude Code를 2시간 정도만 써도 20달러가 훅 넘어가는 경험을 여러 번 했음. 개인 프로젝트엔 너무 비싸서 그냥 못 쓰게 됨

    • 최근 latent space 팟캐스트를 정말 재미있게 들었음. 높은 SNR을 유지하면서 이렇게 높은 생산성의 공개 콘텐츠를 꾸준히 내는 사람/팟캐스트는 정말 드뭄. 여러 비즈니스를 병행하면서도 이 정도 공적 산출물을 유지하는 게 대단함. 이런 생산성 gradient를 더 많은 이가 경험하면 좋겠다고 느낌. 본인이 비결을 공유하긴 하지만 직접 따라 하긴 쉬운 일은 아님

  • 만약 내가 AI 코드 어시스턴트를 만든다면 절대 특정 foundation 모델 제공업체에 종속시키진 않을 것임. 이게 성공하려면 모델 효과가 이제 거의 정점에 도달해서 성능이 다 비슷해지고, 그냥 익숙한 SDK 수준의 작은 차이만 남은 상황이어야만 타당한 전략임

    • 명령어나 인자만 다를 뿐이므로 사실상 종속(lock-in)이 심하진 않다고 생각함. 결국 입력-출력 함수만 있으니 필요한 부분만 바꿔서 사용하거나 래핑하면 됨. 구조적으로 복잡한 건 없음

    • 현시점에서 Claude Code는 agent 기반 코딩 시장에서 차별점 역할을 하고 있다고 생각함. AI code assistant를 직접 개발 중인데, Claude Code 연동을 제일 먼저 시도하게 됨. 초기에 lock-in을 신경 쓸 시점은 아니라고 느낌. 최고의 것을 골라서 그 위주로 개발을 시작해야 한다고 생각함

  • Claude Code는 이미 비상호작용(non-interactive) 모드로도 사용 가능했기 때문에, UNIX 커맨드라인 유틸리티처럼 다른 앱에 쉽게 통합 가능했다는 점을 강조하고 싶음. 이번 SDK도 커맨드라인 사용만 지원하고 있는데, 본질적으로는 기존에 있던 것과 뭐가 다른 건지 잘 모르겠음. 내가 놓치고 있는 포인트가 뭔지 궁금함

  • "서비스를 일반 지능에 경쟁하는 어떤 제품이나 서비스 개발, 훈련, 혹은 리셀을 금지한다"는 Anthropic의 이용 약관을 인용함. 사실상 모든 소프트웨어가 일반 지능에 "경쟁"하는 범주라면, 이를 엄격 해석하면 그 어떤 용도로도 쓸 수 없는 셈 아닌가? 이런 법적 문구 자체가 너무 모호해서 적용 불가하다고 생각함. AI의 결과물을 소유하지만 일반 지능에 경쟁이 안 된다는 식인데, 왜 이렇게 포괄적으로 금지하는지 궁금함. 그냥 법적 책임은 유저가 지라는 뜻인가? 여러 의문이 듦

    • 변호사들이 원하는 대로 규정을 만들면 이런 일이 생긴다고 생각함

  • 새로 추가된 GitHub Action이 내가 찾던 기능과 정확히 일치해서 너무 반가움. https://docs.anthropic.com/en/docs/claude-code/github-action... 그런데 Claude Code의 Max plan과 연동해서 쓸 수 있는 방법이 현재 없는 것 같음. api key만 입력받는 구조라 약간 아쉬움

  • 특히 GitHub Actions와 issue/PR 연동 기능이 내가 그간 원하던 기능임을 강조하고 싶음. https://docs.anthropic.com/en/docs/claude-code/github-action...

  • copilot을 통해 Claude 지원이 시작되면 꼭 써볼 생각임. 회사 정책상 아직 그 외 도구는 사용할 수 없는 상황임

답변달기