Claude Agent SDK 입문: Claude Code를 앱에 안전하게 연결하기

Claude Code를 터미널에서 쓰는 개발 도우미로만 두지 않고, 사내 도구, CI, PR 사전 점검, 콘텐츠 QA, 장애 대응 콘솔에 연결하고 싶다면 현재 기준은 Claude Agent SDK입니다.

예전 글과 검색 결과에는 @anthropic-ai/claude-code, claude-code-sdk, “Claude Code SDK”라는 표현이 아직 남아 있습니다. 하지만 2026년 6월 기준 공식 문서는 TypeScript 패키지로 @anthropic-ai/claude-agent-sdk, Python 패키지로 claude-agent-sdk를 안내합니다. 코드를 복사하기 전에 공식 Agent SDK overview와 Migration Guide를 확인하는 편이 안전합니다.

이 글은 단순 챗봇 예제가 아닙니다. 파일을 읽고, 코드베이스를 검색하고, MCP 도구를 호출하고, 제한된 범위에서 작은 수정을 만들고, 지정된 테스트를 실행한 뒤 사람이 검토할 수 있는 결과를 남기는 흐름을 다룹니다.

현재 기준으로 보는 Agent SDK

Claude Agent SDK는 Claude Code의 agent loop를 TypeScript나 Python 애플리케이션에서 사용할 수 있게 합니다. agent loop는 모델이 다음 행동을 고르고, 도구를 호출하고, 결과를 읽은 뒤 다시 판단하는 반복 흐름입니다. 한 번의 채팅 API 호출과 달리 파일 읽기, 검색, 편집, 명령 실행이 여러 턴에 걸쳐 일어날 수 있습니다.

항목	현재 권장
TypeScript 패키지	@anthropic-ai/claude-agent-sdk
Python 패키지	claude-agent-sdk
CLI와 SDK	CLI는 사람의 대화용, SDK는 앱과 자동화용
Client SDK와 Agent SDK	Client SDK는 tool loop를 직접 구현, Agent SDK는 Claude Code의 loop 사용
가장 큰 리스크	권한이 넓을수록 유용하지만 사고 범위도 커짐

TypeScript SDK는 보통 플랫폼별 Claude Code native binary를 optional dependency로 포함하므로 CLI를 따로 설치하지 않아도 됩니다. 다만 package manager가 optional dependencies를 건너뛰면 native binary를 찾지 못하는 오류가 날 수 있습니다. 이때는 설치 정책을 고치거나 별도로 설치한 claude 경로를 pathToClaudeCodeExecutable에 넘깁니다.

복사해서 실행하는 최소 구성

아래는 TypeScript와 tsx를 사용해 바로 실행하는 구성입니다.

mkdir claude-agent-sdk-demo
cd claude-agent-sdk-demo
npm init -y
npm install @anthropic-ai/claude-agent-sdk zod
npm install -D typescript tsx @types/node

package.json을 다음처럼 정리합니다.

{
  "type": "module",
  "scripts": {
    "audit": "tsx src/read-only-audit.ts",
    "runbook": "tsx src/runbook-agent.ts",
    "fix": "tsx src/safe-fix.ts"
  },
  "dependencies": {
    "@anthropic-ai/claude-agent-sdk": "latest",
    "zod": "latest"
  },
  "devDependencies": {
    "@types/node": "latest",
    "tsx": "latest",
    "typescript": "latest"
  }
}

API key는 환경 변수로만 전달합니다. 저장소, 문서, CI 로그에 직접 쓰지 않습니다.

export ANTHROPIC_API_KEY="sk-ant-..."

Windows PowerShell에서는 다음과 같습니다.

$env:ANTHROPIC_API_KEY = "sk-ant-..."

먼저 src/read-only-audit.ts를 만듭니다. 이 에이전트는 읽기와 검색만 할 수 있고 편집이나 Bash 실행은 하지 못합니다.

import { query } from "@anthropic-ai/claude-agent-sdk";

