Claude Code를 매일 쓰면서 작성한 CLAUDE.md, 스킬(skills), MCP 서버 설정이 그대로 프로덕션 AI 에이전트의 런타임이 된다면 어떨까. Claude Agent SDK는 바로 이 아이디어를 실현하는 Node.js/TypeScript 라이브러리다. Claude Code에서 쓰던 .claude/ 폴더 구조를 그대로 앱 서버에 배포해, 별도의 에이전트 프레임워크(LangGraph, n8n 등) 없이 프로덕션 에이전트를 구동할 수 있다.

핵심 특징 / 차별점

주요 개념 — “.claude/ 폴더가 프로덕션 런타임”

Claude Code에서 이미 사용하던 5가지 프리미티브(primitive)가 그대로 프로덕션 에이전트의 구성 요소가 된다:

1. CLAUDE.md — 에이전트의 정체성, 규칙, 제약. 개발 환경에서는 Claude Code의 동작을 정의하고, 프로덕션에서는 시스템 프롬프트로 로드된다.
2. Skills (.claude/skills/) — 재사용 가능한 동작 정의. Markdown 파일. 개발/프로덕션 동일한 포맷.
3. MCPs (.claude/mcp.json) — 에이전트가 사용할 도구 서버. 개발에선 파일시스템·브라우저, 프로덕션에선 DB·검색 API를 지정.
4. Hooks — 도구 이벤트(PreToolUse, PostToolUse)에 반응하는 함수. 위험한 파일 접근 차단, 비용·소요 시간 로깅 등에 활용.
5. Sub-agents (.claude/agents/<name>/) — 각 디렉터리가 독립적인 에이전트. 새 에이전트 추가 = 새 폴더 생성.

모든 설정이 파일이므로 버전 관리되고, PR에서 diff로 리뷰 가능하다.

아키텍처 — 함수 한 줄이 워크플로우를 대체한다

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

for await (const msg of query({
  prompt: userQuestion,
  options: {
    cwd: './.claude/agents/knowledge-agent', // 에이전트 디렉터리
    settingSources: ['project'],             // CLAUDE.md, skills, MCP 자동 로드
    allowedTools: ['Read', 'Glob', 'Grep'],
    maxTurns: 5,
    maxBudgetUsd: 0.15,
    model: 'claude-sonnet-4-6',
  },
})) {
  // 스트리밍 응답 처리
}

settingSources: ['project']를 설정하면 cwd에 지정한 에이전트 디렉터리의 CLAUDE.md, 스킬, MCP 설정을 자동으로 로드한다. 앱은 라우팅·인증·CRUD를 담당하고, 에이전트는 추론·도구 선택·반복 처리를 담당한다.

언제 쓰면 좋은가

• 이미 Claude Code를 사용 중이고, 같은 설정을 서비스에 그대로 쓰고 싶을 때
• LangGraph/n8n 같은 별도 프레임워크를 배우지 않고 프로덕션 에이전트를 빠르게 만들고 싶을 때
• 에이전트 동작을 코드 배포 없이 Markdown 편집만으로 빠르게 수정하고 싶을 때
• PM이나 기획자가 직접 에이전트 동작을 조정해야 하는 팀

Claude Managed Agents와 비교

Claude Agent SDK는 자신의 서버에서 에이전트를 직접 실행하는 방식. 이미 서버를 운용 중인 앱이라면 SDK가 더 가볍다. Claude Managed Agents는 Anthropic이 호스팅하는 런타임이 필요할 때 선택한다.

라이선스 및 참고

공식 패키지: @anthropic-ai/claude-code (npm) GitHub: anthropics/claude-code

관련 문서

• claude-code-routines — Claude Code 루틴 자동화
• agent-skills — 에이전트 스킬 시스템
• codeburn — Claude Code 토큰 사용량 모니터링