byteforce

CPN 한국어 자습서 · Claude Code in Action

3 · 훅과 SDK

Claude Code SDK

The Claude Code SDK

방금 중복 쿼리 훅이 띄웠던 "또 다른 Claude" — 그것이 바로 SDK입니다. SDK는 Claude Code를 프로그램에서 부르게 해 줍니다. 터미널에서 쓰던 그 Claude Code 그대로, 같은 도구를 갖고 작업을 끝냅니다. 더 큰 파이프라인·도구·훅의 한 부품으로 끼워 넣을 때 가장 빛납니다.

전체 내레이션영상 나레이션 한국어 번역 (전체)›

Stephen Grider · Anthropic 기술 스태프

조금 전 쿼리 리뷰 훅을 보면서 Claude Code SDK를 잠깐 살펴봤습니다. SDK는 Claude Code를 프로그램으로 쓸 수 있게 해 줍니다. CLI로도, 타입스크립트 라이브러리로도, 파이썬 라이브러리로도 쓸 수 있습니다. 이건 여러분이 이미 터미널에서 쓰던 바로 그 Claude Code입니다. 같은 도구를 모두 갖고 있고, 그 도구들을 써서 주어진 작업을 끝냅니다.

SDK는 조금 전 훅에서 본 것처럼 더 큰 파이프라인이나 도구의 한 부분일 때 가장 쓸모가 큽니다. Claude Code를 더 큰 프로세스의 일부로 손쉽게 엮어, 어떤 워크플로에든 지능을 잔뜩 더해 넣을 수 있습니다.

타입스크립트 SDK를 우리 기존 프로젝트에 넣어 빠르게 보여 드리겠습니다. 에디터로 돌아가 루트 프로젝트 디렉터리의 sdk.ts 파일을 엽니다. 안에 SDK를 시작하기 좋은 짧은 코드를 미리 넣어 뒀습니다. 맨 위 프롬프트를 고쳐 src/queries 디렉터리에서 중복 쿼리를 찾아 달라고 시키겠습니다.

그런 다음 파일을 저장하고, 터미널을 열어 npm run sdk를 실행합니다. 참고로 이건 내장 명령 같은 게 아닙니다. 뒤에서는 이 파일을 평범한 타입스크립트 파일로 실행합니다. 타입스크립트 파일을 좀 더 편하게 돌리려고 만들어 둔 작은 단축키입니다.

실행하면 우리 로컬의 Claude Code와 Claude 언어 모델 사이의 대화 원문이 메시지 단위로 그대로 보입니다. 그러다 명령행으로 돌아오게 되고, 마지막에 찍히는 메시지가 Claude의 최종 응답을 담고 있습니다.

여기에 SDK의 작은 함정이 하나 있습니다. 기본값으로는 읽기 능력만 있다는 점입니다. 다시 말해 파일·디렉터리 읽기, grep 같은 것만 할 수 있고, 파일을 쓰거나 고치거나 새로 만들지는 못합니다.

쓰기 권한을 주려면 두 가지 방법이 있습니다. 하나는 여기 query 호출에 직접 쓰기 권한을 더하는 것이고, 다른 하나는 .claude 디렉터리 안의 설정 파일에 권한 설정을 넣는 것입니다. 이 프로젝트 안에서 SDK가 Edit 도구를 쓰도록 허용하는 법을 보여 드리겠습니다. 프롬프트 인자를 찾아 그 바로 뒤에 options를 더하고, 객체를 넣어 allowedTools를 배열로 두고 거기에 Edit을 넣습니다.

맨 위 프롬프트도 고쳐, package.json 파일에 설명(description)을 추가해 달라고 시키겠습니다. 저장하고 npm run sdk를 다시 돌립니다. 끝나고 나서 package.json을 열어 보면, 실제로 설명이 들어간 걸 볼 수 있습니다. 이제 확실히 파일을 고칠 능력이 생긴 것입니다.

앞서 말했듯 Claude Code SDK는 다른 도구의 일부일 때 가장 쓸모가 큽니다. 그러니 여러분 프로젝트의 헬퍼 명령, 스크립트, 그리고 무엇보다 훅 안에서 SDK를 쓸 기회를 떠올려 보시길 권합니다.

이 장에서 배우는 것What you'll learn

약 7분
1

SDK는 Claude Code를 프로그램에서 부른다 — 터미널과 같은 Claude·같은 도구

2

CLI · 타입스크립트 · 파이썬 세 가지 표면으로 쓸 수 있다

3

더 큰 파이프라인·도구·훅의 부품일 때 가장 빛난다

4

query() 호출 → 대화 원문이 메시지 단위로, 마지막이 최종 응답

5

함정: 기본값은 읽기 전용 — 쓰기·수정·생성은 막혀 있다

6

options.allowedTools나 .claude 설정으로 권한을 연다

먼저 짚고 갈 용어
Claude Code SDK
Claude Code를 프로그램에서 호출하는 도구. 터미널의 그 Claude Code와 같고, 같은 도구를 쓴다.
query()
SDK의 핵심 함수. 프롬프트를 넘기면 모델과의 대화를 메시지 단위로 돌려준다(비동기 순회).
allowedTools
query 호출에 줄 수 있는 옵션. SDK가 쓸 수 있는 도구를 열어 준다(기본은 읽기 전용).
npm run sdk
내장 명령이 아니라, sdk.ts를 평범한 타입스크립트 파일로 돌리려고 만든 단축키.

