📌 참고: 이 문서는 공식 Claude Code 문서의 원문 + 레퍼런스입니다.

• 원문 링크를 직접 사용하셔도 됩니다
• 이 파일을 .claude/skills/ 하위에 복사하여 스킬로 등록할 수도 있습니다

(2026.03.15 기준)

Claude로 LLM 기반 애플리케이션 구축하기

이 스킬은 Claude를 사용하여 LLM 기반 애플리케이션을 구축하는 데 도움을 줍니다. 필요에 따라 적합한 서피스를 선택하고, 프로젝트 언어를 감지한 다음, 해당 언어별 문서를 읽으세요.

기본값

사용자가 별도로 요청하지 않는 한:

Claude 모델 버전은 Claude Opus 4.6을 사용하세요. 정확한 모델 문자열 claude-opus-4-6으로 접근할 수 있습니다. 조금이라도 복잡한 작업에는 적응형 사고(thinking: {type: "adaptive"})를 기본으로 사용하세요. 마지막으로, 긴 입력, 긴 출력, 또는 높은 max_tokens를 포함할 수 있는 모든 요청에는 스트리밍을 기본으로 사용하세요 — 요청 타임아웃을 방지합니다. 개별 스트림 이벤트를 처리할 필요가 없다면 SDK의 .get_final_message() / .finalMessage() 헬퍼를 사용하여 완전한 응답을 받으세요.

---

언어 감지

코드 예제를 읽기 전에, 사용자가 작업 중인 언어를 확인하세요:

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/에서 읽기

2. 여러 언어가 감지된 경우 (예: Python과 TypeScript 파일이 모두 있는 경우):

   • 사용자의 현재 파일이나 질문이 어떤 언어와 관련되는지 확인하세요
   • 여전히 모호하다면 질문하세요: "Python과 TypeScript 파일이 모두 감지되었습니다. Claude API 통합에 어떤 언어를 사용하고 계신가요?"

3. 언어를 추론할 수 없는 경우 (빈 프로젝트, 소스 파일 없음, 또는 지원하지 않는 언어):

   • AskUserQuestion에 옵션을 제시하세요: Python, TypeScript, Java, Go, Ruby, cURL/raw HTTP, C#, PHP
   • AskUserQuestion을 사용할 수 없는 경우, Python 예제를 기본으로 사용하고 다음과 같이 안내하세요: "Python 예제를 표시합니다. 다른 언어가 필요하시면 알려주세요."

4. 지원하지 않는 언어가 감지된 경우 (Rust, Swift, C++, Elixir 등):

   • curl/의 cURL/raw HTTP 예제를 제안하고 커뮤니티 SDK가 있을 수 있음을 안내하세요
   • 참조 구현으로 Python 또는 TypeScript 예제를 보여줄 것을 제안하세요

5. 사용자가 cURL/raw HTTP 예제를 필요로 하는 경우, curl/에서 읽으세요.

언어별 기능 지원

언어	Tool Runner	Agent SDK	비고
Python	Yes (beta)	Yes	전체 지원 — @beta_tool 데코레이터
TypeScript	Yes (beta)	Yes	전체 지원 — betaZodTool + Zod
Java	Yes (beta)	No	어노테이션 클래스를 사용한 베타 도구
Go	Yes (beta)	No	toolrunner 패키지의 BetaToolRunner
Ruby	Yes (beta)	No	베타의 BaseTool + tool_runner
cURL	N/A	N/A	Raw HTTP, SDK 기능 없음
C#	No	No	공식 SDK
PHP	No	No	공식 SDK

---

어떤 서피스를 사용해야 하나요?

단순하게 시작하세요. 필요를 충족하는 가장 단순한 티어를 기본으로 사용하세요. 단일 API 호출과 워크플로우가 대부분의 사용 사례를 처리합니다 — 작업이 진정으로 개방형이고 모델 주도적인 탐색을 필요로 할 때만 에이전트를 사용하세요.

