blevels

Home / AI / AI 바이브코딩 / API 연동 자동화 — AI에게 외부 서비스 붙이기 시키기

VIBE

API 연동 자동화 — AI에게 외부 서비스 붙이기 시키기

게시일 2026-04-30수정일 2026-04-30
공식 링크
On this page

:::callout type=info 이 튜토리얼은 Claude Code 1.x / Node.js 20 기준입니다 (2026-04). 도구 업데이트 시 검토 필요. :::

외부 API를 프로젝트에 붙이는 작업은 반복적이다. 인증 설정, 엔드포인트 호출, 에러 처리, 환경 변수 관리. 매번 문서를 뒤지고 시행착오를 겪는 대신, AI에게 연동 작업 전 과정을 위임할 수 있다. 단, 올바른 방법으로 접근해야 한다. 추측이 아닌 공식 문서 기반으로, 실행 전에 먼저 조사하는 순서를 지켜야 한다. 이 원칙 하나가 AI 연동 자동화의 성패를 가른다.

연동 전 조사가 먼저다

AI에게 API 연동을 시키기 전에, AI 스스로 해당 서비스의 공식 문서나 SDK를 먼저 조사하도록 지시한다. 이 단계를 건너뛰면 AI가 기억에 의존한 추측 코드를 작성하고, 실제 API 스펙과 달라 런타임 오류가 발생한다.

좋은 프롬프트 예시:

Notion API를 연동해야 한다. 먼저 공식 문서에서
데이터베이스 조회 엔드포인트 스펙을 확인하고,
그 스펙에 맞는 코드를 작성해라. 추측으로 작성하지 마라.

준비물

  • Claude Code CLI (최신 버전)
  • Node.js 20+
  • 연동할 서비스의 API 키
  • 예상 시간: 40분

1단계 — 환경 변수 파일 정리

연동 전에 필요한 크리덴셜을 .env 파일에 정리한다. .gitignore에 .env가 포함됐는지 반드시 확인한다.

# .env
NOTION_TOKEN=secret_xxxx
NOTION_DATABASE_ID=xxxx
TELEGRAM_BOT_TOKEN=xxxx
TELEGRAM_CHAT_ID=xxxx

Claude Code에 지시할 때는 process.env.NOTION_TOKEN 형태로 참조하도록 명시한다. API 키를 코드에 하드코딩하지 말 것을 명시적으로 금지하는 규칙을 CLAUDE.md에 추가해 두면 AI가 자동으로 환경 변수를 사용한다.

AD

2단계 — SDK 또는 fetch 방식 선택

SDK가 있는 서비스라면 SDK를 우선한다. SDK는 인증, 재시도, 타입 정의를 제공한다. fetch 직접 호출은 SDK가 없거나 번들 크기를 줄여야 할 때 쓴다.

# Notion SDK 설치
npm install @notionhq/client

# Telegram Bot API는 SDK 없이 fetch 직접 사용

Claude Code에 요청할 때 방식을 명확히 지시한다.

@notionhq/client SDK를 사용해서 NOTION_DATABASE_ID 데이터베이스의
레코드를 가져오는 함수를 작성해라.
filter: Status = "발행승인"인 레코드만.
반환 타입을 TypeScript 인터페이스로 정의해라.

3단계 — 에러 처리 구조 지시

API 연동 코드에는 에러 처리가 필수다. silent catch는 금지한다. AI에게 지시할 때 에러 처리 방식을 명확히 포함한다.

에러 처리 규칙:

- 네트워크 오류: 3회 재시도 후 throw
- 인증 오류(401): throw, 재시도 없음
- .catch(() => {}) 같은 silent catch 금지
- 에러 발생 시 console.error로 상세 로그 출력

이 규칙을 CLAUDE.md의 금지 행동 섹션에 한 번만 정의해 두면 매 요청마다 반복하지 않아도 된다.

AD

4단계 — Dry-run으로 먼저 확인

외부 API에 실제 요청을 보내기 전, dry-run 모드를 먼저 구현하도록 지시한다.

--live 플래그 없이 실행하면 실제 API 호출을 하지 않고
예상 동작만 콘솔에 출력하는 dry-run 모드로 동작해야 한다.
# dry-run 실행
node scripts/notion-sync.mjs

# 실제 실행
node scripts/notion-sync.mjs --live

이 패턴을 따르면 실수로 외부 서비스에 중복 요청을 보내거나 데이터를 덮어쓰는 사고를 예방한다.

결과 확인

연동 스크립트가 완성되면 다음 순서로 검증한다.

1. dry-run 실행 → 예상 동작 출력 확인 2. --live 실행 → 실제 API 응답 확인 3. 에러 케이스 테스트 → 잘못된 토큰으로 실행해 에러 처리 확인

다음 단계

API 연동이 완료되면 GitHub Actions에서 자동으로 실행되도록 워크플로를 연결하는 단계로 넘어간다. GHA 워크플로에서 환경 변수는 GitHub Secrets에 저장하고 ${{ secrets.NOTION_TOKEN }} 형태로 참조한다. 워크플로 파일을 push하기 전에 반드시 npm run lint:gha로 문법을 검증한다.

관련 가이드: mcp-입문 / 테스트-자동화 / 훅-설정하기

AD