96단계API로 우리 시스템에 넣기

걸리는 시간 · 읽기 약 5분 · 따라 하기 약 30분 · 난이도 ★★★ 심화 · 처음엔 건너뛰어도 되는 단계 · 화면 확인 2026.09.27

이 단계를 마치면

• 어떤 일에 API가 맞고, 어떤 일은 채팅·프로젝트·스킬·자동화로 충분한지 판단할 수 있다.
• 개발팀에 넘길 한 페이지짜리 요청서를 입력, 출력, 사람이 확인하는 지점, 금지 데이터로 나눠 쓸 수 있다.
• API로 붙인 기능이 제대로 돌아가는지 기준표로 확인하는 방법을 개발팀과 합의할 수 있다.

지금까지는 언제나 사람이 먼저 화면을 열었다. 웹이든 데스크톱이든, Cowork든 Claude Code든 사람이 Claude에게 말을 걸었다. 그런데 회사의 시스템이 직접 Claude를 부를 수도 있다. 그 통로가 Claude API다. API는 프로그램끼리 주고받는 창구라고 생각하면 된다. 사람이 채팅창에 치던 말을 프로그램이 대신 보내고, 답도 프로그램이 받는다.

무엇이 달라지나

채팅과 API의 차이는 "누가 부르는가"다. 채팅에서는 사람이 부르고 사람이 읽는다. API에서는 프로그램이 부르고 프로그램이 받는다. 그래서 사람이 대화 중에 하던 일을 모두 미리 정해 두어야 한다. 채팅에서는 답이 이상하면 다시 물으면 그만이다. 하지만 API로 돌아가는 시스템은 다시 묻지 않는다. 받은 답을 그대로 다음 단계로 넘긴다. 91단계의 다섯 함정이 여기서는 훨씬 비싼 대가를 치르게 한다. 흐린 지시는 매번 흐린 답을 낳고, 확인을 생략한 결과는 사람이 없는 사이에 차곡차곡 쌓인다.

75단계에서 Zapier·Make·n8n으로 Claude를 한 단계로 불렀던 것도 속을 들여다보면 이 창구를 쓴다. 외부 자동화 도구가 API를 대신 불러 주었을 뿐이다. 제3부에서 Claude Code로 만든 사내 도구에 Claude를 부르는 부분이 있다면 그것도 같은 창구다. 회사 시스템에 직접 붙인다는 말은, 이 연결을 개발팀이 우리 시스템 안에 심는다는 의미다.

언제 API인가

경영진이 직접 API 코드를 짤 일은 드물다. 경영진에게 필요한 것은 판단이다. 가장 먼저 물어야 할 질문은 이것이다. "이 일에 정말 API까지 필요한가?"

API가 맞는 일에는 공통점이 있다. 입력이 우리 시스템 안에서 생기고, 건수가 사람이 매번 화면을 열기에는 너무 많으며, 결과가 우리 시스템 화면에 바로 떠야 쓸모가 있다. 셋 중 하나도 해당하지 않는다면 앞의 도구들이 더 싸고 빠르다.

판단할 것이 두 가지 더 있다. 첫째, API는 쓴 만큼 비용이 나가는 방식이라 채팅 요금제와 따로 계산한다. 건수가 늘면 비용도 는다. 자세한 내용은 97단계에서 다룬다. 둘째, API로 보내는 데이터도 회사 밖으로 나가는 데이터다. 98단계의 등급 규칙이 그대로 적용된다. 게다가 시스템이 자동으로 보내니 사람이 한 건씩 걸러 볼 기회도 없다. 그래서 넣으면 안 되는 데이터를 요청서에 미리 적어 둔다.

개발팀에 무엇을 넘기나

개발팀에 "Claude 좀 붙여 주세요"라고만 하면 부족하다. 다음 내용을 적어서 넘긴다. 어느 시스템의 어느 지점에 붙일지, 무엇을 넣고 무엇을 받을지, 받은 결과를 사람이 어디서 확인할지, 넣으면 안 되는 데이터는 무엇인지, 틀렸을 때 어떻게 처리할지. 그리고 93단계의 기준표를 함께 준다. 개발자는 그 기준표로 시험을 설계한다. 기준표가 없으면 개발자는 "돌아가는지"만 시험할 수 있을 뿐, "쓸 만한지"는 시험하지 못한다.

제3부에서 배운 대로 Claude Code에게 API를 쓰는 작은 시험 도구를 만들게 해서, 샘플 입력 몇 건으로 결과를 먼저 살펴보는 방법도 있다. API 키를 발급받고 연결을 시험하는 순서는 75단계에 정리해 두었다. 개발팀이 쓸 키도 같은 방식으로, 이 기능 전용으로 따로 만들고 사용 한도를 걸어 둔다. 요금제별 제공 범위와 사용법은 자주 바뀌니 시작하기 전에 공식 문서를 한 번 확인하자.

현장 장면

생활용품 쇼핑몰의 운영이사 정 이사네 회사는 고객 문의 시스템을 쓴다. 상담원 여섯 명이 문의를 분류하고 답을 쓴다. 87단계를 들은 뒤로 상담원들은 Claude 채팅 화면을 열어 문의를 붙여 넣고 초안을 받기 시작했다. 초안 품질은 좋았다. 문제는 화면을 오가는 일이었다. 문의를 복사해 붙이고, 답을 복사해 다시 붙인다. 그러다 고객 주문번호가 채팅에 그대로 들어가는 일까지 생겼다.