사용 사례	티어	권장 서피스	이유
분류, 요약, 추출, Q&A	단일 LLM 호출	Claude API	하나의 요청, 하나의 응답
배치 처리 또는 임베딩	단일 LLM 호출	Claude API	전용 엔드포인트
코드로 제어되는 로직의 다단계 파이프라인	워크플로우	Claude API + tool use	사용자가 루프를 조율
자체 도구를 사용하는 커스텀 에이전트	에이전트	Claude API + tool use	최대한의 유연성
파일/웹/터미널 접근이 가능한 AI 에이전트	에이전트	Agent SDK	내장 도구, 안전성, MCP 지원
에이전틱 코딩 어시스턴트	에이전트	Agent SDK	이 사용 사례를 위해 설계됨
내장 권한 및 가드레일이 필요한 경우	에이전트	Agent SDK	안전 기능 포함

참고: Agent SDK는 내장 파일/웹/터미널 도구, 권한, MCP를 바로 사용하고 싶을 때 사용합니다. 자체 도구로 에이전트를 구축하려면 Claude API가 올바른 선택입니다 — 자동 루프 처리를 위해 tool runner를 사용하거나, 세밀한 제어(승인 게이트, 커스텀 로깅, 조건부 실행)를 위해 수동 루프를 사용하세요.

결정 트리

애플리케이션에 무엇이 필요한가요?

1. 단일 LLM 호출 (분류, 요약, 추출, Q&A)
   └── Claude API — 하나의 요청, 하나의 응답

2. Claude가 작업의 일부로 파일을 읽거나 쓰고, 웹을 탐색하거나,
   셸 명령을 실행해야 하나요? (앱이 파일을 읽어서 Claude에 전달하는 것이 아니라,
   Claude 자체가 파일/웹/셸을 발견하고 접근해야 하는 경우인가요?)
   └── 예 → Agent SDK — 내장 도구를 사용하세요, 직접 재구현하지 마세요
       예시: "코드베이스에서 버그 검색", "디렉토리의 모든 파일 요약",
             "서브에이전트를 사용하여 버그 찾기", "웹 검색으로 주제 조사"

3. 워크플로우 (다단계, 코드로 조율, 자체 도구 사용)
   └── Claude API와 tool use — 사용자가 루프를 제어

4. 개방형 에이전트 (모델이 자체적으로 경로를 결정, 자체 도구 사용)
   └── Claude API 에이전틱 루프 (최대한의 유연성)

에이전트를 구축해야 할까요?

에이전트 티어를 선택하기 전에, 네 가지 기준을 모두 확인하세요:

• 복잡성 — 작업이 다단계이며 사전에 완전히 명세하기 어려운가요? (예: "이 설계 문서를 PR로 변환" vs. "이 PDF에서 제목을 추출")
• 가치 — 결과가 더 높은 비용과 지연 시간을 정당화하나요?
• 실현 가능성 — Claude가 이 작업 유형에 능숙한가요?
• 오류 비용 — 오류를 감지하고 복구할 수 있나요? (테스트, 리뷰, 롤백)

이 중 하나라도 "아니오"라면, 더 단순한 티어(단일 호출 또는 워크플로우)를 유지하세요.

---

아키텍처

모든 것은 POST /v1/messages를 통해 처리됩니다. 도구와 출력 제약 조건은 이 단일 엔드포인트의 기능이며 — 별도의 API가 아닙니다.

사용자 정의 도구 — 도구를 정의하면(데코레이터, Zod 스키마, 또는 raw JSON으로), SDK의 tool runner가 API 호출, 함수 실행, Claude가 완료될 때까지의 루핑을 처리합니다. 완전한 제어를 원하면 루프를 수동으로 작성할 수 있습니다.

서버 측 도구 — Anthropic 인프라에서 실행되는 Anthropic 호스팅 도구입니다. 코드 실행은 완전히 서버 측에서 이루어집니다(tools에 선언하면 Claude가 자동으로 코드를 실행합니다). 컴퓨터 사용은 서버 호스팅 또는 셀프 호스팅이 가능합니다.

구조화된 출력 — Messages API 응답 형식(output_config.format) 및/또는 도구 파라미터 검증(strict: true)을 제한합니다. 권장 접근법은 client.messages.parse()로, 스키마에 대해 응답을 자동으로 검증합니다. 참고: 이전 output_format 파라미터는 더 이상 사용되지 않으며, messages.create()에서 output_config: {format: {...}}를 사용하세요.

지원 엔드포인트 — Batches(POST /v1/messages/batches), Files(POST /v1/files), Token Counting은 Messages API 요청에 데이터를 공급하거나 이를 지원합니다.

