먼저 볼 카드 — 설치
실습 Headless
창 없이 한 번에 실행하기
이 카드를 다루는 수업 좋은 프롬프트로 이미지와 영상 만들기 파리 거리에서 자전거 타기
- 대화 세션이 맞는 일: 사람이 중간에 판단해야 할 때
- 요청이 매번 같고 결과 형태가 정해져 있으면, 세션 열기부터 답 복사·붙여넣기까지가 전부 반복 비용입니다
claude -p: 대화창을 열지 않고 요청 하나를 실행합니다- 답은 터미널 출력으로 나오고, 실행이 끝나면 세션이 닫힙니다
- 결과를 파일로 넘기거나 다른 프로그램에 이어 붙일 수 있습니다
- 쓰는 곳: 정해진 검사를 저장소에 올릴 때마다 자동으로 돌리는 CI
- 데스크탑 앱에는 같은 기능이 없어, 이 코스에서 명령어를 피하기 어려운 몇 안 되는 지점입니다
- 필요한 세 조각: 요청 문장, 미리 승인할 도구, 결과를 보낼 곳
미리 승인하는 도구는 좁게 잡습니다
-p실행에는 확인 창이 없어, 승인이 필요한 지점에 닿으면 거기서 멈춥니다--allowedTools로 미리 승인하면 멈추지 않고 끝까지 진행합니다- 넓게 잡을수록 확인 없이 실행되는 범위가 넓어집니다
- 읽어서 정리하는 일:
Read - 파일을 고쳐야 할 때:
Edit추가 Bash: 명령을 직접 실행하는 도구라 초보 단계의 자동 실행에는 넣지 않습니다
- 읽어서 정리하는 일:
내가 만들지 않은 폴더에서는 —bare를 붙입니다
-p세션에는 폴더 신뢰 확인 창이 뜨지 않습니다- 옵션 없이 실행하면
.claude/settings.json의 Hook이 그대로 실행되고,.mcp.json의 서버에도 연결됩니다 - 문제가 되는 곳: 내려받은 저장소, 남에게 받은 폴더
--bare: Hook·스킬·플러그인·MCP 서버·CLAUDE.md를 모두 읽지 않고 실행합니다- 어느 컴퓨터에서 돌려도 같은 결과가 나와, 저장소를 처음 열어 볼 때와 CI 검사에 씁니다
성공 여부는 종료 코드로 확인합니다
- 화면에 답이 나왔다고 성공한 것은 아닙니다
- 실행이 실패하면 0이 아닌 종료 코드를 남깁니다
- 인증이 빠진 경우처럼 실행 도중 생긴 실패는 결과에 그대로 출력됩니다
- 명령을 이어 붙이거나 자동으로 돌릴 때는 종료 코드로 다음 동작을 정합니다
- 순서 아래 명령을 그대로 붙여넣어 결과 파일이 실제로 만들어지는지 확인해 보세요
실행 순서
-
한 번에 끝낼 요청 하나를 문장으로 정합니다. 결과가 화면 출력이나 파일로 남는 일만 고르고, 중간에 사람에게 되물어야 하는 일은 대화 세션에 남겨 둡니다.
-
작업할 폴더로 이동한 뒤 요청을 붙여 실행합니다. 답이 대화창 대신 터미널에 바로 출력됩니다.
명령어로 직접 하기
일반 터미널에서 실행합니다. Claude Code 세션 안이 아닙니다. -p는 --print의 짧은 형태이고, 실행이 끝나면 세션이 그대로 닫힙니다.
claude -p "이 폴더의 README를 읽고 핵심을 다섯 줄로 요약해 줘"
-
쓸 도구를 미리 지정합니다. 지정하지 않으면 실행 도중 승인 창이 필요한 지점에서 멈춥니다.
명령어로 직접 하기
미리 승인한 도구는 실행 중 확인 없이 쓰입니다. 읽기만 필요하면 Read만 넣고, 파일을 고치거나 명령을 실행하는 도구는 필요한 것만 하나씩 추가합니다.
claude -p "이 폴더의 문서 목록을 표로 정리해 줘" --allowedTools "Read"
-
결과를 파일로 받습니다. 화면에 흘려보내지 않고 남겨야 다음 작업에서 쓸 수 있습니다.
명령어로 직접 하기
> 뒤에 적은 이름으로 파일이 새로 만들어집니다. 같은 이름이 이미 있으면 덮어쓰므로 새 이름을 씁니다.
claude -p "이 폴더의 README를 읽고 핵심을 다섯 줄로 요약해 줘" --allowedTools "Read" > summary.md
-
내가 만들지 않은 폴더에서 실행할 때는 그 폴더의 설정을 읽지 않게 합니다.
명령어로 직접 하기
--bare는 그 폴더의 Hook·스킬·플러그인·MCP 서버·CLAUDE.md를 읽지 않고 실행합니다. 붙이지 않으면 신뢰 확인 창 없이 그것들이 그대로 실행됩니다.
claude -p "이 폴더가 무슨 프로젝트인지 설명해 줘" --bare --allowedTools "Read"
-
명령이 끝난 뒤 종료 코드를 확인합니다. 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를 통째로 넣으면 확인 없이 명령이 실행되므로, 삭제·배포·발송이 섞일 수 있는 요청에는 쓰지 않습니다. 결과를 > 로 내보낼 때 기존 파일 이름을 쓰면 내용이 덮어써집니다.
용어 풀이
전체 용어집 →2026-08-19 기준 · 출처 · Claude Code — Run Claude Code programmatically, Claude Code — CLI reference