[Claude SDK] TypeScript로 코딩 에이전트 워크플로우 만들기

안녕하세요. 재아군의 관찰인생입니다.

오늘은 Claude SDK을 현업 개발자 관점에서 정리해보겠습니다. 최근 AI 코딩 도구는 단순히 코드를 제안하는 수준을 넘어, 코드베이스를 읽고 작업을 나누고 테스트까지 돌리는 방향으로 빠르게 이동하고 있습니다.

Claude Code를 터미널에서 쓰는 데 익숙해졌다면 다음 질문은 자연스럽게 “이 흐름을 우리 서비스나 CI 안에 넣을 수 있을까?”로 이어집니다. Claude SDK는 이 지점을 공략할 때 유용합니다.

Claude SDK는 Claude Code의 쿼리 실행, 도구 권한, MCP 설정, 메시지 스트림을 코드에서 다루게 해주는 개발자용 인터페이스입니다.

---

1. Claude SDK을 먼저 이해해야 하는 이유

터미널 대화는 빠르게 시작하기 좋지만 반복 작업을 제품화하기에는 한계가 있습니다. 매번 같은 프롬프트를 붙이고, 같은 파일을 읽고, 같은 검증을 요구한다면 코드로 워크플로우를 고정하는 편이 낫습니다.

SDK를 쓰면 “문서 변경 감지 후 요약 PR 생성”, “에러 로그 분석 후 수정 후보 제안”, “MCP 서버를 붙인 내부 도구 호출” 같은 흐름을 애플리케이션으로 만들 수 있습니다.

• 반복 프롬프트를 함수와 설정으로 관리할 수 있습니다.
• MCP 서버와 허용 도구를 실행 시점에 명시할 수 있습니다.
• 메시지 스트림을 받아 진행 상황 UI를 만들 수 있습니다.
• CI나 사내 봇과 연결하기 좋습니다.

구분	기존 방식	Claude SDK 적용 후
실행 방식	사람이 터미널에서 직접 대화	서비스 코드가 정해진 워크플로우 실행
권한 제어	대화 중 허용 여부를 수동 판단	allowedTools와 설정 파일로 제한
결과 처리	답변을 사람이 읽고 복사	메시지를 파싱해 리포트, PR, 티켓으로 연결

---

2. 핵심 구조와 동작 원리

SDK 기반 에이전트는 입력 수집, Claude 실행, 결과 처리, 검증 네 단계로 보면 됩니다. 여기에 MCP를 붙이면 파일시스템, 문서, 이슈 트래커 같은 외부 컨텍스트를 표준화해서 연결할 수 있습니다.

레이어	역할	실무에서 확인할 것
Input Layer	이슈, 로그, 파일 목록, 사용자 요청 수집	민감 정보 필터링
Agent Runtime	Claude SDK query 실행과 도구 권한 제어	allowedTools와 timeout 설정
Output Layer	메시지 스트림 저장, 리포트 생성, PR 코멘트 작성	검증 가능한 산출물로 변환

이 구조를 이해하면 AI 도구를 “똑똑한 채팅창”으로만 쓰지 않고, 팀의 개발 프로세스 안에 넣을 수 있습니다. 중요한 것은 모델 성능보다 작업 단위, 권한, 검증 루프를 먼저 설계하는 것입니다.

Issue or log input
  -> TypeScript workflow
  -> Claude SDK query(options)
  -> MCP tools and allowed tools
  -> streamed messages
  -> report, patch, or PR comment

---

3. 실무 설정 예시

아래는 TypeScript에서 Claude SDK의 query 흐름을 감싸는 기본 형태입니다. 실제 프로젝트에서는 프롬프트 템플릿과 옵션을 별도 파일로 분리하는 편이 좋습니다.

import { query } from '@anthropic-ai/claude-code';

export async function runReview(prompt: string) {
  const messages = [];

  for await (const message of query({
    prompt,
    options: {
      mcpConfig: '.mcp.json',
      allowedTools: ['Read', 'Grep', 'Bash'],
      maxTurns: 8,
    },
  })) {
    messages.push(message);
  }

  return messages;
}

MCP 설정을 함께 두면 외부 도구 연결을 코드에서 재사용할 수 있습니다. 중요한 것은 모든 MCP 도구를 열어두는 것이 아니라 워크플로우별로 필요한 도구만 허용하는 것입니다.

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-filesystem"],
      "env": {
        "ALLOWED_PATHS": "/Users/me/project"
      }
    }
  }
}

작게 시작하는 적용 순서

1. CLI에서 반복하던 작업을 하나 고릅니다.
2. 입력과 출력 형식을 먼저 고정합니다.
3. 프롬프트를 템플릿 함수로 분리합니다.
4. allowedTools를 최소 권한으로 시작합니다.
5. 결과 메시지를 저장해 회귀 테스트 샘플로 사용합니다.

---

4. 팀 워크플로우에 넣는 방법

