9월23일(수)
Claude Code CLI (Anthropic) 사용법
클로드 CLI(claude, Anthropic의 Claude Code CLI)의 핵심 사용법과 명령어 정리입니다.
1. 설치 및 초기 실행
터미널에서 npm을 통해 설치 후 프로젝트 폴더에서 바로 실행합니다.
# 글로벌 설치
npm install -g @anthropic-ai/claude-code
# 프로젝트 루트 디렉터리로 이동 후 실행
cd /path/to/project
claude
- 최초 실행 시 Anthropic API 키 입력 및 인증(OAuth 브라우저 로그인) 창이 열립니다.
2. 세션 내 주요 슬래시 명령어 (/)
claude 대화형(Interactive) 세션 진입 후 입력창에 /를 입력해 시스템 및 컨텍스트를 제어합니다.
/help: 사용 가능한 모든 슬래시 명령어와 단축키 안내/compact: 현재까지 누적된 대화와 로그를 요약하여 컨텍스트 창 크기 절약 (컨텍스트 다이어트 필수 명령)/clear: 현재 세션의 대화 컨텍스트를 완전히 초기화 (새로운 태스크 시작 시 권장)/config: 전역 및 프로젝트별 환경 설정(자동 승인 범위, 테마 등) 확인 및 변경/cost: 현재 세션에서 소모된 토큰 수와 예상 비용 확인/doctor: 네트워크 연결, Node.js 버전, API 키 상태 등 CLI 동작 환경 진단/review: 최근 변경 사항 및 diff를 코드 리뷰 관점에서 점검 요청/bug: 도구 버그 발생 시 Anthropic 팀에 피드백 전송/exit또는/quit: 세션 종료 (Ctrl + C로도 가능)
3. 터미널 단독 실행 옵션 (Non-Interactive / Flags)
대화형 프롬프트로 들어가지 않고 터미널 명령줄에서 직접 요청을 전달할 때 유용합니다.
- 단발성 프롬프트 실행 (
-p/--print)
대화형 모드 진입 없이 결과를 출력하고 즉시 종료합니다 (CI/CD 파이프라인이나 셸 스크립트에 적합).
claude -p "src/utils/date.ts 파일의 유닛 테스트 코드 작성해줘"
- 지속 세션 재개 (
-c/--continue)
가장 최근에 작업하던 세션의 컨텍스트를 이어서 실행합니다.
claude -c
- 새 세션 강제 시작 (
-r/--resume)
특정 세션 ID를 지정하여 과거 작업 기록을 불러올 때 사용합니다. - 자동 실행 허용 모드 (
--dangerously-skip-permissions)
파일 수정이나 터미널 명령어 실행 시 매번 승인 프롬프트를 띄우지 않고 자동 실행합니다 (컨테이너나 샌드박스 환경 권장).
4. 세션 단축키 및 조작 팁
- 취소/중단 (
Ctrl + C): 클로드가 파일 검색, 긴 코드 생성, 터미널 명령을 수행 중일 때 즉시 작업을 중단시킵니다. - 줄바꿈 (
Shift + Enter또는Alt + Enter): 명령어 제출 대신 프롬프트 입력창에서 줄바꿈을 입력할 때 사용합니다. - 프로젝트 규칙 지정 (
CLAUDE.md):
프로젝트 루트에CLAUDE.md파일을 두면 CLI가 실행될 때 프로젝트 빌드/테스트 규칙, 코딩 컨벤션, 주석 규칙을 자동으로 읽어 시스템 컨텍스트로 유지합니다.
settings.json이란?
Claude Code CLI에서 CLAUDE.md가 에이전트가 읽는 "지침/행동 양식(자연어 프롬프트)"이라면, settings.json은 에이전트가 실행할 수 있는 도구, 셸 명령어 권한, 모델 기본값 등을 물리적으로 통제하는 기계적 환경설정 파일입니다.
1. settings.json의 위치 및 우선순위 계층
설정 파일은 적용 범위(Scope)에 따라 3단계로 분리되어 병합(Merge) 적용됩니다.
- 프로젝트 로컬 개인 설정 (
.claude/settings.local.json)
- 현재 프로젝트에서 나만 사용할 오버라이드 설정 (보통
.gitignore에 등록).
- 프로젝트 공유 설정 (
.claude/settings.json)
- 프로젝트 루트에 위치하며 Git에 커밋하여 팀원 전체가 공유하는 공통 정책(권한 허용 목록, 프로젝트 훅 등).
- 사용자 전역 설정 (
~/.claude/settings.json)
- 내 PC의 모든 프로젝트에 적용되는 개인 기본 설정 (기본 모델, 테마 등).
우선순위:
CLI 플래그 > settings.local.json > .claude/settings.json > ~/.claude/settings.json
2. 핵심 설정 항목 및 활용 예시
실제 실무에서 보안, 자동화, 비용 최적화를 위해 구성하는 대표적인 settings.json 템플릿입니다.
{
"$schema": "https://json-schema.org/claude-code-settings.json",
"model": "claude-3-7-sonnet-20250219",
"autoCompactThreshold": 80,
"permissions": {
"allow": [
"Bash(npm test *)",
"Bash(npm run lint)",
"Bash(git status)",
"Bash(git diff *)",
"Bash(ls *)"
],
"deny": [
"Read(./.env*)",
"Read(~/.ssh/*)",
"Bash(git push --force *)",
"Bash(rm -rf *)",
"Bash(DROP TABLE *)"
]
},
"env": {
"NODE_ENV": "development"
},
"autoUpdate": true,
"cleanupPeriodDays": 30
}
3. 주요 속성 상세 설명
permissions(가장 핵심적인 보안 및 자동화 설정)allow: 에이전트가 매번 사용자에게y/n승인을 묻지 않고 즉시 자율 실행할 수 있는 명령어 목록입니다. 테스트 실행(npm test), 린트, 읽기 전용 셸 명령어를 등록해두면 개발 흐름이 끊기지 않습니다.deny: 에이전트가 절대로 실행하거나 접근하지 못하도록 원천 차단하는 블랙리스트입니다..env환경변수 파일이나 개인 SSH 키,git push --force,rm -rf같은 파괴적 명령을 등록하여 보안 사고를 예방합니다.
model:- 세션 시작 시 기본으로 사용할 모델 식별자를 고정합니다. (미설정 시 기본 권장 모델 사용)
autoCompactThreshold:- 컨텍스트 윈도우가 지정한 비율(예:
80%)만큼 차오르면 자동으로/compact요약을 트리거하여 컨텍스트 초과 에러를 방지합니다.
env:- Claude Code가 터미널 셸 명령을 실행할 때 기본 주입할 환경 변수 맵을 지정합니다.
cleanupPeriodDays:- 과거 세션 대화 기록 및 트랜스크립트 파일의 보관 주기를 일(Day) 단위로 제어합니다.
4. CLAUDE.md vs settings.json 차이 요약
CLAUDE.md: "초보자를 위한 분석 주석을 코드에 달 것", "변수명은 카멜케이스를 쓸 것"과 같은 코드 작성 스타일 및 태스크 가이드 (프롬프트 수준의 제어).settings.json: ".env파일은 절대 읽지 말 것", "npm test는 묻지 말고 실행할 것"과 같은 시스템 보안 및 실행 권한 강제 (하드 펜스 수준의 기계적 제어).
WIN