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 SDK 호출이 포함된 파일을 Anthropic이 아닌 파일로 편집하지 마세요. (예외: prompt-audit 하위 명령은 비대화형이며 여기서 중단되지 않습니다. 보고서의 명시된 가정에 Anthropic이 아닌 제공자 마커를 기록하고, Anthropic이 아닌 파일을 Anthropic SDK로 전환하는 것을 제안하지 않습니다.)
출력 요구 사항
사용자가 Claude 기능을 추가, 수정 또는 구현하도록 요청할 때, 코드는 다음 중 하나를 통해 Claude를 호출해야 합니다:
- 공식 Anthropic SDK (프로젝트 언어에 맞는
anthropic,@anthropic-ai/sdk,com.anthropic.*등). 프로젝트에 지원되는 SDK가 있을 때마다 기본값입니다. - 원시 HTTP (
curl,requests,fetch,httpx등) - 사용자가 명시적으로 cURL/REST/raw HTTP를 요청했거나, 프로젝트가 셸/cURL 프로젝트이거나, 언어에 공식 SDK가 없는 경우에만 사용.
두 가지를 혼합하지 마세요 - Python 또는 TypeScript 프로젝트에서 더 가벼워 보인다고 requests/fetch를 사용하지 마세요. OpenAI 호환 shim으로 대체하지 마세요.
SDK 사용법을 추측하지 마세요. 함수 이름, 클래스 이름, 네임스페이스, 메서드 시그니처 및 가져오기 경로는 명시적 문서에서 가져와야 합니다 - 이 스킬의 {lang}/ 파일 또는 shared/live-sources.md에 나열된 공식 SDK 저장소나 문서 링크에서. 필요한 바인딩이 스킬 파일에 명시적으로 문서화되어 있지 않으면, 코드를 작성하기 전에 shared/live-sources.md에서 관련 SDK 저장소를 WebFetch하세요. cURL 형태나 다른 언어의 SDK에서 Ruby/Java/Go/PHP/C# API를 유추하지 마세요.
WebFetch 또는 저장소 접근이 실패하면 (네트워크 제한, 시간 초과, 복제 차단): 계속 재시도하지 말고 - {lang}/ 파일의 패턴과 네임스페이스/패키지 테이블에서 코드를 작성하고, 컴파일러나 인터프리터를 실행한 후 오류 출력을 반복하세요. 정적 타입 SDK(C#, Java, Go)의 경우 로컬 오류에 대한 컴파일-수정 루프가 차단된 네트워크 연구보다 더 빠르게 작동하는 코드에 도달합니다.
기본값
사용자가 달리 요청하지 않는 한:
Claude 모델 버전의 경우 Claude Opus 5.5를 사용하세요. 정확한 모델 문자열 claude-opus-5-5로 접근할 수 있습니다. 복잡한 작업에는 적응형 사고(thinking: {type: "adaptive"})를 기본값으로 사용하세요. 마지막으로, 긴 입력, 긴 출력 또는 높은 max_tokens가 관련된 모든 요청에는 스트리밍을 기본값으로 사용하세요 - 요청 시간 초과를 방지합니다. 개별 스트림 이벤트를 처리할 필요가 없으면 SDK의 .get_final_message() / .finalMessage() 헬퍼를 사용하여 완전한 응답을 얻으세요. 스트리밍 요청이 사용자 정의(클라이언트) 도구를 정의하는 경우, 각 도구에 eager_input_streaming: true를 설정하여 큰 도구 입력(파일 내용, 코드, 문서)이 서버가 버퍼링을 마친 후 한 번에 도착하지 않고 생성되는 대로 스트리밍되도록 하세요. 클라이언트는 유효성 검사를 담당합니다: SDK의 관대한 파서는 조용히 잘린 입력을 반환할 수 있으므로, 실행하기 전에 각 구문 분석된 도구 입력을 해당 스키마에 대해 검증하세요(typed runner 헬퍼 betaZodTool / typed @beta_tool는 이를 수행하고, betaTool() JSON-Schema 도구와 수동 루프는 스스로 검증해야 함). 실패는 잘못된 JSON처럼 처리하고(INVALID_JSON 오류 tool_result 블록을 보유하고 있으면, 그렇지 않으면 재발행), 도구를 실행하기 전에 max_tokens / refusal 중지 이유를 확인하고, SDK의 JSON 오류만 잡고 typed API 오류는 잡지 마세요 - shared/tool-use-concepts.md -> Eager input streaming 패턴 참조. 비스트리밍 요청, 서버 도구, 프록시 또는 필드를 거부하는 이전 Bedrock 모델 배포를 통과하는 요청에는 이 기능을 끄세요.
경고: API 드리프트 - 학습 데이터가 오래되었을 수 있음
여러 일반적인 Claude API 형태가 2025-2026년에 변경되었습니다. 학습에서 패턴을 기억하는 경우, 이 스킬의 {lang}/ 파일에서 확인한 후 작성하세요 - 아래 행이 가장 빈번한 드리프트 지점입니다:
| 영역 | 오래된 이전 버전 | 현재 API |
|---|---|---|
| 확장 사고 | thinking: {type: "enabled", budget_tokens: N} | Claude 4.6+ 모델: thinking: {type: "adaptive"}. budget_tokens는 Opus 4.6 / Sonnet 4.6에서 폐기되었고 Fable 5/5.1 / Sonnet 5.5 / Sonnet 5 / Opus 5.5 / 5 / 4.8 / 4.7에서 400 오류와 함께 거부됩니다. 4.6 이전 모델은 여전히 budget_tokens를 사용합니다. |
| 웹 검색 / 웹 가져오기 도구 유형 | web_search_20250305, web_fetch_20250910 | Opus 5.5/5/4.8/4.7/4.6, Sonnet 5.5, Sonnet 5 및 Sonnet 4.6에서 web_search_20260209, web_fetch_20260209 (동적 필터링). 이전 모델은 기본 변형을 유지함; Vertex AI에서는 기본 web_search_20250305만 사용 가능(웹 가져오기는 Vertex에 없음) - 아래 서버 도구 QR 참조. |
| PHP 매개변수 이름 | snake_case 와이어 이름을 명명된 인자로 (max_tokens) | 최상위 명명된 인자는 camelCase(maxTokens). 중첩 배열 키는 기능에 따라 다름(예: 'taskBudget', 'skillID', 'mcp_server_name') - 문서화된 예제에서 정확한 키를 복사하세요; 일괄 변환하지 마세요. |
| 관리형 에이전트 자격 증명 | 사용자 정의 도구를 통해 호스트 측에 비밀 유지(볼트가 출시되기 전의 유일한 옵션) | Vault environment_variable 자격 증명 - Anthropic이 저장하고, 송신 시 대체되며, 샌드박스에서 절대 볼 수 없음(shared/managed-agents-tools.md -> Vaults). 호스트 측 사용자 정의 도구는 자체 호스팅 샌드박스의 대체 수단으로 남아 있음. |
| Files API / Skills | client.beta.files.* / client.beta.skills.* with beta files-api-2025-04-14 / skills-2025-10-02 | 베타 종료: client.files.* / client.skills.*, beta 헤더 없음. 현재 SDK에서 client.beta.files / client.beta.skills는 이전 버전과 호환되지 않는 형태 변경이 있으며, 안정적인 네임스페이스와 일치함 - shared/live-sources.md -> Files API / Skills Guide에 따라 마이그레이션하세요. |
이 스킬의 {lang}/ 파일은 기억된 패턴보다 권위가 있습니다.
하위 명령어
이 프롬프트 하단의 사용자 요청이 일반 텍스트가 아닌 하위 명령 문자열인 경우, 이 문서의 모든 하위 명령어 테이블(아래에 추가된 섹션 포함)을 검색하고 일치하는 동작 열을 직접 따르세요. 이를 통해 사용자는 /claude-api <하위명령어>를 통해 특정 흐름을 호출할 수 있습니다. 문서의 어떤 테이블도 일치하지 않으면, 요청을 일반 텍스트로 처리하세요.
| 하위 명령어 | 동작 |
|---|---|
migrate | 기존 Claude API 코드를 최신 모델로 마이그레이션합니다. 즉시 shared/model-migration.md를 읽고 순서대로 따르세요: 0단계(범위 확인 - 편집 전에 어떤 파일/디렉토리인지 물어보기), 1단계(각 파일 분류), 그런 다음 대상별 호환성 변경 섹션. 가이드를 요약하지 말고 실행하세요. 사용자가 대상 모델을 지정하지 않으면, 범위 질문과 같은 턴에 마이그레이션할 모델을 물어보세요. 대상별 변경 사항이 적용된 후, 범위 내 프롬프트 텍스트, 도구 설명, 요청 코드를 shared/prompt-audit.md에 대해 감사하세요 - 소스 모델용으로 작성된 프롬프팅은 모든 마이그레이션의 일부이며, 스스로 발표하지 않습니다. |
prompt-audit | 기존 프롬프트, 도구 설명, 스킬 및 에이전트 구성 파일(CLAUDE.md, 규칙 파일, 명령, 하위 에이전트)에서 오래된 패턴("크루프트")을 감사합니다: 이전 모델용으로 작성된 텍스트, 저장소가 벗어났거나 서로 모순되는 지침. 즉시 shared/prompt-audit.md를 읽고 순서대로 따르세요: 0단계(요청과 저장소에서 범위와 대상 모델 설정 - 보고서에서 가정을 명시하고, 중단하여 묻지 않음), 인벤토리, 출처 증명, 그런 다음 패턴 스캔. 두 가지 결과물(찾은 내용이 포함된 감사 보고서(file:line, 패턴, 구식인 이유, 신뢰도)와 제안된 diff)을 확인을 기다리지 않고 전체 생성하세요; 요청이 명시적으로 편집을 요청한 경우에만 편집을 적용하세요. 가이드를 요약하지 말고 실행하세요. |
upgrade | 프로젝트의 Anthropic SDK 종속성을 주요 버전으로 업그레이드합니다 - 현재 Python SDK, anthropic 0.x -> 1.x. 뒤에 오는 단어는 언어 및/또는 범위를 지정할 수 있습니다(upgrade python, upgrade python sdk src/). 즉시 python/claude-api/sdk-upgrade.md를 읽고 순서대로 따르세요: 0단계(범위 확인, 그런 다음 현재 및 대상 버전 설정 - 핀을 작성하기 전에 게시된 1.x가 존재해야 함), 1단계 인벤토리, 각 번호 섹션, 그런 다음 검증 및 보고서. 가이드를 요약하지 말고 실행하세요. 감지되거나 명명된 언어에 이 스킬에 sdk-upgrade.md가 없으면, 해당 SDK에 대한 주요 버전 업그레이드 가이드가 아직 포함되지 않았다고 말하고 사용자에게 해당 SDK의 CHANGELOG(shared/live-sources.md의 저장소)를 안내하세요; Python 가이드에서 즉석으로 만들지 마세요. 이는 모델 마이그레이션이 아닙니다 - 코드를 최신 Claude 모델로 옮기려면 migrate를 사용하세요. |
cost-optimize | 출력 품질을 희생하지 않고 기존 Claude API 코드 실행 비용을 줄입니다. 즉시 shared/cost-optimization.md를 읽고 순서대로 따르세요: 0단계(범위, 품질 기준, 기준선 설정), 토큰 프로필 - 사용자가 Admin API 키를 가지고 있을 때 Usage and Cost Admin API를 통해 측정, 앱 자체 response.usage 로그가 있을 때(요청), 또는 그렇지 않으면 코드에서 추정 - 그런 다음 절감액 순위가 매겨진 지렛대 목록(데이터 소스에 따라 달러, 청구서 비율 또는 상대적 버킷으로 인용), 무료 승리(캐싱, 입력 토큰 위생, 루프 위생, 출력 토큰 위생, 배치) 그런 다음 트레이드오프(예산, 노력, 모델 선택, 다중 모델); 자격을 얻은 모든 지렛대는 자체 diff가 됩니다 - 기본적으로 제안되고, 사용자가 요청하고 승인하면 해당 트래픽을 다루는 평가에 대해 적용 및 측정됩니다. "변경 사항 없음"도 유효한 결과입니다. 두 가지 상시 규칙: 모델을 실행하는 모든 실행은 실제 비용이 들므로 먼저 사용자의 승인을 받으세요; 지렛대에 대한 컨텍스트가 누락된 경우 사용자와 대화형으로 작업하세요 - 이 워크플로우는 한 번에 감사를 완료할 것으로 예상되지 않습니다. 가이드를 요약하지 말고 실행하세요; 프로필과 순위 계획을 사용자에게 제시하는 것은 실행의 일부입니다. |
build-eval | 사용자가 Claude 기반 앱을 위한 평가 세트를 구축할 수 있도록 돕습니다. 즉시 shared/evals/build-eval.md를 읽고 인터뷰를 실행하세요: 0단계(평가 대상), 1단계(프롬프트 소싱 - 기존 평가 / 대화 기록 / 합성), 2단계(채점 방법), 3단계(실행 가능한 스크립트 + 측정된 비용). 평가를 생성하기 전에 입력, 채점 방법 및 비용에 대한 사용자의 명시적 승인을 받으세요. |
preserved-thinking-migration | 기존 통합을 보존된 사고와 호환되도록 만듭니다 - 사고 블록을 생성한 대화에서만 유효하도록 유지하는 검사. 즉시 shared/preserved-thinking-migration.md를 읽고 순서대로 따르세요: 0단계(범위, 트래픽 클래스, 플랫폼 및 모델, 시행 상태, 품질 기준, 기준선), 0.5단계(3개 요청 자체 테스트로 검사가 실행 중임을 증명), 1단계(요청 본문 캡처, shared/preserved-thinking-migration/prefix_diff.py로 연속 쌍 차이 비교, 코드에서 원인 스캔, 각 편집 이름 지정 및 의도적인지 여부), 2단계(thinking-binding-controls-2026-08-01 헤더 아래 prefix_mismatch_behavior: "drop_block"로 테스트 슬라이스 재생, 대화당 새로운 삭제된 블록 수 계산, 존재할 때 진단 헤더 읽기), 3단계(추론 손실 순서대로 diff당 하나의 원인 - 기본적으로 제안되고 사용자가 요청하면 적용, 그런 다음 재측정, 유지 또는 되돌리기; 평가가 있을 때 3군 프로토콜), 모델 전환 섹션( shared/preserved-thinking-migration/causes.md에서 원인 테이블 및 유지 목록 참조) 하네스가 모델 간에 라우팅할 때, 4단계(중단 프로필 및 변경 사항). 두 가지 상시 규칙: 모든 재생은 실제 비용이 들므로 먼저 측정 예산에 대한 사용자의 승인을 받으세요; "변경 사항 없음" - 슬라이스가 사고를 재생했고 아무것도 삭제되지 않음 - 도 유효한 결과입니다. 최신 베타에서만 추가 전용 형태를 갖는 원인(keep-tail 및 백그라운드 압축: compact-2026-09-04; 동일 이름 도구 변경: inline-tools-2026-09-15)은 해당 베타를 사용할 수 없는 경우 측정 및 결정되며, 다시 작성되지 않습니다. 이유(3단계 검사, 추가 전용 편집 테이블)는 shared/model-migration.md -> Breaking change 3에 연결됩니다; 가이드를 요약하지 말고 실행하세요. |
hillclimb | 기존 평가에 대해 사용자의 앱을 반복적으로 개선합니다. 즉시 shared/evals/eval-hillclimb.md를 읽고 따르세요: 0단계(실행 가능한 평가가 존재하는지 확인 - 없으면 build-eval로 라우팅), 1단계(변경할 내용 / 금지 사항), 2단계(측정된 실행당 비용에서 예산 + 중단 조건), 계획 승인 받기, 그런 다음 읽기->제안->적용->실행->기록 루프(디스크 상태 및 학습/검증/테스트 분할 포함). |
언어 감지
코드 예제를 읽기 전에 사용자가 작업 중인 언어를 결정하세요(예외: prompt-audit 하위 명령의 경우 이 섹션의 질문 단계를 건너뛰세요 - 감사는 비대화형이며 인벤토리는 언어에 구애받지 않습니다. 언어를 유추할 수 없는 경우 묻지 않고 진행하고 보고서에 가정을 명시하세요):
- 프로젝트 파일을 보고 언어를 유추하세요:
*.py,requirements.txt,pyproject.toml,setup.py,Pipfile-> Python -python/에서 읽기*.ts,*.tsx,package.json,tsconfig.json-> TypeScript -typescript/에서 읽기