SDK란 — 프로그램 속의 Claude Code

Claude Code, programmatically

SDK는 Claude Code를 프로그램에서 부르게 해 줍니다. CLI·타입스크립트·파이썬 세 가지로 쓸 수 있고, 어느 쪽이든 터미널에서 쓰던 그 Claude Code입니다 — 같은 도구를 갖고 같은 방식으로 작업을 끝냅니다. 더 큰 파이프라인·도구·훅의 한 부품일 때 가장 빛납니다.

CLI

터미널에서 claude -p "…" 처럼 프린트(헤드리스) 모드로 한 번에 실행해 결과만 받는다.

TypeScript

@anthropic-ai/claude-agent-sdk의 query()로 호출. 이 레슨의 데모가 이 방식이다.

Python

claude-agent-sdk의 query()로 호출. 옵션 키는 allowed_tools(스네이크 표기).

왜 쓰나

조금 전 중복 쿼리 훅이 띄운 "또 다른 Claude"가 바로 이 SDK입니다. Claude Code를 더 큰 프로세스에 엮어, 워크플로에 지능을 더해 넣을 수 있습니다.

타입스크립트로 호출하기

A quick TypeScript demo

루트의 sdk.ts에서 프롬프트를 적고 query()로 호출합니다. 실행하면 로컬 Claude Code와 모델의 대화 원문이 메시지 단위로 보이고, 마지막 메시지가 최종 응답입니다.

SDK 사용 흐름 · 단계를 눌러 따라가기

핵심은 같은 Claude Code를 코드에서 부른다는 점입니다 — 그래서 헬퍼 스크립트·파이프라인·훅에 지능을 끼워 넣을 수 있습니다.

코드로 보기 & 권한 함정

Code & the read-only gotcha

query({ prompt })를 비동기로 순회하며 메시지를 출력합니다. 실행은 npm run sdk — 내장 명령이 아니라 sdk.ts를 돌리는 단축키입니다.

sdk.ts · query()로 호출
// sdk.ts — 루트 프로젝트 디렉터리. SDK로 Claude Code를 부른다(개념 예시).
import { query } from "@anthropic-ai/claude-agent-sdk";

const prompt = "src/queries 디렉터리에서 중복 쿼리를 찾아 줘";

for await (const message of query({ prompt })) {
  console.log(message);   // 대화를 메시지 단위로 출력
}
// 마지막에 찍히는 메시지가 Claude의 최종 응답을 담는다.
npm run sdk · 대화 원문과 최종 응답
$ npm run sdk      # 내장 명령 아님 — sdk.ts를 그냥 실행하는 단축키

● Read(src/queries/order_queries.ts)
● Grep("SELECT" in src/queries)
  ...                          # 로컬 Claude Code ↔ 모델의 대화 원문

● 최종 응답: order_queries.ts와 analytics_queries.ts에
  비슷한 집계 쿼리가 중복돼 있습니다. 하나로 합치길 권합니다.   # ← 마지막 메시지

여기에 함정이 있습니다. SDK는 기본값으로 읽기 전용입니다 — 읽기·grep은 되지만 쓰기·수정·생성은 막혀 있습니다. 권한을 열려면 options.allowedTools에 도구를 더하거나, .claude 설정 파일에 권한을 넣습니다.

options.allowedTools · 쓰기 권한 열기
// 함정: 기본값은 읽기 전용(읽기·grep만). 쓰기·수정·생성은 막혀 있다.
// Edit 도구를 허용하려면 prompt 뒤에 options를 더한다:

const prompt = "package.json에 description을 추가해 줘";

for await (const message of query({
  prompt,
  options: { allowedTools: ["Edit"] },   // 쓰기 권한을 연다
})) {
  console.log(message);
}
// 다시 실행하면 package.json에 description이 실제로 추가된다.
두 가지 방법

① query 호출에 직접 allowedTools를 준다(위 예시). ② .claude 디렉터리의 설정 파일에 권한을 넣어 프로젝트 전체에 적용한다. 파이썬에선 키 이름이 allowed_tools입니다.

정리 & 점검

Recap & check
핵심 정리
  • SDK는 Claude Code를 프로그램에서 부른다 — CLI·타입스크립트·파이썬, 같은 Claude·같은 도구.
  • query()를 순회하면 대화가 메시지 단위로, 마지막이 최종 응답이다.
  • 기본값은 읽기 전용 — allowedTools나 .claude 설정으로 쓰기 권한을 연다.
  • 헬퍼 명령·스크립트, 그리고 무엇보다 훅 안에서 쓸 때 가장 쓸모가 크다.

Q1Claude Code SDK가 하는 일은?

Q2npm run sdk의 정체는?

Q3SDK가 파일을 못 고칠 때 해야 할 일은?

MEMBER SESSION REQUIRED · REGISTRATION IS FREE

여기부터는 등록한 분에게 열립니다.

전 코스는 계속 무료입니다. 등록하면 이 코스의 남은 16개 레슨을 끝까지 읽을 수 있습니다.

등록하고 이어서 읽기

이미 등록하셨다면 그때 쓰신 이메일을 넣어 주세요.