[AI][Claude] CLI subprocess 호출 : 프로젝트에 API 없이 AI 붙이기

프로젝트에 API 없이 AI 붙이기

프로젝트에 요약, 분류, 번역 같은 AI 기능을 넣고 싶다. 그런데 API 호출을 사용하여 실험 단계에서 이것저것 돌려보다 보면 한 달에 수십 달러가 우습게 나간다. 이미 구독을 쓰고 있다면, API 호출 대신 Claude Code CLI를 subprocess로 불러서 같은 일을 할 수 있다. Anthropic이 공식적으로 지원하는 헤드리스 모드를 활용하는 방법이다.

이 방식이 맞는 상황인지 먼저 확인해 보자.

상황	적합도
혼자 쓰는 사이드 프로젝트, 로컬 자동화	매우 적합
프롬프트 실험, 반복 테스트	적합
배치 처리 (하루 수십~수백 건)	구독 리밋 체크 필요
외부 사용자에게 서비스 제공	API로 가야 함
24/7 백그라운드 자동화	레이트 리밋 자주 걸림

API 종량제는 개인 프로젝트에 최적화돼 있지 않다. Anthropic API 요금은 본래 B2B 서비스 워크로드 기준으로 설계된다. 숫자만 보면 저렴해 보이지만, 개인 프로젝트 맥락에 올려놓으면 이야기가 달라진다. 예를 들어 사이드 프로젝트에 문서 요약 기능 하나를 붙였다고 해보자. 문서당 평균 3천 토큰 입력 / 500 토큰 출력이고, 개발 중에 프롬프트 튜닝하면서 하루 100번쯤 실험적으로 돌린다면 Opus 기준 계산은 이렇다.

• 입력: 3000 × 100 = 30만 토큰 → $1.5 / 일
• 출력: 500 × 100 = 5만 토큰 → $1.25 / 일
• 하루 약 $2.75, 한 달 약 $82

반면 Pro 구독은 월 $20 정액이다.

다른 대안은 모두 어딘가 부족하다.

대안	한계
API 직접 호출	비용 예측 불가, 청구서 공포
무료 티어(Free)	일일 제한, 자동화 실질 불가
로컬 LLM (Ollama 등)	Claude 대비 성능 격차, 세팅/유지 부담
Claude.ai에서 수동 복붙	자동화 불가, 파이프라인 못 만듦

1. Claude Code CLI subprocess 호출

Claude Code는 원래 터미널에서 대화형으로 쓰는 코딩 CLI지만, -p(또는 --print) 플래그를 붙이면 비대화형(non-interactive) 모드로 돌아간다. 이 모드는 과거에 headless mode라고 불렸고, 공식 문서에도 CI/CD, 스크립트, 자동화 용도로 쓰라고 안내돼 있다.

• Claude Code는 구독 계정으로 인증된다. claude login 한 번이면 Pro/Max 구독으로 연결된다.
• -p 모드에서도 그 인증이 그대로 쓰인다. 즉, API 키 없이 subprocess 호출로 모델을 쓸 수 있다.

환경 변수에 ANTHROPIC_API_KEY가 설정돼 있으면 구독이 아니라 API로 결제된다. subprocess 호출 전에 반드시 이 변수를 비워둬야 한다.

unset ANTHROPIC_API_KEY
claude login   # 구독 계정으로 인증
claude -p "Say hello in 15 words"

2. Claude Code -p 기본기

가장 단순한 호출

claude -p "2 + 2는?"

프롬프트를 인자로 넘기면, Claude가 답을 stdout으로 뱉고 종료된다. 파이프로 stdin을 받을 수도 있다.

cat report.txt | claude -p "이 문서를 세 줄로 요약해줘"

자주 쓰는 플래그

플래그	역할
-p, --print	비대화형 실행
--output-format json	구조화된 JSON 결과
--output-format stream-json	스트리밍 JSON
--allowedTools "Read,Edit"	Claude가 쓸 수 있는 도구를 제한
--append-system-prompt	시스템 프롬프트에 지시 추가
--system-prompt	시스템 프롬프트 전체 교체
--continue	직전 대화 이어가기
--resume <session_id>	특정 세션 이어가기
--bare	자동 탐색 스킵해서 시작 시간 단축

기본 호출은 시작할 때마다 hooks, skills, plugins, MCP 서버, CLAUDE.md 등을 자동 탐색한다. subprocess로 대량 호출할 때는 이 오버헤드가 누적된다. 자동화 용도라면 --bare를 붙이자.

3. 구조화된 출력 받아내기

subprocess 결과를 프로그램이 파싱하려면 JSON이 답이다.

--output-format json

claude -p "함수 이름 리스트를 뽑아줘" --output-format json

결과는 이런 형태로 result 필드만 파싱하면 된다.

{
  "type": "result",
  "subtype": "success",
  "result": "실제 응답 텍스트...",
  "duration_ms": 1234,
  "total_cost_usd": 0.01,
  "session_id": "...",
  "structured_output": null
}

--json-schema로 스키마 강제

출력을 특정 구조에 맞추고 싶으면 JSON Schema를 명시할 수 있다. 이러면 Claude가 스키마에 맞춰 출력한다. 후처리에서 정규식 파싱하는 지옥을 피할 수 있다. 단, --json-schema를 쓰면 파싱된 결과는 result가 아니라 structured_output 필드에 dict 형태로 들어온다.

claude -p "이 파일에서 함수 이름만 뽑아줘" \
  --output-format json \
  --json-schema '{
    "type": "object",
    "properties": {
      "functions": {
        "type": "array",
        "items": { "type": "string" }
      }
    },
    "required": ["functions"]
  }' < auth.py

대화 이어가기