정 이사는 개발팀장을 찾아가 말한다.

"문의 시스템에 Claude 좀 붙여 주세요."

개발팀장이 되묻는다. "무엇을 넣고 무엇을 받나요? 답을 바로 고객에게 보내나요?"

정 이사는 말문이 막힌다.

그날 오후, 정 이사는 아래 프롬프트로 요청서를 쓴다. 붙일 지점은 "문의 접수 직후". 넣을 것은 "문의 제목과 본문, 문의 유형". 받을 것은 "분류 결과(배송·교환·환불·기타)와 답변 초안". 사람이 확인하는 지점은 "상담원 화면에 초안으로만 표시하고, 보내기는 상담원이 누른다". 넣으면 안 되는 데이터는 "고객 이름, 전화번호, 주소, 주문번호. 본문에 들어 있으면 가린 뒤 보낸다". 틀렸을 때의 처리는 "분류가 불확실하면 '기타'로 두고 초안을 만들지 않는다". 여기에 93단계 방식으로 쓴 답변 기준표를 붙인다.

Claude는 요청서 끝에 개발팀이 되물을 만한 질문을 적어 준다. "하루 문의가 몇 건인가요?", "개인정보를 가리는 일은 누가 책임지나요?", "초안이 틀렸다는 것을 상담원이 어떻게 표시하나요?" 세 번째 질문을 본 정 이사는 한 가지를 더한다. "상담원이 초안을 버리면 이유를 하나 고르게 한다." 한 달 뒤 이 이유들을 모아 보니 교환 문의 초안이 가장 많이 버려졌다. 정 이사는 교환 정책 문서를 기준 자료로 넣어 달라며 요청서를 한 번 고친다.

따라 하기

1. 우리 회사 시스템 가운데 "여기서 Claude가 바로 불리면 좋겠다" 싶은 지점 하나를 고른다. 성공 기준: 앞의 표로 따져 보았을 때 채팅·스킬·자동화보다 API가 맞는 이유를 한 문장으로 말할 수 있다.
2. 그 지점에서 Claude에게 들어갈 것(입력)과 나올 것(출력)을 각각 적는다. 성공 기준: 입력과 출력이 "문의 본문", "분류 결과"처럼 구체적인 항목 이름이다.
3. 사람이 확인하는 지점을 표시한다. 성공 기준: 밖으로 나가는 일이 있다면, 그 앞에 반드시 사람이 직접 누르는 단계가 있다.
4. 넣으면 안 되는 데이터를 98단계 등급표에서 가져와 적는다. 성공 기준: 금지 데이터가 항목 이름으로 적혀 있고, 그런 데이터가 들어왔을 때의 처리도 적혀 있다.
5. 아래 프롬프트로 개발팀에 넘길 요청서 초안을 만들고, 93단계 방식의 기준표를 붙인다. 성공 기준: 개발팀장이 읽고 던지는 질문이 "무엇을 넣나요" 같은 기본 질문을 넘어선다.

복사해 쓰는 프롬프트

개발팀에 넘길 요청서를 한 페이지로 써 줘. 개발 용어는 최소로.

- 어느 시스템의 어느 지점: [예: 고객 문의 시스템, 문의 접수 직후]
- 왜 API인가: [예: 하루 문의가 많고, 상담원이 화면을 오가지 않게 하려고]
- Claude에 넣을 것: [예: 문의 제목과 본문, 문의 유형]
- Claude에서 받을 것: [예: 분류 결과와 답변 초안]
- 사람이 확인하는 지점: [누가, 언제, 어느 화면에서]
- 넣으면 안 되는 데이터와 처리: [예: 이름, 전화번호, 주문번호. 가린 뒤 보낸다]
- 좋은 결과의 기준: [기준표]
- 틀렸을 때의 처리: [예: 분류 불가로 표시하고 사람에게 넘김]
- 결과를 되돌아볼 방법: [예: 상담원이 초안을 버린 이유를 기록]

마지막에 개발팀이 나에게 되물을 만한 질문을 다섯 개 적어 줘.
내가 적지 않은 내용을 지어내지 말고, 비어 있는 항목은 [확인 필요]로 둬.

막히면 이렇게

스스로 점검

• ☐ 내가 고른 지점에 왜 API가 필요한지, 채팅이나 자동화로는 왜 부족한지 설명할 수 있는가
• ☐ 요청서에 사람이 확인하는 지점과 넣으면 안 되는 데이터가 적혀 있는가
• ☐ API로 돌아가는 기능이 쓸 만한지 무엇으로 확인할지 개발팀과 합의했는가

기억할 것

• 사람이 가끔 하는 일은 화면에서, 시스템 안에서 건마다 계속 도는 일은 API로.
• API로 보내는 데이터도 밖으로 나가는 데이터다. 사람이 걸러 볼 기회가 없으니 금지 항목을 미리 적는다.
• 개발팀에는 요청서와 기준표를 함께 넘긴다.

더 알아보기 · API 개요 · Claude 쿡북