const prompt = [
  "이 repository를 읽기 전용으로 점검하세요.",
  "TODO 주석, 오래된 의존성, 테스트가 약한 부분을 찾으세요.",
  "우선순위와 구체적인 파일 경로를 함께 보고하세요.",
].join("\n");

for await (const message of query({
  prompt,
  options: {
    cwd: process.cwd(),
    allowedTools: ["Read", "Glob", "Grep"],
    maxTurns: 4,
  },
})) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}

실행합니다.

npm run audit

처음부터 Edit나 Bash를 열지 않는 것이 핵심입니다. 읽기 전용으로 결과가 유용한지 확인한 뒤 권한을 넓혀야 합니다.

자동화할 가치가 있는 사용 사례

Claude Agent SDK는 단순 답변보다 관찰, 도구 사용, 판단이 필요한 일에 어울립니다. Masa의 콘텐츠 운영과 개발 흐름에서는 다음 네 가지가 특히 현실적입니다.

사용 사례	도구	결과물	안전장치
PR 사전 리뷰	Read, Glob, Grep	위험 목록, 누락 테스트, 리뷰 관점	최종 코멘트는 사람이 게시
작은 코드 수정	Read, Edit, Bash(npm test)	작은 diff와 테스트 결과	push, deploy, 삭제 명령 금지
장애 1차 조사	MCP runbook, 로그 검색	가설과 다음 확인 항목	production 도구는 읽기 전용
다국어 기사 QA	Read, Grep	깨진 문자, CTA 누락, 오래된 링크 후보	번역 자연스러움은 사람이 확인

관련해서 Claude Code 권한 가이드, MCP 서버 가이드, Claude Code 생산성 팁을 함께 읽으면 SDK 자동화를 운영 규칙으로 묶는 데 도움이 됩니다.

MCP로 Runbook 도구 추가하기

MCP는 Model Context Protocol입니다. 에이전트가 외부 도구와 데이터 소스를 호출할 수 있게 하는 표준이라고 이해하면 됩니다. 공식 MCP guide는 Agent SDK에서 MCP 서버를 연결하는 방법을 설명합니다. 여기서는 같은 프로세스 안에서 작은 읽기 전용 도구를 정의합니다.

import {
  createSdkMcpServer,
  query,
  tool,
} from "@anthropic-ai/claude-agent-sdk";
import { z } from "zod";

const runbooks: Record<string, string> = {
  billing: "결제 실패율, Stripe webhook, 최근 deploy를 확인한다.",
  search: "index 시간, Algolia task status, API limit을 확인한다.",
  content: "CMS sync, locale slug, hero image 존재 여부를 확인한다.",
};

const lookupRunbook = tool(
  "lookup_runbook",
  "서비스 이름으로 읽기 전용 운영 Runbook을 반환한다",
  { service: z.string().min(1) },
  async ({ service }) => {
    const text = runbooks[service] ?? "해당 Runbook이 없습니다.";
    return { content: [{ type: "text", text }] };
  },
  { annotations: { readOnlyHint: true, openWorldHint: false } },
);

const runbookServer = createSdkMcpServer({
  name: "runbook",
  version: "1.0.0",
  tools: [lookupRunbook],
});

for await (const message of query({
  prompt: "content 게시 사고가 났을 때 첫 확인 항목을 제안하세요.",
  options: {
    mcpServers: { runbook: runbookServer },
    allowedTools: ["mcp__runbook__lookup_runbook"],
    maxTurns: 3,
  },
})) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}

자주 나는 실수는 tool 이름입니다. MCP tool은 mcp__serverName__toolName 형태로 허용해야 합니다. lookup_runbook만 넣으면 SDK 도구 호출이 승인되지 않습니다.

편집을 허용할 때의 최소 권한

읽기 전용 점검이 쓸모 있다면 작은 수정까지 맡길 수 있습니다. 하지만 범위를 좁혀야 합니다. 공식 permissions guide는 파일 쓰기나 명령 실행을 허용하기 전에 꼭 읽어야 합니다.

import { query } from "@anthropic-ai/claude-agent-sdk";