요약 한 번 → 후속 질문 같은 흐름이라면 --continue를 쓰면 된다. --continue는 "직전 세션"을 찾기 때문에 병렬 실행에는 적합하지 않다. 여러 흐름을 동시에 돌려야 하면 --resume <session_id>로 세션 ID를 명시적으로 관리하자.

claude -p "이 코드베이스의 성능 이슈를 분석해줘"
claude -p "방금 찾은 이슈 중 DB 관련만 추려줘" --continue
claude -p "각 이슈에 대한 수정안을 JSON으로 정리" --continue --output-format json

4. Python subprocess로 감싸기

Python에서 Claude Code CLI를 subprocess로 불러 쓰는 가장 기본 형태이다.

import subprocess
import json

def ask_claude(prompt: str) -> dict:
    result = subprocess.run(
        ["claude", "-p", "--bare", "--output-format", "json", prompt],
        capture_output=True,
        text=True,
        timeout=60,
    )
    data = json.loads(result.stdout)
    if data.get("subtype") != "success":
        raise RuntimeError(f"claude error: {data}")
    return data

res = ask_claude("파이썬에서 리스트 정렬하는 한 줄짜리 코드")
print(res["result"])
print(f"소요 시간: {res['duration_ms']}ms")

긴 입력은 stdin으로

프롬프트가 길거나 동적 콘텐츠가 많으면 인자 길이 제한에 걸린다. 이럴 땐 stdin으로 파이프하자.

def summarize_file(path: str) -> str:
    with open(path, "r", encoding="utf-8") as f:
        content = f.read()
    result = subprocess.run(
        ["claude", "-p", "--bare", "이 문서를 세 줄로 요약해줘"],
        input=content,
        capture_output=True,
        text=True,
        timeout=120,
    )
    return result.stdout.strip()

5. 실전 활용 예시

이메일 분류기

받은 메일함을 훑어서 카테고리와 긴급도를 태깅한다. 스키마를 강제하면 파싱이 깔끔해진다.

import json
import subprocess

SCHEMA = {
    "type": "object",
    "properties": {
        "category": {
            "type": "string",
            "enum": ["업무", "광고", "뉴스레터", "개인", "기타"]
        },
        "urgency": {"type": "string", "enum": ["high", "mid", "low"]},
        "summary": {"type": "string"}
    },
    "required": ["category", "urgency", "summary"]
}

def classify_email(body: str) -> dict:
    result = subprocess.run(
        [
            "claude", "-p", "--bare",
            "--output-format", "json",
            "--json-schema", json.dumps(SCHEMA),
            "이 이메일을 분류하고 요약해:"
        ],
        input=body,
        capture_output=True,
        text=True,
        timeout=60,
    )
    data = json.loads(result.stdout)
    return data["structured_output"]

Git 커밋 메시지 생성기

스테이지된 변경사항을 기반으로 커밋 메시지를 만들어 주는 훅이다.

#!/usr/bin/env bash
# .git/hooks/prepare-commit-msg
DIFF=$(git diff --cached)
[ -z "$DIFF" ] && exit 0

MSG=$(echo "$DIFF" | claude -p --bare \
  --append-system-prompt "You output only a conventional commit message, no explanation." \
  "Generate a conventional commit message for this diff")

echo "$MSG" > "$1"

6. 주의사항과 함정

레이트 리밋

구독은 5시간 롤링 윈도우 기준이다. subprocess로 무한 루프 돌려서 갈기면 금방 한도에 걸린다. Pro에서 자주 막힌다면 루프에 지수 백오프를 넣거나, 그래도 자주 걸리면 윈도우 리셋을 기다리거나 Max로 올려야 한다.

import time

for item in items:
    try:
        process(item)
    except RuntimeError as e:
        if "rate limit" in str(e).lower():
            time.sleep(60)
            continue
        raise

헤드리스 모드의 한정된 동작

-p 모드는 대화형 모드와 다르다. /commit 같은 사용자 호출 슬래시 커맨드는 동작하지 않는다. 권한 프롬프트가 뜰 상황이 되면 그냥 실패한다. 이걸 피하려면 --allowedTools로 필요한 도구만 화이트리스트 해야 한다. --dangerously-skip-permissions라는 플래그도 있지만, 이름 그대로 위험하다. 본인 PC의 격리된 디렉토리가 아니면 쓰지 말자.

프롬프트 인젝션 리스크

외부 입력(웹 폼, 크롤링한 HTML, 사용자 입력)을 프롬프트에 그대로 끼워 넣고 --allowedTools "Bash" 같은 걸 허용하면 원격 코드 실행 취약점이 된다. 외부 입력을 쓸 거면 도구 권한을 최소한으로 제한하자.

복합 작업은 쪼개라

한 번의 claude -p 호출에서 "웹 검색 + 페이지 fetch + 대규모 문서 작성"을 한 번에 시키면 응답이 멈추는 현상이 보고된 적이 있다. subprocess 방식으로 자동화할 때는 한 호출 = 한 단위 작업으로 쪼개는 게 안정적이다.

ToS와 선의의 사용

Claude Code 구독은 본인이 개발할 때 쓰는 도구다. 구독 인증을 서버에 띄워 다른 사용자에게 서비스를 제공하거나, 24/7 백그라운드 자동화로 사실상 API 트래픽을 구독으로 치환하는 건 구독의 선을 넘는다. 로컬에서 본인 프로젝트에 쓰는 subprocess 호출은 정상 사용에 가깝다. 서비스화 단계로 가면 API로 전환하는 게 맞다.

참고

https://code.claude.com/docs/en/headless

Run Claude Code programmatically - Claude Code Docs

claude-code GitHub

GitHub - anthropics/claude-code: Claude Code is an agentic coding tool that lives in your terminal, understands your codebase, a

Claude Code pricing & plans

Plans & Pricing | Claude by Anthropic