{"id":"claude-code-headless","kind":"workflow","testedWith":[],"durationMin":15,"url":"https://opencurrent.ai/w/claude-code-headless","title":"claude -p로 스크립트 돌리기","summary":"claude -p 헤드리스 모드로 Claude Code를 스크립트·CI·빌드 명령 안에서 돌려, 대화창을 열지 않고도 리뷰·요약·수정 같은 일을 자동으로 맡길 수 있습니다.","category":"개발","categoryId":"dev","domain":"dev","domainLabel":"개발","capabilities":[{"id":"code","label":"코드 작성"}],"topics":[{"id":"dev","label":"개발"}],"tools":["Claude Code"],"whenToUse":"-p로 한 번 실행하고 결과를 text나 json으로 받습니다. 사람이 승인할 수 없는 실행이므로 --allowedTools와 --permission-mode로 할 수 있는 일을 정하고, --max-turns·--max-budget-usd로 한도를 둡니다. 명령과 설정 이름은 2026년 11월 21일에 Claude Code 공식 문서로 확인했습니다.","prerequisites":["Claude Code 설치와 로그인"],"inputs":[],"howToFollow":"1. 준비물이 갖춰졌는지 먼저 확인할 것.\n2. 단계를 순서대로 진행할 것. kind가 \"ai\"면 프롬프트를 실행하고, \"command\"면 사용자의 허락을 받고 명령을 실행하고, \"human\"이면 사용자에게 할 일을 안내하고 끝났는지 물을 것. tool이 있으면 그 도구·모델로 할 것.\n3. 단계에 output(결과 이름)이 있으면 그 단계 결과를 뒤 단계 프롬프트의 {{output}} 자리에 넣을 것.\n4. 단계마다 expected(기대 결과)와 check(확인 방법)로 제대로 됐는지 확인하고, 다르면 다음 단계로 넘어가지 말고 사용자에게 알릴 것. 끝나면 example.output(있으면)과 비교할 것.\n5. 검증 상태가 verified가 아니면 그 사실을 사용자에게 먼저 알릴 것. 답에 url을 출처로 밝힐 것.","steps":[{"n":1,"kind":"command","title":"한 번 실행","body":"-p 뒤에 요청을 줍니다. 파이프로 받은 내용도 함께 넘길 수 있고, 최대 10MB까지입니다.","prompt":"cat build-error.txt | claude -p '이 빌드 오류의 원인을 짧게 설명해 줘' > why.txt","expected":"why.txt의 설명","check":"명령의 종료 코드가 0인지 확인(echo $?)","tool":"Claude Code"},{"n":2,"kind":"command","title":"할 수 있는 도구 정하기","body":"-p 실행은 아무것도 정하지 않으면 승인이 필요한 동작이 거절됩니다. 필요한 도구만 --allowedTools로 열어 줍니다.","prompt":"claude -p \"테스트를 돌리고 실패를 고쳐 줘\" --allowedTools \"Bash(npm test *),Read,Edit\"","expected":"테스트를 고친 변경","check":"git diff로 고친 내용 확인","tool":"Claude Code"},{"n":3,"kind":"command","title":"JSON으로 받기","body":"--output-format json이면 결과(result)와 세션 id가 함께 옵니다. jq로 결과만 꺼내 다음 명령에 넘깁니다.","prompt":"claude -p \"이 프로젝트를 세 줄로 요약해 줘\" --output-format json | jq -r '.result'","expected":"요약 세 줄","check":"출력이 JSON이 아니라 요약 글인지 확인","tool":"Claude Code"},{"n":4,"kind":"command","title":"한도 두기","body":"자동 실행이 끝없이 돌지 않게 턴 수와 금액 한도를 줍니다.","prompt":"claude -p --max-turns 5 --max-budget-usd 2.00 \"README의 오래된 설치 안내를 고쳐 줘\"","expected":"한도 안에서 끝난 실행","check":"실행이 한도에 닿으면 멈추는지 확인","tool":"Claude Code"},{"n":5,"kind":"command","title":"이어서 실행","body":"앞 실행의 세션 id로 이어 갑니다. 같은 폴더의 가장 최근 대화는 --continue로 이어집니다.","prompt":"sid=$(claude -p \"리뷰를 시작해 줘\" --output-format json | jq -r '.session_id')\nclaude -p \"이어서 보안 문제만 다시 봐 줘\" --resume \"$sid\"","expected":"앞 대화를 이은 결과","check":"두 번째 답이 첫 리뷰 내용을 이어받는지 확인","tool":"Claude Code"}],"pitfalls":["--dangerously-skip-permissions(bypassPermissions)는 격리된 컨테이너·VM에서만","스크립트용으로는 --bare를 권장(훅·스킬·플러그인·MCP·CLAUDE.md를 건너뜀). 대신 ANTHROPIC_API_KEY 필요","CI에서 API 키로 돌리면 실행마다 요금 발생"],"sources":[{"title":"Claude Code 문서: 프로그램으로 실행하기","url":"https://code.claude.com/docs/en/headless"},{"title":"Claude Code 문서: CLI 레퍼런스","url":"https://code.claude.com/docs/en/cli-reference"}],"verification":{"status":"pending","label":"검수 대기","detail":"사람 확인 전","verifiedBy":0,"lastVerifiedAt":null},"quality":{"score":32,"components":{"result":0.5,"trust":0,"freshness":0.4},"explanation":"확인 없음 · 검수 대기"},"workedFor":0,"trials":{"summary":"","lastAt":null,"total":0,"worked":0,"partial":0,"failed":0,"recent":[]},"asOf":{"date":"2026-11-21T10:00:00+00:00","basis":"updated"},"updatedAt":"2026-11-21T10:00:00+00:00","goals":[{"id":"dev","title":"개발"}],"uses":0,"likes":0}