Claude Code Agent SDK 선택법: 터미널 자동화를 제품 루프로 옮기는 기준 | DAKER 커뮤니티
Claude Code Agent SDK는 터미널에서 반복하던 작업을 제품 루프나 내부 서비스로 옮길 때 먼저 검토할 선택지입니다. Claude Code Agent SDK란, Claude Code의 agent loop와 도구 사용 흐름을 Python·TypeScript 애플리케이션 안에서 재사용하는 개발자용 SDK입니다. 공식 문서는 Agent SDK, CLI, Client SDK, Managed Agents의 쓰임을 분리해 설명하므로, 팀 자동화가 커질수록 선택 기준을 먼저 세우는 편이 안전합니다.
문제 상황: 언제 Claude Code Agent SDK를 봐야 하나요?
처음에는 터미널에서 한 번 실행하면 충분합니다. 그런데 같은 작업이 매일 반복되고, 결과를 대시보드나 사내 도구에 붙여야 하는 순간부터는 CLI 프롬프트만으로 운영 기준을 맞추기 어렵습니다.
핵심 개념: 무엇을 기준으로 판단하나요?
핵심은 모델 성능 비교가 아니라 tool loop를 누가 책임지느냐입니다. CLI는 사람이 터미널에서 주도할 때 편하고, Agent SDK는 제품 코드가 agent loop를 품어야 할 때 맞습니다.
단계별 사용법: 오늘 어떤 순서로 적용하나요?
아래 순서는 처음 적용하는 팀이 바로 따라 할 수 있는 최소 루틴입니다.
- 반복되는 작업이 일회성 터미널 실행인지 제품 기능인지 먼저 나눕니다.
- 파일 읽기, 명령 실행, MCP 연결, 권한 판단이 필요한지 적습니다.
- Python 또는 TypeScript 서비스에서 agent loop를 직접 품어야 하면 Agent SDK 후보로 올립니다.
- 다른 언어에서는 CLI의 비대화 실행과 JSON 출력으로 충분한지 먼저 검산합니다.
- 사용자 승인, 세션 보존, 로그 보관, 실패 재시도 기준을 배포 전에 문서화합니다.
짧은 예시: 선택 기준을 어떻게 말하면 좋나요?
작업 요청에는 목표, 확인 기준, 남은 한계를 함께 씁니다. 그러면 Claude Code 세션이 끝날 때 결과와 미확인 범위를 분리해 보고하기 쉬워집니다.
| 선택지 | 맞는 상황 | 주의할 점 |
|---|---|---|
| Claude Code CLI | 터미널에서 사람이 주도하는 반복 작업 | 제품 기능처럼 오래 돌릴 때는 운영 기준이 흩어질 수 있습니다 |
| Agent SDK | Python·TypeScript 서비스가 agent loop를 품어야 할 때 | 권한, 세션, 로그, 인증 기준을 코드로 관리해야 합니다 |
| Client SDK | 직접 API 호출과 자체 tool loop가 필요할 때 | Claude Code의 agent loop를 자동으로 가져오는 선택지는 아닙니다 |
| Managed Agents | 장기 실행 agent와 호스팅 sandbox가 필요할 때 | 서비스 경계와 비용 기준을 먼저 확인해야 합니다 |
워크플로 이미지: 어떤 흐름으로 기억하면 되나요?
팀 적용 체크리스트: 무엇을 빠뜨리면 안 되나요?
체크리스트는 자동화를 더 많이 켜기 위한 문서가 아니라, 끝났다고 말할 수 있는 증거를 남기는 장치입니다.
- 작업 결과가 사용자 화면이나 사내 서비스에 연결되나요?
- 권한 승인과 세션 저장 위치를 팀이 설명할 수 있나요?
- CLI로 충분한 일회성 작업을 SDK 프로젝트로 키우고 있지 않나요?
- 제품 안에서 Claude 브랜드와 인증 방식을 과장해 표시하지 않나요?
- 실패 시 재시도보다 중단해야 하는 조건을 따로 적었나요?
공식 출처: 어디를 기준으로 확인했나요?
작성 기준일 현재 기능 사실은 Anthropic 공식 Claude Code 문서 3개 항목으로 비공개 검증했습니다. 공개 링크는 DAKER 정책에 맞춰 아래 내부 링크만 남깁니다.
- DAKER 클로드 코드 디렉터리
- Claude Code Dynamic Workflows 실무법
- Claude Code workflow schema 안정화 글
- Claude Code agents 팀 보드 운영 글
FAQ: 자주 묻는 질문은 무엇인가요?
Agent SDK를 쓰면 Claude Code CLI가 필요 없어지나요?
아닙니다. CLI는 여전히 빠른 터미널 실험과 일회성 개발 작업에 적합합니다. SDK는 그 루프를 제품 코드 안에 넣어야 할 때 검토합니다.
Python이나 TypeScript가 아니면 Agent SDK를 못 쓰나요?
공식 문서 기준 SDK는 Python과 TypeScript용입니다. 다른 언어에서는 CLI 비대화 실행과 JSON 출력을 subprocess로 쓰는 방법부터 검토합니다.
Client SDK와 Agent SDK의 가장 큰 차이는 무엇인가요?
Client SDK는 API를 직접 호출하고 tool loop를 직접 설계하는 쪽입니다. Agent SDK는 Claude Code의 agent loop를 라이브러리처럼 쓰는 쪽입니다.
오늘 바로 할 결정은 무엇인가요?
반복 자동화 하나를 골라 CLI로 충분한지, 제품 코드 안의 agent loop가 필요한지 한 문장으로 분류해 보세요.
오늘은 팀의 Claude Code 작업 하나를 골라 목표, 확인 기준, 남은 한계를 세 줄로 다시 써 보세요.