SDK 워크플로우는 “AI에게 자유롭게 맡기는 앱”보다 “정해진 작업을 안정적으로 반복하는 앱”에 적합합니다. 즉, 챗봇보다 자동 리뷰기, 로그 분석기, 릴리스 노트 생성기 같은 도구에서 가치가 큽니다.

팀에서 운영한다면 실행 로그, 입력 원본, 사용한 도구, 최종 산출물을 함께 남겨야 합니다. 그래야 모델 결과가 이상했을 때 프롬프트 문제인지, 도구 권한 문제인지, 입력 품질 문제인지 추적할 수 있습니다.

상황	추천 역할	주의점
PR 리뷰 봇	diff와 관련 파일 읽기	쓰기 권한 없이 코멘트만 생성
로그 분석기	에러 로그와 최근 변경 파일 분석	민감 정보 마스킹 필수
문서 동기화	코드 변경 후 문서 후보 생성	자동 커밋보다 리뷰 요청 권장

• 프롬프트와 실행 옵션을 코드 리뷰 대상으로 관리합니다.
• 실패 시 재시도 횟수와 중단 조건을 명확히 둡니다.
• 도구 호출 로그를 보관합니다.
• 출력은 사람이 검토하기 쉬운 구조로 만듭니다.

---

5. 경쟁 도구와 비교해서 보는 포인트

Claude SDK는 직접 워크플로우를 설계하고 싶은 개발자에게 맞습니다. 반대로 완성된 클라우드 작업 환경을 원하면 Codex나 Copilot 에이전트가 더 빠를 수 있습니다.

도구	강점	아쉬운 점	추천 사용처
Claude SDK	앱과 CI에 깊게 통합 가능	직접 설계할 것이 많음	사내 자동화 도구와 개발자 플랫폼
Codex Cloud	백그라운드 코드 작업과 병렬 실행	세밀한 제품 내 제어는 제한적	버그 수정, 테스트 추가, PR 초안
GitHub Copilot Agent	GitHub 이슈와 PR 흐름에 강함	GitHub 중심으로 묶임	이슈 기반 구현 요청

비교의 핵심은 “어떤 도구가 최고인가”가 아니라 “어떤 작업을 맡길 때 실패 비용이 낮은가”입니다. 같은 기능 구현이라도 로컬 탐색, 클라우드 병렬 작업, GitHub 중심 PR 자동화는 운영 방식이 꽤 다릅니다.

---

6. 도입 전 체크리스트와 흔한 실수

SDK 도입에서 흔한 실수는 모델을 API 함수처럼 deterministic하게 기대하는 것입니다. AI 에이전트 워크플로우는 입력, 도구, 검증 기준이 함께 있어야 안정화됩니다.

체크 항목	좋은 기준	실패 신호
입력	필요한 파일과 맥락만 제공	전체 저장소를 무작정 읽게 함
권한	워크플로우별 allowedTools 제한	모든 도구를 기본 허용
검증	테스트와 사람 리뷰를 후단에 배치	모델 답변만으로 완료 처리

자주 생기는 실수

• 프롬프트를 코드 안에 흩뿌리는 실수
• MCP 도구 권한을 전역으로 과하게 여는 실수
• 스트리밍 메시지를 저장하지 않아 디버깅이 어려운 실수
• 테스트 없는 자동 수정 워크플로우를 바로 운영에 넣는 실수

---

7. 앞으로의 발전 방향

Claude SDK 같은 도구는 AI 코딩을 개인 생산성 도구에서 팀 플랫폼으로 옮기는 연결 고리입니다. 앞으로 개발팀은 자체 리뷰 봇, 문서 봇, 마이그레이션 봇을 더 많이 만들게 될 것입니다.

특히 MCP가 표준화되면서 SDK 워크플로우는 단일 모델 호출이 아니라 여러 데이터 소스와 도구를 조합하는 개발 플랫폼에 가까워질 가능성이 큽니다.

• 사내 개발자 포털과 AI 워크플로우 연결
• PR, 이슈, 로그, 문서의 통합 분석
• 에이전트 실행 결과의 품질 평가 자동화
• MCP 서버를 통한 권한 있는 내부 도구 호출

---

마무리

정리하면 Claude SDK은 AI 코딩 도구를 실무 프로세스에 넣기 위한 중요한 퍼즐입니다. 처음부터 거창한 자동화를 목표로 하기보다, 반복되는 작은 작업 하나를 안정적으로 맡기는 쪽이 성공 확률이 높습니다.

Claude SDK는 처음엔 약간 무겁게 느껴질 수 있지만, 반복 작업 하나를 안정적으로 자동화하는 순간 가치가 분명해집니다. CLI로 검증한 습관을 코드로 굳히는 단계라고 보면 좋습니다.

이 글이 도움이 되셨다면 댓글로 현재 사용 중인 AI 코딩 도구와 가장 자동화하고 싶은 작업을 남겨주세요. 다음 글에서 더 실전적인 예제로 이어가겠습니다.