const prompt = [
  "src 아래의 작은 TypeScript 오류 하나만 고치세요.",
  "수정 후 npm test를 실행하고 diff 요약과 결과를 보고하세요.",
  "큰 refactor와 의존성 추가는 금지입니다.",
].join("\n");

for await (const message of query({
  prompt,
  options: {
    cwd: process.cwd(),
    allowedTools: [
      "Read",
      "Glob",
      "Grep",
      "Edit",
      "Bash(npm test)",
    ],
    disallowedTools: [
      "Bash(git push)",
      "Bash(git commit)",
      "Bash(rm -rf *)",
    ],
    permissionMode: "default",
    maxTurns: 6,
  },
})) {
  if (message.type === "result") {
    console.log(message.subtype, message.result ?? "");
  }
}

이 패턴은 에이전트에게 모든 권한을 주는 방식이 아닙니다. 사람이 검토할 수 있는 작은 diff와 테스트 증거를 만들기 위한 방식입니다.

실패 사례와 함정

첫 번째 함정은 오래된 이름입니다. @anthropic-ai/claude-code나 ClaudeCodeOptions를 보면 그대로 복사하지 말고 Migration Guide를 확인하세요.

두 번째는 넓은 Bash 허용입니다. 단순히 Bash만 열면 테스트 외에도 deploy, git 작업, 삭제, 의존성 설치가 후보가 됩니다. 처음에는 Bash(npm test)처럼 명령을 좁히세요.

세 번째는 cwd를 명시하지 않는 것입니다. 로컬, CI, background worker가 서로 다른 위치에서 실행될 수 있습니다. production에서는 대상 repository를 분명히 지정해야 합니다.

네 번째는 Agent SDK를 일반 채팅 SDK처럼 다루는 것입니다. Agent 실행은 여러 tool turn과 파일 읽기를 포함할 수 있어 시간과 비용이 커집니다. 공식 cost tracking guide를 보고 usage와 제한을 기록하세요.

다섯 번째는 custom tool 설명이 흐린 것입니다. 이름, 설명, schema, read-only 여부를 명확히 하지 않으면 Claude가 언제 써야 하는지 판단하기 어렵습니다.

출시 전 체크와 CTA

• API key와 외부 token이 로그에 나오지 않는다
• 첫 실행은 Read, Glob, Grep만 허용한다
• 쓰기 허용 시 cwd, allowedTools, disallowedTools, maxTurns를 설정한다
• MCP 도구는 읽기 전용과 파괴적 작업을 분리한다
• 테스트 명령은 구체적으로 제한한다
• merge 전 사람이 diff와 test output을 확인한다
• 템플릿 공개 전 공식 문서와 changelog를 다시 확인한다

Claude Agent SDK의 질문은 “얼마나 자동화할 수 있나”가 아니라 “자동화 결과를 어떻게 review 가능하게 만들 것인가”입니다. 이 원칙은 개발뿐 아니라 수익화된 콘텐츠 운영에도 중요합니다. 기사 업데이트, CTA, 제품 링크, analytics event, 상담 폼은 한 번의 자동화로 함께 바뀔 수 있습니다.

혼자 시작한다면 무료 Claude Code cheatsheet로 안전한 기본 명령을 익히세요. 반복 가능한 프롬프트와 설정 자료가 필요하면 제품 템플릿을 확인하세요. 팀 단위 권한, MCP, CI review gate, rollout 교육은 Claude Code 교육 및 상담에서 설계하는 편이 안전합니다.

실제 확인 메모

이번 갱신에서는 공식 Agent SDK overview, TypeScript reference, MCP guide, permissions guide, migration guide, cost tracking 문서를 확인하고 예제를 현재 @anthropic-ai/claude-agent-sdk 형식으로 바꿨습니다. 가장 효과적인 변경은 첫 예제를 읽기 전용으로 둔 것입니다. npm run audit로 먼저 관찰하고, 그 다음 MCP, 편집, 테스트 실행으로 넓히는 흐름이 실제 repository에도 적용하기 쉽습니다.