Quick Reference
비대화형 실행은 -p로 프롬프트를 처리한 뒤 종료하는 방식입니다. 사람이 대화하며 승인할 작업은 일반 claude 세션으로, 로그 요약·정해진 검사·기계 처리 결과는 -p로 나눕니다. -p라고 해서 읽기 전용이 되는 것은 아니므로, 자동화에는 권한 모드와 종료·비용 한도를 함께 둡니다.
| 목적 | 명령 | 중요한 경계 |
|---|---|---|
| 대화형 세션 시작 | claude | 승인·후속 질문·화면 조작이 필요한 작업에 맞습니다. |
| 첫 질문과 함께 대화형 시작 | claude "현재 프로젝트를 설명해 줘" | 명령이 끝나도 세션은 계속 열려 있습니다. |
| 한 번 실행 후 종료 | claude -p "빌드 로그를 요약해 줘" | 프롬프트가 필요한 도구 호출은 사람이 답할 수 없습니다. |
| 현재 디렉터리의 최근 대화 재개 | claude -c | 다른 저장소의 최근 대화를 이어가지 않습니다. |
| ID 또는 이름으로 대화 재개 | claude -r auth-refactor | 현재 프로젝트 밖의 세션도 찾을 수 있으므로 작업 경로를 다시 확인합니다. |
# 기계가 읽을 최종 결과와 실행 한도를 함께 둔다.
claude -p --output-format json --max-turns 3 --max-budget-usd 2 \
"현재 git diff에서 수정된 파일과 테스트 위험만 JSON으로 반환해 줘. 파일은 수정하지 마."
# 프롬프트가 필요한 호출을 모두 거부하는 CI용 시작점이다.
claude -p --permission-mode dontAsk --max-turns 3 \
"테스트 결과를 읽고 실패 원인만 요약해 줘."실행과 세션 범위
claude -p는 응답을 표준 출력으로 내보내고 끝납니다. 파일을 수정하거나 셸 명령을 실행하려면 그 도구 호출이 현재 권한 규칙에서 허용되어야 합니다. 따라서 자동화에서 "수정해 줘"라고만 보내는 방식은 실패했을 때 승인 대기·권한 거부·부분 변경 중 무엇이 일어났는지 판단하기 어렵습니다. 분석 단계와 실제 변경 단계를 별도의 명령으로 나눕니다.
-c는 현재 디렉터리에서 가장 최근 대화를 이어 갑니다. -r 또는 --resume은 세션 ID나 이름으로 특정 대화를 다시 열며, ID를 넘기면 현재 프로젝트·worktree를 찾은 뒤 이 컴퓨터의 다른 프로젝트도 검색합니다. 예전 대화의 지시와 현재 브랜치·작업 트리가 다를 수 있으므로 재개 직후에는 현재 위치, Git 상태, 이번 실행의 목표를 다시 명시합니다. 원래 세션을 바꾸지 않고 분기하려면 --fork-session을 --resume 또는 --continue와 함께 씁니다.
# 같은 대화의 맥락은 보되 새 세션 ID에서 작업한다.
claude --resume auth-refactor --fork-session \
"현재 브랜치와 변경 파일을 먼저 확인한 뒤 테스트만 실행해 줘."출력과 한도
--output-format은 -p에서만 쓰며, text, json, stream-json을 고릅니다. text는 사람이 바로 읽을 최종 답에, json은 한 번 끝난 결과를 후처리할 때, stream-json은 도구 이벤트와 진행 상태를 스트림으로 소비할 때 맞습니다. 부분 메시지·hook 이벤트·subagent 본문까지 받는 옵션에는 --verbose와 stream-json이 함께 필요할 수 있습니다.
정해진 JSON 구조가 필요하면 --json-schema를 -p와 함께 씁니다. 이는 에이전트 작업이 끝난 뒤 결과가 스키마를 만족하는지 검증하며, 스키마가 잘못되면 명령을 오류로 끝냅니다. format 키는 주석처럼 받아들이므로, 이메일·URI 같은 형식을 엄격하게 검증하는 서버 측 계약을 대신하지는 않습니다.
| 옵션 | 기본값 | 언제 넣는가 | 한계와 실패 방식 |
|---|---|---|---|
--output-format | text | 파이프·파일·후속 프로그램이 결과를 읽을 때 | json도 프롬프트 내용의 정확성을 보장하지 않습니다. |
--max-turns | 제한 없음 | 검사 작업이 무한히 이어지지 않게 할 때 | 한도에 닿으면 오류로 종료합니다. |
--max-budget-usd | 제한 없음 | API 비용 상한이 필요한 자동화 | subagent 비용도 한도에 포함됩니다. |
--no-session-persistence | 세션 저장 | 민감한 일회성 비대화형 실행 | 실행 뒤 재개할 수 없습니다. |
--safe-mode | 사용자 설정 로드 | 설정·plugin·hook이 문제인지 진단 | 관리형 정책은 계속 적용될 수 있습니다. |
자동화의 권한 경계
비대화형 실행에서는 승인 대화 상자가 열릴 수 없습니다. dontAsk는 질문이 필요한 도구 호출을 모두 거부하고, 미리 허용한 도구와 읽기 전용 Bash 명령만 실행합니다. CI에서 예측 가능한 읽기 작업을 하려면 이 모드와 좁은 permissions.allow 규칙을 함께 사용합니다. 반대로 --allowedTools는 해당 도구를 자동 승인할 뿐, 다른 도구를 숨기는 allowlist가 아닙니다. 사용 가능한 도구 자체를 제한하려면 --tools 또는 --disallowedTools를 별도로 검토합니다.
--permission-mode auto는 일반 승인 창을 줄이고 별도 분류기가 작업을 검사하는 모드입니다. ask 규칙과 사용자 상호작용이 필요한 MCP 도구는 여전히 승인을 요구할 수 있으며, 중요한 인프라 변경이나 민감한 외부 전송의 검토를 대체하지 않습니다. bypassPermissions 또는 --dangerously-skip-permissions는 권한 검사와 안전 검토를 건너뛰므로, 인터넷과 호스트 자산에서 격리된 container·VM에서만 사용합니다.
자주 틀리는 부분
-p의 성공 종료가 요청한 검증이 성공했다는 뜻은 아닙니다. 표준 출력의 구조, 테스트 명령의 종료 코드, 실제 변경 파일, 권한 거부·한도 초과·MCP 인증 실패를 각각 자동화에서 검사해야 합니다.
피해야 할 흐름
- -p로 배포·커밋·외부 전송을 한 번에 요청한다.
- 출력 형식만 JSON으로 바꾸고 종료 코드와 스키마 오류를 무시한다.
- -r로 재개한 뒤 이전 세션의 저장소·브랜치를 현재 작업에도 적용한다.
권장 흐름
1. dontAsk와 좁은 허용 규칙으로 읽기 전용 검사를 실행한다.
2. JSON 결과와 테스트 종료 코드를 CI가 직접 검증한다.
3. 변경·배포는 별도 단계에서 격리 환경과 명시적 승인으로 처리한다.참고 링크
2 sources