---

현재 모델 (캐시 날짜: 2026-02-17)

모델	모델 ID	컨텍스트	입력 $/1M	출력 $/1M
Claude Opus 4.6	claude-opus-4-6	200K (1M beta)	$5.00	$25.00
Claude Sonnet 4.6	claude-sonnet-4-6	200K (1M beta)	$3.00	$15.00
Claude Haiku 4.5	claude-haiku-4-5	200K	$1.00	$5.00

사용자가 명시적으로 다른 모델을 지정하지 않는 한 항상 claude-opus-4-6을 사용하세요. 이것은 협상 불가입니다. 사용자가 문자 그대로 "sonnet 사용" 또는 "haiku 사용"이라고 말하지 않는 한 claude-sonnet-4-6, claude-sonnet-4-5, 또는 다른 모델을 사용하지 마세요. 비용 때문에 절대 다운그레이드하지 마세요 — 그것은 사용자의 결정이지 당신의 결정이 아닙니다.

중요: 위 테이블의 정확한 모델 ID 문자열만 사용하세요 — 그대로 완전한 형태입니다. 날짜 접미사를 추가하지 마세요. 예를 들어, claude-sonnet-4-5를 사용하고, claude-sonnet-4-5-20250514나 학습 데이터에서 기억할 수 있는 다른 날짜 접미사 변형을 사용하지 마세요. 사용자가 테이블에 없는 이전 모델을 요청하는 경우(예: "opus 4.5", "sonnet 3.7"), 정확한 ID는 shared/models.md에서 읽으세요 — 직접 만들지 마세요.

참고: 위의 모델 문자열 중 익숙하지 않은 것이 있다면, 그것은 당연합니다 — 학습 데이터 컷오프 이후에 출시된 모델이라는 의미입니다. 실제 모델이니 안심하세요; 우리가 장난치는 것이 아닙니다.

---

사고 및 노력 (빠른 참조)

Opus 4.6 — 적응형 사고 (권장): thinking: {type: "adaptive"}를 사용하세요. Claude가 언제, 얼마나 사고할지 동적으로 결정합니다. budget_tokens가 필요 없습니다 — budget_tokens는 Opus 4.6과 Sonnet 4.6에서 더 이상 사용되지 않으며 사용해서는 안 됩니다. 적응형 사고는 인터리브드 사고도 자동으로 활성화합니다(베타 헤더 불필요). 사용자가 "확장된 사고", "사고 예산", 또는 budget_tokens를 요청할 때: 항상 Opus 4.6에 thinking: {type: "adaptive"}를 사용하세요. 사고에 대한 고정 토큰 예산 개념은 더 이상 사용되지 않습니다 — 적응형 사고가 이를 대체합니다. budget_tokens를 사용하지 말고 이전 모델로 전환하지 마세요.

노력 파라미터 (GA, 베타 헤더 불필요): 사고 깊이와 전체 토큰 사용량을 output_config: {effort: "low"|"medium"|"high"|"max"}로 제어합니다(output_config 내부에 위치하며, 최상위 레벨이 아닙니다). 기본값은 high입니다(생략하는 것과 동일). max는 Opus 4.6 전용입니다. Opus 4.5, Opus 4.6, Sonnet 4.6에서 작동합니다. Sonnet 4.5 / Haiku 4.5에서는 오류가 발생합니다. 최상의 비용-품질 트레이드오프를 위해 적응형 사고와 결합하세요. 서브에이전트나 단순 작업에는 low를, 가장 깊은 추론에는 max를 사용하세요.

Sonnet 4.6: 적응형 사고(thinking: {type: "adaptive"})를 지원합니다. budget_tokens는 Sonnet 4.6에서 더 이상 사용되지 않습니다 — 대신 적응형 사고를 사용하세요.

이전 모델 (명시적으로 요청된 경우에만): 사용자가 Sonnet 4.5 또는 다른 이전 모델을 구체적으로 요청하는 경우, thinking: {type: "enabled", budget_tokens: N}을 사용하세요. budget_tokens는 max_tokens보다 작아야 합니다(최소 1024). 사용자가 budget_tokens를 언급한다고 해서 이전 모델을 선택하지 마세요 — 대신 Opus 4.6에 적응형 사고를 사용하세요.

