Claude Code 명령어 총정리 — 실행·세션·자동화 실전 예제
Claude Code는 터미널에서 자연어로 코드를 분석하고 수정하는 에이전트형 개발 도구입니다. 기본 실행 명령은 간단하지만, 세션을 이어서 작업하거나 결과를 JSON으로 받아 자동화하고, 모델과 권한 범위를 제한하는 옵션까지 익히면 활용도가 크게 높아집니다. 이 글에서는 2026년 8월 Anthropic 공식 CLI 문서를 기준으로 자주 쓰는 Claude Code 명령어와 실전 예제를 목적별로 정리합니다.
기본 실행과 일회성 질문
현재 프로젝트에서 대화형 세션을 시작하려면 프로젝트 폴더로 이동한 뒤 claude를 실행합니다. Claude Code가 저장소의 파일을 읽고 도구 사용이 필요할 때 권한을 요청하는 기본 방식입니다.
cd /path/to/project
claude첫 질문을 명령행에서 바로 전달할 수도 있습니다. 아래 명령은 질문을 넣은 상태로 대화형 세션을 열기 때문에 답변을 받은 뒤 계속 대화할 수 있습니다.
claude "이 프로젝트의 구조와 실행 방법을 설명해 줘"답변만 출력하고 즉시 종료하려면 -p 또는 --print를 사용합니다. 셸 스크립트와 CI 작업에서 특히 유용합니다.
claude -p "이 함수의 잠재적인 버그를 설명해 줘"파일이나 로그를 표준 입력으로 전달할 수도 있습니다. 비밀키나 개인정보가 포함된 파일을 그대로 전달하지 않도록 주의해야 합니다.
cat error.log | claude -p "오류 원인과 해결 순서를 요약해 줘"대화와 세션 이어서 사용하기
Claude Code는 대화 맥락을 세션으로 저장합니다. 현재 디렉터리에서 가장 최근 대화를 이어가려면 -c를 사용합니다.
claude -c이전 세션을 이어서 일회성 작업만 실행하려면 -c와 -p를 함께 사용합니다.
claude -c -p "방금 수정한 코드에 타입 오류가 없는지 확인해 줘"특정 세션을 선택하려면 -r 또는 --resume을 사용합니다. 인자 없이 실행하면 선택 화면이 열리고, 세션 ID나 이름을 지정하면 해당 대화를 바로 불러옵니다.
claude --resume
claude -r "auth-refactor" "이 작업을 마무리하고 테스트해 줘"긴 작업은 시작할 때 이름을 붙이면 찾기 쉽습니다. -n은 세션 표시 이름을 지정합니다.
claude -n "payment-api-review"자동화와 출력 형식
-p 실행 결과는 기본적으로 일반 텍스트입니다. 다른 프로그램이 읽어야 한다면 --output-format json을 사용합니다. 실시간 이벤트가 필요한 시스템은 stream-json을 선택할 수 있습니다.
claude -p "변경된 파일을 검토해 줘" --output-format json자동화 작업에서 추가 규칙을 적용하려면 기본 시스템 프롬프트를 유지하는 --append-system-prompt가 안전한 선택입니다. --system-prompt는 기본 프롬프트 전체를 교체해 도구 사용 지침과 안전 지침도 사라질 수 있으므로 용도를 이해할 때만 사용해야 합니다.
claude -p "현재 변경 사항을 리뷰해 줘" \
--append-system-prompt "결과는 심각도 순으로 정리하고 파일 경로를 표시하세요"일회성 스크립트의 세션을 디스크에 남기고 싶지 않다면 print 모드에서 --no-session-persistence를 지정합니다.
claude -p --no-session-persistence "README의 맞춤법을 검사해 줘"모델·권한·접근 범위 제어
--model은 현재 세션에 사용할 모델을 지정합니다. sonnet, opus, haiku 같은 별칭이나 전체 모델 ID를 사용할 수 있습니다.
claude --model sonnet코드를 변경하지 않고 분석과 계획만 먼저 받고 싶다면 plan 권한 모드로 시작합니다. 낯선 저장소나 중요한 운영 코드에서는 이 방식이 유용합니다.
claude --permission-mode plan--allowedTools는 특정 도구를 확인 없이 허용하고, --disallowedTools는 위험한 작업 패턴을 막습니다. 다음 예시는 Git 로그와 diff 조회만 자동 허용합니다.
claude --allowedTools "Bash(git log *)" "Bash(git diff *)" "Read"--dangerously-skip-permissions는 권한 확인을 건너뛰므로 격리된 임시 환경이 아니라면 피하는 편이 좋습니다. 이름 그대로 파일 변경과 명령 실행의 안전장치를 크게 낮춥니다.
현재 폴더 밖의 추가 디렉터리에 접근해야 한다면 --add-dir을 사용합니다. 이 옵션은 해당 경로에 읽기와 편집 권한을 부여하므로 필요한 디렉터리만 지정해야 합니다.
claude --add-dir ../shared-libMCP·플러그인·백그라운드 작업
MCP 서버는 claude mcp 하위 명령으로 관리합니다. OAuth가 필요한 서버는 터미널에서 로그인과 로그아웃을 실행할 수 있습니다.
claude mcp login sentry
claude mcp logout sentry세션 하나에서 별도 MCP 설정 파일을 불러오려면 --mcp-config를 사용합니다. 다른 설정에 등록된 서버를 무시하고 지정한 파일만 쓰려면 --strict-mcp-config를 함께 사용합니다.
claude --strict-mcp-config --mcp-config ./mcp.json플러그인은 claude plugin 명령으로 관리합니다. 설치 예시는 다음과 같습니다.
claude plugin install code-review@claude-plugins-official긴 조사 작업은 --background 또는 --bg로 백그라운드 세션을 시작할 수 있습니다. 반환된 ID를 이용해 상태를 확인하거나 다시 연결합니다.
claude --bg "간헐적으로 실패하는 테스트 원인을 조사해 줘"
claude agents --json
claude logs <session-id>
claude attach <session-id>진단·업데이트와 실전 조합
설치 상태와 설정 파일 오류를 읽기 전용으로 점검하려면 claude doctor를 사용합니다. 로그인 상태는 claude auth status --text, 버전은 claude -v로 확인합니다.
claude doctor
claude auth status --text
claude -v네이티브 설치를 즉시 업데이트하려면 claude update를 실행합니다. 특정 채널이나 버전으로 다시 설치해야 할 때는 claude install stable 또는 버전 번호를 지정할 수 있습니다.
claude update
claude install stable실무에서는 옵션을 목적에 맞게 조합하는 것이 핵심입니다. 예를 들어 코드 변경 없이 별도 라이브러리까지 읽어 보안 검토를 수행하려면 다음처럼 실행할 수 있습니다.
claude --permission-mode plan \
--add-dir ../shared-lib \
--model sonnet \
"인증 흐름을 검토하고 위험 요소와 수정 계획만 작성해 줘"자동화에서는 먼저 제한된 권한과 텍스트 출력으로 동작을 검증하고, 안정된 뒤 JSON 출력과 허용 도구를 추가하는 순서가 좋습니다. 특히 권한 우회 옵션을 기본 별칭에 넣는 방식은 작은 프롬프트 실수도 실제 파일 변경으로 이어질 수 있으므로 권장하기 어렵습니다.
참고 자료
'Claude Code' 카테고리의 다른 글
| Claude Code 플러그인 사용법: 설치·마켓플레이스·보안 정리 (0) | 2026.08.31 |
|---|---|
| How to Resume Claude Code CLI Sessions in the Desktop App (0) | 2026.08.30 |
| Claude Code 2.1.251 업데이트: 모델 전환·캐시 비용 정리 (0) | 2026.08.29 |
| Claude Workbench 종료 후 프롬프트 운영 전환 가이드 (0) | 2026.08.18 |
| Claude Code 설치 방법 — macOS·Windows·Linux 완벽 가이드 (0) | 2026.08.09 |
