studiosoluta

먼저 볼 카드 — 설치

실습 Headless

창 없이 한 번에 실행하기

이 카드를 다루는 수업 좋은 프롬프트로 이미지와 영상 만들기 파리 거리에서 자전거 타기

  • 대화 세션이 맞는 일: 사람이 중간에 판단해야 할 때
  • 요청이 매번 같고 결과 형태가 정해져 있으면, 세션 열기부터 답 복사·붙여넣기까지가 전부 반복 비용입니다
  • claude -p: 대화창을 열지 않고 요청 하나를 실행합니다
    • 답은 터미널 출력으로 나오고, 실행이 끝나면 세션이 닫힙니다
    • 결과를 파일로 넘기거나 다른 프로그램에 이어 붙일 수 있습니다
    • 쓰는 곳: 정해진 검사를 저장소에 올릴 때마다 자동으로 돌리는 CI
  • 데스크탑 앱에는 같은 기능이 없어, 이 코스에서 명령어를 피하기 어려운 몇 안 되는 지점입니다
  • 필요한 세 조각: 요청 문장, 미리 승인할 도구, 결과를 보낼 곳

미리 승인하는 도구는 좁게 잡습니다

  • -p 실행에는 확인 창이 없어, 승인이 필요한 지점에 닿으면 거기서 멈춥니다
  • --allowedTools로 미리 승인하면 멈추지 않고 끝까지 진행합니다
  • 넓게 잡을수록 확인 없이 실행되는 범위가 넓어집니다
    • 읽어서 정리하는 일: Read
    • 파일을 고쳐야 할 때: Edit 추가
    • Bash: 명령을 직접 실행하는 도구라 초보 단계의 자동 실행에는 넣지 않습니다

내가 만들지 않은 폴더에서는 —bare를 붙입니다

  • -p 세션에는 폴더 신뢰 확인 창이 뜨지 않습니다
  • 옵션 없이 실행하면 .claude/settings.json의 Hook이 그대로 실행되고, .mcp.json의 서버에도 연결됩니다
  • 문제가 되는 곳: 내려받은 저장소, 남에게 받은 폴더
  • --bare: Hook·스킬·플러그인·MCP 서버·CLAUDE.md를 모두 읽지 않고 실행합니다
  • 어느 컴퓨터에서 돌려도 같은 결과가 나와, 저장소를 처음 열어 볼 때와 CI 검사에 씁니다

성공 여부는 종료 코드로 확인합니다

  • 화면에 답이 나왔다고 성공한 것은 아닙니다
  • 실행이 실패하면 0이 아닌 종료 코드를 남깁니다
  • 인증이 빠진 경우처럼 실행 도중 생긴 실패는 결과에 그대로 출력됩니다
  • 명령을 이어 붙이거나 자동으로 돌릴 때는 종료 코드로 다음 동작을 정합니다
  • 순서 아래 명령을 그대로 붙여넣어 결과 파일이 실제로 만들어지는지 확인해 보세요