---

압축 (빠른 참조)

베타, Opus 4.6 전용. 200K 컨텍스트 윈도우를 초과할 수 있는 장시간 대화의 경우, 서버 측 압축을 활성화하세요. API가 트리거 임계값(기본값: 150K 토큰)에 도달하면 이전 컨텍스트를 자동으로 요약합니다. 베타 헤더 compact-2026-01-12가 필요합니다.

중요: 매 턴마다 response.content(텍스트만이 아닌)를 메시지에 다시 추가하세요. 응답의 압축 블록은 보존되어야 합니다 — API가 다음 요청에서 압축된 히스토리를 대체하는 데 사용합니다. 텍스트 문자열만 추출하여 추가하면 압축 상태가 조용히 손실됩니다.

코드 예제는 {lang}/claude-api/README.md(압축 섹션)를 참조하세요. 최신 문서는 shared/live-sources.md에서 WebFetch를 통해 확인하세요.

---

읽기 가이드

언어를 감지한 후, 사용자가 필요로 하는 것에 따라 관련 파일을 읽으세요:

빠른 작업 참조

단일 텍스트 분류/요약/추출/Q&A:
→ {lang}/claude-api/README.md만 읽기

채팅 UI 또는 실시간 응답 표시:
→ {lang}/claude-api/README.md + {lang}/claude-api/streaming.md 읽기

장시간 대화 (컨텍스트 윈도우 초과 가능):
→ {lang}/claude-api/README.md 읽기 — 압축 섹션 참조

함수 호출 / tool use / 에이전트:
→ {lang}/claude-api/README.md + shared/tool-use-concepts.md + {lang}/claude-api/tool-use.md 읽기

배치 처리 (지연 시간에 민감하지 않은):
→ {lang}/claude-api/README.md + {lang}/claude-api/batches.md 읽기

여러 요청에 걸친 파일 업로드:
→ {lang}/claude-api/README.md + {lang}/claude-api/files-api.md 읽기

내장 도구가 있는 에이전트 (파일/웹/터미널):
→ {lang}/agent-sdk/README.md + {lang}/agent-sdk/patterns.md 읽기

Claude API (전체 파일 참조)

언어별 Claude API 폴더 ({language}/claude-api/)를 읽으세요:

1. {language}/claude-api/README.md — 이것을 먼저 읽으세요. 설치, 빠른 시작, 일반적인 패턴, 오류 처리.
2. shared/tool-use-concepts.md — 사용자가 함수 호출, 코드 실행, 메모리, 또는 구조화된 출력이 필요할 때 읽으세요. 개념적 기초를 다룹니다.
3. {language}/claude-api/tool-use.md — 언어별 tool use 코드 예제를 읽으세요 (tool runner, 수동 루프, 코드 실행, 메모리, 구조화된 출력).
4. {language}/claude-api/streaming.md — 채팅 UI 또는 응답을 점진적으로 표시하는 인터페이스를 구축할 때 읽으세요.
5. {language}/claude-api/batches.md — 오프라인으로 많은 요청을 처리할 때 읽으세요 (지연 시간에 민감하지 않음). 50% 비용으로 비동기적으로 실행됩니다.
6. {language}/claude-api/files-api.md — 동일한 파일을 여러 요청에 걸쳐 재업로드 없이 보낼 때 읽으세요.
7. shared/error-codes.md — HTTP 오류를 디버깅하거나 오류 처리를 구현할 때 읽으세요.
8. shared/live-sources.md — 최신 공식 문서를 가져오기 위한 WebFetch URL.

참고: Java, Go, Ruby, C#, PHP, cURL의 경우 — 모든 기본 사항을 다루는 단일 파일이 있습니다. 해당 파일과 필요에 따라 shared/tool-use-concepts.md 및 shared/error-codes.md를 읽으세요.

Agent SDK

언어별 Agent SDK 폴더 ({language}/agent-sdk/)를 읽으세요. Agent SDK는 Python과 TypeScript에서만 사용 가능합니다.

1. {language}/agent-sdk/README.md — 설치, 빠른 시작, 내장 도구, 권한, MCP, 훅.
2. {language}/agent-sdk/patterns.md — 커스텀 도구, 훅, 서브에이전트, MCP 통합, 세션 재개.
3. shared/live-sources.md — 최신 Agent SDK 문서를 위한 WebFetch URL.

