Headless 모드 & SDK

동작하는 코드

claude -p 플래그로 비대화형(headless) 모드를 사용해봅시다:

claude -p "이 프로젝트의 아키텍처를 분석해줘"

결과가 출력되고 프로세스가 종료됩니다. 대화형 세션을 열지 않으므로 스크립트에서 사용하기 좋습니다.

파이프로 입력을 전달할 수도 있습니다:

cat error.log | claude -p "이 에러 로그를 분석해줘"

JSON 형태로 출력받으려면:

claude -p --output-format json "package.json의 의존성을 분석해줘"

구조화된 JSON으로 결과를 받아서 다른 도구에서 파싱할 수 있습니다.

직접 수정하기

일일 자동화 스크립트를 만들어봅시다:

#!/bin/bash
# daily-check.sh — 매일 아침 실행하는 프로젝트 점검 스크립트

echo "=== 코드 품질 점검 ==="
claude -p "src/ 디렉토리에서 TODO, FIXME, HACK 주석을 모아서 우선순위를 매겨줘"

echo ""
echo "=== 보안 점검 ==="
claude -p "package.json의 의존성 중 보안 취약점이 있는지 확인해줘"

echo ""
echo "=== 테스트 상태 ==="
claude -p "npm test를 실행하고 실패하는 것이 있으면 원인을 분석해줘"

이 스크립트를 cron이나 CI에 등록하면 자동으로 매일 점검이 실행됩니다.

"왜?" — 대화형을 넘어 시스템으로

지금까지 Claude Code를 터미널에서 대화형으로 사용했습니다. Headless 모드는 Claude Code를 하나의 CLI 도구로 바꿉니다. grep, jq, curl처럼 파이프라인의 한 단계로 사용할 수 있습니다.

핵심 플래그

| 플래그 | 기능 | | ----------------------------- | --------------------------------- | | -p "프롬프트" | 비대화형 실행 (결과 출력 후 종료) | | --output-format json | JSON 형식 출력 | | --output-format stream-json | 스트리밍 JSON 출력 | | --max-turns N | 최대 턴 수 제한 |

파이프라인 활용 패턴

# 에러 로그 분석
cat error.log | claude -p "이 에러의 근본 원인을 찾아줘"

# PR diff 리뷰
gh pr diff 42 | claude -p "이 변경 사항을 시니어 개발자로 리뷰해줘"

# 코드 변환
cat legacy.js | claude -p "이 코드를 TypeScript로 변환해줘" > modern.ts

# 릴리스 노트 생성
git log --oneline v1.0..HEAD | claude -p "이 커밋들로 릴리스 노트를 작성해줘"

Claude Code SDK

TypeScript/JavaScript에서 프로그래밍적으로 호출할 수 있습니다:

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

const result = await claude({
  prompt: "이 파일의 보안 취약점을 분석해줘",
  workingDirectory: "./my-project",
});

console.log(result.stdout);

SDK를 사용하면:

• 커스텀 자동화 도구를 만들 수 있습니다.
• CI/CD 파이프라인에 Claude Code를 통합할 수 있습니다.
• 모니터링 시스템에서 코드 분석을 자동화할 수 있습니다.

CI/CD 통합 예시

# .github/workflows/ai-review.yml
name: AI Code Review
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Install Claude Code
        run: npm install -g @anthropic-ai/claude-code

      - name: Review PR
        run: |
          gh pr diff ${{ github.event.number }} | \
            claude -p "이 PR을 리뷰해줘. 버그, 보안, 성능 관점에서." \
            > review.md
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

      - name: Post Review Comment
        run: gh pr comment ${{ github.event.number }} --body-file review.md
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

심화 학습

result=$(claude -p "분석해줘" 2>/dev/null)