> ## Documentation Index
> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Claude Code를 프로그래밍 방식으로 실행하기

> Agent SDK를 사용하여 CLI, Python 또는 TypeScript에서 Claude Code를 프로그래밍 방식으로 실행합니다.

[Agent SDK](https://platform.claude.com/docs/ko/agent-sdk/overview)는 Claude Code를 구동하는 동일한 도구, 에이전트 루프 및 컨텍스트 관리를 제공합니다. 스크립트 및 CI/CD용 CLI로 사용하거나 완전한 프로그래밍 방식 제어를 위한 [Python](https://platform.claude.com/docs/ko/agent-sdk/python) 및 [TypeScript](https://platform.claude.com/docs/ko/agent-sdk/typescript) 패키지로 사용할 수 있습니다.

<Note>
  CLI는 이전에 "헤드리스 모드"라고 불렸습니다. `-p` 플래그 및 모든 CLI 옵션은 동일한 방식으로 작동합니다.
</Note>

CLI에서 Claude Code를 프로그래밍 방식으로 실행하려면 프롬프트와 함께 `-p`를 전달하고 [CLI 옵션](/ko/cli-reference)을 사용합니다:

```bash theme={null}
claude -p "Find and fix the bug in auth.py" --allowedTools "Read,Edit,Bash"
```

이 페이지는 CLI(`claude -p`)를 통한 Agent SDK 사용을 다룹니다. 구조화된 출력, 도구 승인 콜백 및 기본 메시지 객체가 있는 Python 및 TypeScript SDK 패키지의 경우 [전체 Agent SDK 문서](https://platform.claude.com/docs/ko/agent-sdk/overview)를 참조하십시오.

## 기본 사용법

`-p`(또는 `--print`) 플래그를 모든 `claude` 명령에 추가하여 비대화형으로 실행합니다. 모든 [CLI 옵션](/ko/cli-reference)은 `-p`와 함께 작동합니다:

* `--continue`는 [대화 계속하기](#continue-conversations)용
* `--allowedTools`는 [도구 자동 승인](#auto-approve-tools)용
* `--output-format`은 [구조화된 출력](#get-structured-output)용

이 예제는 코드베이스에 대해 Claude에 질문하고 응답을 출력합니다:

```bash theme={null}
claude -p "What does the auth module do?"
```

## 예제

이 예제들은 일반적인 CLI 패턴을 강조합니다.

### 구조화된 출력 가져오기

`--output-format`을 사용하여 응답이 반환되는 방식을 제어합니다:

* `text`(기본값): 일반 텍스트 출력
* `json`: 결과, 세션 ID 및 메타데이터가 포함된 구조화된 JSON
* `stream-json`: 실시간 스트리밍을 위한 줄 구분 JSON

이 예제는 세션 메타데이터와 함께 프로젝트 요약을 JSON으로 반환하며, 텍스트 결과는 `result` 필드에 있습니다:

```bash theme={null}
claude -p "Summarize this project" --output-format json
```

특정 스키마를 준수하는 출력을 얻으려면 `--output-format json`을 `--json-schema` 및 [JSON Schema](https://json-schema.org/) 정의와 함께 사용합니다. 응답에는 요청에 대한 메타데이터(세션 ID, 사용량 등)가 포함되며 구조화된 출력은 `structured_output` 필드에 있습니다.

이 예제는 함수 이름을 추출하고 문자열 배열로 반환합니다:

```bash theme={null}
claude -p "Extract the main function names from auth.py" \
  --output-format json \
  --json-schema '{"type":"object","properties":{"functions":{"type":"array","items":{"type":"string"}}},"required":["functions"]}'
```

<Tip>
  [jq](https://jqlang.github.io/jq/)와 같은 도구를 사용하여 응답을 구문 분석하고 특정 필드를 추출합니다:

  ```bash theme={null}
  # 텍스트 결과 추출
  claude -p "Summarize this project" --output-format json | jq -r '.result'

  # 구조화된 출력 추출
  claude -p "Extract function names from auth.py" \
    --output-format json \
    --json-schema '{"type":"object","properties":{"functions":{"type":"array","items":{"type":"string"}}},"required":["functions"]}' \
    | jq '.structured_output'
  ```
</Tip>

### 응답 스트리밍

`--output-format stream-json`을 `--verbose` 및 `--include-partial-messages`와 함께 사용하여 생성되는 토큰을 수신합니다. 각 줄은 이벤트를 나타내는 JSON 객체입니다:

```bash theme={null}
claude -p "Explain recursion" --output-format stream-json --verbose --include-partial-messages
```

다음 예제는 [jq](https://jqlang.github.io/jq/)를 사용하여 텍스트 델타를 필터링하고 스트리밍 텍스트만 표시합니다. `-r` 플래그는 원본 문자열(따옴표 없음)을 출력하고 `-j`는 줄 바꿈 없이 조인하므로 토큰이 계속 스트리밍됩니다:

```bash theme={null}
claude -p "Write a poem" --output-format stream-json --verbose --include-partial-messages | \
  jq -rj 'select(.type == "stream_event" and .event.delta.type? == "text_delta") | .event.delta.text'
```

콜백 및 메시지 객체를 사용한 프로그래밍 방식 스트리밍의 경우 Agent SDK 문서의 [실시간 응답 스트리밍](https://platform.claude.com/docs/ko/agent-sdk/streaming-output)을 참조하십시오.

### 도구 자동 승인

`--allowedTools`를 사용하여 Claude가 프롬프트 없이 특정 도구를 사용하도록 합니다. 이 예제는 테스트 스위트를 실행하고 실패를 수정하며, Claude가 권한을 요청하지 않고 Bash 명령을 실행하고 파일을 읽고 편집할 수 있도록 합니다:

```bash theme={null}
claude -p "Run the test suite and fix any failures" \
  --allowedTools "Bash,Read,Edit"
```

### 커밋 생성

이 예제는 스테이징된 변경 사항을 검토하고 적절한 메시지로 커밋을 생성합니다:

```bash theme={null}
claude -p "Look at my staged changes and create an appropriate commit" \
  --allowedTools "Bash(git diff *),Bash(git log *),Bash(git status *),Bash(git commit *)"
```

`--allowedTools` 플래그는 [권한 규칙 구문](/ko/settings#permission-rule-syntax)을 사용합니다. 뒤의 ` *`는 접두사 일치를 활성화하므로 `Bash(git diff *)`는 `git diff`로 시작하는 모든 명령을 허용합니다. 공백이 중요합니다: 없으면 `Bash(git diff*)`도 `git diff-index`와 일치합니다.

<Note>
  사용자가 호출한 [skills](/ko/skills)(`/commit` 등) 및 [기본 제공 명령](/ko/commands)은 대화형 모드에서만 사용할 수 있습니다. `-p` 모드에서는 대신 수행하려는 작업을 설명합니다.
</Note>

### 시스템 프롬프트 사용자 정의

`--append-system-prompt`를 사용하여 Claude Code의 기본 동작을 유지하면서 지침을 추가합니다. 이 예제는 PR diff를 Claude에 파이프하고 보안 취약점을 검토하도록 지시합니다:

```bash theme={null}
gh pr diff "$1" | claude -p \
  --append-system-prompt "You are a security engineer. Review for vulnerabilities." \
  --output-format json
```

기본 프롬프트를 완전히 바꾸는 `--system-prompt`를 포함한 더 많은 옵션은 [시스템 프롬프트 플래그](/ko/cli-reference#system-prompt-flags)를 참조하십시오.

### 대화 계속하기

`--continue`를 사용하여 가장 최근 대화를 계속하거나 `--resume`을 세션 ID와 함께 사용하여 특정 대화를 계속합니다. 이 예제는 검토를 실행한 다음 후속 프롬프트를 보냅니다:

```bash theme={null}
# 첫 번째 요청
claude -p "Review this codebase for performance issues"

# 가장 최근 대화 계속
claude -p "Now focus on the database queries" --continue
claude -p "Generate a summary of all issues found" --continue
```

여러 대화를 실행 중인 경우 세션 ID를 캡처하여 특정 대화를 재개합니다:

```bash theme={null}
session_id=$(claude -p "Start a review" --output-format json | jq -r '.session_id')
claude -p "Continue that review" --resume "$session_id"
```

## 다음 단계

* [Agent SDK 빠른 시작](https://platform.claude.com/docs/ko/agent-sdk/quickstart): Python 또는 TypeScript로 첫 번째 에이전트 구축
* [CLI 참조](/ko/cli-reference): 모든 CLI 플래그 및 옵션
* [GitHub Actions](/ko/github-actions): GitHub 워크플로우에서 Agent SDK 사용
* [GitLab CI/CD](/ko/gitlab-ci-cd): GitLab 파이프라인에서 Agent SDK 사용