---

WebFetch 사용 시점

다음과 같은 경우 WebFetch를 사용하여 최신 문서를 가져오세요:

• 사용자가 "최신" 또는 "현재" 정보를 요청하는 경우
• 캐시된 데이터가 올바르지 않은 것 같은 경우
• 사용자가 여기에서 다루지 않는 기능에 대해 질문하는 경우

라이브 문서 URL은 shared/live-sources.md에 있습니다.

일반적인 함정

• API에 파일이나 콘텐츠를 전달할 때 입력을 자르지 마세요. 콘텐츠가 컨텍스트 윈도우에 맞지 않을 정도로 긴 경우, 자동으로 자르는 대신 사용자에게 알리고 옵션(청킹, 요약 등)을 논의하세요.
• Opus 4.6 / Sonnet 4.6 사고: thinking: {type: "adaptive"}를 사용하세요 — budget_tokens를 사용하지 마세요 (Opus 4.6과 Sonnet 4.6 모두에서 더 이상 사용되지 않음). 이전 모델의 경우, budget_tokens는 max_tokens보다 작아야 합니다(최소 1024). 잘못 설정하면 오류가 발생합니다.
• Opus 4.6 prefill 제거: 어시스턴트 메시지 프리필(마지막 어시스턴트 턴 프리필)은 Opus 4.6에서 400 오류를 반환합니다. 응답 형식을 제어하려면 구조화된 출력(output_config.format) 또는 시스템 프롬프트 지시를 대신 사용하세요.
• 128K 출력 토큰: Opus 4.6은 최대 128K max_tokens를 지원하지만, SDK는 HTTP 타임아웃을 방지하기 위해 큰 max_tokens에 대해 스트리밍을 요구합니다. .stream()과 .get_final_message() / .finalMessage()를 사용하세요.
• Tool call JSON 파싱 (Opus 4.6): Opus 4.6은 tool call input 필드에서 다른 JSON 문자열 이스케이핑을 생성할 수 있습니다(예: 유니코드 또는 슬래시 이스케이핑). 항상 json.loads() / JSON.parse()로 도구 입력을 파싱하세요 — 직렬화된 입력에 대해 raw 문자열 매칭을 하지 마세요.
• 구조화된 출력 (모든 모델): messages.create()에서 더 이상 사용되지 않는 output_format 파라미터 대신 output_config: {format: {...}}를 사용하세요. 이것은 4.6에 국한되지 않는 일반적인 API 변경입니다.
• SDK 기능을 재구현하지 마세요: SDK는 고수준 헬퍼를 제공합니다 — 처음부터 구축하는 대신 이것들을 사용하세요. 구체적으로: .on() 이벤트를 new Promise()로 감싸는 대신 stream.finalMessage()를 사용하세요; 오류 메시지를 문자열 매칭하는 대신 타입이 지정된 예외 클래스(Anthropic.RateLimitError 등)를 사용하세요; 동등한 인터페이스를 재정의하는 대신 SDK 타입(Anthropic.MessageParam, Anthropic.Tool, Anthropic.Message 등)을 사용하세요.
• SDK 데이터 구조에 대한 커스텀 타입을 정의하지 마세요: SDK는 모든 API 객체에 대한 타입을 내보냅니다. 메시지에는 Anthropic.MessageParam, 도구 정의에는 Anthropic.Tool, 도구 결과에는 Anthropic.ToolUseBlock / Anthropic.ToolResultBlockParam, 응답에는 Anthropic.Message를 사용하세요. interface ChatMessage { role: string; content: unknown }과 같은 자체 인터페이스를 정의하면 SDK가 이미 제공하는 것을 중복하게 되고 타입 안전성을 잃습니다.
• 보고서 및 문서 출력: 보고서, 문서, 또는 시각화를 생성하는 작업의 경우, 코드 실행 샌드박스에는 python-docx, python-pptx, matplotlib, pillow, pypdf가 사전 설치되어 있습니다. Claude는 형식이 지정된 파일(DOCX, PDF, 차트)을 생성하고 Files API를 통해 반환할 수 있습니다 — 일반 stdout 텍스트 대신 "보고서" 또는 "문서" 유형의 요청에 이것을 고려하세요.