CCDV-F · CHAPTER 02 · D2 APPLICATIONS AND INTEGRATION · 33.1%

요구사항에서 운영까지: Claude를 실제 서비스에 통합하는 법

이 도메인은 시험 전체에서 33.1%로 가장 큰 비중을 차지합니다. 사업 관점의 요구를 실제 시스템으로 옮기고, Claude API의 동작 원리를 정확히 이해하며, 그 위에 견고한 소프트웨어 공학을 얹는 능력을 묻습니다. 프로토타입을 넘어 6개월 뒤에도 운영 가능한 통합을 설계하는 것이 이 장의 목표입니다.

2.1 비즈니스 요구에서 시스템 설계로, 그리고 생명주기 관점

비즈니스 요구사항(business requirement, 사업 관점의 목표)을 그대로 코드로 옮길 수는 없습니다. "상담 응답 시간을 절반으로 줄인다"는 목표는 엔지니어의 손에서 기능 요구사항(functional requirement, 시스템이 무엇을 해야 하는가)과 인프라 요구사항(infrastructure requirement, 어떤 처리량·지연·비용으로 감당하는가)으로 분해되어야 합니다. 여기에 시스템 생명주기(systems life cycle) — 개발·구현·운영·유지보수 — 관점을 얹으면, 초기 데모가 아니라 오래 감당 가능한 설계가 나옵니다.

실무 예시

국내 커머스사의 백엔드 엔지니어가 "고객 문의 자동 분류"를 맡았다면, 먼저 "분류 정확도 몇 %", "하루 몇 건", "실시간이어야 하는가 배치로 충분한가"를 사업팀과 확정한 뒤에야 모델·엔드포인트·재시도 정책을 고를 수 있습니다.

2.2 Messages API 한 곳으로 흐른다 — 도구·스트리밍·비전·사고·캐싱

Claude의 모든 요청은 단일 엔드포인트 POST /v1/messages로 흐릅니다. 도구 사용(tool use, 모델이 함수를 호출하게 하는 정의), 스트리밍(streaming, 응답을 토큰 단위로 흘려보내기), 비전(vision, 이미지 입력), 확장 사고(extended thinking, 답 전에 추론하는 단계)는 별도 API가 아니라 이 엔드포인트의 옵션입니다. 최신 모델은 사고를 adaptive(적응형)로 켜고 effort로 깊이를 조절합니다. 프롬프트 캐싱(prompt caching)은 반복되는 앞부분을 재사용해 비용·지연을 줄이는데, 접두 일치(prefix match) 방식이라 앞쪽 한 글자만 바뀌어도 캐시가 깨집니다.

실무 예시

사내 개발자 도구를 만드는 플랫폼 엔지니어가 긴 사내 규정 문서를 매 요청 앞에 붙인다면, 그 문서 블록에 cache_control을 걸어 두 번째 요청부터 cache_read_input_tokens로 재사용을 확인합니다. 시스템 프롬프트에 현재 시각을 끼워 넣으면 캐시가 매번 깨지므로 피합니다.

2.3 실시간이냐 배치냐, 그리고 어느 벤더를 거쳐 부를 것인가

지연이 사용자 경험을 좌우하는 곳은 실시간 Messages API로, 대량·비동기 처리는 Message Batches API로 나눕니다. 배치는 요청당 표준가의 50%로, 최대 24시간 안에 처리되고 결과는 순서가 아니라 custom_id로 짝지어 받습니다. 한편 같은 Messages API를 Amazon Bedrock, Google Vertex AI, Microsoft Foundry 같은 서드파티 벤더를 거쳐 부를 수도 있는데, 이때 모델 ID 표기(예: Bedrock은 anthropic. 접두어)와 인증 방식이 달라집니다. 어느 경로든 요청은 상태를 저장하지 않으므로(stateless) 대화 이력은 매번 전부 실어 보냅니다.

실무 예시

핀테크사의 데이터팀이 밤사이 10만 건의 거래 메모를 분류한다면 실시간 호출 대신 배치로 묶어 비용을 절반으로 줄이고, custom_id에 거래 ID를 넣어 결과를 원래 행과 맞춥니다. 반대로 상담 챗봇의 응답은 배치로 미룰 수 없으니 실시간 스트리밍으로 답합니다.

2.4 REST·JSON·비동기, 그리고 버전 관리·코드 리뷰·리팩터링

Claude 통합은 결국 평범한 소프트웨어 공학 위에 얹힙니다. REST API(HTTP 규약으로 자원을 주고받는 방식)와 JSON(구조화된 데이터 표현) 이해는 기본이고, 응답이 느린 LLM 호출을 다룰 때는 비동기 프로그래밍(async programming, 결과를 기다리는 동안 다른 일을 처리)이 처리량을 좌우합니다. 프롬프트와 도구 정의도 코드이므로 버전 관리(version control) 아래 두고, 코드 리뷰(code review)로 스키마·에러 처리를 점검하며, 늘어난 호출 로직은 리팩터링(refactoring)으로 정리합니다. 프롬프트를 코드에서 분리해 두면 모델 교체 때 변경 지점이 명확해집니다.