실행 순서

  1. 한 번에 끝낼 요청 하나를 문장으로 정합니다. 결과가 화면 출력이나 파일로 남는 일만 고르고, 중간에 사람에게 되물어야 하는 일은 대화 세션에 남겨 둡니다.

  2. 작업할 폴더로 이동한 뒤 요청을 붙여 실행합니다. 답이 대화창 대신 터미널에 바로 출력됩니다.

    명령어로 직접 하기

    일반 터미널에서 실행합니다. Claude Code 세션 안이 아닙니다. -p는 --print의 짧은 형태이고, 실행이 끝나면 세션이 그대로 닫힙니다.

    claude -p "이 폴더의 README를 읽고 핵심을 다섯 줄로 요약해 줘"
  3. 쓸 도구를 미리 지정합니다. 지정하지 않으면 실행 도중 승인 창이 필요한 지점에서 멈춥니다.

    명령어로 직접 하기

    미리 승인한 도구는 실행 중 확인 없이 쓰입니다. 읽기만 필요하면 Read만 넣고, 파일을 고치거나 명령을 실행하는 도구는 필요한 것만 하나씩 추가합니다.

    claude -p "이 폴더의 문서 목록을 표로 정리해 줘" --allowedTools "Read"
  4. 결과를 파일로 받습니다. 화면에 흘려보내지 않고 남겨야 다음 작업에서 쓸 수 있습니다.

    명령어로 직접 하기

    > 뒤에 적은 이름으로 파일이 새로 만들어집니다. 같은 이름이 이미 있으면 덮어쓰므로 새 이름을 씁니다.

    claude -p "이 폴더의 README를 읽고 핵심을 다섯 줄로 요약해 줘" --allowedTools "Read" > summary.md
  5. 내가 만들지 않은 폴더에서 실행할 때는 그 폴더의 설정을 읽지 않게 합니다.

    명령어로 직접 하기

    --bare는 그 폴더의 Hook·스킬·플러그인·MCP 서버·CLAUDE.md를 읽지 않고 실행합니다. 붙이지 않으면 신뢰 확인 창 없이 그것들이 그대로 실행됩니다.

    claude -p "이 폴더가 무슨 프로젝트인지 설명해 줘" --bare --allowedTools "Read"
  6. 명령이 끝난 뒤 종료 코드를 확인합니다. 0이면 성공이고, 0이 아니면 실행이 실패한 것입니다.

    명령어로 직접 하기

    직전 명령의 종료 코드를 출력합니다. Windows PowerShell에서는 $LASTEXITCODE를 씁니다.

    echo $?
이 순서를 한 번에 실행
터미널에서 claude -p를 써서 지금 폴더의 파일 목록을 표로 정리하고 결과를 files.md로 저장하는 명령 한 줄을 만들어 줘. 읽기 도구만 미리 승인하고, 명령의 각 부분이 무슨 뜻인지 한 줄씩 설명해 줘.

직접 해보기

대괄호 안은 실제 값으로 바꿔서 붙여넣습니다.

내 상황에 맞춰
내가 매번 반복하는 요청이 있어: [여기에 반복 요청]. 이걸 claude -p 한 줄로 바꿔 줘. 도중에 나한테 되물어야 하는 부분이 있으면 그건 대화 세션에 남기라고 알려 주고, 명령으로 옮길 수 있는 부분만 만들어 줘.
한 단계 더
claude -p를 --bare 없이 남의 저장소 폴더에서 실행하면 무엇이 자동으로 실행되는지 공식 문서를 근거로 설명해 줘. 지금 이 폴더에 그런 설정 파일이 있는지도 확인해 줘.

지금 작업 중인 폴더에서 읽기만 하는 요청 하나를 골라 claude -p로 실행하고, 결과를 파일로 저장해 열어 보세요.

헷갈리기 쉬운 것

--bare 없이 실행하면 그 폴더의 .claude/settings.json에 있는 Hook과 .mcp.json에 적힌 서버가 신뢰 확인 창 없이 실행되고 연결됩니다. 내려받은 폴더나 남이 준 폴더에서는 --bare를 붙이거나 설정 파일을 먼저 열어 봅니다. --allowedTools에 Bash를 통째로 넣으면 확인 없이 명령이 실행되므로, 삭제·배포·발송이 섞일 수 있는 요청에는 쓰지 않습니다. 결과를 > 로 내보낼 때 기존 파일 이름을 쓰면 내용이 덮어써집니다.

용어 풀이

전체 용어집 →
비대화형 실행
대화창을 열지 않고 명령 한 줄로 요청을 실행해 결과만 받는 방식입니다.
종료 코드
명령이 끝날 때 남기는 숫자입니다. 0이면 성공, 0이 아니면 실패를 뜻합니다.
CI
코드를 저장소에 올릴 때마다 정해진 검사를 자동으로 돌려 주는 서버입니다.

2026-08-19 기준 · 출처 · Claude Code — Run Claude Code programmatically, Claude Code — CLI reference