Claude를 사용한 LLM 기반 애플리케이션 구축
이 스킬은 Claude를 사용하여 LLM 기반 애플리케이션을 구축하는 방법을 알려줍니다. 필요에 따라 적절한 표면을 선택하고, 프로젝트 언어를 감지한 후 관련 언어별 문서를 읽어보세요.
시작하기 전에
대상 파일(또는 대상 파일이 없으면 프롬프트와 프로젝트)에서 Anthropic 이외의 제공업체 마커를 스캔하세요 — import openai, from openai, langchain_openai, OpenAI(, gpt-4, gpt-5, agent-openai.py 또는 *-generic.py 같은 파일 이름, 또는 코드를 제공업체 중립적으로 유지하라는 명시적 지시. 찾으면 중단하고 사용자에게 이 스킬이 Claude/Anthropic SDK 코드를 생성한다고 알리고, 파일을 Claude로 전환할지 또는 비-Claude 구현을 원하는지 물어보세요. Anthropic이 아닌 파일을 Anthropic SDK 호출로 편집하지 마세요.
출력 요구 사항
사용자가 Claude 기능을 추가, 수정 또는 구현하도록 요청하면 코드는 다음 중 하나를 통해 Claude를 호출해야 합니다:
- 프로젝트 언어의 공식 Anthropic SDK (
anthropic,@anthropic-ai/sdk,com.anthropic.*등). 프로젝트에 지원되는 SDK가 있을 때 기본값입니다. - 원시 HTTP (
curl,requests,fetch,httpx등) — 사용자가 명시적으로 cURL/REST/원시 HTTP를 요청하거나, 프로젝트가 셸/cURL 프로젝트이거나, 언어에 공식 SDK가 없는 경우에만 사용합니다.
둘을 혼합하지 마세요 — Python이나 TypeScript 프로젝트에서 더 가볍다고 requests/fetch를 사용하지 마세요. OpenAI 호환 shim으로 대체하지 마세요.
SDK 사용법을 추측하지 마세요. 함수 이름, 클래스 이름, 네임스페이스, 메서드 시그니처, 임포트 경로는 명시적인 문서에서 가져와야 합니다 — 이 스킬의 {lang}/ 파일 또는 shared/live-sources.md에 나열된 공식 SDK 리포지토리나 문서 링크에서. 필요한 바인딩이 스킬 파일에 명시적으로 문서화되어 있지 않으면, 코드를 작성하기 전에 shared/live-sources.md에서 관련 SDK 리포지토리를 웹페치하세요. cURL 모양이나 다른 언어의 SDK에서 Ruby/Java/Go/PHP/C# API를 유추하지 마세요.
웹페치 또는 리포지토리 접근이 실패하면 (네트워크 제한, 시간 초과, 클론 차단): 재시도하지 말고 — {lang}/ 파일의 패턴과 네임스페이스/패키지 테이블에서 코드를 작성하고, 컴파일러나 인터프리터를 실행한 후 오류 출력을 반복하세요. 정적 타입 SDK(C#, Java, Go)의 경우 로컬 오류에 대한 컴파일-수정 루프가 차단된 네트워크 연구보다 작업 코드에 더 빠르게 도달합니다.
기본값
사용자가 달리 요청하지 않는 한:
Claude 모델 버전의 경우, 정확한 모델 문자열 claude-opus-5로 접근할 수 있는 Claude Opus 5를 사용하세요. 복잡한 작업에는 적응형 사고(thinking: {type: "adaptive"})를 기본으로 사용하세요. 마지막으로, 긴 입력, 긴 출력 또는 높은 max_tokens가 관련된 요청에는 스트리밍을 기본값으로 사용하세요 — 요청 시간 초과를 방지합니다. SDK의 .get_final_message() / .finalMessage() 헬퍼를 사용하여 개별 스트림 이벤트를 처리할 필요가 없을 때 전체 응답을 얻으세요.
⚠️ API 변경 — 훈련 데이터가 오래되었을 수 있습니다
2025~2026년에 여러 일반적인 Claude API 형태가 변경되었습니다. 훈련에서 패턴을 기억한다면, 코드를 작성하기 전에 이 스킬의 {lang}/ 파일에서 확인하세요 — 아래 행은 가장 빈번한 변경 지점입니다:
| 영역 | 구버전 API | 현재 API |
|---|---|---|
| 확장된 사고 | thinking: {type: "enabled", budget_tokens: N} | Claude 4.6+ 모델: thinking: {type: "adaptive"}. budget_tokens는 Opus 4.6 / Sonnet 4.6에서 더 이상 사용되지 않으며 Fable 5 / Sonnet 5 / Opus 5 / 4.8 / 4.7에서 400 오류와 함께 거부됩니다. 4.6 이전 모델은 여전히 budget_tokens를 사용합니다. |
| 웹 검색 / 웹 페치 도구 유형 | web_search_20250305, web_fetch_20250910 | web_search_20260209, web_fetch_20260209 (동적 필터링) (Opus 5/4.8/4.7/4.6, Sonnet 5, Sonnet 4.6). 구형 모델은 기본 변형을 유지합니다. Vertex AI에서는 기본 web_search_20250305만 사용 가능합니다 (웹 페치는 Vertex에 없음) — 아래 서버 도구 빠른 참조를 참조하세요. |
| PHP 매개변수 이름 | 명명된 인수로서의 snake_case 와이어 이름 (max_tokens) | 최상위 명명된 인수는 camelCase (maxTokens). 중첩 배열 키는 기능에 따라 다릅니다 (예: 'taskBudget', 'skillID', 'mcp_server_name') — 문서화된 예제에서 정확한 키를 복사하세요. 일괄 변환하지 마세요. |
| 관리형 에이전트 자격 증명 | 사용자 정의 도구를 통해 호스트 측에서 비밀 유지 (볼트가 출시되기 전의 유일한 옵션) | Vault environment_variable 자격 증명 — Anthropic이 저장하고, 송신 시 대체되며, 샌드박스에서 절대 표시되지 않습니다 (shared/managed-agents-tools.md → Vaults). 호스트 측 사용자 정의 도구는 자체 호스팅 샌드박스의 대체 수단으로 남아 있습니다. |
이 스킬의 {lang}/ 파일은 기억된 패턴보다 권위가 있습니다.
하위 명령어
이 프롬프트 하단의 사용자 요청이 순수한 하위 명령어 문자열(설명 없음)인 경우, 이 문서의 모든 하위 명령어 테이블(아래에 추가된 섹션 포함)을 검색하고 일치하는 Action 열을 직접 따르세요. 이를 통해 사용자는 /claude-api <하위 명령어>로 특정 흐름을 호출할 수 있습니다. 문서의 어떤 테이블과도 일치하지 않으면 요청을 일반 설명으로 처리하세요.
| 하위 명령어 | 동작 |
|---|---|
migrate | 기존 Claude API 코드를 최신 모델로 마이그레이션합니다. 즉시 shared/model-migration.md를 읽고 순서대로 따르세요: 0단계 (범위 확인 — 편집 전 어떤 파일/디렉토리인지 물어보기), 1단계 (각 파일 분류), 그 다음 대상별 호환성 변경 사항 섹션. 가이드를 요약하지 말고 실행하세요. 사용자가 대상 모델을 지정하지 않았다면, 범위 질문과 동시에 마이그레이션할 모델을 물어보세요. |
언어 감지
코드 예제를 읽기 전에 사용자가 작업 중인 언어를 확인하세요:
-
프로젝트 파일을 보고 언어를 유추하세요:
*.py,requirements.txt,pyproject.toml,setup.py,Pipfile→ Python —python/에서 읽기*.ts,*.tsx,package.json,tsconfig.json→ TypeScript —typescript/에서 읽기*.js,*.jsx(.ts파일 없음) → TypeScript — JS는 동일한 SDK를 사용하므로typescript/에서 읽기*.java,pom.xml,build.gradle→ Java —java/에서 읽기*.kt,*.kts,build.gradle.kts→ Java — Kotlin은 Java SDK를 사용하므로java/에서 읽기*.scala,build.sbt→ Java — Scala는 Java SDK를 사용하므로java/에서 읽기*.go,go.mod→ Go —go/에서 읽기*.rb,Gemfile→ Ruby —ruby/에서 읽기*.cs,*.csproj→ C# —csharp/에서 읽기*.php,composer.json→ PHP —php/에서 읽기
-
여러 언어가 감지되면 (예: Python과 TypeScript 파일 모두):
- 사용자의 현재 파일이나 질문이 어떤 언어와 관련이 있는지 확인하세요
- 여전히 모호하면 질문: "Python과 TypeScript 파일이 모두 감지되었습니다. Claude API 통합에 어떤 언어를 사용하고 계신가요?"
-
언어를 추론할 수 없으면 (빈 프로젝트, 소스 파일 없음, 또는 지원되지 않는 언어):
- AskUserQuestion을 사용하여 옵션 제공: Python, TypeScript, Java, Go, Ruby, cURL/원시 HTTP, C#, PHP
- AskUserQuestion을 사용할 수 없으면 Python 예제를 기본값으로 사용하고 "Python 예제를 보여드립니다. 다른 언어가 필요하면 알려주세요."라고 메모
-
지원되지 않는 언어가 감지되면 (Rust, Swift, C++, Elixir 등):
curl/에서 cURL/원시 HTTP 예제를 제안하고 커뮤니티 SDK가 있을 수 있음을 알림- 참조 구현으로 Python 또는 TypeScript 예제를 제공하겠다고 제안
-
사용자가 cURL/원시 HTTP 예제가 필요한 경우,
curl/에서 읽으세요.
언어별 기능 지원
위의 모든 SDK 언어는 베타 도구 실행기와 관리형 에이전트(베타)를 모두 지원합니다 — Python (@beta_tool 데코레이터), TypeScript (betaZodTool + Zod), Java (어노테이션 클래스), Go (BetaToolRunner in toolrunner pkg), Ruby (BaseTool + tool_runner), C# (BetaToolRunner + 원시 JSON 스키마), PHP (BetaRunnableTool + toolRunner()); 코드 진입점은 아래 도구 사용 패턴 빠른 참조에 있습니다. cURL은 원시 HTTP(SDK 기능 없음)이며 관리형 에이전트를 지원합니다.
관리형 에이전트 코드 예제: 아래
## 관리형 에이전트 (베타)섹션의 읽기 가이드를 참조하세요.
어떤 표면을 사용해야 하나요?
간단하게 시작하세요. 필요에 맞는 가장 간단한 계층을 기본값으로 사용하세요. 단일 API 호출과 워크플로우가 대부분의 사용 사례를 처리합니다 — 작업이 진정으로 개방형, 모델 기반 탐색을 요구할 때만 에이전트에 도달하세요. "가장 간단함"은 당신이 소유해야 하는 코드가 가장 적다는 것을 의미합니다: 호스팅, 예약 또는 메모리 백업 에이전트의 경우 관리형 에이전트가 일반적으로 가장 간단한 옵션입니다(루프 코드, 상태 파일, 스케줄러 없음). 더 큰 플랫폼임에도 불구하고.
| 사용 사례 | 계층 | 권장 표면 | 이유 |
|---|---|---|---|
| 분류, 요약, 추출, Q&A | 단일 LLM 호출 | Claude API | 하나의 요청, 하나의 응답 |
| 배치 처리 또는 임베딩 | 단일 LLM 호출 | Claude API | 특수 엔드포인트 |
| 코드 제어 로직을 사용한 다단계 파이프라인 | 워크플로우 | Claude API + 도구 사용 | 사용자가 루프를 조율 |
| 자체 도구를 사용한 사용자 정의 에이전트 | 에이전트 | Claude API + 도구 사용 | 최대 유연성 |
| 서버 관리 상태 저장 에이전트(작업 공간 포함) | 에이전트 | 관리형 에이전트 | Anthropic이 루프를 실행하고 도구 실행 샌드박스를 호스팅 |
| 지속적, 버전 관리 에이전트 구성 | 에이전트 | 관리형 에이전트 | 에이전트는 저장된 객체이며, 세션은 버전에 고정 |
| 파일 마운트가 있는 장기 실행 다중 턴 에이전트 | 에이전트 | 관리형 에이전트 | 세션별 컨테이너, SSE 이벤트 스트림, 스킬 + MCP |
| 예약 실행 에이전트 (cron, "매일 밤") | 에이전트 | 관리형 에이전트 — 예약 배포 | 배포가 자율적으로 세션을 실행하며, 클라이언트 측 스케줄러 불필요 |
참고: 관리형 에이전트는 Anthropic이 에이전트 루프를 실행하고 도구가 실행되는 컨테이너를 호스팅하도록 할 때 적합한 선택입니다 — 파일 작업, bash, 코드 실행 모두 세션별 작업 공간에서 실행됩니다. 컴퓨팅을 직접 호스팅하거나 자체 사용자 정의 도구 런타임을 실행하려면 Claude API + 도구 사용이 적합합니다 — 도구 실행기를 에이전트 루프에 사용하세요 — 턴별 후크는 여전히 승인 게이트, 로깅, 오류 가로채기, 조건부 실행을 제공합니다(
shared/tool-use-concepts.md참조) — 또는 전체 루프를 직접 소유하려면 수동 루프를 사용하세요.
클라우드 제공업체 접근. AWS의 Claude 플랫폼은 Anthropic이 운영하며, 동일한 날 API 패리티를 제공합니다 — 클라이언트 설정은
shared/claude-platform-on-aws.md를 참조하세요. AWS의 Claude 플랫폼, Amazon Bedrock, Google Vertex AI, Microsoft Foundry의 기능별 가용성은shared/platform-availability.md를 참조하세요 — 이 테이블은 이 스킬의 단일 정보 출처입니다. 다른 곳에서 가용성을 유추하지 마세요.
에이전트 구축: 네 가지 접근 방식
실제로 에이전트가 필요하다고 결정한 후(개방형, 모델 기반 도구 사용), 구축할 수 있는 네 가지 뚜렷한 방법이 있습니다. 두 가지 독립적인 질문이 이를 구분합니다: 누가 하니스를 공급하는가 (에이전트 루프 + 컨텍스트 관리)와 누가 배포를 공급하는가 (에이전트가 실행되는 인프라). 도구 실행기와 Claude Agent SDK는 모두 하니스만 공급합니다 — 여전히 직접 호스팅하고 배포해야 하므로 쉽게 혼동됩니다. 관리형 에이전트(CMA)는 하니스와 관리형 배포를 모두 공급하는 유일한 옵션입니다. 수동 루프는 둘 다 공급하지 않습니다.
| # | 접근 방식 | 사용자가 작성하는 것 | 하니스 및 배포 | 사용 가능한 도구 | 사용 시기 |
|---|---|---|---|---|---|
| 1 | Claude API — 수동 루프 | 직접 while stop_reason == "tool_use" 루프 | 사용자가 하니스를 구축하고 호스팅 | 사용자가 정의한 도구만 | 전체 루프를 직접 소유하려는 경우 — 베타 종속성 없음, 또는 도구 실행기의 턴별 후크가 맞지 않는 제어 흐름 |
| 2 | Claude API — 도구 실행기 (client.beta.messages.tool_runner + @beta_tool / betaZodTool) | 도구 함수만 | SDK가 하니스만 제공; 사용자가 호스팅 | 사용자가 정의한 도구만 | 루프를 직접 작성하지 않고 사용자 정의 도구 에이전트(대부분의 경우). 턴별 후크는 여전히 승인 게이트, 오류 가로채기, 결과 수정(예: cache_control), 재시도, 스트리밍, 압축을 제공 |
| 3 | 관리형 에이전트 (REST, 베타) | 에이전트 구성 + 도구 결과 | Anthropic이 하니스를 제공하고 세션별 샌드박스 호스팅 (하니스 + 배포) | Anthropic 호스팅 샌드박스 (bash, 파일, 코드 실행) + 스킬/MCP + 사용자 도구 | Anthropic이 루프를 실행하고 세션별 작업 공간을 호스팅하기를 원할 때; 지속적/버전 관리 구성; 장기 실행 세션 |
| 4 | Claude Agent SDK — 별도 제품 (claude-agent-sdk / @anthropic-ai/claude-agent-sdk) | 프롬프트 + 옵션 | SDK가 Claude Code 하니스 + 내장 도구 제공 (하니스만); 사용자가 호스팅 | 내장 읽기/쓰기/편집/bash/glob/grep/웹 검색/웹 페치 + MCP + 하위 에이전트 | 자체 인프라에서 실행되는 완전한 기능의 코딩/파일 시스템 에이전트를 원할 때 |
하니스/배포 분할이 핵심 개념입니다: 옵션 1, 2, 4는 모두 배포를 사용자에게 맡깁니다. 옵션 3(CMA)만 관리형 배포를 추가합니다. 옵션 1~3은 이 스킬이 생성하는 것입니다. 옵션 4는 자체 문서가 있는 다른 라이브러리입니다 — 아래 명확한 구분을 참조하세요.
도구 실행기 ≠ Claude Agent SDK. 이름은 비슷하지만 다른 패키지입니다:
- 도구 실행기는 일반 Anthropic API SDK(
anthropic/@anthropic-ai/sdk)의 일부이며client.beta.messages.tool_runner를 통해 접근합니다. 자동화...