실무 예시

국내 SaaS의 API 통합 팀이 Claude 호출을 추가할 때, 동기 호출로 요청을 하나씩 기다리면 응답 시간이 쌓입니다. 비동기로 여러 분류 요청을 동시에 띄우고, 프롬프트 문자열은 별도 파일에 두어 Git 이력으로 변경을 추적하는 편이 리뷰와 롤백 모두에 유리합니다.

2.5 같은 지시도 인터페이스마다 다르게 읽힌다

Claude Code, Claude Desktop, claude.ai, API, SDK는 같은 모델을 쓰지만 지시를 받아들이는 층위가 다릅니다. API·SDK에서는 시스템 프롬프트와 도구 스키마가 지시의 중심이고, Claude Code에서는 CLAUDE.md 같은 설정 파일이 더해집니다. 통합을 설계할 때는 콘텐츠 경계(content boundary, 신뢰할 입력과 그렇지 않은 입력의 구분)를 정하고, 도구 입력 스키마(schema design)를 엄격히 정의하며, 대화가 길어질 때 오래된 도구 결과를 정리하는 세션 위생(session hygiene)을 지킵니다. 플러그인·MCP 연결도 무엇을 언제 켤지 관리해야 합니다.

실무 예시

사내 도구 개발자가 claude.ai에서 잘 되던 프롬프트를 API로 옮기면, 어시스턴트 프리필 같은 UI 편의가 사라져 그대로는 동작하지 않을 수 있습니다. 사용자 입력을 그대로 시스템 프롬프트에 붙이지 말고, 신뢰 경계를 나눠 도구 결과와 사용자 텍스트를 구분해 다루는 편이 안전합니다.

2.6 구성 관리 — CLAUDE.md·설정 파일·모델 고정·프롬프트 버전

통합이 커질수록 "무엇이 어떤 버전으로 돌아가는지"를 붙들어 두는 구성 관리(configuration management)가 안정성을 결정합니다. Claude Code의 CLAUDE.md와 settings.json은 프로젝트 규약·권한을 한곳에 모으고, 모델 버전 고정(model version pinning, claude-opus-4-8처럼 정확한 ID를 명시)으로 조용한 동작 변화를 막습니다. 프롬프트 버전 관리(prompt versioning)로 언제 무엇을 바꿨는지 추적하고, 플러그인 의존성(plugin dependency)까지 명세해 두면 재현 가능한 배포가 됩니다.

실무 예시

여러 팀이 같은 Claude 파이프라인을 쓰는 조직이라면, 모델 ID를 별칭 대신 정확한 문자열로 고정하고 프롬프트 변경을 커밋 단위로 남깁니다. 그래야 "지난주엔 잘 됐는데"라는 회귀가 생겼을 때 어떤 프롬프트·모델·설정이 바뀌었는지 되짚을 수 있습니다.

! 흔한 함정

Claude API가 이전 대화를 기억한다고 가정하는 것. API는 상태를 저장하지 않으므로(stateless) 매 요청에 이전 대화 전체를 다시 실어 보내야 하며, 이력을 빠뜨리면 모델이 맥락을 잃습니다.
배치 결과가 보낸 순서대로 돌아온다고 믿는 것. Message Batches 결과는 순서가 보장되지 않으므로 위치가 아니라 custom_id로 원래 요청과 짝지어야 합니다.
프롬프트 캐싱을 켜 두었으니 당연히 재사용된다고 여기는 것. 시스템 프롬프트 앞부분에 현재 시각·요청 ID처럼 매번 바뀌는 값이 들어가면 접두 일치가 깨져 캐시가 전혀 안 잡히므로, cache_read_input_tokens가 0인지로 확인해야 합니다.
서드파티 벤더에서 1차 API의 모델 ID를 그대로 쓰는 것. 예를 들어 Amazon Bedrock은 anthropic. 접두어가 붙은 ID를 요구하므로, 첫 API용 문자열을 그대로 보내면 요청이 실패합니다.

HANDS-ON 이 도메인은 byteforce learn의 '2-claude-api' 코스와 정확히 맞물립니다 — Messages API·스트리밍·도구 사용·프롬프트 캐싱·배치를 직접 호출하며 익히는 실습형 코스입니다. learn으로 →

Q 확인 퀴즈

CH 02 · 01/5

국내 SaaS의 백엔드 엔지니어가 Claude를 처음 붙이면서, 도구 사용·스트리밍·이미지 입력을 각각 어떤 API로 불러야 하는지 정리하려 합니다.

Claude API에서 도구 사용, 스트리밍, 이미지 입력(비전)을 다룰 때의 구조로 옳은 것은?